3.1 KiB
ADR-0009: Connection-Local NAT Candidate Experiment
- Status: accepted as an opt-in Browser experiment; default off
- Date: 2026-09-01
Context
The self-hosted deployment has two auxiliary STUN-only listeners for controlled NAT measurements. A disposable namespace lab showed that a sequential, endpoint-dependent mapping can sometimes be reached when the remote peer receives a small set of adjacent server-reflexive candidates. The result is network- and generation-specific; it is not a reliable NAT type or participant capability.
The existing route-policy and ICE candidate owners are sufficient. Making the experiment room-wide requires one strict protocol revision for the added policy field, but no new message type, route-controller state, or media path.
Decision
- Host Advanced settings exposes
NAT traversal experiment, disabled by default and locked while sharing. It is part of the current share's room policy and is broadcast to every authenticated Viewer; it is not persisted beyond that share generation. - When enabled, every Browser P2P connection adds ports 3479 and 3480 for the same STUN authority already supplied by the server. This covers Host direct, Viewer upstream, and Viewer relay connections. SFU PeerConnections remain unchanged.
- For one ICE gathering generation, the adapter observes only UDP
srflxcandidates. If three or more distinct candidates for one media section and public address form an arithmetic port sequence, it appends at most eight bounded candidates around the latest observation (four in each direction). Every ordinary candidate is retained; no ordinary candidate is rejected or replaced. A failed or inconclusive experiment uses the existing ICE and SFU fallback unchanged. - Candidate observations remain in memory for that connection only. No NAT label, raw address, port, score, hard candidate skip, periodic probe, or route-controller branch is introduced.
Consequences
Positive:
- operators can test the measured hole-punching mechanism without changing the default media path;
- normal ICE remains available, so an unsuccessful prediction cannot remove the existing direct or SFU fallback; and
- the experiment is bounded to one connection generation and one small candidate set.
Negative:
- the Browser may still reject synthetic candidates or the NAT may not have a matching mapping; and
- two endpoint-dependent NATs remain sensitive to candidate scheduling and intervening mappings, so room-wide coverage is not a success guarantee.
The controlled lab result (14/15 sequential-to-restricted runs with a bounded prediction set) is mechanism evidence, not a production success guarantee. Target-network prevalence, candidate direction, and long-run resource impact remain acceptance work.