Alawn/shadowsocks-libev
1
0
Fork 0
mirror of https://github.com/shadowsocks/shadowsocks-libev.git synced 2026-10-31 22:45:45 +00:00
Code Releases Activity

Modernize C builds with offline dependencies and portable runtime helpers (#3050)

Browse Source 
Bundle pinned offline dependencies, remove libcork/libipset and submodule requirements, and add portable runtime helpers with relocatable static/shared library installations.

Add Clang static build validation for Linux/musl, macOS and Windows, real TCP/UDP and SIP003 interoperability coverage, and recorded performance tradeoffs. All 21 hosted checks pass at the reviewed PR head 8d504e6218.
This commit is contained in:
Max Lv
2026-09-11 13:42:11 +08:00
committed by GitHub
parent 8fe386b5c2
commit 201e70c4bd
120 changed files with 4631 additions and 1523 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/measurements/baseline-binaries-macos-arm64.json
+42
View File
@@ -0,0 +1,42 @@
{
"commit": "8fe386b5c270fc34d2bf53ef5ffb93d93242fac2",
"platform": "Darwin arm64",
"binaries": {
"ss-local": {
"bytes": 295912,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/opt/homebrew/opt/libev/lib/libev.4.dylib (compatibility version 5.0.0, current version 5.0.0)",
"\t/opt/homebrew/opt/c-ares/lib/libcares.2.dylib (compatibility version 2.0.0, current version 2.19.5)",
"\t/usr/lib/libpcre2-8.0.dylib (compatibility version 12.0.0, current version 12.2.0)",
"\t/opt/homebrew/opt/libsodium/lib/libsodium.26.dylib (compatibility version 31.0.0, current version 31.0.0)",
"\t/opt/homebrew/opt/mbedtls@3/lib/libmbedtls.21.dylib (compatibility version 21.0.0, current version 3.6.6)",
"\t/opt/homebrew/opt/mbedtls@3/lib/libmbedcrypto.16.dylib (compatibility version 16.0.0, current version 3.6.6)"
]
},
"ss-server": {
"bytes": 314360,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/opt/homebrew/opt/libev/lib/libev.4.dylib (compatibility version 5.0.0, current version 5.0.0)",
"\t/opt/homebrew/opt/c-ares/lib/libcares.2.dylib (compatibility version 2.0.0, current version 2.19.5)",
"\t/usr/lib/libpcre2-8.0.dylib (compatibility version 12.0.0, current version 12.2.0)",
"\t/opt/homebrew/opt/libsodium/lib/libsodium.26.dylib (compatibility version 31.0.0, current version 31.0.0)",
"\t/opt/homebrew/opt/mbedtls@3/lib/libmbedtls.21.dylib (compatibility version 21.0.0, current version 3.6.6)",
"\t/opt/homebrew/opt/mbedtls@3/lib/libmbedcrypto.16.dylib (compatibility version 16.0.0, current version 3.6.6)"
]
},
"ss-tunnel": {
"bytes": 268680,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/opt/homebrew/opt/libev/lib/libev.4.dylib (compatibility version 5.0.0, current version 5.0.0)",
"\t/opt/homebrew/opt/c-ares/lib/libcares.2.dylib (compatibility version 2.0.0, current version 2.19.5)",
"\t/usr/lib/libpcre2-8.0.dylib (compatibility version 12.0.0, current version 12.2.0)",
"\t/opt/homebrew/opt/libsodium/lib/libsodium.26.dylib (compatibility version 31.0.0, current version 31.0.0)",
"\t/opt/homebrew/opt/mbedtls@3/lib/libmbedtls.21.dylib (compatibility version 21.0.0, current version 3.6.6)",
"\t/opt/homebrew/opt/mbedtls@3/lib/libmbedcrypto.16.dylib (compatibility version 16.0.0, current version 3.6.6)"
]
}
}
}
docs/measurements/baseline-static-binaries-macos-arm64.json
+24
View File
@@ -0,0 +1,24 @@
{
"commit": "8fe386b5c270fc34d2bf53ef5ffb93d93242fac2",
"platform": "Darwin arm64",
"binaries": {
"ss-local": {
"bytes": 1326328,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)"
]
},
"ss-server": {
"bytes": 1500968,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)"
]
},
"ss-tunnel": {
"bytes": 828712,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)"
]
}
}
}
docs/measurements/baseline-stress-macos-arm64.json
+101
View File
@@ -0,0 +1,101 @@
[
{
"cipher": "aes-128-gcm",
"bandwidth_mbps": 7063.43292556653,
"duration_sec": 0.11876106262207031,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2656,
"server_rss_after_kb": 3472,
"tunnel_rss_before_kb": 2400,
"tunnel_rss_after_kb": 2576,
"error": null
},
{
"cipher": "aes-128-gcm",
"bandwidth_mbps": 7001.809356509003,
"duration_sec": 0.11980628967285156,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2704,
"server_rss_after_kb": 3504,
"tunnel_rss_before_kb": 2400,
"tunnel_rss_after_kb": 2576,
"error": null
},
{
"cipher": "aes-128-gcm",
"bandwidth_mbps": 6698.608105647417,
"duration_sec": 0.1252291202545166,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2688,
"server_rss_after_kb": 3488,
"tunnel_rss_before_kb": 2384,
"tunnel_rss_after_kb": 2560,
"error": null
},
{
"cipher": "aes-256-gcm",
"bandwidth_mbps": 7690.119291065227,
"duration_sec": 0.10908293724060059,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2704,
"server_rss_after_kb": 3472,
"tunnel_rss_before_kb": 2400,
"tunnel_rss_after_kb": 2576,
"error": null
},
{
"cipher": "aes-256-gcm",
"bandwidth_mbps": 7890.252575300613,
"duration_sec": 0.10631608963012695,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2672,
"server_rss_after_kb": 3488,
"tunnel_rss_before_kb": 2400,
"tunnel_rss_after_kb": 2576,
"error": null
},
{
"cipher": "aes-256-gcm",
"bandwidth_mbps": 7775.56902641376,
"duration_sec": 0.10788416862487793,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2704,
"server_rss_after_kb": 3520,
"tunnel_rss_before_kb": 2400,
"tunnel_rss_after_kb": 2576,
"error": null
},
{
"cipher": "chacha20-ietf-poly1305",
"bandwidth_mbps": 3438.7140620682108,
"duration_sec": 0.24394607543945312,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2656,
"server_rss_after_kb": 3552,
"tunnel_rss_before_kb": 2384,
"tunnel_rss_after_kb": 2592,
"error": null
},
{
"cipher": "chacha20-ietf-poly1305",
"bandwidth_mbps": 3471.04357984401,
"duration_sec": 0.24167394638061523,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2656,
"server_rss_after_kb": 3408,
"tunnel_rss_before_kb": 2368,
"tunnel_rss_after_kb": 2576,
"error": null
},
{
"cipher": "chacha20-ietf-poly1305",
"bandwidth_mbps": 3387.1740528144805,
"duration_sec": 0.24765801429748535,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2656,
"server_rss_after_kb": 3472,
"tunnel_rss_before_kb": 2384,
"tunnel_rss_after_kb": 2592,
"error": null
}
]
docs/measurements/baseline-udp-macos-arm64.json
+74
View File
@@ -0,0 +1,74 @@
[
{
"cipher": "aes-128-gcm",
"trial": 0,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.25436816699948395,
"payload_mbps": 75.4811430474276
},
{
"cipher": "aes-128-gcm",
"trial": 1,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.2318156250003085,
"payload_mbps": 82.8244429165396
},
{
"cipher": "aes-128-gcm",
"trial": 2,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.24796225000136474,
"payload_mbps": 77.43114123175735
},
{
"cipher": "aes-256-gcm",
"trial": 0,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.2386028750006517,
"payload_mbps": 80.46843526067134
},
{
"cipher": "aes-256-gcm",
"trial": 1,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.2360522500002844,
"payload_mbps": 81.33792412475148
},
{
"cipher": "aes-256-gcm",
"trial": 2,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.23466012499920907,
"payload_mbps": 81.82046268007704
},
{
"cipher": "chacha20-ietf-poly1305",
"trial": 0,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.24850704099844734,
"payload_mbps": 77.26139236481416
},
{
"cipher": "chacha20-ietf-poly1305",
"trial": 1,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.24412816600124643,
"payload_mbps": 78.64721352923273
},
{
"cipher": "chacha20-ietf-poly1305",
"trial": 2,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.24165658300080395,
"payload_mbps": 79.45159102053563
}
]
docs/measurements/bundled-binaries-macos-arm64.json
+27
View File
@@ -0,0 +1,27 @@
{
"commit": "46d3acd9d6b72e088b688c2f84aae5c0466885d8",
"platform": "Darwin arm64",
"binaries": {
"ss-local": {
"bytes": 756920,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)"
]
},
"ss-server": {
"bytes": 962632,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)"
]
},
"ss-tunnel": {
"bytes": 416440,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)"
]
}
}
}
docs/measurements/bundled-stress-macos-arm64.json
+101
View File
@@ -0,0 +1,101 @@
[
{
"cipher": "aes-128-gcm",
"bandwidth_mbps": 7860.532450008042,
"duration_sec": 0.10671806335449219,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2288,
"server_rss_after_kb": 3072,
"tunnel_rss_before_kb": 1872,
"tunnel_rss_after_kb": 2016,
"error": null
},
{
"cipher": "aes-128-gcm",
"bandwidth_mbps": 6582.251473027347,
"duration_sec": 0.1274428367614746,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2256,
"server_rss_after_kb": 3040,
"tunnel_rss_before_kb": 1872,
"tunnel_rss_after_kb": 2032,
"error": null
},
{
"cipher": "aes-128-gcm",
"bandwidth_mbps": 7002.575801490699,
"duration_sec": 0.11979317665100098,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2256,
"server_rss_after_kb": 3008,
"tunnel_rss_before_kb": 1872,
"tunnel_rss_after_kb": 2032,
"error": null
},
{
"cipher": "aes-256-gcm",
"bandwidth_mbps": 8336.501684349796,
"duration_sec": 0.10062503814697266,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2256,
"server_rss_after_kb": 2768,
"tunnel_rss_before_kb": 1872,
"tunnel_rss_after_kb": 2016,
"error": null
},
{
"cipher": "aes-256-gcm",
"bandwidth_mbps": 8556.573148352736,
"duration_sec": 0.0980370044708252,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2256,
"server_rss_after_kb": 2992,
"tunnel_rss_before_kb": 1872,
"tunnel_rss_after_kb": 2032,
"error": null
},
{
"cipher": "aes-256-gcm",
"bandwidth_mbps": 8498.291637500875,
"duration_sec": 0.0987093448638916,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2288,
"server_rss_after_kb": 3072,
"tunnel_rss_before_kb": 1872,
"tunnel_rss_after_kb": 2016,
"error": null
},
{
"cipher": "chacha20-ietf-poly1305",
"bandwidth_mbps": 3276.7750490181143,
"duration_sec": 0.25600194931030273,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2272,
"server_rss_after_kb": 3072,
"tunnel_rss_before_kb": 1856,
"tunnel_rss_after_kb": 2000,
"error": null
},
{
"cipher": "chacha20-ietf-poly1305",
"bandwidth_mbps": 3267.788061223197,
"duration_sec": 0.25670599937438965,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2272,
"server_rss_after_kb": 3072,
"tunnel_rss_before_kb": 1840,
"tunnel_rss_after_kb": 1984,
"error": null
},
{
"cipher": "chacha20-ietf-poly1305",
"bandwidth_mbps": 2988.673848516679,
"duration_sec": 0.28067994117736816,
"bytes_transferred": 104857600,
"server_rss_before_kb": 2272,
"server_rss_after_kb": 3040,
"tunnel_rss_before_kb": 1856,
"tunnel_rss_after_kb": 2032,
"error": null
}
]
docs/measurements/bundled-udp-macos-arm64.json
+74
View File
@@ -0,0 +1,74 @@
[
{
"cipher": "aes-128-gcm",
"trial": 0,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.25596854199829977,
"payload_mbps": 75.00921734408884
},
{
"cipher": "aes-128-gcm",
"trial": 1,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.25268954199964355,
"payload_mbps": 75.98256678160065
},
{
"cipher": "aes-128-gcm",
"trial": 2,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.2656113329994696,
"payload_mbps": 72.28607222131723
},
{
"cipher": "aes-256-gcm",
"trial": 0,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.31145487499998126,
"payload_mbps": 61.6461694491093
},
{
"cipher": "aes-256-gcm",
"trial": 1,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.30316929199943843,
"payload_mbps": 63.3309523974993
},
{
"cipher": "aes-256-gcm",
"trial": 2,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.281550084000628,
"payload_mbps": 68.1939061327262
},
{
"cipher": "chacha20-ietf-poly1305",
"trial": 0,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.29268420900007186,
"payload_mbps": 65.59971262404282
},
{
"cipher": "chacha20-ietf-poly1305",
"trial": 1,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.282807709001645,
"payload_mbps": 67.89065286720428
},
{
"cipher": "chacha20-ietf-poly1305",
"trial": 2,
"packets": 2000,
"payload_bytes": 1200,
"seconds": 0.25814837500001886,
"payload_mbps": 74.37583134117578
}
]
docs/measurements/minimal-binaries-macos-arm64.json
+27
View File
@@ -0,0 +1,27 @@
{
"commit": "46d3acd9d6b72e088b688c2f84aae5c0466885d8",
"platform": "Darwin arm64",
"binaries": {
"ss-local": {
"bytes": 416424,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)"
]
},
"ss-server": {
"bytes": 622024,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)"
]
},
"ss-tunnel": {
"bytes": 397704,
"dependencies": [
"\t/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)",
"\t/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)"
]
}
}
}
docs/modernization.md
+165
View File
@@ -0,0 +1,165 @@
# Self-contained C modernization
Status: complete for the agreed modernization scope. Native MSVC remains an
explicitly deferred milestone. Implementation branch: feature/self-contained-portable-c;
review: https://github.com/shadowsocks/shadowsocks-libev/pull/3050 (draft).
## Compatibility contract
Keep C11 and the existing CLI, JSON configuration, ss:// parsing, SIP003 plugins,
ACL blacklist/whitelist/outbound precedence, public shadowsocks.h API, legacy
stream ciphers, AEAD and SIP022 TCP/UDP behavior in the compatibility profile.
Removing regex or legacy ciphers is explicit opt-in, with configuration errors
for unavailable functionality. Linux redirection/netfilter remains Linux-only.
## Work and evidence
- [x] Baseline: fresh rebuild, unit/integration results, binary/dependency sizes,
TCP and UDP throughput, and memory measurements.
- [x] Required independent interoperability including TCP and UDP; missing peers
fail the required CI job and are reported as skips in optional local runs.
- [x] Target-scoped CMake, separate programs/static/shared library options,
reliable dependency discovery, installation/export metadata and presets.
- [x] Offline bundled dependency mode and source release archive; explicit system
mode for distro packages; checksums, licenses, versions, update procedure.
- [x] Remove libcork: address parsing, lists, hash maps, subprocess lifecycle.
- [x] Remove libipset: bounded IPv4/IPv6 prefix storage with insertion/deletion;
differential tests including holes inside larger networks.
- [x] Vendor the small bloom filter and remove all three submodule requirements.
- [x] Portability layer for sockets/errors, I/O, clocks, randomness and processes.
- [x] Runtime CI: Linux glibc/musl, macOS, FreeBSD, Windows MinGW.
- [x] Document MSVC/event-loop compatibility assessment as a later milestone.
- [x] Minimal profile: no regex/plugins/manager/legacy stream ciphers.
- [x] Crypto-only Mbed TLS configuration and evidence-backed provider assessment.
- [x] Complete sanitizers/static analysis, compatibility and stress validation,
release archive offline build, installed consumer, before/after report.
## Baseline provenance
Base commit: 8fe386b. Its libcork checkout is 074e074b, different from the
superproject gitlink; this was pre-existing local state. That checkout, libipset
and libbloom are preserved and ignored locally. Fresh baseline builds use those
same checkouts, with no modernization changes applied to baseline source.
The fresh baseline passes all 13 original unit tests.
## Build interface
Requires CMake 3.20+, a C11 compiler, and a build executor. Presets use Ninja;
manual configuration may use another generator.
```
cmake --preset system
cmake --build --preset system
ctest --preset system
```
Programs are in build-system/bin for either linkage mode. WITH_STATIC selects
static third-party dependencies; it does not promise a static libc or OS runtime.
SS_BUILD_EXECUTABLES, SS_BUILD_STATIC_LIBRARY and SS_BUILD_SHARED_LIBRARY control
outputs independently. Docs and platform shell tools are explicit opt-ins.
Bundled mode is the default and the `bundled` / `minimal` presets exercise it.
Maintainers stage the intended source files, then run
`scripts/source_archive.py build-artifacts/shadowsocks-libev.tar.gz`.
The archive includes tracked working-tree contents (so uncommitted changes are
included); record the final commit with a published release and use a clean
checkout for publishing. No submodules are accepted in the archive.
## Platform validation
Implementation validation at commit cdb192a passes the full platform matrix:
Linux glibc x86-64/ARM64 and macOS full/minimal builds, real TCP/UDP relay, SIP003
cleanup (full profile), and relocated installed consumers. FreeBSD 14.3 passes
compilation, unit/vendor tests, real TCP/UDP relay and installed consumers.
Native Windows UCRT64 passes all 31 unit/vendor tests, six-method TCP/UDP relay,
and installed static/shared consumers. Relay and consumer execution excludes
MSYS2/toolchain DLL directories from PATH; binaries require only Windows system
DLLs. Zig cross-builds also include both libraries and installed consumers.
Alpine/musl builds the release archive with networking and Python discovery
disabled and passes all unit/vendor and TCP/UDP tests. Linux Valgrind, ASan/UBSan,
coverage, required shadowsocks-rust interoperability, clang-tidy-18, and Debian
package construction pass. Evidence: [platform matrix](https://github.com/shadowsocks/shadowsocks-libev/actions/runs/34505389620),
[tests and analysis](https://github.com/shadowsocks/shadowsocks-libev/actions/runs/34505389548),
[system builds and packaging](https://github.com/shadowsocks/shadowsocks-libev/actions/runs/34505389561).
The same committed source archive also builds locally on Linux arm64 with
networking and Python discovery disabled, passing all 31 unit/vendor tests and
six-method TCP/UDP plus SIP003 tests. The source release itself needs no Git or
Python to compile. Executable-only installation omits library metadata, and a
minimal static-library-only build succeeds with the PCRE2 archive removed.
The final documentation commit is rechecked by the same CI matrix before delivery.
## Compatibility details
Address classification now uses inet_pton consistently with socket conversion;
malformed dotted addresses previously accepted by libcork but rejected by
inet_pton are no longer classified as IP literals. Full and suffix ACL rules
are explicit additions; normal regex remains available by default.
Legacy methods unavailable in Mbed TLS 3 (such as RC4) are not resurrected.
Crypto providers remain libsodium plus the reduced Mbed TLS primitive set:
AES-128/192-GCM, software AES fallback, MD5/SHA1 compatibility derivation, and
legacy AES/Camellia stream modes prevent a transparent libsodium-only switch.
See https://doc.libsodium.org/secret-key_cryptography/aead/aes-256-gcm and
https://shadowsocks.org/doc/sip022.html for the provider and protocol contracts.
## Local validation
- Fresh base-commit build (8fe386b) passes all 13 original unit tests, using the
preserved dependency checkouts described above. Both its system-shared and
static-dependency programs were rebuilt for size comparisons.
- macOS full bundled: 31 tests; minimal: 29 tests. System dependencies: 17 tests.
- ASan + UBSan: all 17 project tests and six-method TCP/UDP SIP003 tests pass.
- Clang-tidy: zero warnings/errors with Homebrew LLVM; project compiler warnings
remain errors. CI additionally uses its existing pinned clang-tidy-18 check.
- IP-set differential test: 1,028,000 comparisons against the original libipset,
including randomized full-width IPv4/IPv6 insertion/deletion and membership.
- Linux x86-64 musl: 31 unit/vendor tests and all six TCP/UDP relay cases pass
in containers with networking disabled. The preinstalled cross compiler
intermittently crashed under CPU emulation; incremental retries completed.
- Installed bundled static/shared consumers run after relocation. Installed
system-mode static/shared consumers also link and run. System static exports
require the exact Mbed TLS version used at build time to avoid an ABI mismatch.
- Windows x86-64: programs, both libraries, all tests and installed consumers
cross-compile with Zig. Native UCRT64 execution and installed consumers pass
with runtime DLL lookup restricted to the installation and Windows system paths.
- SIP003 fixture: real TCP forwarding, UDP bypass, and child cleanup pass through
the actual programs. DNS cancellation covers outstanding A/AAAA requests,
exactly-once callbacks/free callbacks and reinitialization after shutdown.
### MSVC assessment
MSVC is an explicitly deferred milestone, not a supported build today. MinGW-w64
supplies the POSIX compatibility headers/functions (`unistd.h`, `getopt`,
`ssize_t`, string helpers) used throughout the existing CLI. Native MSVC needs
those interfaces isolated, compiler-specific flags in the libsodium adapter,
libev/Win32 build verification and export/import validation. CMake now rejects
MSVC early with the supported UCRT64/Zig alternatives. Removing the event loop
or inventing replacement crypto implementations is outside this modernization.
### Crypto provider decision
Retain libsodium plus Mbed TLS crypto primitives. The bundled Mbed TLS config
omits TLS, X.509, certificate parsing and handshake machinery; it retains only
cipher/hash primitives needed by protocol compatibility. Libsodium alone cannot
replace AES-128-GCM, software AES fallback, MD5/SHA1 compatibility derivation and
legacy stream modes. PCRE2 is absent in the minimal profile. This removes three
submodule dependencies and reduces what is built without replacing audited
cryptographic algorithms with project-specific implementations.
See [measurements and tradeoffs](performance.md) for reproducible local results.
## Static build CI
The `static-macos` and `static-windows` jobs use Clang, bundled dependencies and
`SS_BUILD_SHARED_LIBRARY=OFF`. They run unit/vendor tests, relocate the installed
static library, build its consumer, and exercise the installed TCP/UDP programs.
The macOS job also exercises SIP003. `tests/check_static_runtime.py` rejects
non-system dylibs and DLLs (including Windows delay imports) in every installed
program and the static consumer. Windows runtime tests exclude toolchain DLL
paths. Windows uses the native [MSYS2 CLANG64 environment](https://www.msys2.org/docs/environments/).
macOS and Windows retain their OS libraries; static builds on these platforms
mean no separately distributed project, crypto, event-loop or toolchain shared
libraries. The `static-linux` job builds the Clang/musl Dockerfile, which also
links libc statically and rejects ELF interpreters and `NEEDED` entries. All
three jobs publish the tested installations as workflow artifacts.
docs/performance.md
+76
View File
@@ -0,0 +1,76 @@
# Modernization measurements
Local macOS arm64 results, 2026-09-10. Base commit: `8fe386b`; comparison:
`feature/self-contained-portable-c`. Raw JSON lives in [measurements](measurements/).
These are short loopback measurements on one machine, not capacity guarantees.
## Size and runtime dependencies
Unstripped Release executable sizes in bytes:
| Program | Old system-shared | Old static dependencies | Bundled | Minimal |
|---|---:|---:|---:|---:|
| ss-local | 295,912 | 1,326,328 | 756,920 | 416,424 |
| ss-server | 314,360 | 1,500,968 | 962,632 | 622,024 |
| ss-tunnel | 268,680 | 828,712 | 416,440 | 397,704 |
Bundled programs link only macOS OS libraries (`libSystem`, and where needed
`libresolv`). They need no separately installed libev, c-ares, PCRE2, libsodium
or Mbed TLS. Compared with the old static-dependency build, ss-server shrinks
about 36%; minimal shrinks about 59%. Compared with a shared-dependency binary
alone, bundling makes the executable larger; that comparison excludes the old
libraries' disk footprint. Bundled source archives add roughly 12 MB to checkout
and release size. There is no configure-time network access or submodule fetch.
## TCP and resident memory
Median of three 100 MiB transfers using `tests/stress_test.py`, old shared
dependencies versus bundled. Both sets pass all nine transfers.
| Cipher | Before Mbps | Bundled Mbps | Before server RSS after, KiB | Bundled server RSS after, KiB |
|---|---:|---:|---:|---:|
| AES-128-GCM | 7,002 | 7,003 | 3,488 | 3,040 |
| AES-256-GCM | 7,776 | 8,498 | 3,488 | 2,992 |
| ChaCha20-IETF-Poly1305 | 3,439 | 3,268 | 3,472 | 3,072 |
Bundled tunnel RSS after transfer was about 2,000–2,032 KiB versus
2,576–2,592 KiB before. RSS includes OS accounting and shared-page effects;
this is not a proof of bounded memory under arbitrary workloads. Transfer times
are short (roughly 0.1–0.3 s), so the apparent AES-256 improvement and ChaCha
regression need longer controlled measurements before drawing performance claims.
## UDP
Median of three runs, 2,000 sequential 1,200-byte echo packets per run through
SOCKS5 UDP ASSOCIATE. Every packet's payload and relay source port are checked.
| Cipher | Before payload Mbps | Bundled payload Mbps |
|---|---:|---:|
| AES-128-GCM | 77.43 | 75.01 |
| AES-256-GCM | 81.34 | 63.33 |
| ChaCha20-IETF-Poly1305 | 78.65 | 67.89 |
This round-trip benchmark includes Python thread creation, scheduling and SOCKS
overhead. It shows lower observed UDP rates in this run, up to 22%; modernization
is not claimed to improve UDP throughput. The portable libsodium backend is a
maintenance/performance tradeoff. Optimized backends require separate compiler
probes and cross-platform known-answer tests before adoption.
Independently of these timings, the new interoperability test exposed the old
MTU-sized receive buffer truncating 4 KiB UDP payloads. Full datagram reception
now passes 1, 128, 1,200 and 4,096-byte interoperability cases against
shadowsocks-rust in both directions.
## Reproduce
```sh
python3 tests/stress_test.py --bin build-bundled/bin --size 100 --repeat 3 --json tcp.json
python3 tests/measure_udp.py --bin build-bundled/bin --output udp.json
python3 tests/interop.py --bin build-bundled/bin
python3 tests/interop.py --self --bin build-bundled/bin --plugin tests/sip003_fixture.py
```
Run comparisons serially. The baseline was rebuilt from its own worktree using
the preserved original dependency checkouts; no modernization fixes were applied
to that source. The historical curl interop harness obeyed `no_proxy` and could
bypass SOCKS, so its old results are excluded from compatibility evidence.