Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

feat(nat): make NAT prediction deployment-configurable (#372)

AAA3583e9293892
diff --git a/.env.example b/.env.example
index 88ce17e8..0d907997 100644
--- a/.env.example
+++ b/.env.example
@@ -40,14 +40,15 @@ LIVEKIT_API_SECRET=
# Separate multiple URLs with commas.
STUN_URLS=
-# Optional independent STUN observations used only when a Host enables the
-# default-off NAT traversal experiment. Maximum two comma-separated URLs.
-NAT_PREDICTION_STUN_URLS=
+# Optional bounded NAT traversal support. When enabled, Hosts see a per-share
+# switch that defaults on, and Browser P2P derives self-hosted UDP 3479/3480
+# from the first STUN_URLS endpoint on UDP 3478.
+NAT_PREDICTION_ENABLED=false
# Minimal production example (use independent untracked secrets):
# SITE_ACCESS_PASSWORD=replace-with-an-independent-access-key
# STUN_URLS=stun:stun.example.com:3478
-# NAT_PREDICTION_STUN_URLS=stun:stun-observer.example.com:3478
+# NAT_PREDICTION_ENABLED=true
# Automatic SFU fallback (requires PEER_ASSISTED_MEDIA=true and does not
# replace STUN above):
# LIVEKIT_URL=wss://share.example.com
diff --git a/docs/README.md b/docs/README.md
index b80889c9..d7cc5717 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -45,8 +45,8 @@ ordinary implementation and UI detail.
owned media adaptation.
- [ADR-0008](./adr/0008-window-scoped-audio-capture.md): Browser/native window
audio boundary.
-- [ADR-0009](./adr/0009-connection-local-nat-prediction-experiment.md): opt-in
- connection-local NAT candidate experiment.
+- [ADR-0009](./adr/0009-optional-nat-prediction.md): optional connection-local
+ NAT prediction.
## Evidence
diff --git a/docs/adr/0009-connection-local-nat-prediction-experiment.md b/docs/adr/0009-connection-local-nat-prediction-experiment.md
deleted file mode 100644
index b1b65839..00000000
--- a/docs/adr/0009-connection-local-nat-prediction-experiment.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# 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. The current
-strict protocol carries the room policy, bounded independent observation URLs,
-and anonymous selected-path provenance, but adds no NAT label, route-controller
-state, or media path.
-
-## Decision
-
-1. 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.
-2. 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. A deployment may also provide at most two independent `stun:`
- observation URLs. They are added only inside the enabled experiment and are
- never part of ordinary room ICE.
-3. For one ICE gathering generation, the adapter observes only UDP `srflx`
- candidates whose Browser-reported STUN URL belongs to the self-hosted
- 3478/3479/3480 survey set. Independent observations remain ordinary ICE
- candidates and cannot enter the arithmetic sequence. If three or more
- distinct survey candidates for one media section and public address form an
- arithmetic port sequence, the adapter appends at most eight bounded
- candidates outward from both sequence endpoints: four above the high endpoint
- and four below the low endpoint. Every ordinary candidate keeps normal
- Trickle ICE timing; no ordinary candidate is delayed, rejected, or replaced.
- A Browser that does not expose candidate source URLs keeps ordinary ICE but
- does not mix independent observations into prediction.
-4. 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. Sanitized diagnostics record only
- whether a signaled candidate was ordinary, predicted, or end-of-candidates,
- and whether the selected remote foundation was ordinary, predicted, or
- unknown.
-
-## Consequences
-
-Positive:
-
-- operators can test the measured hole-punching mechanism without changing the
- default media path;
-- normal ICE remains immediately available, so an unavailable auxiliary STUN
- listener or unsuccessful prediction cannot delay the existing direct or SFU
- fallback; and
-- the experiment is bounded to one connection generation and one small
- candidate set; and
-- selected-foundation attribution can validate actual field benefit without
- uploading candidate endpoints.
-
-Negative:
-
-- the Browser may still reject synthetic candidates or the NAT may not have a
- matching mapping;
-- every independent STUN operator observes connection metadata and supplies no
- availability promise unless its own service contract says otherwise; 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.
-
-## Primary Sources
-
-- [RFC 8445: Interactive Connectivity Establishment](https://www.rfc-editor.org/rfc/rfc8445)
-- [RFC 4787: UDP NAT behavioral requirements](https://www.rfc-editor.org/rfc/rfc4787)
-- [RFC 5780: NAT Behavior Discovery Using STUN](https://www.rfc-editor.org/rfc/rfc5780)
-- [W3C WebRTC candidate model](https://www.w3.org/TR/webrtc/)
diff --git a/docs/adr/0009-optional-nat-prediction.md b/docs/adr/0009-optional-nat-prediction.md
new file mode 100644
index 00000000..61d49152
--- /dev/null
+++ b/docs/adr/0009-optional-nat-prediction.md
@@ -0,0 +1,86 @@
+# ADR-0009: Optional Connection-Local NAT Prediction
+
+- Status: accepted as an optional deployment capability
+- Date: 2026-09-02
+
+## 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 deployment configuration, route policy, and ICE candidate owners
+are sufficient. The mechanism needs no NAT label, route-controller state, new
+media path, or third-party STUN dependency.
+
+## Decision
+
+1. `NAT_PREDICTION_ENABLED` defaults to `false`. A disabled deployment does not
+ expose the Host control and the server rejects NAT prediction in the room
+ policy. An enabled deployment exposes `NAT traversal`; the pre-share switch
+ defaults on, remains Host-controllable, locks while sharing, and is not
+ persisted beyond that share generation.
+2. An enabled deployment derives ports 3479 and 3480 from the first ordinary
+ STUN authority on UDP 3478. When the share switch is on, every Browser P2P
+ connection adds those same-host endpoints. This covers Host direct, Viewer
+ upstream, and Viewer relay connections. SFU PeerConnections remain
+ unchanged. No independent or third-party STUN endpoint is added.
+3. For one ICE gathering generation, the adapter observes only UDP `srflx`
+ candidates whose Browser-reported STUN URL belongs to the self-hosted
+ 3478/3479/3480 survey set. If three or more distinct survey candidates for
+ one media section and public address form an arithmetic port sequence, the
+ adapter appends at most eight bounded candidates outward from both sequence
+ endpoints: four above the high endpoint and four below the low endpoint.
+ Every ordinary candidate keeps normal Trickle ICE timing; no ordinary
+ candidate is delayed, rejected, or replaced. A Browser that does not expose
+ candidate source URLs keeps ordinary ICE without prediction. Rejection of a
+ predicted remote candidate discards only that optional candidate; ordinary
+ candidate errors retain their normal connection error semantics.
+4. 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. Sanitized diagnostics record only
+ whether a signaled candidate was ordinary, predicted, or end-of-candidates,
+ and whether the selected remote foundation was ordinary, predicted, or
+ unknown.
+
+## Consequences
+
+Positive:
+
+- deployments that operate the required STUN listeners can offer the bounded
+ mechanism while smaller deployments retain stock ICE;
+- normal ICE remains immediately available, so an unavailable auxiliary STUN
+ listener or unsuccessful prediction cannot delay direct or SFU fallback;
+- prediction is bounded to one connection generation and one small candidate
+ set; and
+- selected-foundation attribution can validate actual field benefit without
+ uploading candidate endpoints.
+
+Negative:
+
+- the Browser may still reject synthetic candidates or the NAT may not have a
+ matching mapping;
+- enabled P2P connections perform two extra self-hosted STUN transactions and
+ may add connectivity checks for up to eight adjacent UDP ports; and
+- two endpoint-dependent NATs remain sensitive to candidate scheduling and
+ intervening mappings, so room-wide coverage is not a success guarantee.
+
+Predicted connectivity checks originate from participant Browsers and target
+the other participant's bounded candidate window. The Screener server only
+receives Binding requests on its fixed 3478/3479/3480 listeners; enabling this
+capability does not make the cloud host scan external ports.
+
+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.
+
+## Primary Sources
+
+- [RFC 8445: Interactive Connectivity Establishment](https://www.rfc-editor.org/rfc/rfc8445)
+- [RFC 4787: UDP NAT behavioral requirements](https://www.rfc-editor.org/rfc/rfc4787)
+- [RFC 5780: NAT Behavior Discovery Using STUN](https://www.rfc-editor.org/rfc/rfc5780)
+- [W3C WebRTC candidate model](https://www.w3.org/TR/webrtc/)
diff --git a/docs/operations/self-hosting.md b/docs/operations/self-hosting.md
index 30c9a148..78113982 100644
--- a/docs/operations/self-hosting.md
+++ b/docs/operations/self-hosting.md
@@ -73,10 +73,10 @@ Coturn runs `stun-only`, `no-tcp`, and `no-tls`. It must answer STUN binding and
reject TURN allocation. Avoid verbose STUN/ICE logging because infrastructure
necessarily observes client IP addresses.
-## Optional NAT Prediction Experiment
+## Optional NAT Prediction
-Rooms can use the default-off NAT prediction experiment only while both
-auxiliary STUN-only listeners are reachable. Add the following to the
+Set `NAT_PREDICTION_ENABLED=true` only while both auxiliary STUN-only listeners
+are reachable. Add the following to the
service-owned coturn configuration, using the local address already bound by
the main listener:
@@ -91,21 +91,14 @@ the complete ruleset with `nft -c -f /etc/nftables.conf`, then restart only
`coturn.service`. Verify `ss -lunp` shows all three UDP listeners and that an
ordinary STUN Binding succeeds on each. Do not add these URLs to production
`STUN_URLS`; enabled Browser connections derive them from the ordinary STUN
-authority. Keep both listeners and firewall rules for as long as the room
-experiment is offered. Disable the experiment before removing both
+authority. Keep both listeners and firewall rules for as long as the capability
+is enabled. Set `NAT_PREDICTION_ENABLED=false` before removing both
`aux-server` lines and both firewall rules, validate again, and restart coturn.
These same-IP auxiliary ports measure destination-port mapping behavior. They
are not a full RFC 5780 alternate-address deployment; that requires a second
public IPv4.
-An operator may configure at most two independent observation URLs through
-`NAT_PREDICTION_STUN_URLS`. They are contacted only by Browser P2P connections
-in an opted-in room, remain ordinary ICE candidates, and require no local
-listener or firewall change. Verify them with a real Browser from the target
-network before use. DNS resolution alone is not a STUN availability check, and
-an unaffiliated public endpoint has no implied SLA.
-
## Operational Verification
- `/healthz` returns `{"status":"ok"}` locally and through the public origin.
diff --git a/docs/product/routing-transport.md b/docs/product/routing-transport.md
index bc5b8881..8eb34c2a 100644
--- a/docs/product/routing-transport.md
+++ b/docs/product/routing-transport.md
@@ -32,13 +32,14 @@ share generation:
- native-edge topology convergence is enabled by default. The Host may disable
it before sharing; when disabled, quality evidence stays diagnostic and
availability routing is unchanged;
-- the default-off NAT traversal experiment augments direct ICE candidates on
- every Browser P2P edge in that share. It is not a participant capability,
- route score, or SFU preference. A deployment may add a bounded independent
- STUN observation list only inside that experiment. Candidate generation and
- selected-pair diagnostics retain only `ordinary | predicted | unknown`
- provenance. [ADR-0009](../adr/0009-connection-local-nat-prediction-experiment.md)
- owns the bounded behavior and evidence boundary.
+- NAT traversal is absent unless the deployment enables its self-hosted
+ auxiliary STUN capability. When available, its Host switch defaults on and
+ augments every Browser P2P edge in that share; the Host may disable it before
+ sharing. It is not a participant capability, route score, or SFU preference.
+ Candidate generation and selected-pair diagnostics retain only
+ `ordinary | predicted | unknown` provenance.
+ [ADR-0009](../adr/0009-optional-nat-prediction.md) owns the bounded behavior
+ and evidence boundary.
These are route-policy gates, not new routing algorithms. Changing any
policy requires stopping the current share and starting another generation.
diff --git a/docs/project-memory.md b/docs/project-memory.md
index fd22dd26..e7493337 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -1,6 +1,6 @@
# Project Memory
-Last updated: 2026-09-01
+Last updated: 2026-09-02
Screener is private, low-latency game screen sharing for one Host and up to 20
authenticated friends. The current product surface is Web Host, Web Viewer, and
@@ -30,11 +30,11 @@ implementation and routine UI detail.
lease. Production enables optional SQLite stable room authority; live
participants, routes, and media remain process-only.
- Media is automatic and distributed. Ordinary peers are STUN-only and prefer
- direct/peer UDP. Host may opt the current share into a bounded, room-wide,
- connection-local NAT candidate experiment; a deployment may add two
- independent observation STUN URLs only inside that experiment, and anonymous
- provenance distinguishes ordinary from predicted selected paths. The default
- path remains stock ICE. The only application fallback is one bounded LiveKit SFU/UDP
+ direct/peer UDP. A deployment may enable same-host auxiliary STUN for bounded,
+ room-wide, connection-local NAT prediction; its Host switch defaults on when
+ available, and anonymous provenance distinguishes ordinary from predicted
+ selected paths. The configuration default remains stock ICE. The only
+ application fallback is one bounded LiveKit SFU/UDP
publication; Screener configures no TURN or TCP media route. A pre-share
peer-only policy can exclude that SFU suffix for one share generation.
- Every endpoint shares one steady outbound-copy cap, default `2` and limited to
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 875fd4ec..8e83b2d5 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -20,7 +20,7 @@ service secret store or an untracked access-restricted environment file.
| `PEER_ASSISTED_MEDIA` | Enables the all-room bounded Peer/SFU controller. |
| `ENDPOINT_MEDIA_COPY_CAPACITY` | Shared endpoint steady-copy cap `1..3`, default `2`. |
| `STUN_URLS` | Comma-separated `stun:` URLs; at least one is required in production. |
-| `NAT_PREDICTION_STUN_URLS` | Optional comma-separated independent `stun:` observations, maximum `2`; used only by rooms that enable the default-off NAT experiment. |
+| `NAT_PREDICTION_ENABLED` | Optional bounded NAT prediction capability, default `false`; requires an ordinary `STUN_URLS` endpoint on UDP 3478 plus reachable same-host UDP 3479/3480 listeners. |
Automatic SFU fallback is enabled only when `PEER_ASSISTED_MEDIA=true` and all
four values below are present:
@@ -51,7 +51,7 @@ Peer IDs, SDP, ICE candidates, tokens or media credentials.
| ---: | --- | --- |
| TCP 80/443 | public | HTTP redirect and HTTPS/WSS reverse proxy |
| UDP 3478 | public | STUN-only coturn |
-| UDP 3479/3480 | public while the optional NAT experiment is offered | auxiliary STUN-only coturn listeners |
+| UDP 3479/3480 | public when NAT prediction is enabled | auxiliary STUN-only coturn listeners |
| UDP 7882 | public when SFU enabled | LiveKit WebRTC media |
| TCP 8787 | private | Screener application |
| TCP 7880 | private when SFU enabled | LiveKit signaling/control |
@@ -60,20 +60,16 @@ TCP 3478, TCP/TLS 5349, TURN relay ranges, LiveKit media TCP, and other media
ports remain closed. HTTPS/WSS transport is independent of the UDP-only media
contract.
-The default-off NAT experiment derives `stun:<same-hostname>:3479` and `:3480`
-from the ordinary STUN authority for enabled Browser P2P connections. It does
-not change `STUN_URLS` or add a media route, and it needs both cloud
-security-group rules and the host's `/etc/nftables.conf` rule. Coturn must bind
-the auxiliary listeners to the host's local address with `aux-server`; opening
-a cloud port without a listener has no effect. No new DNS record is required.
-Keep both listeners available while the experiment is offered and remove them
-only after disabling it. Same-IP ports expose destination-port allocation
-behavior; a full RFC 5780 alternate-address test requires a second public IPv4.
-Optional `NAT_PREDICTION_STUN_URLS` add independent ordinary candidates without
-changing `STUN_URLS`. Their operators receive client address, port, time, and
-protocol metadata when the Host enables the experiment. They need no inbound
-server port or DNS change, but should be omitted when that dependency is not
-accepted.
+When `NAT_PREDICTION_ENABLED=true`, the server derives
+`stun:<same-hostname>:3479` and `:3480` from the first ordinary STUN authority
+on UDP 3478. The Host sees a pre-share switch that defaults on and may disable
+it. The capability adds no media route or third-party service. It needs both
+cloud security-group rules and the host's `/etc/nftables.conf` rule; coturn must
+bind both auxiliary listeners with `aux-server`. Opening a cloud port without a
+listener has no effect, and no new DNS record is required. Disable the
+capability before removing either listener or firewall rule. Same-IP ports
+expose destination-port allocation behavior; a full RFC 5780 alternate-address
+test requires a second public IPv4.
## Bounds
diff --git a/docs/research/nat-traversal.md b/docs/research/nat-traversal.md
index 8d6f2021..9d049b57 100644
--- a/docs/research/nat-traversal.md
+++ b/docs/research/nat-traversal.md
@@ -1,6 +1,6 @@
# Browser NAT Traversal
-Last reviewed: 2026-09-01
+Last reviewed: 2026-09-02
This document owns evidence for improving direct Browser ICE without adding a
new relay or a custom transport. The current product contract remains standard
@@ -56,20 +56,20 @@ supports an opt-in mechanism, not a default or a participant-wide classifier.
## Current Decision
-The flagship STUN configuration remains unchanged. The self-hosted endpoint is
-still the ordinary discovery service; ports 3479 and 3480 are optional
-STUN-only listeners for an explicitly enabled room experiment.
+The ordinary self-hosted endpoint remains the discovery service. NAT prediction
+is absent by default; a deployment may enable same-host STUN-only listeners on
+3479 and 3480. Enabled deployments expose a per-share Host switch that defaults
+on and remains locked while sharing.
-The accepted experiment is deliberately connection-local and additive. It
+The accepted adapter is deliberately connection-local and additive. It
derives the two auxiliary ports from the existing STUN authority, waits for a
clear three-point arithmetic `srflx` shape in one ICE generation, and appends a
small two-sided candidate window from the observed port-sequence endpoint.
Ordinary candidates trickle immediately, so unavailable auxiliary listeners
cannot hold back stock ICE. There is no NAT label, hard candidate skip,
-route-controller input, or SFU preference. The Host switch is default off,
-locks while sharing, and applies to Host, Viewer upstream, and Viewer relay P2P
-connections. Its exact scope is recorded in
-[ADR-0009](../adr/0009-connection-local-nat-prediction-experiment.md).
+route-controller input, or SFU preference. The switch applies to Host, Viewer
+upstream, and Viewer relay P2P connections. Its exact scope is recorded in
+[ADR-0009](../adr/0009-optional-nat-prediction.md).
### Independent Observation And Attribution Preflight
@@ -77,9 +77,9 @@ On 2026-09-01, Chrome 151 on the flagship Windows network gathered one `srflx`
candidate independently from the self-hosted endpoint, Xiaomi, Bilibili, and
Cloudflare within a five-second bound. `stun.qq.com:3478` produced none in the
same ordered run. Candidate events and local candidate stats preserved the exact
-STUN `url`, so independent destinations can remain ordinary candidates while
-only self-hosted 3478/3479/3480 observations feed prediction. These are measured
-reachability results, not third-party availability commitments.
+STUN `url`, but the destinations supplied no selected-path benefit. They remain
+research evidence only; the product has no independent or third-party STUN
+configuration.
A second real-Chrome loopback rewrote only one remote candidate foundation to
`sp1`, established the data channel, and read `sp1` from the selected remote
@@ -88,6 +88,21 @@ unknown` selection without retaining or uploading addresses, ports, foundations,
or STUN URLs. Field acceptance still requires target-network outcomes; this
preflight proves the attribution mechanism, not prediction prevalence.
+The first flagship field runs emitted six predicted candidates in one 8545
+generation and selected none. Later 8545 and 5643 generations did not form the
+required arithmetic survey shape, so no prediction was emitted. This is
+negative prevalence evidence, not a regression: ordinary ICE and SFU fallback
+remained independent. The flagship deployment enables the bounded capability
+to continue attributable field observation without claiming a demonstrated
+reachability gain.
+
+After an SFU commit, the current route controller gives each deferred Peer
+parent one full direct-convergence attempt and then consumes that continuation.
+Further generations come from a new participant session, publication, or share,
+not a periodic retry loop. This bounds current field exposure. A fixed repeat
+budget remains unjustified until attributable runs show that fresh generations
+repeatedly recover a usable arithmetic shape.
+
The Browser-only alternatives do not yet have an accepted implementation:
- WebRTC ICE already exchanges observed candidates and performs coordinated
@@ -120,11 +135,11 @@ but cannot produce the proposed `eim | edm-sequential | edm-random` participant
fact. They cannot safely remove a Peer candidate or alter route ordering and
deadlines.
-Port prediction remains an experiment rather than a default path. The
-controlled namespace matrix supports the bounded mechanism, but field
-prevalence, direction, and resource impact are not established. The experiment
-therefore stays opt-in and additive until target-network evidence justifies
-enabling it by default.
+Port prediction remains additive rather than an assumed path. The controlled
+namespace matrix supports the bounded mechanism, but field prevalence,
+direction, and resource impact are not established. Configuration therefore
+stays off by default even though the flagship deployment explicitly enables its
+field rollout.
## Rejected Product Inference
diff --git a/docs/status.md b/docs/status.md
index d45011bb..bd183599 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -1,6 +1,6 @@
# Current Status
-Last updated: 2026-09-01
+Last updated: 2026-09-02
This is the current execution index. Git history owns completed timelines;
[verification status](./verification-status.md) owns evidence boundaries.
@@ -23,11 +23,12 @@ This is the current execution index. Git history owns completed timelines;
- Site access uses a stateless 24-hour rolling idle cookie. An active
site-authorized page renews it hourly through the existing status request;
Viewer-grant admission remains independent and cannot create or renew it.
-- Public media listeners remain STUN-only UDP 3478 and LiveKit UDP 7882. The
- optional NAT experiment also uses auxiliary STUN-only UDP 3479 and 3480;
- ordinary `STUN_URLS` and media routes remain unchanged. Web ingress
- is TCP 80/443; Node 8787 and LiveKit control/signaling 7880 are private. TURN,
- ICE/TCP, media TCP, TLS relay, port 5349, and relay ranges are disabled.
+- Public media listeners remain STUN-only UDP 3478 and LiveKit UDP 7882.
+ Production enables optional NAT prediction with self-hosted STUN-only UDP
+ 3479 and 3480; ordinary `STUN_URLS` and media routes remain unchanged. Web
+ ingress is TCP 80/443; Node 8787 and LiveKit control/signaling 7880 are
+ private. TURN, ICE/TCP, media TCP, TLS relay, port 5349, and relay ranges are
+ disabled.
- Browser video uses the content-independent H.264 sender gate with VP8
fallback, plus the locked pre-share `VP8 | Auto | H264` Host selector and
resolved codec display. Video retains `contentHint = "motion"`; audio uses
@@ -75,12 +76,13 @@ This is the current execution index. Git history owns completed timelines;
sender windows retain the bounded Peer operation; failed exact candidates stay
consumed until the sender or candidate opportunity changes. The pre-share gate
defaults on and locks while sharing.
-- Host Advanced settings include a default-off, per-share NAT traversal
- experiment. Every Browser P2P role uses the same bounded, connection-local
- candidate adapter. At most two deployment-supplied independent STUN
- observations are contacted only inside opted-in rooms; candidate and selected
- path logs retain anonymous `ordinary | predicted | unknown` provenance.
- Ordinary candidates and SFU fallback remain unchanged.
+- Source keeps NAT prediction deployment-gated and disabled by default. When a
+ deployment enables it, Host Advanced settings shows a per-share switch that
+ defaults on. Every Browser P2P role uses the same bounded, connection-local
+ adapter with only the deployment's self-hosted 3478/3479/3480 STUN endpoints;
+ candidate and selected-path logs retain anonymous
+ `ordinary | predicted | unknown` provenance. Ordinary candidates and SFU
+ fallback remain unchanged.
- Every direct, Browser-relay, and Host SFU video sender owns one clone of its
source track; the original remains presentation and source authority only.
Replacement, rollback, unpublish, physical LiveKit sender recreation, and
diff --git a/docs/todo.md b/docs/todo.md
index 0ce3da11..080095a5 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -1,6 +1,6 @@
# Current TODO Ledger
-Last reviewed: 2026-09-01
+Last reviewed: 2026-09-02
Only **Now** is executable. Observations, old branches, experiments, and parked
topics are not implementation authority.
@@ -81,14 +81,17 @@ until their stated boundary is met.
`MediaStream` output contract. Reopen only for a registered custom receiver
acting as an ordinary Viewer after a named Browser and physical receiver
pass the [platform-output gate](./research/platform-output.md).
-14. **NAT inference and predictive candidates.** The default-off room-wide,
- connection-local experiment is accepted under
- [ADR-0009](./adr/0009-connection-local-nat-prediction-experiment.md). Keep
- multi-STUN observations and injected candidates additive and diagnostic;
- do not make them a participant-wide NAT label, hard candidate skip, route
- score, or SFU preference. Candidate generation and selected-path provenance
- are now observable without endpoint data. Validate target-network success,
- candidate direction, and bounded resource impact before enabling it by default.
+14. **NAT inference and predictive candidates.** The deployment-gated,
+ connection-local capability is accepted under
+ [ADR-0009](./adr/0009-optional-nat-prediction.md). Production enables its
+ self-hosted field rollout; the general configuration default stays off.
+ Keep injected candidates additive and diagnostic; do not make them a
+ participant-wide NAT label, hard candidate skip, route score, or SFU
+ preference. Validate selected predicted paths and bounded resource impact
+ before recommending it as a default for other deployments. Direct
+ convergence currently consumes each deferred Peer parent once; add no
+ cross-generation retry budget until field evidence proves that fresh ICE
+ generations expose a repeatable prediction opportunity.
15. **Unresolved route-state ownership claims.** Reopen lower-revision
reauthentication, active SFU failure during an unrelated prepare, and
multi-child relay-evidence ownership only from an exact current-wire
diff --git a/scripts/access-privacy-gate.ts b/scripts/access-privacy-gate.ts
index b124bb6c..bbbe43d1 100644
--- a/scripts/access-privacy-gate.ts
+++ b/scripts/access-privacy-gate.ts
@@ -99,7 +99,7 @@ async function main(): Promise<void> {
publicBaseUrl: new URL(baseUrl), allowedOrigins: new Set([baseUrl]),
siteAccessPassword: sitePassword, roomLeaseMs: 86_400_000,
maxViewersPerRoom: 2, endpointMediaCopyCapacity: 2,
- peerAssistedMedia: false, stunUrls: [], natPredictionStunUrls: [],
+ peerAssistedMedia: false, stunUrls: [], natPredictionEnabled: false,
};
server = await createScreenerServer({ config, staticDirectory: resolve(root, "dist/client") });
server.httpServer.prependListener("request", (request, response) => {
diff --git a/src/client/App.tsx b/src/client/App.tsx
index 0786b6d6..38f28d85 100644
--- a/src/client/App.tsx
+++ b/src/client/App.tsx
@@ -8,9 +8,11 @@ import {
import {
ApiError,
authenticateSiteAccess,
+ getRuntimeCapabilities,
getSiteAccess,
type SiteAccessStatus,
} from "./lib/api";
+import type { RuntimeCapabilities } from "../shared/protocol";
import { parseAppRoute, readViewerRoute } from "./lib/session";
import { AppHeader } from "./components/living/Header";
import { BrandLoader } from "./components/living/BrandMark";
@@ -157,13 +159,24 @@ function SiteAccessGate({
}) {
const { t, vis } = useCopy();
const [access, setAccess] = useState<AccessState>({ kind: "checking" });
+ const [capabilities, setCapabilities] =
+ useState<RuntimeCapabilities | null>(null);
const [password, setPassword] = useState("");
const [submitting, setSubmitting] = useState(false);
useEffect(() => {
let active = true;
- void getSiteAccess().then(
- (status) => active && setAccess(stateFromStatus(status)),
+ void Promise.all([
+ getSiteAccess(),
+ surface === "host"
+ ? getRuntimeCapabilities()
+ : Promise.resolve<RuntimeCapabilities>({ natPrediction: false }),
+ ]).then(
+ ([status, nextCapabilities]) => {
+ if (!active) return;
+ setCapabilities(nextCapabilities);
+ setAccess(stateFromStatus(status));
+ },
(error: unknown) =>
active &&
setAccess({ kind: "unavailable", message: readableError(error, t) }),
@@ -206,7 +219,14 @@ function SiteAccessGate({
async function retry(): Promise<void> {
setAccess({ kind: "checking" });
try {
- setAccess(stateFromStatus(await getSiteAccess()));
+ const [status, nextCapabilities] = await Promise.all([
+ getSiteAccess(),
+ surface === "host"
+ ? getRuntimeCapabilities()
+ : Promise.resolve<RuntimeCapabilities>({ natPrediction: false }),
+ ]);
+ setCapabilities(nextCapabilities);
+ setAccess(stateFromStatus(status));
} catch (error) {
setAccess({ kind: "unavailable", message: readableError(error, t) });
}
@@ -248,6 +268,7 @@ function SiteAccessGate({
}
return (
<HostPage
+ natPredictionAvailable={capabilities?.natPrediction === true}
onAuthorizationRequired={() =>
setAccess({ kind: "required", error: t("gate.expired") })
}
diff --git a/src/client/components/living/hints/set4.tsx b/src/client/components/living/hints/set4.tsx
index 0fa55d54..685e0e8e 100644
--- a/src/client/components/living/hints/set4.tsx
+++ b/src/client/components/living/hints/set4.tsx
@@ -493,8 +493,8 @@ ${rmBlock(
);
/* hint-nat-prediction: [one direct path] -> [a small bounded fan of
- alternate direct paths]. The dots stay lightweight so the scene describes
- extra ICE chances without suggesting a media relay. */
+ alternate direct paths]. The scene describes extra direct chances without
+ suggesting a media relay. */
const HintNatPrediction: HintScene = ({ theme }) => (
<>
<style>{`
diff --git a/src/client/lib/api.ts b/src/client/lib/api.ts
index f592cb02..7039cc25 100644
--- a/src/client/lib/api.ts
+++ b/src/client/lib/api.ts
@@ -2,10 +2,12 @@ import { say } from "../ui/copy";
import {
createRoomResponseSchema,
roomAccessUpdateResponseSchema,
+ runtimeCapabilitiesSchema,
type CreateRoomResponse,
type CodeEntryPolicy,
type RoomAccessUpdateRequest,
type RoomAccessUpdateResponse,
+ type RuntimeCapabilities,
} from "../../shared/protocol";
export interface SiteAccessStatus {
@@ -66,6 +68,24 @@ export async function getSiteAccess(): Promise<SiteAccessStatus> {
return parseSiteAccessStatus(body);
}
+export async function getRuntimeCapabilities(): Promise<RuntimeCapabilities> {
+ const response = await fetch("/api/capabilities", {
+ headers: { Accept: "application/json" },
+ });
+ const body = await responseBody(response);
+ if (!response.ok) {
+ throw new ApiError(
+ say("gate.serviceUnavailable", { status: String(response.status) }),
+ response.status,
+ );
+ }
+ const parsed = runtimeCapabilitiesSchema.safeParse(body);
+ if (!parsed.success) {
+ throw new ApiError(say("host.err.serverError"), 502);
+ }
+ return parsed.data;
+}
+
export async function authenticateSiteAccess(
password: string,
): Promise<SiteAccessStatus> {
diff --git a/src/client/locales/en.ts b/src/client/locales/en.ts
index b7b7b129..199fb56e 100644
--- a/src/client/locales/en.ts
+++ b/src/client/locales/en.ts
@@ -157,9 +157,9 @@ export const en: Record<CopyKey, string> = {
"host.advanced.route.peerOnly": "Privacy mode",
"host.advanced.route.peerOnlyHint":
"Use P2P routes only; viewers without a P2P path cannot watch",
- "host.advanced.route.natPrediction": "NAT traversal experiment",
+ "host.advanced.route.natPrediction": "NAT traversal",
"host.advanced.route.natPredictionHint":
- "Try extra self-hosted STUN candidates for direct links; ordinary ICE remains available",
+ "Use self-hosted STUN for a bounded set of extra direct attempts; ordinary ICE is unchanged",
"host.advanced.codec": "Video codec",
"host.advanced.codec.auto": "Auto",
"host.advanced.codec.autoHint": "Pick automatically",
diff --git a/src/client/locales/zh.ts b/src/client/locales/zh.ts
index fef44b25..ddbb6413 100644
--- a/src/client/locales/zh.ts
+++ b/src/client/locales/zh.ts
@@ -155,9 +155,9 @@ export const zh = {
"host.advanced.route.peerOnly": "隐私模式",
"host.advanced.route.peerOnlyHint":
"仅使用 P2P 路线,不经过媒体服务器;无可用 P2P 路线时无法观看",
- "host.advanced.route.natPrediction": "NAT 打洞实验",
+ "host.advanced.route.natPrediction": "NAT 穿透",
"host.advanced.route.natPredictionHint":
- "为直连尝试额外的自托管 STUN 候选;失败时仍使用普通连接",
+ "使用自建 STUN 增加有限的直连尝试;普通连接不受影响",
"host.advanced.codec": "视频编码",
"host.advanced.codec.auto": "自动",
"host.advanced.codec.autoHint": "自动选择",
diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsx
index b130b5eb..678f3fd1 100644
--- a/src/client/pages/HostPage.tsx
+++ b/src/client/pages/HostPage.tsx
@@ -370,10 +370,14 @@ function hostTerminationKey(reason: SignalingTerminationReason): CopyKey {
}
interface HostPageProps {
+ natPredictionAvailable?: boolean;
onAuthorizationRequired?: () => void;
}
-export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
+export function HostPage({
+ natPredictionAvailable = false,
+ onAuthorizationRequired,
+}: HostPageProps = {}) {
const { lang, vis, t, titleFrames } = useCopy();
const [qualitySettings, setQualitySettings] = useState<QualitySettings>(
DEFAULT_QUALITY_SETTINGS,
@@ -382,7 +386,10 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
DEFAULT_QUALITY_SETTINGS,
);
const [routePolicy, setRoutePolicy] = useState<RoutePolicy>(
- DEFAULT_ROUTE_POLICY,
+ () => ({
+ ...DEFAULT_ROUTE_POLICY,
+ natPrediction: natPredictionAvailable,
+ }),
);
const [videoCodecMode, setVideoCodecMode] =
useState<BrowserVideoCodecMode>("auto");
@@ -513,7 +520,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
const qualityChangeRef = useRef<object | null>(null);
const pendingQualityChangeRef = useRef<QualitySettings | null>(null);
const qualitySettingsRef = useRef<QualitySettings>(DEFAULT_QUALITY_SETTINGS);
- const routePolicyRef = useRef<RoutePolicy>(DEFAULT_ROUTE_POLICY);
+ const routePolicyRef = useRef<RoutePolicy>(routePolicy);
const advancedQualityRef = useRef<QualitySettings>(advancedQuality);
const videoCodecModeRef = useRef<BrowserVideoCodecMode>(videoCodecMode);
const roomMutationRef = useRef<object | null>(null);
@@ -3813,6 +3820,18 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
note={t("host.advanced.route.topoHint")}
hint="hint-topology"
/>
+ {natPredictionAvailable ? (
+ <SwitchItem
+ checked={routePolicy.natPrediction}
+ disabled={phase === "starting" || phase === "live"}
+ onChange={(checked) =>
+ changeRoutePolicy({ natPrediction: checked })
+ }
+ label={t("host.advanced.route.natPrediction")}
+ note={t("host.advanced.route.natPredictionHint")}
+ hint="hint-nat-prediction"
+ />
+ ) : null}
<SwitchItem
checked={routePolicy.peerOnly}
disabled={phase === "starting" || phase === "live"}
@@ -3823,16 +3842,6 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
note={t("host.advanced.route.peerOnlyHint")}
hint="hint-route-p2p"
/>
- <SwitchItem
- checked={routePolicy.natPrediction}
- disabled={phase === "starting" || phase === "live"}
- onChange={(checked) =>
- changeRoutePolicy({ natPrediction: checked })
- }
- label={t("host.advanced.route.natPrediction")}
- note={t("host.advanced.route.natPredictionHint")}
- hint="hint-nat-prediction"
- />
</div>
</div>
<div className="lr-door-group">
diff --git a/src/client/webrtc/host-peer.ts b/src/client/webrtc/host-peer.ts
index 6421c63c..b4223b5b 100644
--- a/src/client/webrtc/host-peer.ts
+++ b/src/client/webrtc/host-peer.ts
@@ -38,6 +38,7 @@ import {
VP8_ONLY_VIDEO_CODEC,
} from "./video-codec";
import {
+ addRemoteIceCandidate,
iceServersWithNatPrediction,
natPredictionSurveyUrls,
NatPredictionCandidateEmitter,
@@ -122,6 +123,7 @@ export class HostPeer {
(candidate) => this.sendIceCandidate(candidate),
natPredictionSurveyUrls(
iceConfig.iceServers,
+ iceConfig.natPredictionStunUrls,
),
);
this.snapshot = {
@@ -383,7 +385,7 @@ export class HostPeer {
}
await this.enqueueNegotiation(() => this.acceptAnswer(payload));
} else if (this.connection.remoteDescription) {
- await this.connection.addIceCandidate(payload.candidate);
+ await addRemoteIceCandidate(this.connection, payload.candidate);
} else if (this.pendingCandidates.length < MAX_PENDING_CANDIDATES) {
this.pendingCandidates.push(payload.candidate);
}
@@ -427,6 +429,7 @@ export class HostPeer {
this.localIceCandidates.setSurveyUrls(
natPredictionSurveyUrls(
iceConfig.iceServers,
+ iceConfig.natPredictionStunUrls,
),
);
} catch (error) {
@@ -571,7 +574,7 @@ export class HostPeer {
private async flushCandidates(): Promise<void> {
const candidates = this.pendingCandidates.splice(0);
for (const candidate of candidates) {
- await this.connection.addIceCandidate(candidate);
+ await addRemoteIceCandidate(this.connection, candidate);
}
}
diff --git a/src/client/webrtc/nat-prediction.ts b/src/client/webrtc/nat-prediction.ts
index e7d8c9c8..5d295063 100644
--- a/src/client/webrtc/nat-prediction.ts
+++ b/src/client/webrtc/nat-prediction.ts
@@ -1,7 +1,5 @@
-import {
- MAX_NAT_PREDICTION_STUN_URLS,
- type SignalPayload,
-} from "../../shared/protocol";
+import type { SignalPayload } from "../../shared/protocol";
+import { candidateSignalOrigin } from "../../shared/nat-candidate";
export type SignalCandidate = Extract<
SignalPayload,
@@ -18,6 +16,21 @@ const MAX_PREDICTABLE_PORT = 65_535;
export const NAT_PREDICTION_STEPS = 4;
export const MAX_NAT_PREDICTION_CANDIDATES = NAT_PREDICTION_STEPS * 2;
+export async function addRemoteIceCandidate(
+ connection: RTCPeerConnection,
+ candidate: SignalCandidate,
+): Promise<void> {
+ try {
+ await connection.addIceCandidate(candidate);
+ } catch (error) {
+ if (
+ candidateSignalOrigin(candidate?.candidate ?? null) !== "predicted"
+ ) {
+ throw error;
+ }
+ }
+}
+
interface SrflxObservation {
candidate: SignalCandidate;
fields: string[];
@@ -104,19 +117,30 @@ function normalizedStunUrl(url: string): string | null {
/** URLs whose same-socket observations may form the controlled port sequence. */
export function natPredictionSurveyUrls(
iceServers: readonly RTCIceServer[] | undefined,
+ auxiliaryStunUrls: readonly string[] = [],
): ReadonlySet<string> {
+ const configuredAuxiliaryUrls = new Set(
+ auxiliaryStunUrls.flatMap((url) => {
+ const normalized = normalizedStunUrl(url);
+ return normalized ? [normalized] : [];
+ }),
+ );
for (const server of iceServers ?? []) {
for (const url of urlsOf(server)) {
const auxiliaryUrls = auxiliaryUrlsFor(url);
const baseUrl = normalizedStunUrl(url);
- if (baseUrl && auxiliaryUrls.length > 0) {
- return new Set([
- baseUrl,
- ...auxiliaryUrls.flatMap((entry) => {
- const normalized = normalizedStunUrl(entry);
- return normalized ? [normalized] : [];
- }),
- ]);
+ const normalizedAuxiliaryUrls = auxiliaryUrls.flatMap((entry) => {
+ const normalized = normalizedStunUrl(entry);
+ return normalized ? [normalized] : [];
+ });
+ if (
+ baseUrl &&
+ normalizedAuxiliaryUrls.length === AUXILIARY_STUN_PORTS.length &&
+ normalizedAuxiliaryUrls.every((entry) =>
+ configuredAuxiliaryUrls.has(entry),
+ )
+ ) {
+ return new Set([baseUrl, ...normalizedAuxiliaryUrls]);
}
}
}
@@ -130,7 +154,7 @@ export function natPredictionSurveyUrls(
export function iceServersWithNatPrediction(
iceServers: readonly RTCIceServer[] | undefined,
enabled: boolean,
- externalStunUrls: readonly string[] = [],
+ auxiliaryStunUrls: readonly string[] = [],
): RTCIceServer[] {
const base = (iceServers ?? []).map(cloneIceServer);
if (!enabled) {
@@ -143,25 +167,7 @@ export function iceServersWithNatPrediction(
.flatMap((server) => urlsOf(server))
.map((url) => normalizedStunUrl(url) ?? url),
);
- for (const server of iceServers ?? []) {
- for (const url of urlsOf(server)) {
- for (const auxiliaryUrl of auxiliaryUrlsFor(url)) {
- const normalized = normalizedStunUrl(auxiliaryUrl) ?? auxiliaryUrl;
- if (!existing.has(normalized)) {
- additions.add(auxiliaryUrl);
- existing.add(normalized);
- }
- }
- if (additions.size >= AUXILIARY_STUN_PORTS.length) {
- break;
- }
- }
- if (additions.size >= AUXILIARY_STUN_PORTS.length) {
- break;
- }
- }
-
- for (const url of externalStunUrls.slice(0, MAX_NAT_PREDICTION_STUN_URLS)) {
+ for (const url of auxiliaryStunUrls) {
const normalized = normalizedStunUrl(url);
if (normalized && !existing.has(normalized)) {
additions.add(url);
diff --git a/src/client/webrtc/viewer-peer.ts b/src/client/webrtc/viewer-peer.ts
index b1679e70..9fe618c2 100644
--- a/src/client/webrtc/viewer-peer.ts
+++ b/src/client/webrtc/viewer-peer.ts
@@ -13,6 +13,7 @@ import {
import { preferScreenAudioStereo } from "./screen-audio-sdp";
import { observeDecodedFrameProof } from "../media/decoded-frame-proof";
import {
+ addRemoteIceCandidate,
iceServersWithNatPrediction,
natPredictionSurveyUrls,
NatPredictionCandidateEmitter,
@@ -133,6 +134,7 @@ export class ViewerPeer {
this.localIceCandidates?.setSurveyUrls(
natPredictionSurveyUrls(
iceConfig.iceServers,
+ iceConfig.natPredictionStunUrls,
),
);
} catch (error) {
@@ -251,6 +253,7 @@ export class ViewerPeer {
},
natPredictionSurveyUrls(
this.currentIceConfig.iceServers,
+ this.currentIceConfig.natPredictionStunUrls,
),
);
this.connection = connection;
@@ -402,7 +405,7 @@ export class ViewerPeer {
const connection = this.connection;
const connectionId = payload.connectionId;
try {
- await connection.addIceCandidate(payload.candidate);
+ await addRemoteIceCandidate(connection, payload.candidate);
} catch (error) {
if (this.isCurrentConnection(connection, connectionId)) {
this.setError(error, say("host.fail.connection"));
@@ -569,7 +572,7 @@ export class ViewerPeer {
const candidates = this.pendingByConnection.get(connectionId) ?? [];
this.pendingByConnection.delete(connectionId);
for (const candidate of candidates) {
- await connection.addIceCandidate(candidate);
+ await addRemoteIceCandidate(connection, candidate);
if (!this.isCurrentConnection(connection, connectionId)) {
return;
}
diff --git a/src/server/app.ts b/src/server/app.ts
index 6a541b09..cb56b344 100644
--- a/src/server/app.ts
+++ b/src/server/app.ts
@@ -105,7 +105,7 @@ export async function createScreenerServer(
});
const iceOptions = {
stunUrls: config.stunUrls,
- natPredictionStunUrls: config.natPredictionStunUrls,
+ natPredictionEnabled: config.natPredictionEnabled,
};
let frontendHandler: FrontendHandler | undefined;
@@ -341,6 +341,20 @@ async function handleRequest(
return;
}
+ if (url.pathname === "/api/capabilities") {
+ response.setHeader("Cache-Control", "no-store");
+ response.setHeader("X-Content-Type-Options", "nosniff");
+ if (request.method !== "GET") {
+ response.setHeader("Allow", "GET");
+ sendJson(response, 405, { error: "Method not allowed" });
+ return;
+ }
+ sendJson(response, 200, {
+ natPrediction: config.natPredictionEnabled,
+ });
+ return;
+ }
+
if (url.pathname === "/api/site-access") {
handleSiteAccessRequest(request, response, config, siteAccess);
return;
diff --git a/src/server/config.ts b/src/server/config.ts
index 62dc2006..61b87872 100644
--- a/src/server/config.ts
+++ b/src/server/config.ts
@@ -2,7 +2,6 @@ import { isAbsolute } from "node:path";
import {
MAX_ICE_SERVER_URLS,
- MAX_NAT_PREDICTION_STUN_URLS,
MAX_VIEWERS_PER_ROOM_LIMIT,
stunUrlSchema,
} from "../shared/protocol.js";
@@ -10,6 +9,7 @@ import {
DEFAULT_ENDPOINT_MEDIA_COPY_CAPACITY,
MAX_ENDPOINT_MEDIA_COPY_CAPACITY,
} from "../shared/media-copy-accounting.js";
+import { natPredictionStunUrls } from "./ice.js";
export type RuntimeEnvironment = "development" | "test" | "production";
@@ -57,7 +57,7 @@ export interface ServerConfig {
endpointMediaCopyCapacity: number;
livekitFallback?: LiveKitFallbackConfig;
stunUrls: readonly string[];
- natPredictionStunUrls: readonly string[];
+ natPredictionEnabled: boolean;
}
function parseBoolean(
@@ -323,17 +323,22 @@ export function loadConfig(
environment.ROOM_DATABASE_PATH,
);
const stunUrls = parseStunUrlList(environment.STUN_URLS, "STUN_URLS");
- const natPredictionStunUrls = parseStunUrlList(
- environment.NAT_PREDICTION_STUN_URLS,
- "NAT_PREDICTION_STUN_URLS",
- MAX_NAT_PREDICTION_STUN_URLS,
+ const natPredictionEnabled = parseBoolean(
+ environment.NAT_PREDICTION_ENABLED,
+ false,
+ "NAT_PREDICTION_ENABLED",
);
if (
- stunUrls.length + natPredictionStunUrls.length >
- MAX_ICE_SERVER_URLS
+ natPredictionEnabled &&
+ natPredictionStunUrls(stunUrls).length === 0
) {
throw new Error(
- `STUN_URLS and NAT_PREDICTION_STUN_URLS must contain at most ${MAX_ICE_SERVER_URLS} URLs together`,
+ "NAT_PREDICTION_ENABLED requires a STUN_URLS entry on UDP 3478",
+ );
+ }
+ if (natPredictionEnabled && stunUrls.length + 2 > MAX_ICE_SERVER_URLS) {
+ throw new Error(
+ `STUN_URLS must contain at most ${MAX_ICE_SERVER_URLS - 2} URLs when NAT_PREDICTION_ENABLED=true`,
);
}
const maxViewersPerRoom = parseBoundedInteger(
@@ -410,6 +415,6 @@ export function loadConfig(
endpointMediaCopyCapacity,
livekitFallback,
stunUrls,
- natPredictionStunUrls,
+ natPredictionEnabled,
};
}
diff --git a/src/server/ice.ts b/src/server/ice.ts
index 05310034..73c6939e 100644
--- a/src/server/ice.ts
+++ b/src/server/ice.ts
@@ -2,13 +2,47 @@ import type { WireIceConfig } from "../shared/protocol.js";
export interface IceConfigOptions {
stunUrls: readonly string[];
- natPredictionStunUrls?: readonly string[];
+ natPredictionEnabled: boolean;
+}
+
+const NAT_PREDICTION_BASE_PORT = 3478;
+const NAT_PREDICTION_AUXILIARY_PORTS = [3479, 3480] as const;
+
+export function natPredictionStunUrls(
+ stunUrls: readonly string[],
+): string[] {
+ for (const stunUrl of stunUrls) {
+ const authorityText = stunUrl.slice(stunUrl.indexOf(":") + 1);
+ let authority: URL;
+ try {
+ authority = new URL(`http://${authorityText}`);
+ } catch {
+ continue;
+ }
+ const port = authority.port
+ ? Number(authority.port)
+ : NAT_PREDICTION_BASE_PORT;
+ if (port !== NAT_PREDICTION_BASE_PORT) {
+ continue;
+ }
+ const hostname = authority.hostname.startsWith("[")
+ ? authority.hostname
+ : authority.hostname.includes(":")
+ ? `[${authority.hostname}]`
+ : authority.hostname;
+ return NAT_PREDICTION_AUXILIARY_PORTS.map(
+ (auxiliaryPort) => `stun:${hostname}:${auxiliaryPort}`,
+ );
+ }
+ return [];
}
export function createIceConfig(options: IceConfigOptions): WireIceConfig {
return {
iceServers:
options.stunUrls.length > 0 ? [{ urls: [...options.stunUrls] }] : [],
- natPredictionStunUrls: [...(options.natPredictionStunUrls ?? [])],
+ natPredictionStunUrls: options.natPredictionEnabled
+ ? natPredictionStunUrls(options.stunUrls)
+ : [],
};
}
diff --git a/src/server/signaling.ts b/src/server/signaling.ts
index 4ef1c877..5d457141 100644
--- a/src/server/signaling.ts
+++ b/src/server/signaling.ts
@@ -83,6 +83,16 @@ interface SenderQualityRateWindow {
count: number;
}
+function configuredRoutePolicy(
+ policy: RoutePolicy,
+ natPredictionEnabled: boolean,
+): RoutePolicy {
+ return {
+ ...policy,
+ natPrediction: natPredictionEnabled && policy.natPrediction,
+ };
+}
+
export interface SignalingOptions {
server: HttpServer;
roomStore: RoomStore;
@@ -583,9 +593,10 @@ export class SignalingServer {
currentGeneration !== shareGeneration ||
!this.routePolicyByRoom.has(participant.roomId)
) {
- const routePolicy = {
- ...(message.routePolicy ?? DEFAULT_ROUTE_POLICY),
- };
+ const routePolicy = configuredRoutePolicy(
+ message.routePolicy ?? DEFAULT_ROUTE_POLICY,
+ this.options.ice.natPredictionEnabled,
+ );
this.routePolicyByRoom.set(participant.roomId, routePolicy);
for (const viewer of this.options.roomStore.getConnectedViewers(
participant.roomId,
diff --git a/src/shared/protocol.ts b/src/shared/protocol.ts
index 373316f1..d08eada8 100644
--- a/src/shared/protocol.ts
+++ b/src/shared/protocol.ts
@@ -19,7 +19,7 @@ export const ROOM_CODE_LENGTH = 4;
export const MAX_MEDIA_ROUTE_REVISION = Number.MAX_SAFE_INTEGER;
export const MAX_SFU_TOKEN_LENGTH = 8 * 1024;
export const MAX_ICE_SERVER_URLS = 8;
-export const MAX_NAT_PREDICTION_STUN_URLS = 2;
+export const MAX_NAT_PREDICTION_AUXILIARY_STUN_URLS = 2;
export const MAX_VIEWER_QUALITY_EVIDENCE_BYTES = 2 * 1024;
export const VIEWER_QUALITY_EVIDENCE_INTERVAL_MS = 2_000;
export const VIEWER_QUALITY_EVIDENCE_EXPIRY_MS = 5_000;
@@ -230,6 +230,13 @@ export const DEFAULT_ROUTE_POLICY = {
natPrediction: false,
} as const satisfies RoutePolicy;
+export const runtimeCapabilitiesSchema = z
+ .object({
+ natPrediction: z.boolean(),
+ })
+ .strict();
+export type RuntimeCapabilities = z.infer<typeof runtimeCapabilitiesSchema>;
+
export const relayDownstreamEdgesSchema = z
.number()
.int()
@@ -292,7 +299,7 @@ export const iceConfigSchema = z
iceServers: z.array(iceServerSchema).max(8),
natPredictionStunUrls: z
.array(stunUrlSchema)
- .max(MAX_NAT_PREDICTION_STUN_URLS),
+ .max(MAX_NAT_PREDICTION_AUXILIARY_STUN_URLS),
})
.strict();
export type WireIceConfig = z.infer<typeof iceConfigSchema>;
diff --git a/tests/copy.test.ts b/tests/copy.test.ts
index 59509525..04deb929 100644
--- a/tests/copy.test.ts
+++ b/tests/copy.test.ts
@@ -21,6 +21,10 @@ describe("copy catalog", () => {
expect(t("en", "join.title")).toBe("Join a room");
expect(t("zh", "host.advanced.route.peerOnly")).toBe("隐私模式");
expect(t("en", "host.advanced.route.peerOnly")).toBe("Privacy mode");
+ expect(t("zh", "host.advanced.route.natPrediction")).toBe("NAT 穿透");
+ expect(t("en", "host.advanced.route.natPrediction")).toBe(
+ "NAT traversal",
+ );
expect(isCopyKey("viewer.reconnect")).toBe(true);
expect(isCopyKey("Reconnect media")).toBe(false);
});
diff --git a/tests/host-peer-tracks.test.ts b/tests/host-peer-tracks.test.ts
index e98cbf47..8e54e36a 100644
--- a/tests/host-peer-tracks.test.ts
+++ b/tests/host-peer-tracks.test.ts
@@ -728,7 +728,10 @@ describe("HostPeer source replacement", () => {
"viewer-peer",
{
iceServers: [{ urls: "stun:share.example.test:3478" }],
- natPredictionStunUrls: ["stun:observer.example.test:3478"],
+ natPredictionStunUrls: [
+ "stun:share.example.test:3479",
+ "stun:share.example.test:3480",
+ ],
},
createStream(createTrack("video", "video"), null),
QUALITY_PROFILES["720p30"],
@@ -748,7 +751,6 @@ describe("HostPeer source replacement", () => {
{ urls: "stun:share.example.test:3478" },
{ urls: "stun:share.example.test:3479" },
{ urls: "stun:share.example.test:3480" },
- { urls: "stun:observer.example.test:3478" },
]);
const surveyUrls = [
@@ -774,7 +776,6 @@ describe("HostPeer source replacement", () => {
});
connection.dispatchEvent(event);
};
- emitCandidate(50_000, "stun:observer.example.test:3478");
emitCandidate(40_000, surveyUrls[0]);
emitCandidate(40_003, surveyUrls[1]);
emitCandidate(40_006, surveyUrls[2]);
@@ -799,7 +800,7 @@ describe("HostPeer source replacement", () => {
candidateSignals.filter((signal) =>
signal.candidate?.candidate.startsWith("candidate:base"),
),
- ).toHaveLength(4);
+ ).toHaveLength(3);
expect(candidateSignals.at(-1)?.candidate).toBeNull();
expect(candidateSignals.filter((signal) => signal.candidate === null)).toHaveLength(1);
peer.dispose();
@@ -1840,7 +1841,13 @@ describe("Host provisional child runtime ownership", () => {
describe("ViewerRelay downstream ownership", () => {
it("applies the room NAT policy to downstream Peer connections", async () => {
const relay = new ViewerRelay(
- { iceServers: [{ urls: "stun:share.example.test:3478" }] },
+ {
+ iceServers: [{ urls: "stun:share.example.test:3478" }],
+ natPredictionStunUrls: [
+ "stun:share.example.test:3479",
+ "stun:share.example.test:3480",
+ ],
+ },
QUALITY_PROFILES["720p30"],
{ sendSignal: () => true },
2,
diff --git a/tests/ice.test.ts b/tests/ice.test.ts
index 07c4a6c2..4aa6a953 100644
--- a/tests/ice.test.ts
+++ b/tests/ice.test.ts
@@ -10,7 +10,7 @@ describe("ordinary ICE configuration", () => {
"stun:stun-a.example.test:3478",
"stun:stun-b.example.test:3478",
],
- natPredictionStunUrls: ["stun:observer.example.test:3478"],
+ natPredictionEnabled: true,
}),
).toEqual({
iceServers: [
@@ -21,13 +21,40 @@ describe("ordinary ICE configuration", () => {
],
},
],
- natPredictionStunUrls: ["stun:observer.example.test:3478"],
+ natPredictionStunUrls: [
+ "stun:stun-a.example.test:3479",
+ "stun:stun-a.example.test:3480",
+ ],
});
});
it("keeps local development explicit when STUN is absent", () => {
expect(
- createIceConfig({ stunUrls: [], natPredictionStunUrls: [] }),
+ createIceConfig({ stunUrls: [], natPredictionEnabled: false }),
).toEqual({ iceServers: [], natPredictionStunUrls: [] });
});
+
+ it("does not expose auxiliary listeners when the capability is disabled", () => {
+ expect(
+ createIceConfig({
+ stunUrls: ["stun:share.example.test:3478"],
+ natPredictionEnabled: false,
+ }),
+ ).toEqual({
+ iceServers: [{ urls: ["stun:share.example.test:3478"] }],
+ natPredictionStunUrls: [],
+ });
+ });
+
+ it("derives auxiliary listeners from an IPv6 STUN authority", () => {
+ expect(
+ createIceConfig({
+ stunUrls: ["STUN:[2001:db8::1]:3478"],
+ natPredictionEnabled: true,
+ }).natPredictionStunUrls,
+ ).toEqual([
+ "stun:[2001:db8::1]:3479",
+ "stun:[2001:db8::1]:3480",
+ ]);
+ });
});
diff --git a/tests/nat-prediction.test.ts b/tests/nat-prediction.test.ts
index 796ec5a2..7dd9a217 100644
--- a/tests/nat-prediction.test.ts
+++ b/tests/nat-prediction.test.ts
@@ -1,6 +1,7 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
import {
+ addRemoteIceCandidate,
iceServersWithNatPrediction,
MAX_NAT_PREDICTION_CANDIDATES,
NatPredictionCandidateBatch,
@@ -42,6 +43,30 @@ function rtcCandidate(port: number): RTCIceCandidate {
}
describe("NAT prediction ICE adapter", () => {
+ it("ignores only rejected predicted candidates", async () => {
+ const error = new Error("candidate rejected");
+ const connection = {
+ addIceCandidate: vi.fn(async () => {
+ throw error;
+ }),
+ } as unknown as RTCPeerConnection;
+ const predicted = candidate(40_000);
+ if (predicted) {
+ predicted.candidate = predicted.candidate.replace(
+ "candidate:base",
+ "candidate:sp1",
+ );
+ }
+
+ await expect(
+ addRemoteIceCandidate(connection, predicted),
+ ).resolves.toBeUndefined();
+ await expect(
+ addRemoteIceCandidate(connection, candidate(40_000)),
+ ).rejects.toBe(error);
+ await expect(addRemoteIceCandidate(connection, null)).rejects.toBe(error);
+ });
+
it("leaves the configured servers unchanged when disabled", () => {
const servers = [
{ urls: ["stun:share.example.test:3478"] },
@@ -52,26 +77,30 @@ describe("NAT prediction ICE adapter", () => {
iceServersWithNatPrediction(
servers,
false,
- ["stun:observer.example.test:3478"],
+ [
+ "stun:share.example.test:3479",
+ "stun:share.example.test:3480",
+ ],
),
).toEqual(servers);
});
- it("adds independent observers only inside the enabled experiment", () => {
+ it("adds only configured self-hosted auxiliary listeners", () => {
const servers = [{ urls: "stun:share.example.test:3478" }];
+ const auxiliary = [
+ "stun:share.example.test:3479",
+ "stun:share.example.test:3480",
+ ];
expect(
- iceServersWithNatPrediction(servers, true, [
- "stun:observer.example.test:3478",
- ]),
+ iceServersWithNatPrediction(servers, true, auxiliary),
).toEqual([
...servers,
{ urls: "stun:share.example.test:3479" },
{ urls: "stun:share.example.test:3480" },
- { urls: "stun:observer.example.test:3478" },
]);
expect(
- natPredictionSurveyUrls(servers),
+ natPredictionSurveyUrls(servers, auxiliary),
).toEqual(
new Set([
"stun:share.example.test:3478",
@@ -82,21 +111,18 @@ describe("NAT prediction ICE adapter", () => {
expect(
natPredictionSurveyUrls([
{ urls: "stun:share.example.test:5349" },
- ]),
+ ], auxiliary),
).toEqual(new Set());
});
- it("derives only the two optional same-host survey listeners", () => {
+ it("does not invent auxiliary listeners that the server did not enable", () => {
const servers = [
{ urls: ["stun:share.example.test:3478", "stun:share.example.test:3478"] },
{ urls: "stun:other.example.test:3478" },
];
- expect(iceServersWithNatPrediction(servers, true)).toEqual([
- ...servers,
- { urls: "stun:share.example.test:3479" },
- { urls: "stun:share.example.test:3480" },
- ]);
+ expect(iceServersWithNatPrediction(servers, true)).toEqual(servers);
+ expect(natPredictionSurveyUrls(servers)).toEqual(new Set());
});
it("does not duplicate already configured auxiliary listeners", () => {
@@ -105,7 +131,10 @@ describe("NAT prediction ICE adapter", () => {
{ urls: "stun:share.example.test:3479" },
];
- expect(iceServersWithNatPrediction(servers, true)).toEqual([
+ expect(iceServersWithNatPrediction(servers, true, [
+ "stun:share.example.test:3479",
+ "stun:share.example.test:3480",
+ ])).toEqual([
...servers,
{ urls: "stun:share.example.test:3480" },
]);
@@ -214,7 +243,7 @@ describe("NAT prediction ICE adapter", () => {
expect(sent).toEqual([first]);
});
- it("retains independent observations without using them as sequence evidence", () => {
+ it("forwards an ineligible srflx candidate without using it as sequence evidence", () => {
const sent: Array<SignalCandidate | null> = [];
const batch = new NatPredictionCandidateBatch((value) => sent.push(value));
const external = candidate(50_000);
diff --git a/tests/server-config.test.ts b/tests/server-config.test.ts
index 25f4ad54..6d968425 100644
--- a/tests/server-config.test.ts
+++ b/tests/server-config.test.ts
@@ -18,7 +18,7 @@ describe("server configuration", () => {
expect(config.allowedOrigins).toEqual(new Set(["http://localhost:9123"]));
expect(config.roomDatabasePath).toBeUndefined();
expect(config.stunUrls).toEqual([]);
- expect(config.natPredictionStunUrls).toEqual([]);
+ expect(config.natPredictionEnabled).toBe(false);
expect(config.maxViewersPerRoom).toBe(8);
expect(config.peerAssistedMedia).toBe(false);
expect(config.endpointMediaCopyCapacity).toBe(2);
@@ -327,28 +327,29 @@ describe("server configuration", () => {
).toEqual(["STUN:[2001:db8::1]:3478"]);
});
- it("accepts a bounded independent NAT prediction STUN list", () => {
+ it("enables bounded NAT prediction only with a base STUN listener", () => {
expect(
loadConfig({
- NAT_PREDICTION_STUN_URLS:
- "stun:observer-a.test:3478, stun:observer-b.test:3478",
- }).natPredictionStunUrls,
- ).toEqual([
- "stun:observer-a.test:3478",
- "stun:observer-b.test:3478",
- ]);
- });
-
- it("rejects invalid or excessive NAT prediction STUN URLs", () => {
+ STUN_URLS: "stun:share.test:3478",
+ NAT_PREDICTION_ENABLED: "true",
+ }).natPredictionEnabled,
+ ).toBe(true);
expect(() =>
- loadConfig({ NAT_PREDICTION_STUN_URLS: "turn:observer.test:3478" }),
- ).toThrow("NAT_PREDICTION_STUN_URLS contains an invalid STUN URL");
+ loadConfig({ NAT_PREDICTION_ENABLED: "true" }),
+ ).toThrow(
+ "NAT_PREDICTION_ENABLED requires a STUN_URLS entry on UDP 3478",
+ );
expect(() =>
loadConfig({
- NAT_PREDICTION_STUN_URLS:
- "stun:a.test:3478,stun:b.test:3478,stun:c.test:3478",
+ STUN_URLS: "stun:share.test:5349",
+ NAT_PREDICTION_ENABLED: "true",
}),
- ).toThrow("NAT_PREDICTION_STUN_URLS must contain at most 2 URLs");
+ ).toThrow(
+ "NAT_PREDICTION_ENABLED requires a STUN_URLS entry on UDP 3478",
+ );
+ expect(() =>
+ loadConfig({ NAT_PREDICTION_ENABLED: "sometimes" }),
+ ).toThrow("NAT_PREDICTION_ENABLED must be true or false");
});
it.each([
@@ -402,18 +403,17 @@ describe("server configuration", () => {
).toThrow("STUN_URLS must contain at most 8 URLs");
});
- it("bounds ordinary and NAT prediction STUN URLs together", () => {
+ it("reserves two ICE URL slots for configured NAT prediction", () => {
expect(() =>
loadConfig({
STUN_URLS: Array.from(
{ length: 7 },
(_, index) => `stun:ordinary-${index}.test:3478`,
).join(","),
- NAT_PREDICTION_STUN_URLS:
- "stun:observer-a.test:3478,stun:observer-b.test:3478",
+ NAT_PREDICTION_ENABLED: "true",
}),
).toThrow(
- "STUN_URLS and NAT_PREDICTION_STUN_URLS must contain at most 8 URLs together",
+ "STUN_URLS must contain at most 6 URLs when NAT_PREDICTION_ENABLED=true",
);
});
diff --git a/tests/server-http.test.ts b/tests/server-http.test.ts
index 26ece4b9..8b5ace09 100644
--- a/tests/server-http.test.ts
+++ b/tests/server-http.test.ts
@@ -57,7 +57,7 @@ function testConfig(overrides: Partial<ServerConfig> = {}): ServerConfig {
peerAssistedMedia: false,
endpointMediaCopyCapacity: 2,
stunUrls: [],
- natPredictionStunUrls: [],
+ natPredictionEnabled: false,
...overrides,
};
}
@@ -167,6 +167,33 @@ async function replaceRoom(
});
}
+describe("runtime capabilities", () => {
+ it("keeps NAT prediction absent by default", async () => {
+ const baseUrl = await start();
+ const response = await fetch(`${baseUrl}/api/capabilities`);
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({ natPrediction: false });
+ });
+
+ it("reports optional NAT prediction without exposing configuration", async () => {
+ const baseUrl = await start(
+ testConfig({
+ stunUrls: ["stun:share.example.test:3478"],
+ natPredictionEnabled: true,
+ }),
+ );
+ const response = await fetch(`${baseUrl}/api/capabilities`);
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get("cache-control")).toBe("no-store");
+ expect(await response.json()).toEqual({ natPrediction: true });
+ expect(
+ (await fetch(`${baseUrl}/api/capabilities`, { method: "POST" })).status,
+ ).toBe(405);
+ });
+});
+
describe("site access", () => {
it("reports status and issues a stateless 24-hour cookie", async () => {
const baseUrl = await start();
diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.ts
index be8bb4a3..9c89e7f8 100644
--- a/tests/server-signal.test.ts
+++ b/tests/server-signal.test.ts
@@ -137,7 +137,7 @@ function testConfig(): ServerConfig {
peerAssistedMedia: false,
endpointMediaCopyCapacity: 2,
stunUrls: [],
- natPredictionStunUrls: [],
+ natPredictionEnabled: false,
};
}
@@ -152,7 +152,7 @@ async function startHarness(
peerAssistedMedia?: boolean;
endpointMediaCopyCapacity?: number;
stunUrls?: readonly string[];
- natPredictionStunUrls?: readonly string[];
+ natPredictionEnabled?: boolean;
now?: () => number;
roomStore?: RoomStore;
room?: CreatedRoom;
@@ -164,7 +164,7 @@ async function startHarness(
config.endpointMediaCopyCapacity =
overrides.endpointMediaCopyCapacity ?? 2;
config.stunUrls = overrides.stunUrls ?? [];
- config.natPredictionStunUrls = overrides.natPredictionStunUrls ?? [];
+ config.natPredictionEnabled = overrides.natPredictionEnabled ?? false;
const maxViewersPerRoom = overrides.maxViewersPerRoom ?? 8;
config.maxViewersPerRoom = maxViewersPerRoom;
const roomStore =
@@ -466,7 +466,11 @@ async function closeClient(client: TestClient): Promise<void> {
describe("WebSocket signaling", () => {
it("echoes the exact per-share route policy authority", async () => {
- const harness = await startHarness({ peerAssistedMedia: true });
+ const harness = await startHarness({
+ peerAssistedMedia: true,
+ stunUrls: ["stun:share.example.test:3478"],
+ natPredictionEnabled: true,
+ });
const viewer = await openClient(harness.webSocketUrl);
const waiting = peerAssisted(
await authenticate(
@@ -504,8 +508,12 @@ describe("WebSocket signaling", () => {
});
});
- it("broadcasts the NAT experiment policy in lightweight rooms", async () => {
- const harness = await startHarness({ peerAssistedMedia: false });
+ it("broadcasts configured NAT prediction in lightweight rooms", async () => {
+ const harness = await startHarness({
+ peerAssistedMedia: false,
+ stunUrls: ["stun:share.example.test:3478"],
+ natPredictionEnabled: true,
+ });
const waitingViewer = await openClient(harness.webSocketUrl);
const waiting = await authenticate(
waitingViewer,
@@ -546,23 +554,47 @@ describe("WebSocket signaling", () => {
expect(joined.routePolicy).toEqual(routePolicy);
});
- it("delivers independent NAT experiment STUN without changing ordinary ICE", async () => {
+ it("clamps NAT prediction off when the server capability is disabled", async () => {
+ const harness = await startHarness({ peerAssistedMedia: false });
+ const host = await openClient(harness.webSocketUrl);
+ const authenticated = await authenticate(
+ host,
+ harness.room,
+ "host",
+ "disabled-nat-host",
+ null,
+ "disabled_nat_share_generation_12345678",
+ {
+ routePolicy: {
+ ...DEFAULT_ROUTE_POLICY,
+ natPrediction: true,
+ },
+ },
+ );
+
+ expect(authenticated.routePolicy.natPrediction).toBe(false);
+ });
+
+ it("delivers only self-hosted auxiliary NAT STUN endpoints", async () => {
const harness = await startHarness({
stunUrls: ["stun:ordinary.example.test:3478"],
- natPredictionStunUrls: ["stun:observer.example.test:3478"],
+ natPredictionEnabled: true,
});
const viewer = await openClient(harness.webSocketUrl);
const authenticated = await authenticate(
viewer,
harness.room,
"viewer",
- "nat-observer-viewer",
+ "nat-auxiliary-viewer",
null,
);
expect(authenticated.iceConfig).toEqual({
iceServers: [{ urls: ["stun:ordinary.example.test:3478"] }],
- natPredictionStunUrls: ["stun:observer.example.test:3478"],
+ natPredictionStunUrls: [
+ "stun:ordinary.example.test:3479",
+ "stun:ordinary.example.test:3480",
+ ],
});
});
diff --git a/tests/viewer-peer-generation.test.ts b/tests/viewer-peer-generation.test.ts
index 71aed7ae..80c1be08 100644
--- a/tests/viewer-peer-generation.test.ts
+++ b/tests/viewer-peer-generation.test.ts
@@ -344,7 +344,10 @@ describe("ViewerPeer connection generations", () => {
[],
{
iceServers: [{ urls: "stun:share.example.test:3478" }],
- natPredictionStunUrls: ["stun:observer.example.test:3478"],
+ natPredictionStunUrls: [
+ "stun:share.example.test:3479",
+ "stun:share.example.test:3480",
+ ],
},
true,
);
@@ -354,7 +357,6 @@ describe("ViewerPeer connection generations", () => {
{ urls: "stun:share.example.test:3478" },
{ urls: "stun:share.example.test:3479" },
{ urls: "stun:share.example.test:3480" },
- { urls: "stun:observer.example.test:3478" },
]);
const surveyUrls = [