@fairfox/polly 0.54.0 → 0.55.0

package/dist/src/shared/lib/mesh-client.d.ts

@@ -75,6 +75,21 @@ export interface CreateMeshClientOptions {
          * the credential window closes.
          */
         iceCredentialResolver?: () => Promise<RTCIceServer[]>;
+        /** Forward of {@link MeshWebRTCAdapterOptions.iceTransportPolicy}.
+         * Set to `"relay"` to force every candidate pair through TURN; the
+         * default leaves the underlying {@link RTCPeerConnection}
+         * implementation's default in place. The
+         * `examples/mesh-large-initial-sync-turn` harness uses `"relay"` to
+         * exercise the polly#105 real-transport contract. */
+        iceTransportPolicy?: MeshWebRTCAdapterOptions["iceTransportPolicy"];
+        /** Forward of {@link MeshWebRTCAdapterOptions.iceRelayEnforcement}.
+         * Defaults to `true`. Set to `false` to bypass the polly#105
+         * relay-only enforcement layer; the
+         * `examples/mesh-large-initial-sync-turn` falsification path
+         * (`POLLY_105_DISABLE_TURN_FIX=1`) does this to reproduce the
+         * pre-#105 candidate-leak shape. Production callers should leave
+         * this at the default. */
+        iceRelayEnforcement?: MeshWebRTCAdapterOptions["iceRelayEnforcement"];
         dataChannelLabel?: string;
         /** How often the mesh client re-evaluates whether to dial peers
          * already present in the signalling roster against the live
@@ -186,6 +201,14 @@ export interface MeshClient {
      * harness can answer "is the mesh layer in a known good state"
      * without instrumenting polly internals. Polly issue #103 item 7. */
     getPeerStateSnapshot(): ReturnType<MeshWebRTCAdapter["getPeerStateSnapshot"]>;
+    /** Refresh every active peer slot's transport-level summary —
+     * selected ICE candidate pair, SCTP retransmission counters, last
+     * data-channel error — and populate it into the next
+     * {@link getPeerStateSnapshot}. Walks {@link RTCPeerConnection.getStats}
+     * once per peer, so it isn't free; consumers that want continuous
+     * visibility should call this on a polling cadence the cost can
+     * absorb. Polly issue #105 item 7. */
+    refreshTransportStats(): Promise<void>;
     /** Close the signalling WebSocket, tear down every RTCPeerConnection,
      * and shut the Repo cleanly. Idempotent. */
     close(): Promise<void>;

package/dist/src/shared/lib/mesh-webrtc-adapter.d.ts

@@ -102,6 +102,27 @@ export interface MeshWebRTCAdapterOptions {
     knownPeersRefreshIntervalMs?: number;
     /** Optional ICE server list override. Defaults to {@link DEFAULT_ICE_SERVERS}. */
     iceServers?: RTCIceServer[];
+    /** Optional ICE transport policy. Defaults to the
+     * {@link RTCPeerConnection} implementation's own default (`"all"` in
+     * Chrome, Firefox, and werift). Set to `"relay"` to force every
+     * candidate pair through a TURN relay — the shape the polly#105
+     * falsification harness needs to exercise the real-transport contract
+     * the polly#104 in-process throttle could not reach. */
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    /** When `true` (the default), polly enforces
+     * {@link iceTransportPolicy} `"relay"` on its side of the signalling
+     * channel by filtering non-relay ICE candidates out of both the SDP
+     * description it forwards and the trickle ICE stream it emits. This
+     * closes the gap exposed by polly#105: Chrome's implementation
+     * already filters at the source, but werift only filters its own
+     * outgoing connectivity checks and still advertises host and srflx
+     * candidates upstream — so a relay-only peer on werift will, against
+     * a peer with the default policy, still pair through a non-relay
+     * candidate (or against a host-derived peer-reflexive remote).
+     * Setting this option to `false` reverts the enforcement and is the
+     * shape used by the `POLLY_105_DISABLE_TURN_FIX=1` falsification
+     * path. Production callers should leave this at the default. */
+    iceRelayEnforcement?: boolean;
     /** Optional data channel label. Defaults to "polly-mesh". Applications
      * that share a signalling server between multiple meshes may want
      * distinct labels per mesh. */
@@ -161,6 +182,43 @@ export interface SyncProgressEvent {
     /** `performance.now()` at event emission. */
     at: number;
 }
+/** Last-seen transport-level summary for a peer slot. Populated
+ * lazily by {@link MeshWebRTCAdapter.refreshTransportStats}, which
+ * the consumer calls (typically from a polling loop in a debugging
+ * harness) so the cost of {@link RTCPeerConnection.getStats} is
+ * incurred only on demand. Polly issue #105 item 7 — exposes the
+ * dimension of the transport that {@link InFlightSyncSnapshot}
+ * doesn't reach: the negotiated ICE candidate pair, the SCTP
+ * retransmission counters, and the last data-channel-level error if
+ * one has been observed.
+ *
+ * Field names mirror the W3C stats spec (`selectedCandidatePairId`,
+ * `localCandidateType`, etc.) so consumers can correlate with the
+ * raw `RTCStatsReport`. werift exposes a stats shape close to the
+ * spec; Chrome exposes the spec itself; this view is implementation-
+ * agnostic. */
+export interface TransportSnapshot {
+    /** ICE-level summary of the pair currently carrying data. */
+    selectedCandidatePair: {
+        localCandidateType: string;
+        remoteCandidateType: string;
+        state: string;
+        nominated: boolean;
+        bytesSent: number;
+        bytesReceived: number;
+    } | undefined;
+    /** SCTP / data-channel retransmission counters. Some implementations
+     * surface these on the transport stat, others on the data-channel
+     * stat — we expose the values we found, leaving the field undefined
+     * when the underlying impl doesn't surface them. */
+    retransmittedPacketsSent: number | undefined;
+    retransmittedBytesSent: number | undefined;
+    /** Most-recent data-channel error message, if `error` ever fired on
+     * the channel for this peer. Cleared only when the slot is replaced. */
+    lastDataChannelError: string | undefined;
+    /** `performance.now()` at the time the stats were last refreshed. */
+    at: number;
+}
 /** Per-peer view of an in-flight initial sync. Populated by
  * {@link MeshWebRTCAdapter.handleSyncFragment} as fragments of a
  * single reassembly arrive, and reset to `undefined` once the
@@ -192,6 +250,8 @@ export interface InFlightSyncSnapshot {
 export declare class MeshWebRTCAdapter extends NetworkAdapter {
     readonly signaling: MeshSignalingClient;
     readonly iceServers: RTCIceServer[];
+    readonly iceTransportPolicy: RTCIceTransportPolicy | undefined;
+    private readonly iceRelayEnforcement;
     readonly dataChannelLabel: string;
     /** Peers this adapter is willing to dial. Mutable so callers that pair
      * a new device after construction (e.g. a CLI `add-device` process whose
@@ -300,6 +360,7 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
                 pendingSendCount: number;
                 pendingRemoteIceCount: number;
                 inFlightSync: InFlightSyncSnapshot | undefined;
+                transport: TransportSnapshot | undefined;
             };
         }>;
     };
@@ -411,6 +472,44 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * method.
      */
     handleSignal(fromPeerId: string, rawPayload: unknown): void;
+    /** Assemble the {@link RTCConfiguration} every new
+     * {@link RTCPeerConnection} is built with. Centralised so every slot
+     * (initiator and answerer) honours the same iceTransportPolicy. */
+    private buildRtcConfiguration;
+    /** Decide whether a local ICE candidate should be relayed through
+     * the signalling channel to the remote peer. Chrome's iceTransport
+     * Policy = "relay" implementation filters non-relay candidates at
+     * the source so the remote peer never sees them; werift's only
+     * filters its own outgoing connectivity checks and still emits host
+     * and srflx candidates upstream, so a remote peer with policy "all"
+     * can pair against them — making relay-only enforcement leaky in
+     * the mixed-implementation case the polly#105 falsification harness
+     * exposes. Mirroring Chrome's filter at this layer gives a uniform
+     * contract on every RTCPeerConnection implementation polly supports.
+     *
+     * The candidate `type` field is the SDP-spec form; we additionally
+     * parse it out of the legacy `candidate` string for implementations
+     * that don't surface the typed field directly (werift exposes the
+     * SDP string only). */
+    private isRelayCandidateInit;
+    private shouldSendCandidate;
+    /** Strip non-relay `a=candidate:` lines from an SDP when
+     * iceTransportPolicy is `"relay"`. Some RTCPeerConnection
+     * implementations (werift, notably) embed every gathered candidate
+     * in the SDP regardless of policy, and a remote peer parsing those
+     * via `setRemoteDescription` will pair against them — bypassing the
+     * relay-only contract. Chrome already filters in-SDP candidates by
+     * policy, so this is only load-bearing for werift consumers, but
+     * the SDP rewrite is implementation-agnostic and idempotent. */
+    private filterSdpCandidatesByPolicy;
+    /** Apply {@link filterSdpCandidatesByPolicy} to an SDP
+     * description ahead of `setLocalDescription` (filter outgoing) or
+     * `setRemoteDescription` (filter incoming). The defensive
+     * receive-side filter exists because we cannot trust the remote
+     * peer's adapter to have stripped its non-relay candidates first —
+     * polly might be talking to a pre-#105 polly, or to a non-polly
+     * peer whose policy enforcement is different. */
+    private applySdpPolicyFilter;
     private createInitiatingSlot;
     private initiateOffer;
     private handleOffer;
@@ -423,6 +522,21 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
     private flushPendingRemoteIce;
     private wireConnection;
     private wireDataChannel;
+    /** Refresh the per-peer {@link TransportSnapshot} for one peer by
+     * pulling {@link RTCPeerConnection.getStats} and distilling the
+     * result. Cheap-ish but not free — getStats walks the underlying
+     * stats graph — so this is opt-in: callers (typically a debugging
+     * harness or a periodic observability loop) invoke it explicitly
+     * and the result lives on the slot for the next
+     * {@link getPeerStateSnapshot}. Returns the refreshed snapshot, or
+     * `undefined` if there is no slot for the peer or stats are
+     * unavailable. Polly issue #105 item 7. */
+    refreshTransportStats(peerId: string): Promise<TransportSnapshot | undefined>;
+    /** Refresh transport stats for every active peer slot in one shot.
+     * Returns a map keyed by peerId so a caller can render the result
+     * without re-walking {@link getPeerStateSnapshot}. The underlying
+     * `getStats` calls run concurrently. */
+    refreshAllTransportStats(): Promise<Map<string, TransportSnapshot>>;
     private dispatchMessage;
     /** Hand a deserialised Automerge message off to whoever is listening
      * on this adapter's `"message"` event. When

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "private": false,
   "type": "module",
   "description": "Multi-execution-context framework with reactive state and cross-context messaging for Chrome extensions, PWAs, and worker-based applications",