@fairfox/polly 0.53.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
@@ -89,6 +104,20 @@ export interface CreateMeshClientOptions {
          * `examples/mesh-recovery-pair`). Forwarded straight to
          * {@link MeshWebRTCAdapterOptions.knownPeersRefreshIntervalMs}. */
         knownPeersRefreshIntervalMs?: MeshWebRTCAdapterOptions["knownPeersRefreshIntervalMs"];
+        /** Forward of {@link MeshWebRTCAdapterOptions.syncYieldEnabled}.
+         * Defaults to `true`. The `examples/mesh-large-initial-sync`
+         * example flips this to `false` when `POLLY_104_DISABLE_FIX=1` is
+         * set, to demonstrate the pre-#104 tight-loop behaviour against
+         * post-fix polly. Production callers should leave this at the
+         * default. */
+        syncYieldEnabled?: MeshWebRTCAdapterOptions["syncYieldEnabled"];
+        /** Forward of
+         * {@link MeshWebRTCAdapterOptions.syncFragmentChunkSizeOverride}.
+         * Production callers should leave this undefined. The
+         * `examples/mesh-large-initial-sync` example passes 64 KiB when
+         * `POLLY_104_DISABLE_FIX=1` to recreate the pre-#104
+         * fragmentation bug. */
+        syncFragmentChunkSizeOverride?: MeshWebRTCAdapterOptions["syncFragmentChunkSizeOverride"];
     };
     /** The local peer's keyring — one of three shapes:
      *
@@ -172,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. */
@@ -111,6 +132,115 @@ export interface MeshWebRTCAdapterOptions {
      * (e.g. `werift` or `@roamhq/wrtc`) when running outside a browser, or
      * to use a custom subclass for tests or instrumentation. */
     RTCPeerConnection?: typeof RTCPeerConnection;
+    /** When `true` (the default), the adapter yields to the event loop
+     * between the points where a large initial sync would otherwise hold
+     * the main thread for tens of seconds: between each batch of
+     * fragmented `RTCDataChannel.send` calls on the sender side, and at
+     * the boundary between reassembling a sync message and dispatching
+     * it (deserialise → MeshNetworkAdapter unwrap → Automerge
+     * `applyChanges`) on the receiver side. Set to `false` to recover
+     * the pre-#104 tight-loop behaviour; this is the configuration the
+     * `POLLY_104_DISABLE_FIX=1` falsification path in
+     * `examples/mesh-large-initial-sync` uses to demonstrate the bug
+     * against post-fix polly. Production callers should leave this at
+     * the default. */
+    syncYieldEnabled?: boolean;
+    /** Override the sync fragment chunk size. Defaults to
+     * {@link SYNC_FRAGMENT_CHUNK_SIZE} (60 KiB), which leaves header
+     * overhead inside werift's hard 64 KiB max-message-size cap.
+     * Setting this to 64 KiB recreates the pre-#104 fragmentation bug,
+     * where peer A's outbound fragments overshoot the cap and werift
+     * rejects them silently — sync stalls forever. Used by the
+     * `POLLY_104_DISABLE_FIX=1` falsification path. Production callers
+     * should leave this at the default. */
+    syncFragmentChunkSizeOverride?: number;
+}
+/** Payload of the polly-specific `"sync-progress"` event emitted by
+ * {@link MeshWebRTCAdapter}. Consumers can subscribe via the adapter's
+ * standard `.on()` surface (the same one that carries `peer-candidate`
+ * and `peer-disconnected`) to observe fragment receive and dispatch
+ * activity in real time, without polling
+ * {@link MeshWebRTCAdapter.getPeerStateSnapshot}. Polly issue #104
+ * item 7. */
+export interface SyncProgressEvent {
+    /** Remote peer the fragment or dispatch is for. */
+    peerId: string;
+    /** Lifecycle stage. `fragment-received` fires for each chunk that
+     * arrives during reassembly; `dispatch-applied` fires once the
+     * reassembled message has been emitted upward to Automerge. */
+    kind: "fragment-received" | "dispatch-applied";
+    /** Bytes carried by the chunk that triggered the event. Zero for
+     * `dispatch-applied`. */
+    bytesDelta: number;
+    /** Running total of fragments received for the current reassembly. */
+    chunksReceived: number;
+    /** Running total of bytes received for the current reassembly. */
+    bytesReceived: number;
+    /** Number of reassembled messages whose dispatch has been scheduled
+     * but not yet emitted upward to Automerge. */
+    applyBacklog: number;
+    /** `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
+ * reassembled message has been dispatched. Exposed verbatim through
+ * {@link MeshWebRTCAdapter.getPeerStateSnapshot} so a consumer
+ * harness can observe progress mid-stream. Polly issue #104 item 7. */
+export interface InFlightSyncSnapshot {
+    /** Fragments received for the current reassembly. Cleared once
+     * reassembly completes. */
+    chunksReceived: number;
+    /** Bytes received across the fragments of the current reassembly.
+     * The reassembled message will be slightly smaller than this sum
+     * because each fragment carries a small header. */
+    bytesReceived: number;
+    /** `performance.now()` value at the last fragment arrival. */
+    lastChunkAt: number;
+    /** Count of reassembled messages whose dispatch has been
+     * scheduled but not yet run. With the receiver-side `setTimeout(0)`
+     * yield enabled, this is normally 0 or 1; with the yield
+     * disabled (the falsification path) dispatch runs synchronously
+     * and this stays 0. */
+    applyBacklog: number;
 }
 /**
  * Automerge-Repo NetworkAdapter backed by real WebRTC data channels.
@@ -120,6 +250,8 @@ export interface MeshWebRTCAdapterOptions {
 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
@@ -142,6 +274,17 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * {@link MeshWebRTCAdapterOptions.knownPeersRefreshIntervalMs} at
      * construction. Defaults to 2000ms; tests override to 100–250ms. */
     private readonly knownPeersRefreshIntervalMs;
+    /** When `true`, the sender side awaits between batches of fragment
+     * sends and the receiver side schedules dispatch via `setTimeout(0)`
+     * so the JS event loop can drain timers (including the consumer's
+     * own setInterval-based liveness probes) between large-message
+     * apply calls. Defaults to `true`; set to `false` only by the
+     * `POLLY_104_DISABLE_FIX` falsification path. */
+    private readonly syncYieldEnabled;
+    /** Resolved chunk size for fragmenting oversized messages.
+     * Defaults to {@link SYNC_FRAGMENT_CHUNK_SIZE}; can be overridden
+     * via {@link MeshWebRTCAdapterOptions.syncFragmentChunkSizeOverride}. */
+    private readonly syncFragmentChunkSize;
     /** Peers currently visible in the signalling roster — populated by
      * {@link handlePeersPresent} / {@link handlePeerJoined} and pruned by
      * {@link handlePeerLeft}. Read by {@link addKnownPeer} to decide
@@ -216,6 +359,8 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
                 dataChannelState: string;
                 pendingSendCount: number;
                 pendingRemoteIceCount: number;
+                inFlightSync: InFlightSyncSnapshot | undefined;
+                transport: TransportSnapshot | undefined;
             };
         }>;
     };
@@ -293,13 +438,30 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * queued until the data channel is open.
      */
     send(message: Message): void;
+    /** Number of consecutive fragment sends after which the sender
+     * yields to the macrotask queue when {@link syncYieldEnabled} is on.
+     * 8 × 64 KiB = 512 KiB of bytes between yields — small enough that
+     * a 5 MB sync produces many yield points (and the JS event loop
+     * drains the consumer's `setInterval` liveness probes between
+     * them), large enough that the per-yield overhead does not dominate
+     * the wire cost. */
+    private static readonly SEND_YIELD_EVERY_N_FRAGMENTS;
     /** Send raw wire bytes, fragmenting if they exceed the SCTP maxMessageSize
      *  cap. The default RTCDataChannel limit is 256 KiB in current Chrome and
      *  werift; oversized sends either throw, drop silently, or stall the
      *  channel, none of which surface as an error to the caller. Fragments
      *  use the same length-prefixed JSON header wire format as ordinary
      *  messages but carry a `sync-fragment` type that the receive path
-     *  detects and reassembles before deserialising. */
+     *  detects and reassembles before deserialising.
+     *
+     *  When {@link MeshWebRTCAdapterOptions.syncYieldEnabled} is true (the
+     *  default), the loop awaits the macrotask queue every
+     *  {@link SEND_YIELD_EVERY_N_FRAGMENTS} fragments so the JS event
+     *  loop drains between batches — without this, a 5–8 MB initial
+     *  sync produces 78–125 back-to-back `RTCDataChannel.send` calls in
+     *  a tight loop, starving anything else on the main thread (polly
+     *  issue #104, sender side). When the option is false the legacy
+     *  tight-loop shape is preserved for the falsification path. */
     private sendBytesMaybeFragmented;
     /**
      * Entry point the signalling client calls when it receives a signal
@@ -310,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;
@@ -322,8 +522,47 @@ 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
+     * {@link MeshWebRTCAdapterOptions.syncYieldEnabled} is true (the
+     * default), the emit runs on a fresh macrotask so the crypto-unwrap
+     * and Automerge `applyChanges` chain downstream of this method does
+     * not sit on the same JS stack frame as the wire `onmessage` callback
+     * — that's the receiver-side starvation site polly issue #104
+     * documents. When the option is false the emit is synchronous,
+     * recovering the pre-fix shape used by the falsification path.
+     *
+     * The `viaFragmentPath` argument tags whether this dispatch came out
+     * of a reassembled fragment chain; only those carry an
+     * `inFlightSync` reassembly state worth bookkeeping. Small
+     * single-message dispatches yield but don't touch inFlightSync. */
+    private scheduleEmitMessage;
+    private finishInFlightSyncApply;
+    private emitSyncProgress;
     private handleSyncFragment;
+    /** Dispatch a reassembled fragment payload back through
+     * {@link dispatchMessage}, but tagged so the
+     * {@link scheduleEmitMessage} path knows it owes a
+     * `finishInFlightSyncApply` afterwards. Synchronous re-entry into
+     * `dispatchMessage` would lose that signal, so the post-fragment
+     * deserialise+emit is inlined here. */
+    private dispatchReassembled;
     /** Peer IDs with an open data channel, suitable for blob requests. */
     get connectedPeerIds(): string[];
     /** Send a pre-serialised blob message to a specific peer. Returns false

package/dist/src/shared/lib/sync-fragment.d.ts

@@ -17,12 +17,23 @@
  * does not mistake a sync fragment for a blob chunk.
  */
 /** Maximum bytes a single channel.send may carry without fragmentation.
- *  Chosen well below the 256 KiB SCTP cap so the framing header for a
- *  single chunk cannot push the wire frame over the limit. Matches the
- *  blob-transfer chunk size so the two transports have a consistent
- *  per-message footprint on the data channel. */
+ *  Werift (the node-side WebRTC implementation polly recommends for
+ *  CLI/daemon use) enforces a hard 64 KiB (65536 bytes) maxMessageSize
+ *  on its RTCDataChannel — anything larger is rejected with a
+ *  `max-message-size exceeded` error and silently drops the channel
+ *  for that send. Chrome's SCTP cap is 256 KiB and would tolerate
+ *  larger frames, but the threshold is chosen to fit inside werift's
+ *  cap WITH per-fragment header overhead included so a single mesh
+ *  deployment works on both transports. Matches the blob-transfer
+ *  chunk size so the two transports have a consistent per-message
+ *  footprint on the data channel. */
 export declare const SYNC_FRAGMENT_THRESHOLD: number;
-/** Chunk size used when a message exceeds the threshold. */
+/** Chunk size used when a message exceeds the threshold. Left at the
+ *  same value as {@link SYNC_FRAGMENT_THRESHOLD} so the framing
+ *  header (a JSON-encoded `SyncFragmentHeader` of ~90 bytes plus a
+ *  4-byte length prefix) does not push any fragment over werift's
+ *  64 KiB wire limit — see polly issue #104 for the failure mode
+ *  this guards against. */
 export declare const SYNC_FRAGMENT_CHUNK_SIZE: number;
 export interface SyncFragmentHeader {
     type: "sync-fragment";

package/package.json

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