@fairfox/polly 0.54.0 → 0.56.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,138 @@ 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;
+}
+/** Reasons the adapter declined to construct an RTC slot for a peer
+ * that appeared in the signalling roster or the keyring. Recorded
+ * per-peer in {@link MeshWebRTCAdapter.getPeerStateSnapshot} so a
+ * consumer harness observing "(no slot)" can tell which gate inside
+ * the adapter stopped construction without having to log-correlate
+ * through three layers of timing. Polly issue #106 item 7.
+ *
+ * - `self`: the peerId equals the local peerId.
+ * - `not-in-keyring`: the live keyring (or captured Set) does not
+ *   currently authorise this peer.
+ * - `not-present`: the peer is not in the signalling roster. The
+ *   adapter only dials peers it has heard about through
+ *   `peers-present` or `peer-joined`; keyring entries that have not
+ *   appeared on signalling are quietly held without a slot.
+ * - `tie-break-other-side`: the lex-tie-break designates the remote
+ *   peer as the initiator; we wait for their offer.
+ * - `slot-already-exists`: a slot exists already, possibly in any
+ *   negotiation state.
+ * - `fatal-error`: an exception was thrown while attempting to build
+ *   the slot. The accompanying {@link SlotInitiationDecision.error}
+ *   string carries the message.
+ */
+export type SlotInitiationRejectionReason = "self" | "not-in-keyring" | "not-present" | "tie-break-other-side" | "slot-already-exists" | "fatal-error";
+/** Most-recent slot-initiation decision for a peer. Computed at
+ * snapshot time so the view always reflects the current state of the
+ * relevant gates; a `decision === "accepted"` value paired with a
+ * `slot === undefined` view on the same snapshot is the load-bearing
+ * signal for "the adapter wants to dial but isn't" — the failure
+ * shape polly#106 documents. */
+export interface SlotInitiationDecision {
+    /** "accepted" means every gate in `shouldInitiateTo` would pass right
+     * now and a sweep tick would construct a slot. "rejected" means at
+     * least one gate failed; the `reason` names it. */
+    decision: "accepted" | "rejected";
+    /** Populated only on `rejected` decisions. */
+    reason: SlotInitiationRejectionReason | undefined;
+    /** If the previous sweep tick caught a synchronous throw while
+     * building this peer's slot, the message is preserved here for the
+     * next snapshot. The reason will be `fatal-error`. */
+    error: string | undefined;
+    /** `performance.now()` at the time the decision was computed. */
+    at: number;
+}
+/** Most-recent sync-handshake timeline for a peer slot. Each timestamp
+ * is `performance.now()` of the corresponding event the first time it
+ * fired on the current slot — slots that get evicted and rebuilt start
+ * over. The four fields together describe whether the adapter and the
+ * receiver downstream of it have done their part in initiating sync:
+ *
+ * - `dataChannelOpenedAt`: when the wire is ready to carry bytes.
+ * - `peerCandidateEmittedAt`: when polly emitted `peer-candidate`
+ *   upward; Automerge's network subsystem hooks this event to add the
+ *   peer to its known set and kick off the per-document sync exchange.
+ *   If this is `undefined` long after the data channel has opened,
+ *   polly never signalled "ready" to Automerge — that's a failure in
+ *   the adapter.
+ * - `firstOutboundSendAt`: when polly first dispatched bytes through
+ *   {@link MeshWebRTCAdapter.send} for this peer. If
+ *   `peerCandidateEmittedAt` is set but this is still `undefined`, the
+ *   wrapper above polly (Automerge's NetworkSubsystem, MeshNetworkAdapter)
+ *   never asked the adapter to send anything; that's a failure
+ *   upstream of polly.
+ * - `firstInboundMessageAt`: when polly first emitted a `message` event
+ *   for this peer. If `peerCandidateEmittedAt` is set on the remote and
+ *   `firstOutboundSendAt` is set on the remote but this is `undefined`
+ *   locally, bytes were sent across the wire but never decoded — that
+ *   points at the crypto envelope or the wire fragmenter.
+ *
+ * Polly issue #106 item 7. */
+export interface SyncHandshakeAttemptSnapshot {
+    dataChannelOpenedAt: number | undefined;
+    peerCandidateEmittedAt: number | undefined;
+    firstOutboundSendAt: number | undefined;
+    firstInboundMessageAt: number | undefined;
+}
+/** Sweep-loop observability for the periodic dial re-evaluation. The
+ * sweep is what catches peers that were not in the keyring at the time
+ * of their `peer-joined` notification (polly#103) AND peers whose
+ * previous slot failed and got evicted (polly#106). Exposing its tick
+ * counter lets a consumer distinguish "sweep is running but
+ * `shouldInitiateTo` rejected the peer" from "sweep is broken and
+ * never fires" without instrumenting polly internals. */
+export interface SweepSnapshot {
+    /** True iff the sweep timer is currently scheduled — false on the
+     * captured-set fallback path (no keyringSource) or when the interval
+     * is configured to 0. */
+    enabled: boolean;
+    /** Configured interval in milliseconds. 0 means disabled. */
+    intervalMs: number;
+    /** How many times the sweep callback has fired since `connect()`. */
+    runCount: number;
+    /** `performance.now()` at the last tick. `undefined` until the
+     * first tick fires. */
+    lastRunAt: number | undefined;
+}
 /** 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 +345,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
@@ -241,6 +396,21 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
     private readonly slots;
     private ready;
     private readyResolver;
+    /** Sticky cache of the most recent {@link SlotInitiationDecision}
+     * per peer. Updated on every `shouldInitiateTo` call and on every
+     * caught throw inside the sweep loop, so a snapshot taken at any
+     * moment can answer "why is there no slot for this peer right
+     * now?". Polly issue #106 item 7. */
+    private readonly lastSlotInitiationDecisions;
+    /** Tick count of the periodic sweep — incremented inside the
+     * `setInterval` callback, exposed via {@link getPeerStateSnapshot}.
+     * Lets a consumer rule out "sweep is dead" before chasing the
+     * shouldInitiateTo gates. */
+    private sweepRunCount;
+    /** `performance.now()` at the last sweep tick. Paired with
+     * {@link sweepRunCount} so a stalled sweep is visible at a glance
+     * via the snapshot's `sweep` block. */
+    private lastSweepAt;
     /** The peers this adapter will dial. Backward-compatible read accessor
      * for callers that previously iterated the `knownPeerIds` array. With
      * a {@link MeshWebRTCAdapterOptions.keyringSource} configured, the
@@ -288,10 +458,13 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
         localPeerId: string;
         knownPeerIds: string[];
         presentPeerIds: string[];
+        sweep: SweepSnapshot;
         peers: Array<{
             peerId: string;
             knownInKeyring: boolean;
             presentInSignalling: boolean;
+            slotInitiationRejectionReason: SlotInitiationRejectionReason | undefined;
+            slotInitiationDecision: SlotInitiationDecision;
             slot: undefined | {
                 signalingState: string;
                 iceConnectionState: string;
@@ -300,6 +473,8 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
                 pendingSendCount: number;
                 pendingRemoteIceCount: number;
                 inFlightSync: InFlightSyncSnapshot | undefined;
+                transport: TransportSnapshot | undefined;
+                lastSyncHandshakeAttempt: SyncHandshakeAttemptSnapshot;
             };
         }>;
     };
@@ -317,6 +492,17 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * every listed peer, so a device joining into an established lobby
      * dials every knownPeer it is meant to initiate to in one pass. */
     handlePeersPresent(peerIds: string[]): void;
