heaven/proxy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
proxy/docs/architecture.md

11 KiB
Raw Blame History

Architecture

The data path

 routed app
   │  (only apps allowed by the per-app filter; see below)
   ▼
 VpnService tun           ProxyVpnService.establish()
   │  IPv4 198.18.0.1/32, route 0.0.0.0/0, DNS = dnsServerFor(settings)
   │  (IPv6 fc00::1/128 ULA + ::/0 ONLY when settings.ipv6 = true)
   ▼
 hev-socks5-tunnel        native engine, reads the tun fd over JNI (Tun2Socks / tun2socks.c)
   │  config built by ProxyVpnService.buildEngineConfig() (a small YAML blob)
   │  speaks SOCKS5 upstream only → points at our loopback server
   ▼
 LocalSocks5Server        127.0.0.1:<random port>, random per-session user/pass
   │  RFC 1928/1929; handles CONNECT (TCP) and UDP ASSOCIATE
   ▼
 Upstream client          Socks5Upstream | HttpUpstream | ShadowsocksUpstream
   │  socket is VpnService.protect()-ed → it exits the tunnel, no loop
   ▼
 real proxy server  →  internet

Why a local SOCKS5 server in the middle? hev-socks5-tunnel only speaks SOCKS5 to its upstream. To support HTTP(S) and Shadowsocks upstreams we run our own loopback SOCKS5 server that hev forwards into, and it translates to whatever the configured upstream speaks. This loopback-bridge pattern is standard for this engine. The bridge is gated with a random per-session username/password so a non-whitelisted local app can't hijack it.

Why the upstream socket is protect()-ed. Without protect(), the upstream connection would itself be captured by the tun and loop. protect() excludes that socket from the VPN. (Note: protect() returning false here is benign — our own app is already excluded by the app filter — so we log and continue, never throw. See conventions.md.)

Connect / restart / stop sequence

The VpnService is driven by three intent actions (ProxyVpnService.ACTION_START / ACTION_STOP / ACTION_RESTART; static helpers ProxyVpnService.start/stop/restart(context)):

  1. UI tap → MainActivity calls VpnService.prepare() (consent dialog, or null when the ACTIVATE_VPN appop is granted) → ProxyVpnService.start().
  2. onStartCommand(ACTION_START) promotes to foreground immediately (the 5 s FGS window starts here), then runs startTunnel() on a dedicated lifecycle thread.
  3. startTunnel() → establish() builds the tun → starts LocalSocks5Server → buildEngineConfig() → starts the native engine (generation counter + stuck-engine reaper) → fires the one-shot upstream probe.
  4. MainViewModel.reconnectIfRunning() sends ACTION_RESTART when the active server or the app filter changes while connected. ACTION_STOP tears down and stopSelf()s.

To touch lifecycle, start at onStartCommand / startTunnel / establish, not the 700-line file top.

