feat(webrtc): raise browser listener limits, and ADR-0023 for hot reads and full-session refusal

[mickvandijke]

ADR-0023 covers what happens when thousands of browsers want the same chunks, for example everyone watching the same film, and what we change first. This PR also raises the browser listener's session limits.

Findings it records

• Every client reads a record from its nearest holder first. A hot record is served by one node while the other six in its close group sit idle.
• A node at its WebRTC Direct session limit ignores new browsers. The browser waits out a 10 s timeout, then blocks that node for 30 minutes. Busy nodes therefore disappear from clients' view exactly when demand peaks.
• For synchronised demand, upload bandwidth runs out before session slots do. 1,000 viewers of a 5 Mbit/s stream ask for about 5 Gbit/s of one chunk.

Decision

1. Clients spread first reads uniformly across the close group, then fall back to nearest-first.
2. A transport with no free slot answers a proven browser with a STUN error (486) instead of silence. This amends ADR-0015's rule of rejecting without an error response, for transport capacity refusals.
3. Browsers treat a dial the node declined as Refused, with a 15 s cooldown instead of 30 minutes.
4. This PR's code change: the listener defaults go from 32 to 256 sessions (the transport's ceiling), 32 to 512 channels, and 16 to 512 concurrent requests.
   • Channels and request slots are sized at two per session. On the testnet, browsers held 1.4 channels per session at the median and 1.9 at p90, so channel slots ran out before session slots. The old 32 channels filled at 18–23 sessions. At 192 browsers, 256 channels and 128 request slots both filled at 194 sessions.
   • The per-IP quota, the rate buckets and the in-flight byte budgets are unchanged, so frame and response memory stays bounded as before.

Each of the following needs its own ADR, and all are deferred:

• raising the transport's 256 ceiling;
• caching hot records on more nodes;
• batched or delegated lookups.

Implementation PRs

• feat(webrtc): refuse full listeners with a STUN error instead of silence saorsa-transport#183 (transport refusal)
• feat(read): spread hot-record reads across the close group, and back off briefly from nodes that decline ant-client#225 (read spreading, refusal handling)
• This PR: the new defaults. ant-node picks up the refusal when it bumps to a saorsa-transport release that contains it.

Linear issue

Closes V2-1508

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

Compatibility

• Wire: none
• Storage: none
• API: none
• Config: three default values change. A node whose --config file sets them keeps its values. The new defaults satisfy every startup invariant: per-IP sessions × channels per session = 8, which is below both 512 channels and 512 requests.

Semver impact

• breaking
• feature
• fix

Test evidence

• cargo test --lib -- web_rtc config: 108 passed. This includes the test that checks the default config satisfies the listener's invariants.
• cargo clippy --all-features --lib -- -D clippy::panic -D clippy::unwrap_used -D clippy::expect_used: clean. cargo fmt --check: clean.
• python3 scripts/adr-governance.py: passed (19 ADR files).
• Local real-browser run (7-node devnet, limits 2 sessions / 1 per IP): a full node turned the second browser away in 67 ms in Chromium and 54 ms in WebKit, against 10,011 ms and 10,005 ms on the unpatched transport. After the 15 s cooldown the browser connected again, where the baseline still blocked it.
• Dev testnet A/B (2026-10-13), recorded in the ADR's Validation section:
  • Setup: 60 nodes, 18 of them behind NAT. 64 headless-Chromium browsers, each on its own IP, all download the same 50 MiB file at once, over 18 rounds.
  • Today's limits: 61–66% of downloads completed, with today's client and with the new one alike. Every failure was a false "record not found".
  • New limits: 384 of 384 completed. Nodes peaked at 203 MiB and 1.2 cores, against 184 MiB and 1.25 cores before.
  • Scale test, 192 browsers at once:
    • 256 channels and 128 request slots: 762 of 768 completed, with about 2,300 channels closed per round.
    • 512 and 512: 768 of 768 completed, with no channel or request rejections, at 268 MiB and 1.3 cores peak per node.
  • Memory cost: about 0.5 MiB per session.
  • Follow-up found, ant-client: a read whose holders are all refusing reports "record not found" before their 15 s cooldown ends. With the new limits that only happened once channel or request slots filled.

New dependency

none

ADR

This PR adds ADR-0023 (Proposed).

Mitigation / rollback

Revert the commits, or have operators set max_connections, max_channels and max_concurrent_requests in [webrtc_direct] of their --config file to the old values.

🤖 Generated with Claude Code