+    /** Construct an initiating slot inside a per-peer try/catch and
+     * record any throw as a `fatal-error` rejection on the per-peer
+     * decision map so the snapshot surface names it. Every dial entry
+     * point ({@link handlePeerJoined}, {@link handlePeersPresent},
+     * {@link addKnownPeer}, {@link refreshKnownPeers}) routes through
+     * here so a single peer's broken construction can never take down a
+     * batch of peers — pre-#106 a thrown `new RTCPeerConnection()`
+     * inside `handlePeersPresent` would skip every later peer in the
+     * same batch with no observable trace because the signalling
+     * client's frame dispatch swallowed the rejection. */
+    private tryCreateInitiatingSlot;
     /** Handle the signalling server's `peer-left` notification: a
      * previously joined peer has closed its socket. Evict any slot we
      * hold for that peer so a subsequent `peer-joined` from the same
@@ -345,9 +531,41 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * dial the ones the keyring authorises that we do not already have
      * a slot for. The periodic sweep started in {@link connect} calls
      * this; consumers can call it manually to skip the wait after they
-     * apply a fresh pairing token. Idempotent. */
+     * apply a fresh pairing token. Idempotent.
+     *
+     * A throw from {@link createInitiatingSlot} for one peer must not
+     * prevent the sweep from continuing to the next one — pre-#106 a
+     * synchronous throw inside `new RTCPeerConnection()` (a real risk
+     * once the page has built dozens of connections and Chrome's
+     * per-page cap is in play) skipped every later peer in the same
+     * sweep, with no observable trace because `setInterval` swallows
+     * the rejection silently. {@link tryCreateInitiatingSlot} caches
+     * the error onto the snapshot's slotInitiationRejectionReason as
+     * `fatal-error` so the failing peer is named instead of disguised
+     * as "(no slot)". */
     refreshKnownPeers(): void;
     private shouldInitiateTo;
