{"owner":"shadowsocks","repo":"shadowsocks-libev","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":2040,"categories":["claude-rule"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nshadowsocks-c (formerly shadowsocks-libev) is a lightweight SOCKS5 proxy. Version 3.3.6, licensed under GPLv3.\nThe sources are C++20 (no exceptions, no RTTI, no heap allocation after startup; see `docs/cpp-core.md`).\nThe public `src/shadowsocks.h` stays a C header with a stable ABI.\n\n## Build Commands\n\n### CMake (sole build system)\n\n```bash\ncmake --preset bundled          # or: cmake -S . -B build -G Ninja\ncmake --build --preset bundled\nctest --preset bundled\n```\n\nBundled mode (the default, `SS_DEPENDENCY_MODE=bundled`) builds every dependency from the pinned archives in\n`third_party/dist` with no network access. `SS_DEPENDENCY_MODE=system` uses distro libraries instead.\nThere are no git submodules.\n\nBinaries land in `<build>/bin/`, libraries in `<build>/lib/`.\n\n### Build Dependencies\n\n- CMake >= 3.20, C11 and C++20 compilers (GCC >= 11, Clang >= 14, Apple Clang >= 15), Ninja for the presets\n- System mode only: Mbed TLS 2.x/3.x, libsodium >= 1.0.4, PCRE2 (8-bit), libuv, c-ares\n- Doxygen (documentation only)\n\n### CMake Options\n\n- `-DSS_MINIMAL=ON`: no regex, plugins or manager\n- `-DWITH_STATIC=OFF`: link third-party dependencies dynamically\n- `-DSS_BUILD_EXECUTABLES / SS_BUILD_STATIC_LIBRARY / SS_BUILD_SHARED_LIBRARY`: choose outputs\n- `-DWITH_DOC_MAN=ON` / `-DWITH_DOC_HTML=ON`: build documentation\n- `-DENABLE_CONNMARKTOS=ON`, `-DENABLE_NFTABLES=ON`: Linux netfilter features\n- `-DENABLE_SANITIZERS=ON`, `-DENABLE_COVERAGE=ON`, `-DDISABLE_SSP=ON`, `-DBUILD_TESTING=OFF`\n\n## Testing\n\n### Unit Tests (CTest)\n\n```bash\nctest --test-dir build -LE memcheck --output-on-failure\n```\n\nUnit tests compile the specific `src/*.cpp` files they need (see `ss_add_test` in `tests/CMakeLists.txt`).\nNew tests are C++ (`tests/test_*_cpp.cpp`, `tests/test_core_*.cpp`) using `tests/test_helpers.hpp`; older\nones are C (`tests/test_*.c`). Codec tests compare against the C oracle in `tests/reference/`. The\n`alloc_steady_*` tests fail on any heap allocation in steady state.\nLabels: `unit`, `vendor`, `integration`, `memcheck` (Linux + valgrind).\n\n### Integration Tests\n\n```bash\npython3 tests/interop.py --self --bin build/bin          # TCP/UDP relay, all AEAD/2022 methods\npython3 tests/tunnel_interop.py --bin build/bin          # ss-tunnel, every method\npython3 tests/test_manager.py --bin build/bin            # ss-manager (needs -DWITH_SS_MANAGER=ON on macOS)\npython3 tests/test.py --bin build/bin/ -c tests/aes-gcm.json   # one cipher via curl/dig (needs network)\npython3 tests/test_cli.py --bin-dir build/bin           # CLI contract: help/version/exit codes\npython3 tests/stress_test.py --bin build/bin/ --size 10\n```\n\n### Allocation audit\n\n```bash\npython3 tests/alloc_audit/measure_alloc.py --bin build/bin --shim build/lib/libss_alloc_audit.dylib\n```\n\nReports heap allocations per relayed connection (C baseline numbers are in `docs/cpp-core.md`).\n\n## Code Formatting\n\nUses **uncrustify** with the config at `.uncrustify.cfg`. Key settings: 4-space indent, no tabs, 120-column width, K&R brace style (braces on same line).\n\n## Code Quality Tooling\n\n- **clang-tidy**: config in `.clang-tidy`. The build exports `compile_commands.json` automatically. Run locally:\n  ```bash\n  run-clang-tidy -quiet -p build '/(src/(core/|event/|relay/|crypto/|api/)?[^/]+\\.(c|cpp)|tests/test_(core_[^/]+|[a-z0-9_]+_cpp)\\.cpp)$'\n  ```\n  On macOS with Homebrew LLVM, add `-extra-arg=\"-isysroot$(xcrun --show-sdk-path)\"`. CI (`clang-tidy` job in `tests.yml`) enforces a warning-count ratchet via `MAX_WARNINGS` — lower it when fixing findings; never raise it without justification.\n- **No-heap lint**: `scripts/check_no_heap.py --self-test` (also a ctest) rejects heap allocation in C++ sources under `src/`.\n- **Sanitizers**: `cmake .. -DENABLE_SANITIZERS=ON` builds with ASan + UBSan. CI runs ctest and the stress test under sanitizers on every PR.\n- **Coverage**: `cmake .. -DENABLE_COVERAGE=ON`, run tests, then `make coverage` (needs lcov). HTML report lands in `build/coverage-html/`. CI uploads it as the `coverage-html` artifact.\n\n## Architecture\n\n### Binaries (all in `src/`)\n\nEach binary is compiled with a module define that controls conditional compilation:\n\n| Binary | Define | Purpose |\n|---|---|---|\n| `ss-local` | `MODULE_LOCAL` | SOCKS5 client proxy |\n| `ss-server` | `MODULE_REMOTE` | Server-side proxy |\n| `ss-tunnel` | `MODULE_TUNNEL` | Port forwarding tunnel (implies `MODULE_LOCAL`) |\n| `ss-redir` | `MODULE_REDIR` | Transparent proxy via iptables (Linux only, implies `MODULE_LOCAL`) |\n| `ss-manager` | `MODULE_MANAGER` | Multi-server manager daemon (Linux only by default) |\n\nA library `libshadowsocks-c` (legacy names `libshadowsocks-libev.*` are kept) is built from the ss-local sources with `-DLIB_ONLY`. Its public API is in `src/shadowsocks.h`.\n\n### Source Organization (`src/`)\n\n**Shared by all binaries:**\n- `utils.cpp` - logging, system utilities, `ss_malloc`/`ss_free` (startup only), CLI help snippets\n- `jconf.cpp` / `json.cpp` - JSON config file parsing\n- `netutils.cpp` - network address utilities\n- `ppbloom.cpp` - ping-pong bloom filter for salt replay detection (`third_party/bloom`)\n\n**Relay engines** (`src/relay/`): `tcp.cpp` (one TCP engine for all four programs, `Kind` selects the\nhandshake), `udp.cpp` (UDP relay), `codec.cpp` (per-connection encoder/decoder variants), `resolver.cpp`\n(pooled c-ares queries), `socket.cpp` (upstream sockets, TFO). Each program's `main()` builds a config and\nruns them.\n\n**Crypto** (`src/crypto/`): value-type codecs `aead.cpp` (AES-GCM, ChaCha20-Poly1305), `aead2022.cpp`\n(Shadowsocks 2022, BLAKE3 from `src/blake3`), `keys.cpp`\n(key derivation, method tables). The old C implementation lives in `tests/reference/` as a test oracle.\n\n**ACL:** `acl.cpp` / `rule.cpp` / `ipset.cpp` - IP prefix sets and PCRE2/literal domain rules.\n\n**Plugins:** `plugin.cpp` / `process.cpp` - SIP003 plugin subprocess management.\n\n**C++ core:** `src/core/*.hpp` - ownership and allocation primitives (pools, handles, fixed buffers, arena,\nfixed hash map/LRU, intrusive list, bounded heap, `heap_guard` for third-party allocators).\n\n**Embedding API:** `src/shadowsocks.h` (unchanged C ABI), `src/shadowsocks/control.h`\n(`ss_local_start`/`stop`/`wait`/`destroy`) and `src/shadowsocks/shadowsocks.hpp` (RAII wrapper).\n\n### Event Loop\n\n`src/event/loop.hpp` wraps libuv (kqueue/epoll/IOCP) handles embedded by value in their owners;\n`src/event/program.hpp` is the per-process loop, signals and timers. Connections come from fixed pools sized by\n`--max-connections`, `--max-udp-sessions` and `--max-dns-queries`; a full TCP pool pauses accepting.\nNon-owning references (DNS answers, timers) are generation-checked handles. Each binary still defines its\nown `main()` and option parsing in `local.cpp`, `tunnel.cpp`, `redir.cpp`, `server.cpp`, `manager.cpp`.\n\n### Compiler Flags\n\nFrom `cmake/ProjectOptions.cmake`: `-Wall -Werror -Wno-deprecated-declarations -fno-strict-aliasing -fstack-protector-strong`, plus `_GNU_SOURCE` on Linux. C is C11 with GNU extensions. C++ is C++20 without extensions and adds `-Wextra -fno-exceptions -fno-rtti -fno-threadsafe-statics`.\n\n`-Werror` means all warnings are errors — new code must compile warning-free.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nshadowsocks-c (formerly shadowsocks-libev) is a lightweight SOCKS5 proxy. Version 3.3.6, licensed under GPLv3.\nThe sources are C++20 (no exceptions, no RTTI, no heap allocation after startup; see `docs/cpp-core.md`).\nThe public `src/shadowsocks.h` stays a C header with a stable ABI.\n\n## Build Commands\n\n### CMake (sole build system)\n\n```bash\ncmake --preset bundled          # or: cmake -S . -B build -G Ninja\ncmake --build --preset bundled\nctest --preset bundled\n```\n\nBundled mode (the default, `SS_DEPENDENCY_MODE=bundled`) builds every dependency from the pinned archives in\n`third_party/dist` with no network access. `SS_DEPENDENCY_MODE=system` uses distro libraries instead.\nThere are no git submodules.\n\nBinaries land in `<build>/bin/`, libraries in `<build>/lib/`.\n\n### Build Dependencies\n\n- CMake >= 3.20, C11 and C++20 compilers (GCC >= 11, Clang >= 14, Apple Clang >= 15), Ninja for the presets\n- System mode only: Mbed TLS 2.x/3.x, libsodium >= 1.0.4, PCRE2 (8-bit), libuv, c-ares\n- Doxygen (documentation only)\n\n### CMake Options\n\n- `-DSS_MINIMAL=ON`: no regex, plugins or manager\n- `-DWITH_STATIC=OFF`: link third-party dependencies dynamically\n- `-DSS_BUILD_EXECUTABLES / SS_BUILD_STATIC_LIBRARY / SS_BUILD_SHARED_LIBRARY`: choose outputs\n- `-DWITH_DOC_MAN=ON` / `-DWITH_DOC_HTML=ON`: build documentation\n- `-DENABLE_CONNMARKTOS=ON`, `-DENABLE_NFTABLES=ON`: Linux netfilter features\n- `-DENABLE_SANITIZERS=ON`, `-DENABLE_COVERAGE=ON`, `-DDISABLE_SSP=ON`, `-DBUILD_TESTING=OFF`\n\n## Testing\n\n### Unit Tests (CTest)\n\n```bash\nctest --test-dir build -LE memcheck --output-on-failure\n```\n\nUnit tests compile the specific `src/*.cpp` files they need (see `ss_add_test` in `tests/CMakeLists.txt`).\nNew tests are C++ (`tests/test_*_cpp.cpp`, `tests/test_core_*.cpp`) using `tests/test_helpers.hpp`; older\nones are C (`tests/test_*.c`). Codec tests compare against the C oracle in `tests/reference/`. The\n`alloc_steady_*` tests fail on any heap allocation in steady state.\nLabels: `unit`, `vendor`, `integration`, `memcheck` (Linux + valgrind).\n\n### Integration Tests\n\n```bash\npython3 tests/interop.py --self --bin build/bin          # TCP/UDP relay, all AEAD/2022 methods\npython3 tests/tunnel_interop.py --bin build/bin          # ss-tunnel, every method\npython3 tests/test_manager.py --bin build/bin            # ss-manager (needs -DWITH_SS_MANAGER=ON on macOS)\npython3 tests/test.py --bin build/bin/ -c tests/aes-gcm.json   # one cipher via curl/dig (needs network)\npython3 tests/test_cli.py --bin-dir build/bin           # CLI contract: help/version/exit codes\npython3 tests/stress_test.py --bin build/bin/ --size 10\n```\n\n### Allocation audit\n\n```bash\npython3 tests/alloc_audit/measure_alloc.py --bin build/bin --shim build/lib/libss_alloc_audit.dylib\n```\n\nReports heap allocations per relayed connection (C baseline numbers are in `docs/cpp-core.md`).\n\n## Code Formatting\n\nUses **uncrustify** with the config at `.uncrustify.cfg`. Key settings: 4-space indent, no tabs, 120-column width, K&R brace style (braces on same line).\n\n## Code Quality Tooling\n\n- **clang-tidy**: config in `.clang-tidy`. The build exports `compile_commands.json` automatically. Run locally:\n  ```bash\n  run-clang-tidy -quiet -p build '/(src/(core/|event/|relay/|crypto/|api/)?[^/]+\\.(c|cpp)|tests/test_(core_[^/]+|[a-z0-9_]+_cpp)\\.cpp)$'\n  ```\n  On macOS with Homebrew LLVM, add `-extra-arg=\"-isysroot$(xcrun --show-sdk-path)\"`. CI (`clang-tidy` job in `tests.yml`) enforces a warning-count ratchet via `MAX_WARNINGS` — lower it when fixing findings; never raise it without justification.\n- **No-heap lint**: `scripts/check_no_heap.py --self-test` (also a ctest) rejects heap allocation in C++ sources under `src/`.\n- **Sanitizers**: `cmake .. -DENABLE_SANITIZERS=ON` builds with ASan + UBSan. CI runs ctest and the stress test under sanitizers on every PR.\n- **Coverage**: `cmake .. -DENABLE_COVERAGE=ON`, run tests, then `make coverage` (needs lcov). HTML report lands in `build/coverage-html/`. CI uploads it as the `coverage-html` artifact.\n\n## Architecture\n\n### Binaries (all in `src/`)\n\nEach binary is compiled with a module define that controls conditional compilation:\n\n| Binary | Define | Purpose |\n|---|---|---|\n| `ss-local` | `MODULE_LOCAL` | SOCKS5 client proxy |\n| `ss-server` | `MODULE_REMOTE` | Server-side proxy |\n| `ss-tunnel` | `MODULE_TUNNEL` | Port forwarding tunnel (implies `MODULE_LOCAL`) |\n| `ss-redir` | `MODULE_REDIR` | Transparent proxy via iptables (Linux only, implies `MODULE_LOCAL`) |\n| `ss-manager` | `MODULE_MANAGER` | Multi-server manager daemon (Linux only by default) |\n\nA library `libshadowsocks-c` (legacy names `libshadowsocks-libev.*` are kept) is built from the ss-local sources with `-DLIB_ONLY`. Its public API is in `src/shadowsocks.h`.\n\n### Source Organization (`src/`)\n\n**Shared by all binaries:**\n- `utils.cpp` - logging, system utilities, `ss_malloc`/`ss_free` (startup only), CLI help snippets\n- `jconf.cpp` / `json.cpp` - JSON config file parsing\n- `netutils.cpp` - network address utilities\n- `ppbloom.cpp` - ping-pong bloom filter for salt replay detection (`third_party/bloom`)\n\n**Relay engines** (`src/relay/`): `tcp.cpp` (one TCP engine for all four programs, `Kind` selects the\nhandshake), `udp.cpp` (UDP relay), `codec.cpp` (per-connection encoder/decoder variants), `resolver.cpp`\n(pooled c-ares queries), `socket.cpp` (upstream sockets, TFO). Each program's `main()` builds a config and\nruns them.\n\n**Crypto** (`src/crypto/`): value-type codecs `aead.cpp` (AES-GCM, ChaCha20-Poly1305), `aead2022.cpp`\n(Shadowsocks 2022, BLAKE3 from `src/blake3`), `keys.cpp`\n(key derivation, method tables). The old C implementation lives in `tests/reference/` as a test oracle.\n\n**ACL:** `acl.cpp` / `rule.cpp` / `ipset.cpp` - IP prefix sets and PCRE2/literal domain rules.\n\n**Plugins:** `plugin.cpp` / `process.cpp` - SIP003 plugin subprocess management.\n\n**C++ core:** `src/core/*.hpp` - ownership and allocation primitives (pools, handles, fixed buffers, arena,\nfixed hash map/LRU, intrusive list, bounded heap, `heap_guard` for third-party allocators).\n\n**Embedding API:** `src/shadowsocks.h` (unchanged C ABI), `src/shadowsocks/control.h`\n(`ss_local_start`/`stop`/`wait`/`destroy`) and `src/shadowsocks/shadowsocks.hpp` (RAII wrapper).\n\n### Event Loop\n\n`src/event/loop.hpp` wraps libuv (kqueue/epoll/IOCP) handles embedded by value in their owners;\n`src/event/program.hpp` is the per-process loop, signals and timers. Connections come from fixed pools sized by\n`--max-connections`, `--max-udp-sessions` and `--max-dns-queries`; a full TCP pool pauses accepting.\nNon-owning references (DNS answers, timers) are generation-checked handles. Each binary still defines its\nown `main()` and option parsing in `local.cpp`, `tunnel.cpp`, `redir.cpp`, `server.cpp`, `manager.cpp`.\n\n### Compiler Flags\n\nFrom `cmake/ProjectOptions.cmake`: `-Wall -Werror -Wno-deprecated-declarations -fno-strict-aliasing -fstack-protector-strong`, plus `_GNU_SOURCE` on Linux. C is C11 with GNU extensions. C++ is C++20 without extensions and adds `-Wextra -fno-exceptions -fno-rtti -fno-threadsafe-statics`.\n\n`-Werror` means all warnings are errors — new code must compile warning-free.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/shadowsocks/shadowsocks-libev/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nshadowsocks-c (formerly shadowsocks-libev) is a lightweight SOCKS5 proxy. Version 3.3.6, licensed under GPLv3.\nThe sources are C++20 (no exceptions, no RTTI, no heap allocation after startup; see `docs/cpp-core.md`).\nThe public `src/shadowsocks.h` stays a C header with a stable ABI.\n\n## Build Commands\n\n### CMake (sole build system)\n\n```bash\ncmake --preset bundled          # or: cmake -S . -B build -G Ninja\ncmake --build --preset bundled\nctest --preset bundled\n```\n\nBundled mode (the default, `SS_DEPENDENCY_MODE=bundled`) builds every dependency from the pinned archives in\n`third_party/dist` with no network access. `SS_DEPENDENCY_MODE=system` uses distro libraries instead.\nThere are no git submodules.\n\nBinaries land in `<build>/bin/`, libraries in `<build>/lib/`.\n\n### Build Dependencies\n\n- CMake >= 3.20, C11 and C++20 compilers (GCC >= 11, Clang >= 14, Apple Clang >= 15), Ninja for the presets\n- System mode only: Mbed TLS 2.x/3.x, libsodium >= 1.0.4, PCRE2 (8-bit), libuv, c-ares\n- Doxygen (documentation only)\n\n### CMake Options\n\n- `-DSS_MINIMAL=ON`: no regex, plugins or manager\n- `-DWITH_STATIC=OFF`: link third-party dependencies dynamically\n- `-DSS_BUILD_EXECUTABLES / SS_BUILD_STATIC_LIBRARY / SS_BUILD_SHARED_LIBRARY`: choose outputs\n- `-DWITH_DOC_MAN=ON` / `-DWITH_DOC_HTML=ON`: build documentation\n- `-DENABLE_CONNMARKTOS=ON`, `-DENABLE_NFTABLES=ON`: Linux netfilter features\n- `-DENABLE_SANITIZERS=ON`, `-DENABLE_COVERAGE=ON`, `-DDISABLE_SSP=ON`, `-DBUILD_TESTING=OFF`\n\n## Testing\n\n### Unit Tests (CTest)\n\n```bash\nctest --test-dir build -LE memcheck --output-on-failure\n```\n\nUnit tests compile the specific `src/*.cpp` files they need (see `ss_add_test` in `tests/CMakeLists.txt`).\nNew tests are C++ (`tests/test_*_cpp.cpp`, `tests/test_core_*.cpp`) using `tests/test_helpers.hpp`; older\nones are C (`tests/test_*.c`). Codec tests compare against the C oracle in `tests/reference/`. The\n`alloc_steady_*` tests fail on any heap allocation in steady state.\nLabels: `unit`, `vendor`, `integration`, `memcheck` (Linux + valgrind).\n\n### Integration Tests\n\n```bash\npython3 tests/interop.py --self --bin build/bin          # TCP/UDP relay, all AEAD/2022 methods\npython3 tests/tunnel_interop.py --bin build/bin          # ss-tunnel, every method\npython3 tests/test_manager.py --bin build/bin            # ss-manager (needs -DWITH_SS_MANAGER=ON on macOS)\npython3 tests/test.py --bin build/bin/ -c tests/aes-gcm.json   # one cipher via curl/dig (needs network)\npython3 tests/test_cli.py --bin-dir build/bin           # CLI contract: help/version/exit codes\npython3 tests/stress_test.py --bin build/bin/ --size 10\n```\n\n### Allocation audit\n\n```bash\npython3 tests/alloc_audit/measure_alloc.py --bin build/bin --shim build/lib/libss_alloc_audit.dylib\n```\n\nReports heap allocations per relayed connection (C baseline numbers are in `docs/cpp-core.md`).\n\n## Code Formatting\n\nUses **uncrustify** with the config at `.uncrustify.cfg`. Key settings: 4-space indent, no tabs, 120-column width, K&R brace style (braces on same line).\n\n## Code Quality Tooling\n\n- **clang-tidy**: config in `.clang-tidy`. The build exports `compile_commands.json` automatically. Run locally:\n  ```bash\n  run-clang-tidy -quiet -p build '/(src/(core/|event/|relay/|crypto/|api/)?[^/]+\\.(c|cpp)|tests/test_(core_[^/]+|[a-z0-9_]+_cpp)\\.cpp)$'\n  ```\n  On macOS with Homebrew LLVM, add `-extra-arg=\"-isysroot$(xcrun --show-sdk-path)\"`. CI (`clang-tidy` job in `tests.yml`) enforces a warning-count ratchet via `MAX_WARNINGS` — lower it when fixing findings; never raise it without justification.\n- **No-heap lint**: `scripts/check_no_heap.py --self-test` (also a ctest) rejects heap allocation in C++ sources under `src/`.\n- **Sanitizers**: `cmake .. -DENABLE_SANITIZERS=ON` builds with ASan + UBSan. CI runs ctest and the stress test under sanitizers on every PR.\n- **Coverage**: `cmake .. -DENABLE_COVERAGE=ON`, run tests, then `make coverage` (needs lcov). HTML report lands in `build/coverage-html/`. CI uploads it as the `coverage-html` artifact.\n\n## Architecture\n\n### Binaries (all in `src/`)\n\nEach binary is compiled with a module define that controls conditional compilation:\n\n| Binary | Define | Purpose |\n|---|---|---|\n| `ss-local` | `MODULE_LOCAL` | SOCKS5 client proxy |\n| `ss-server` | `MODULE_REMOTE` | Server-side proxy |\n| `ss-tunnel` | `MODULE_TUNNEL` | Port forwarding tunnel (implies `MODULE_LOCAL`) |\n| `ss-redir` | `MODULE_REDIR` | Transparent proxy via iptables (Linux only, implies `MODULE_LOCAL`) |\n| `ss-manager` | `MODULE_MANAGER` | Multi-server manager daemon (Linux only by default) |\n\nA library `libshadowsocks-c` (legacy names `libshadowsocks-libev.*` are kept) is built from the ss-local sources with `-DLIB_ONLY`. Its public API is in `src/shadowsocks.h`.\n\n### Source Organization (`src/`)\n\n**Shared by all binaries:**\n- `utils.cpp` - logging, system utilities, `ss_malloc`/`ss_free` (startup only), CLI help snippets\n- `jconf.cpp` / `json.cpp` - JSON config file parsing\n- `netutils.cpp` - network address utilities\n- `ppbloom.cpp` - ping-pong bloom filter for salt replay detection (`third_party/bloom`)\n\n**Relay engines** (`src/relay/`): `tcp.cpp` (one TCP engine for all four programs, `Kind` selects the\nhandshake), `udp.cpp` (UDP relay), `codec.cpp` (per-connection encoder/decoder variants), `resolver.cpp`\n(pooled c-ares queries), `socket.cpp` (upstream sockets, TFO). Each program's `main()` builds a config and\nruns them.\n\n**Crypto** (`src/crypto/`): value-type codecs `aead.cpp` (AES-GCM, ChaCha20-Poly1305), `aead2022.cpp`\n(Shadowsocks 2022, BLAKE3 from `src/blake3`), `keys.cpp`\n(key derivation, method tables). The old C implementation lives in `tests/reference/` as a test oracle.\n\n**ACL:** `acl.cpp` / `rule.cpp` / `ipset.cpp` - IP prefix sets and PCRE2/literal domain rules.\n\n**Plugins:** `plugin.cpp` / `process.cpp` - SIP003 plugin subprocess management.\n\n**C++ core:** `src/core/*.hpp` - ownership and allocation primitives (pools, handles, fixed buffers, arena,\nfixed hash map/LRU, intrusive list, bounded heap, `heap_guard` for third-party allocators).\n\n**Embedding API:** `src/shadowsocks.h` (unchanged C ABI), `src/shadowsocks/control.h`\n(`ss_local_start`/`stop`/`wait`/`destroy`) and `src/shadowsocks/shadowsocks.hpp` (RAII wrapper).\n\n### Event Loop\n\n`src/event/loop.hpp` wraps libuv (kqueue/epoll/IOCP) handles embedded by value in their owners;\n`src/event/program.hpp` is the per-process loop, signals and timers. Connections come from fixed pools sized by\n`--max-connections`, `--max-udp-sessions` and `--max-dns-queries`; a full TCP pool pauses accepting.\nNon-owning references (DNS answers, timers) are generation-checked handles. Each binary still defines its\nown `main()` and option parsing in `local.cpp`, `tunnel.cpp`, `redir.cpp`, `server.cpp`, `manager.cpp`.\n\n### Compiler Flags\n\nFrom `cmake/ProjectOptions.cmake`: `-Wall -Werror -Wno-deprecated-declarations -fno-strict-aliasing -fstack-protector-strong`, plus `_GNU_SOURCE` on Linux. C is C11 with GNU extensions. C++ is C++20 without extensions and adds `-Wextra -fno-exceptions -fno-rtti -fno-threadsafe-statics`.\n\n`-Werror` means all warnings are errors — new code must compile warning-free.\n","isInternal":false,"tokens":2040,"sizeBytes":7334}],"systemPromptSnippet":"<yakaai_skills repo=\"shadowsocks/shadowsocks-libev\">\n<!-- File: CLAUDE.md (Tokens: ~2040 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nshadowsocks-c (formerly shadowsocks-libev) is a lightweight SOCKS5 proxy. Version 3.3.6, licensed under GPLv3.\nThe sources are C++20 (no exceptions, no RTTI, no heap allocation after startup; see `docs/cpp-core.md`).\nThe public `src/shadowsocks.h` stays a C header with a stable ABI.\n\n## Build Commands\n\n### CMake (sole build system)\n\n```bash\ncmake --preset bundled          # or: cmake -S . -B build -G Ninja\ncmake --build --preset bundled\nctest --preset bundled\n```\n\nBundled mode (the default, `SS_DEPENDENCY_MODE=bundled`) builds every dependency from the pinned archives in\n`third_party/dist` with no network access. `SS_DEPENDENCY_MODE=system` uses distro libraries instead.\nThere are no git submodules.\n\nBinaries land in `<build>/bin/`, libraries in `<build>/lib/`.\n\n### Build Dependencies\n\n- CMake >= 3.20, C11 and C++20 compilers (GCC >= 11, Clang >= 14, Apple Clang >= 15), Ninja for the presets\n- System mode only: Mbed TLS 2.x/3.x, libsodium >= 1.0.4, PCRE2 (8-bit), libuv, c-ares\n- Doxygen (documentation only)\n\n### CMake Options\n\n- `-DSS_MINIMAL=ON`: no regex, plugins or manager\n- `-DWITH_STATIC=OFF`: link third-party dependencies dynamically\n- `-DSS_BUILD_EXECUTABLES / SS_BUILD_STATIC_LIBRARY / SS_BUILD_SHARED_LIBRARY`: choose outputs\n- `-DWITH_DOC_MAN=ON` / `-DWITH_DOC_HTML=ON`: build documentation\n- `-DENABLE_CONNMARKTOS=ON`, `-DENABLE_NFTABLES=ON`: Linux netfilter features\n- `-DENABLE_SANITIZERS=ON`, `-DENABLE_COVERAGE=ON`, `-DDISABLE_SSP=ON`, `-DBUILD_TESTING=OFF`\n\n## Testing\n\n### Unit Tests (CTest)\n\n```bash\nctest --test-dir build -LE memcheck --output-on-failure\n```\n\nUnit tests compile the specific `src/*.cpp` files they need (see `ss_add_test` in `tests/CMakeLists.txt`).\nNew tests are C++ (`tests/test_*_cpp.cpp`, `tests/test_core_*.cpp`) using `tests/test_helpers.hpp`; older\nones are C (`tests/test_*.c`). Codec tests compare against the C oracle in `tests/reference/`. The\n`alloc_steady_*` tests fail on any heap allocation in steady state.\nLabels: `unit`, `vendor`, `integration`, `memcheck` (Linux + valgrind).\n\n### Integration Tests\n\n```bash\npython3 tests/interop.py --self --bin build/bin          # TCP/UDP relay, all AEAD/2022 methods\npython3 tests/tunnel_interop.py --bin build/bin          # ss-tunnel, every method\npython3 tests/test_manager.py --bin build/bin            # ss-manager (needs -DWITH_SS_MANAGER=ON on macOS)\npython3 tests/test.py --bin build/bin/ -c tests/aes-gcm.json   # one cipher via curl/dig (needs network)\npython3 tests/test_cli.py --bin-dir build/bin           # CLI contract: help/version/exit codes\npython3 tests/stress_test.py --bin build/bin/ --size 10\n```\n\n### Allocation audit\n\n```bash\npython3 tests/alloc_audit/measure_alloc.py --bin build/bin --shim build/lib/libss_alloc_audit.dylib\n```\n\nReports heap allocations per relayed connection (C baseline numbers are in `docs/cpp-core.md`).\n\n## Code Formatting\n\nUses **uncrustify** with the config at `.uncrustify.cfg`. Key settings: 4-space indent, no tabs, 120-column width, K&R brace style (braces on same line).\n\n## Code Quality Tooling\n\n- **clang-tidy**: config in `.clang-tidy`. The build exports `compile_commands.json` automatically. Run locally:\n  ```bash\n  run-clang-tidy -quiet -p build '/(src/(core/|event/|relay/|crypto/|api/)?[^/]+\\.(c|cpp)|tests/test_(core_[^/]+|[a-z0-9_]+_cpp)\\.cpp)$'\n  ```\n  On macOS with Homebrew LLVM, add `-extra-arg=\"-isysroot$(xcrun --show-sdk-path)\"`. CI (`clang-tidy` job in `tests.yml`) enforces a warning-count ratchet via `MAX_WARNINGS` — lower it when fixing findings; never raise it without justification.\n- **No-heap lint**: `scripts/check_no_heap.py --self-test` (also a ctest) rejects heap allocation in C++ sources under `src/`.\n- **Sanitizers**: `cmake .. -DENABLE_SANITIZERS=ON` builds with ASan + UBSan. CI runs ctest and the stress test under sanitizers on every PR.\n- **Coverage**: `cmake .. -DENABLE_COVERAGE=ON`, run tests, then `make coverage` (needs lcov). HTML report lands in `build/coverage-html/`. CI uploads it as the `coverage-html` artifact.\n\n## Architecture\n\n### Binaries (all in `src/`)\n\nEach binary is compiled with a module define that controls conditional compilation:\n\n| Binary | Define | Purpose |\n|---|---|---|\n| `ss-local` | `MODULE_LOCAL` | SOCKS5 client proxy |\n| `ss-server` | `MODULE_REMOTE` | Server-side proxy |\n| `ss-tunnel` | `MODULE_TUNNEL` | Port forwarding tunnel (implies `MODULE_LOCAL`) |\n| `ss-redir` | `MODULE_REDIR` | Transparent proxy via iptables (Linux only, implies `MODULE_LOCAL`) |\n| `ss-manager` | `MODULE_MANAGER` | Multi-server manager daemon (Linux only by default) |\n\nA library `libshadowsocks-c` (legacy names `libshadowsocks-libev.*` are kept) is built from the ss-local sources with `-DLIB_ONLY`. Its public API is in `src/shadowsocks.h`.\n\n### Source Organization (`src/`)\n\n**Shared by all binaries:**\n- `utils.cpp` - logging, system utilities, `ss_malloc`/`ss_free` (startup only), CLI help snippets\n- `jconf.cpp` / `json.cpp` - JSON config file parsing\n- `netutils.cpp` - network address utilities\n- `ppbloom.cpp` - ping-pong bloom filter for salt replay detection (`third_party/bloom`)\n\n**Relay engines** (`src/relay/`): `tcp.cpp` (one TCP engine for all four programs, `Kind` selects the\nhandshake), `udp.cpp` (UDP relay), `codec.cpp` (per-connection encoder/decoder variants), `resolver.cpp`\n(pooled c-ares queries), `socket.cpp` (upstream sockets, TFO). Each program's `main()` builds a config and\nruns them.\n\n**Crypto** (`src/crypto/`): value-type codecs `aead.cpp` (AES-GCM, ChaCha20-Poly1305), `aead2022.cpp`\n(Shadowsocks 2022, BLAKE3 from `src/blake3`), `keys.cpp`\n(key derivation, method tables). The old C implementation lives in `tests/reference/` as a test oracle.\n\n**ACL:** `acl.cpp` / `rule.cpp` / `ipset.cpp` - IP prefix sets and PCRE2/literal domain rules.\n\n**Plugins:** `plugin.cpp` / `process.cpp` - SIP003 plugin subprocess management.\n\n**C++ core:** `src/core/*.hpp` - ownership and allocation primitives (pools, handles, fixed buffers, arena,\nfixed hash map/LRU, intrusive list, bounded heap, `heap_guard` for third-party allocators).\n\n**Embedding API:** `src/shadowsocks.h` (unchanged C ABI), `src/shadowsocks/control.h`\n(`ss_local_start`/`stop`/`wait`/`destroy`) and `src/shadowsocks/shadowsocks.hpp` (RAII wrapper).\n\n### Event Loop\n\n`src/event/loop.hpp` wraps libuv (kqueue/epoll/IOCP) handles embedded by value in their owners;\n`src/event/program.hpp` is the per-process loop, signals and timers. Connections come from fixed pools sized by\n`--max-connections`, `--max-udp-sessions` and `--max-dns-queries`; a full TCP pool pauses accepting.\nNon-owning references (DNS answers, timers) are generation-checked handles. Each binary still defines its\nown `main()` and option parsing in `local.cpp`, `tunnel.cpp`, `redir.cpp`, `server.cpp`, `manager.cpp`.\n\n### Compiler Flags\n\nFrom `cmake/ProjectOptions.cmake`: `-Wall -Werror -Wno-deprecated-declarations -fno-strict-aliasing -fstack-protector-strong`, plus `_GNU_SOURCE` on Linux. C is C11 with GNU extensions. C++ is C++20 without extensions and adds `-Wextra -fno-exceptions -fno-rtti -fno-threadsafe-statics`.\n\n`-Werror` means all warnings are errors — new code must compile warning-free.\n</yakaai_skills>"}