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).
• Human-readable text lives in string resources — English base + full values-ru parity (see architecture.md). Language-neutral tokens (IPs, ports, MTU, IPv6, example.com, protocol names — ProxyType.label/badge included) stay code literals. Russian developer comments are fine as they are; only user-visible text gets translated.

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.
10. Domain routing recovers domains via hev mapped-DNS (fake-IP); the DIRECT path must bypass it. When routedSites is non-empty, buildEngineConfig() enables a mapdns: block and the tun DNS is pointed at the synthetic resolver 198.18.0.2. The fake-IP pool is 198.19.0.0/16 — it clears the 198.18.0.1/32 tun address and is deliberately NOT in the isUnroutableRelay() CGNAT/private set (those fake IPs become domains before reaching any upstream, so that relay path is never involved). DirectDialer resolves on the underlying non-VPN network and protect()s the socket: resolving via the default resolver would return a fake IP and loop the "direct" flow back into the tun. The direct dialer also requires the underlying network to carry NET_CAPABILITY_INTERNET — a device can expose an IMS/MMTEL cellular network (NOT_VPN, but no INTERNET) that can't resolve, which silently broke every direct dial until filtered out (device-confirmed). Mapped-DNS is IPv4-only, so v6 is force-suppressed while sites are active — don't "restore" it. Keep the fake-IP cache sized to the whole pool (MAPDNS_CACHE_SIZE == ~netmask): the LRU evicts by the cache limit, not the pool, and an evicted-but-still-referenced fake IP reverse-maps to nothing and dead-ends.

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.