+    /** Pure-function form of the gate cascade behind {@link shouldInitiateTo}.
+     * Returns `undefined` when every gate passes (the slot would be
+     * built); otherwise returns the named reason the dial was declined.
+     * Pulling the gates out of the boolean wrapper lets the snapshot
+     * surface name *which* gate stopped construction without the caller
+     * having to re-implement the check. Polly issue #106 item 7.
+     *
+     * The "not-present" gate is checked here even though the inbound
+     * call sites (`handlePeerJoined`, `handlePeersPresent`,
+     * `refreshKnownPeers`, `addKnownPeer`) only invoke `shouldInitiateTo`
+     * for peers in the signalling roster — so on those paths the gate
+     * never fires. It's load-bearing on the snapshot path, where the
+     * reason is computed for every peer the caller might ask about
+     * (including keyring entries that aren't currently signalling). */
+    private evaluateInitiation;
+    /** Compute the latest initiation decision for a peer at snapshot
+     * time. Prefers the cached decision when a sweep tick fixed the
+     * outcome to `fatal-error` (a thrown construction is sticky until
+     * the next successful sweep clears it); otherwise re-evaluates the
+     * gates against current state. Pure read; never mutates the map. */
+    private snapshotInitiationDecision;
     whenReady(): Promise<void>;
     /**
      * Start the adapter. Marks the adapter ready so Automerge's
@@ -367,7 +585,15 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * keyring after their `peer-joined` notification has already fired.
      * No-op when no keyringSource was supplied — the captured-set
      * fallback has no live source to re-read, so the sweep would be
-     * useless. No-op when the interval is configured to 0. */
+     * useless. No-op when the interval is configured to 0.
+     *
+     * Each tick increments {@link sweepRunCount} and stamps
+     * {@link lastSweepAt} *before* dispatching to
+     * {@link refreshKnownPeers} so a snapshot can distinguish "sweep is
+     * running but every peer is rejected" from "sweep is dead". An
+     * outer try/catch keeps the timer alive even if the per-peer
+     * try/catch inside `refreshKnownPeers` somehow leaks. Polly issue
+     * #106 item 7. */
     private startKnownPeersSweep;
     private stopKnownPeersSweep;
     /**
@@ -411,6 +637,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;
@@ -422,7 +686,35 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * them — a single bad candidate must not stall the connection. */
     private flushPendingRemoteIce;
     private wireConnection;
+    /** Emit `peer-candidate` upward exactly once per slot lifetime,
+     * stamping the slot's `lastSyncHandshakeAttempt.peerCandidateEmittedAt`
+     * with the moment of emission. The "once" semantics protect Automerge's
+     * NetworkSubsystem from a double-add when both the
+     * `connectionstatechange = connected` event AND the
+     * `dataChannel.onopen` event fire on the same slot — under werift
+     * the former is sometimes flaky, under Chrome the latter sometimes
+     * fires first; pre-#106 only the connection-state path emitted, so a
+     * werift slot whose data channel opened cleanly but whose connection
+     * state never advanced past `connecting` would never signal "ready"
+     * upward. Polly issue #106 Failure B item — closing one named
+     * mechanism for "data channel open, sync never started". */
+    private emitPeerCandidateOnce;
     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
@@ -439,6 +731,11 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * `inFlightSync` reassembly state worth bookkeeping. Small
      * single-message dispatches yield but don't touch inFlightSync. */
     private scheduleEmitMessage;
+    /** Stamp the slot's `firstInboundMessageAt` the first time a
+     * dispatched (non-fragment, non-blob) message lands for a peer. Pure
+     * observability for {@link SyncHandshakeAttemptSnapshot}; does not
+     * affect dispatch. */
+    private stampFirstInboundMessage;
     private finishInFlightSyncApply;
     private emitSyncProgress;
     private handleSyncFragment;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.54.0",
+  "version": "0.56.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",