Components

  • service/ProxyVpnService — the heart. Builds the tun (establish()), starts/stops the native engine with a generation counter + a stuck-engine reaper thread, runs a one-shot upstream connectivity probe after connect (journal flips to «Прокси подтверждён» or a classified error), watches network changes, owns the foreground notification.
  • service/VpnState — StateFlow holder for status, stats, and the journal (TunnelEvent list). The UI observes this; the service writes it.
  • core/socks/LocalSocks5Server — the loopback bridge. Accept loop on a control dispatcher, relay on a separate dispatcher, a both-directions idle watchdog, per-session auth.
  • core/upstream/* — Upstream is the interface (connectTcp, openUdpAssociation, protect). Three implementations. Socks5Upstream also does UDP ASSOCIATE with a BND.ADDR rewrite for broken servers (see conventions.md).
  • core/crypto/* — Shadowsocks AEAD (SIP004): ShadowsocksCrypto (EVP_BytesToKey master key, HKDF-SHA1 subkey, AES-GCM / ChaCha20-Poly1305 Aead), ShadowsocksStream (the TCP chunk framing + UDP packet framing). Implemented on platform JCA — no extra crypto dep.
  • core/ConfigImport — parses ss:// (SIP002 + legacy), socks5://, http(s):// share links into ProxyConfig.
  • data/ConfigStore — the only persistence. One DataStore Preferences entry state holding ProxyState JSON (configs + settings). Keeps a last-known-good backup and recovers from it rather than wiping on a decode failure.
  • ui/ — MainScreen hosts a 4-tab HorizontalPager: ConnectionScreen, ServersScreen, AppsScreen, SettingsScreen. MainViewModel bridges UI ↔ ConfigStore/VpnState.
  • native — tun2socks.c is the JNI bridge (start/stop, hands the tun fd + YAML config to hev). hev-socks5-tunnel/ is the vendored engine; its hev-mapped-dns.c fake-DNS facility is what makes domain routing possible and is enabled via a mapdns: config block (see Domain routing below).

Per-app routing (model for any future per-target filtering)

AppSettings.allowedApps: Set<String> drives ProxyVpnService.applyAppFilter():

  • non-empty → whitelist: builder.addAllowedApplication(pkg) for each (skipping our own package). If every selected package is uninstalled it throws rather than silently routing everything (that would violate the whitelist contract).
  • empty → route everything except our own app (addDisallowedApplication(self)).

This is an OS-level filter keyed by app UID. It is the model the "Apps" tab exposes. Note that anything keyed by destination (domain/IP) is NOT an OS feature and cannot reuse this — it has to be decided in the data path (the local SOCKS5 server sees the destination host). That is exactly how the "Сайты" tab works, below.

Domain routing ("Сайты" tab)

AppSettings.routedSites: Set<String> + routingMode: RoutingMode add a destination-keyed proxy-vs-direct split on top of the per-app filter — orthogonal layers: per-app decides which apps enter the tun; domain routing decides, within that traffic, where each destination goes.

The data path is IP-only by the time it reaches hev (the OS already resolved the domain), so domains are recovered with hev's mapped-DNS / fake-IP facility, enabled only when routedSites is non-empty:

  1. buildEngineConfig() emits a mapdns: block (synthetic resolver 198.18.0.2:53, fake-IP pool 198.19.0.0/16, cache-size 10000); establish() points the tun's DNS at 198.18.0.2.
  2. hev intercepts A-queries to that resolver, answers with a fake IP from the pool, and on the resulting TCP connection reverse-maps the fake IP back to the original domain, sending it upstream as a SOCKS5 domain CONNECT (hev-mapped-dns.c + misc/hev-utils.c).
  3. LocalSocks5Server now sees the real domain in dest.host; core/route/SiteRouter picks PROXY (the existing upstream path) or DIRECT (a protect()-ed socket dialed straight to the host on the underlying non-VPN network, via ProxyVpnService as DirectDialer) — both reuse the same half-close relay.

Entries are explicit suffix domains (example.com ⇒ it + all subdomains) or geosite categories (geosite:netflix). The full MIT v2fly geosite.dat (assets/geosite/, ~1500 categories, refresh via tools/fetch-geosite.sh) is parsed lazily by core/route/GeositeIndex (a small hand-rolled protobuf reader, no dependency) into a process-shared index used both by the Сайты search (live category/domain suggestions) and by SiteRouter at tunnel build. RoutingMode is the global default and the list is the exceptions: PROXY_ALL ⇒ listed go direct; DIRECT_ALL ⇒ listed go through the proxy.

Known limitation — DNS that bypasses the fake resolver isn't split. hev only diverts UDP whose destination is exactly the advertised resolver 198.18.0.2:53. An app that hardcodes its own resolver (e.g. 8.8.8.8), or uses DoH/DoT/QUIC, never hits the fake DNS, so its flows arrive as IP literals and take the global default. Under DIRECT_ALL that means a site the user added to go through the proxy can still exit direct if its app resolves on its own. Closing this would require hijacking all :53 (and ideally DoH) in the engine — a possible follow-up. (Also: synthesized answers carry TTL=1 and only A records; AAAA/HTTPS-SVCB get an empty answer, which is fine while v6 is suppressed but strips HTTP/3 hints.)

Known limitation — UDP is not domain-routed. Only handleConnect (TCP) consults the router; handleUdpAssociate always sends UDP through the proxy (and an HTTP(S) upstream, which has no UDP relay, drops it). So QUIC / HTTP-3 is proxied regardless of mode — under DIRECT_ALL a "direct" site's QUIC still traverses the proxy. TCP is the routed path; UDP direct-routing is a possible follow-up (it needs a protected per-destination UDP relay, mindful of the §3 anti-spoof invariant).

Mapped-DNS is IPv4-only, so while routedSites is non-empty the tun is forced IPv4-only (v6 suppressed regardless of settings.ipv6) to stop dual-stack apps bypassing the split over v6.

State & status

  • ProxyState = { configs: List<ProxyConfig>, settings: AppSettings }. activeConfig is settings.activeConfigId (or the first config).
  • The tunnel is built from a snapshot of the active config; live/green UI styling keys off the applied config id, not the merely-selected server.
  • Settings take effect only at establish() / buildEngineConfig() time. MainViewModel force-restarts a running tunnel (reconnectIfRunning() → ACTION_RESTART) when the active server, the app filter, or the site list / routing mode changes.

Status & journal

service/VpnState (a set of StateFlows) is the service↔UI contract. To surface a step in the UI, call VpnState.event(label, detail?, tone) — tone ∈ {NEUTRAL, OK, WARN, ERROR}. Events are a ring buffer (MAX_EVENTS = 30); ConnectionScreen renders them newest-first with auto-scroll. This is the only channel the service uses to report progress (connect steps, the probe verdict, errors) — use it rather than inventing a parallel one.

Localization (RU / EN)

Base language is English (res/values/strings.xml); the Russian override is res/values-ru/strings.xml, and resourceConfigurations += setOf("en", "ru") keeps other locales out of the APK (they fall back to English). The in-app switcher (Система / Русский / English) is LanguageSelector in ui/SettingsScreen.kt.

The per-app locale is applied without AppCompat — this app is Compose + ComponentActivity only and the tiny dependency surface is a hard constraint, so localization uses the classic framework-only pattern. core/LocaleManager persists the tag in its own small SharedPreferences and applies it as a Configuration override from attachBaseContext of every component that resolves strings: MainActivity, ProxyVpnService, ProxyTileService. Switching persists the tag and recreate()s the activity. On SYSTEM the process-default Locale is restored, so a once-picked UI language can't leak into date/number formatting elsewhere.

Language is deliberately not in AppSettings/DataStore. It is a presentation concern, it has to be read synchronously at attachBaseContext (before any coroutine or DataStore exists), and it must not run through reconnectIfRunning() the way a routing or app-filter change does.