proxy/docs/conventions.md

Conventions & load-bearing invariants

Code style

• Match the surrounding code: dense, explanatory comments that say why (the data path is full of non-obvious protocol/platform reasoning — keep that). Kotlin idioms, coroutines with explicit dispatchers, runCatching at boundaries.
• Keep platform glue thin and honest. Comments must not over-claim (a probe detects a bad Shadowsocks key but usually can't name it — say exactly that).
• No new dependencies without a strong reason — a deliberate property of this app is a tiny dependency surface (no crypto lib; AEAD is on platform JCA).

Commits

• No Co-Authored-By trailer. Keep each commit message ≤ 30 words.
• Split work into logical, per-subsystem commits.

Load-bearing invariants — DO NOT "fix" these without reading

Each of these looks like a bug or an easy cleanup and has already cost a regression. Verify against the code and the harness before touching.

1. protect() returning false is benign. Our own sockets are already excluded by the app filter, so protect() may return false with no harm. Log, don't throw. (Throwing here once broke every upstream connection.)
2. IPv6 is routed into the tun only when settings.ipv6. hev does not drop unconfigured- family packets — it forwards a v6 CONNECT to a v6-incapable proxy (rep=5), stalling Happy-Eyeballs apps. With v6 absent, Android adds ::/0 unreachable, so v6 is blackholed (no leak). dnsServerFor() coerces a v6-literal DNS to 1.1.1.1 while v6 is off — keep it.
3. SOCKS5 UDP socket is connect()-ed to the relay. RFC 1928 §7 anti-spoof = the kernel (IP, port) filter; that's also the ephemeral-port DNS-spoof defence. Do not replace it with a host-only userspace filter (weaker — drops the port check). Matches sing-box/canon.
4. isUnroutableRelay() rewrite is intentional and broader than canon. A SOCKS5 UDP ASSOCIATE BND.ADDR that is wildcard/loopback/private/CGNAT/ULA is rewritten to the proxy host. This fixes real servers (e.g. 3proxy returning 10.x) that would otherwise black-hole all UDP/DNS. Narrowing it to wildcard-only would reintroduce a device-confirmed bug.
5. Shadowsocks reader EOF semantics. EOF on a frame boundary = clean end of stream (return -1). EOF inside a frame = truncation = error. And a zero-length chunk is valid (canon emits/accepts empty keep-alive frames) — reject only > MAX_PAYLOAD.
6. The local SOCKS5 bridge requires random per-session auth. It's the boundary that stops a non-whitelisted local app from using the loopback proxy. Don't make it no-auth.
7. ChaCha20 cipher name is ChaCha20/Poly1305/NoPadding (Conscrypt registers the slash name since API 28; the hyphenated alias only exists on newer Mainline). Not a typo.
8. ConfigStore never wipes on a decode failure. It snapshots last-known-good before each write and recovers from it; only a genuine SerializationException/IllegalArgumentException counts as corruption (let Error/OOM propagate so a transient failure doesn't wipe servers).
9. MTU 8500 is the baseline (not a tuned value); the engine config and tun must agree.

The "no universal core" decision

Replacing the Kotlin backend (SS crypto + local SOCKS5 + upstream clients) with sing-box / sing-tun / mihomo / libbox was evaluated and rejected: those are GPLv3 (live enforcement) and would force open-sourcing this closed app, and any Go/Rust runtime breaks the small-APK goal. hev-socks5-tunnel is MIT and stays. The only defensible strategic swap is shadowsocks-rust (MIT) for the SS crypto surface only, and only if Kotlin-SS upkeep ever dominates — soak-test behind hev before deleting anything. Our SS crypto is verified correct against shadowsocks-rust and sing-shadowsocks.