{"owner":"shadowsocks","repo":"shadowsocks-libev","hasSkills":true,"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-libev is a lightweight SOCKS5 proxy written in pure C. Version 3.3.6, licensed under GPLv3.\n\n## Build Commands\n\n### CMake (sole build system)\n\n```bash\ngit submodule update --init --recursive\nmkdir -p build && cd build\ncmake ..\nmake\nsudo make install\n```\n\nOn macOS, CMake should auto-detect library paths. If needed, specify paths:\n```bash\ncmake .. -DCMAKE_PREFIX_PATH=\"/usr/local/opt/mbedtls;/usr/local/opt/libsodium\"\n```\n\nCMake outputs binaries to `build/bin/` (static) and `build/shared/bin/` (shared).\n\n### Build Dependencies\n\n- cmake (>= 3.2), a C compiler (gcc or clang), pkg-config\n- libmbedtls, libsodium (>= 1.0.4), libpcre3, libev, libc-ares\n- asciidoc + xmlto (documentation only)\n\n### CMake Options\n\n- `-DWITH_EMBEDDED_SRC=OFF`: use system libcork/libipset/libbloom instead of bundled submodules\n- `-DWITH_DOC_MAN=OFF`: skip man page generation\n- `-DENABLE_CONNMARKTOS=ON`: Linux netfilter conntrack QoS support\n- `-DENABLE_NFTABLES=ON`: nftables firewall integration\n- `-DDISABLE_SSP=ON`: disable stack protector\n- `-DBUILD_TESTING=OFF`: disable unit tests\n\n## Testing\n\n### Unit Tests (CTest)\n\n```bash\ncd build\nctest --output-on-failure\n```\n\n10 unit test modules cover: base64, buffer, crypto, json, jconf, cache, ppbloom, rule, netutils, utils.\n\n### Integration Tests\n\nIntegration tests use Python and require `curl` and `dig` to be available:\n```bash\nbash tests/test.sh\n```\n\nThe test harness (`tests/test.py`) starts ss-server, ss-local, and ss-tunnel locally, then runs curl through the SOCKS5 proxy and dig through the tunnel. Each test config in `tests/*.json` exercises a different cipher.\n\nRun a single cipher test:\n```bash\npython tests/test.py --bin build/bin/ -c tests/aes-gcm.json\n```\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` (clang-analyzer + bugprone + cert checks, scoped to `src/`). The build exports `compile_commands.json` automatically. Run locally:\n  ```bash\n  run-clang-tidy -quiet -p build '/src/[^/]+\\.c$'\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- **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 |\n\nA shared library `libshadowsocks-libev` is also 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.c` - logging, system utilities\n- `jconf.c` / `json.c` - JSON config file parsing\n- `netutils.c` - network address utilities\n- `cache.c` - hash-based LRU connection cache\n- `udprelay.c` - UDP relay implementation (shared, but uses `#ifdef MODULE_*` for per-binary behavior)\n\n**Crypto layer** (two parallel implementations behind a common `crypto_t` interface):\n- `crypto.c` / `crypto.h` - crypto initialization, key derivation (HKDF), buffer management. Defines `crypto_t` with function pointers for encrypt/decrypt.\n- `stream.c` - stream cipher implementation (CFB mode via mbedTLS)\n- `aead.c` - AEAD cipher implementation (AES-GCM via mbedTLS, ChaCha20-Poly1305 via libsodium)\n- `ppbloom.c` - ping-pong bloom filter for nonce replay detection\n\n**ACL (Access Control Lists):**\n- `acl.c` / `rule.c` - IP/domain-based routing rules using libipset\n\n**Plugin support:**\n- `plugin.c` - SIP003 plugin subprocess management\n\n### Bundled Submodules\n\nThree git submodules in the repo root (can be replaced with system libs via `-DWITH_EMBEDDED_SRC=OFF`):\n- `libcork/` - data structures (dllist, hash-table, buffers)\n- `libipset/` - IP set operations for ACL\n- `libbloom/` - bloom filter implementation\n\n### Event Loop\n\nAll binaries use **libev** for async I/O. The connection lifecycle follows stages defined in `src/common.h`: `STAGE_INIT` -> `STAGE_HANDSHAKE` -> `STAGE_RESOLVE` -> `STAGE_STREAM` -> `STAGE_STOP`. Each binary defines its own `listen_ctx_t`, `server_t`, and `remote_t` structs (note: \"server\" in `local.h` means the local-side connection, \"remote\" means the ss-server side).\n\n### Compiler Flags\n\nDefault flags from `CMakeLists.txt`: `-g -O2 -Wall -Werror -Wno-deprecated-declarations -fno-strict-aliasing -std=gnu99 -D_GNU_SOURCE`\n\nThe `-Werror` flag 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-libev is a lightweight SOCKS5 proxy written in pure C. Version 3.3.6, licensed under GPLv3.\n\n## Build Commands\n\n### CMake (sole build system)\n\n```bash\ngit submodule update --init --recursive\nmkdir -p build && cd build\ncmake ..\nmake\nsudo make install\n```\n\nOn macOS, CMake should auto-detect library paths. If needed, specify paths:\n```bash\ncmake .. -DCMAKE_PREFIX_PATH=\"/usr/local/opt/mbedtls;/usr/local/opt/libsodium\"\n```\n\nCMake outputs binaries to `build/bin/` (static) and `build/shared/bin/` (shared).\n\n### Build Dependencies\n\n- cmake (>= 3.2), a C compiler (gcc or clang), pkg-config\n- libmbedtls, libsodium (>= 1.0.4), libpcre3, libev, libc-ares\n- asciidoc + xmlto (documentation only)\n\n### CMake Options\n\n- `-DWITH_EMBEDDED_SRC=OFF`: use system libcork/libipset/libbloom instead of bundled submodules\n- `-DWITH_DOC_MAN=OFF`: skip man page generation\n- `-DENABLE_CONNMARKTOS=ON`: Linux netfilter conntrack QoS support\n- `-DENABLE_NFTABLES=ON`: nftables firewall integration\n- `-DDISABLE_SSP=ON`: disable stack protector\n- `-DBUILD_TESTING=OFF`: disable unit tests\n\n## Testing\n\n### Unit Tests (CTest)\n\n```bash\ncd build\nctest --output-on-failure\n```\n\n10 unit test modules cover: base64, buffer, crypto, json, jconf, cache, ppbloom, rule, netutils, utils.\n\n### Integration Tests\n\nIntegration tests use Python and require `curl` and `dig` to be available:\n```bash\nbash tests/test.sh\n```\n\nThe test harness (`tests/test.py`) starts ss-server, ss-local, and ss-tunnel locally, then runs curl through the SOCKS5 proxy and dig through the tunnel. Each test config in `tests/*.json` exercises a different cipher.\n\nRun a single cipher test:\n```bash\npython tests/test.py --bin build/bin/ -c tests/aes-gcm.json\n```\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` (clang-analyzer + bugprone + cert checks, scoped to `src/`). The build exports `compile_commands.json` automatically. Run locally:\n  ```bash\n  run-clang-tidy -quiet -p build '/src/[^/]+\\.c$'\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- **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 |\n\nA shared library `libshadowsocks-libev` is also 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.c` - logging, system utilities\n- `jconf.c` / `json.c` - JSON config file parsing\n- `netutils.c` - network address utilities\n- `cache.c` - hash-based LRU connection cache\n- `udprelay.c` - UDP relay implementation (shared, but uses `#ifdef MODULE_*` for per-binary behavior)\n\n**Crypto layer** (two parallel implementations behind a common `crypto_t` interface):\n- `crypto.c` / `crypto.h` - crypto initialization, key derivation (HKDF), buffer management. Defines `crypto_t` with function pointers for encrypt/decrypt.\n- `stream.c` - stream cipher implementation (CFB mode via mbedTLS)\n- `aead.c` - AEAD cipher implementation (AES-GCM via mbedTLS, ChaCha20-Poly1305 via libsodium)\n- `ppbloom.c` - ping-pong bloom filter for nonce replay detection\n\n**ACL (Access Control Lists):**\n- `acl.c` / `rule.c` - IP/domain-based routing rules using libipset\n\n**Plugin support:**\n- `plugin.c` - SIP003 plugin subprocess management\n\n### Bundled Submodules\n\nThree git submodules in the repo root (can be replaced with system libs via `-DWITH_EMBEDDED_SRC=OFF`):\n- `libcork/` - data structures (dllist, hash-table, buffers)\n- `libipset/` - IP set operations for ACL\n- `libbloom/` - bloom filter implementation\n\n### Event Loop\n\nAll binaries use **libev** for async I/O. The connection lifecycle follows stages defined in `src/common.h`: `STAGE_INIT` -> `STAGE_HANDSHAKE` -> `STAGE_RESOLVE` -> `STAGE_STREAM` -> `STAGE_STOP`. Each binary defines its own `listen_ctx_t`, `server_t`, and `remote_t` structs (note: \"server\" in `local.h` means the local-side connection, \"remote\" means the ss-server side).\n\n### Compiler Flags\n\nDefault flags from `CMakeLists.txt`: `-g -O2 -Wall -Werror -Wno-deprecated-declarations -fno-strict-aliasing -std=gnu99 -D_GNU_SOURCE`\n\nThe `-Werror` flag means all warnings are errors - new code must compile warning-free.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","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-libev is a lightweight SOCKS5 proxy written in pure C. Version 3.3.6, licensed under GPLv3.\n\n## Build Commands\n\n### CMake (sole build system)\n\n```bash\ngit submodule update --init --recursive\nmkdir -p build && cd build\ncmake ..\nmake\nsudo make install\n```\n\nOn macOS, CMake should auto-detect library paths. If needed, specify paths:\n```bash\ncmake .. -DCMAKE_PREFIX_PATH=\"/usr/local/opt/mbedtls;/usr/local/opt/libsodium\"\n```\n\nCMake outputs binaries to `build/bin/` (static) and `build/shared/bin/` (shared).\n\n### Build Dependencies\n\n- cmake (>= 3.2), a C compiler (gcc or clang), pkg-config\n- libmbedtls, libsodium (>= 1.0.4), libpcre3, libev, libc-ares\n- asciidoc + xmlto (documentation only)\n\n### CMake Options\n\n- `-DWITH_EMBEDDED_SRC=OFF`: use system libcork/libipset/libbloom instead of bundled submodules\n- `-DWITH_DOC_MAN=OFF`: skip man page generation\n- `-DENABLE_CONNMARKTOS=ON`: Linux netfilter conntrack QoS support\n- `-DENABLE_NFTABLES=ON`: nftables firewall integration\n- `-DDISABLE_SSP=ON`: disable stack protector\n- `-DBUILD_TESTING=OFF`: disable unit tests\n\n## Testing\n\n### Unit Tests (CTest)\n\n```bash\ncd build\nctest --output-on-failure\n```\n\n10 unit test modules cover: base64, buffer, crypto, json, jconf, cache, ppbloom, rule, netutils, utils.\n\n### Integration Tests\n\nIntegration tests use Python and require `curl` and `dig` to be available:\n```bash\nbash tests/test.sh\n```\n\nThe test harness (`tests/test.py`) starts ss-server, ss-local, and ss-tunnel locally, then runs curl through the SOCKS5 proxy and dig through the tunnel. Each test config in `tests/*.json` exercises a different cipher.\n\nRun a single cipher test:\n```bash\npython tests/test.py --bin build/bin/ -c tests/aes-gcm.json\n```\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` (clang-analyzer + bugprone + cert checks, scoped to `src/`). The build exports `compile_commands.json` automatically. Run locally:\n  ```bash\n  run-clang-tidy -quiet -p build '/src/[^/]+\\.c$'\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- **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 |\n\nA shared library `libshadowsocks-libev` is also 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.c` - logging, system utilities\n- `jconf.c` / `json.c` - JSON config file parsing\n- `netutils.c` - network address utilities\n- `cache.c` - hash-based LRU connection cache\n- `udprelay.c` - UDP relay implementation (shared, but uses `#ifdef MODULE_*` for per-binary behavior)\n\n**Crypto layer** (two parallel implementations behind a common `crypto_t` interface):\n- `crypto.c` / `crypto.h` - crypto initialization, key derivation (HKDF), buffer management. Defines `crypto_t` with function pointers for encrypt/decrypt.\n- `stream.c` - stream cipher implementation (CFB mode via mbedTLS)\n- `aead.c` - AEAD cipher implementation (AES-GCM via mbedTLS, ChaCha20-Poly1305 via libsodium)\n- `ppbloom.c` - ping-pong bloom filter for nonce replay detection\n\n**ACL (Access Control Lists):**\n- `acl.c` / `rule.c` - IP/domain-based routing rules using libipset\n\n**Plugin support:**\n- `plugin.c` - SIP003 plugin subprocess management\n\n### Bundled Submodules\n\nThree git submodules in the repo root (can be replaced with system libs via `-DWITH_EMBEDDED_SRC=OFF`):\n- `libcork/` - data structures (dllist, hash-table, buffers)\n- `libipset/` - IP set operations for ACL\n- `libbloom/` - bloom filter implementation\n\n### Event Loop\n\nAll binaries use **libev** for async I/O. The connection lifecycle follows stages defined in `src/common.h`: `STAGE_INIT` -> `STAGE_HANDSHAKE` -> `STAGE_RESOLVE` -> `STAGE_STREAM` -> `STAGE_STOP`. Each binary defines its own `listen_ctx_t`, `server_t`, and `remote_t` structs (note: \"server\" in `local.h` means the local-side connection, \"remote\" means the ss-server side).\n\n### Compiler Flags\n\nDefault flags from `CMakeLists.txt`: `-g -O2 -Wall -Werror -Wno-deprecated-declarations -fno-strict-aliasing -std=gnu99 -D_GNU_SOURCE`\n\nThe `-Werror` flag means all warnings are errors - new code must compile warning-free.\n","category":"root","tokens":1363}]}