ZapretKVN-android/docs/NETWORK_BOOTSTRAP.md
loop-uh 849b05a9d8 Docs: NETWORK_BOOTSTRAP, APP_UPDATER, RULESETS and the RUNTIME_LOG additions in English
Second batch of the English documentation set (owner decision 2026-11-08). Hashes, error codes
and commands are kept exactly. RUNTIME_LOG.md documents tunnel statistics and the stalled flow
reset.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 16:56:40 -05:00

26 lines
1.8 KiB
Markdown

# network-bootstrap
A narrow Android library module for the bootstrap that happens before the TUN is created. It owns only:
- choosing the current non-VPN network;
- reconciling `NetworkCapabilities` and `LinkProperties`;
- a short stabilization of the snapshot and retries when the network identity, the validation/Private DNS state or the list of DNS servers really changes;
- the system `DnsResolver` / `Network.getAllByName()`;
- stable support codes and a safe technical reason.
The module knows nothing about profiles, Compose, `libbox`, the VPN allowlist, runtime JSON or the LKG cache. Those decisions stay in `app`. It also does not decide what counts as a usable network: the wait accepts a predicate, because during a Wi-Fi ↔ cellular transition Android publishes a candidate long before it is good enough for bootstrap. The maturity criterion and the recovery policy live in `app`.
| Code | Meaning |
|---|---|
| `NET-101` | Android did not provide an underlying network |
| `NET-102` | The network changed during bootstrap and did not stabilize |
| `DNS-101` | DNS timeout |
| `DNS-102` | Name not found / NXDOMAIN |
| `DNS-103` | DNS refused / REFUSED |
| `DNS-104` | Successful answer without addresses |
| `DNS-105` | System error of the Android resolver (`DnsException`/errno) |
| `DNS-106` | Other DNS RCODE |
The codes `NET-110`, `DNS-110`, `VPN-1xx` and `VPN-2xx` belong to `app`: they describe the captive portal, strict Private DNS, the connection deadline and the checks on top of a ready TUN.
`NET-101` and `NET-102` no longer mean the end of the session: `app` treats them as transient and reconnects by itself in a bounded series of attempts. The other codes stay terminal. The text of an error may be refined, but the meaning of a published code does not change.