@fairfox/polly 0.53.0 → 0.54.0

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

@@ -89,6 +89,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:
      *

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

@@ -111,6 +111,78 @@ 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;
+}
+/** 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.
@@ -142,6 +214,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 +299,7 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
                 dataChannelState: string;
                 pendingSendCount: number;
                 pendingRemoteIceCount: number;
+                inFlightSync: InFlightSyncSnapshot | undefined;
             };
         }>;
     };
@@ -293,13 +377,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
@@ -323,7 +424,31 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
     private wireConnection;
     private wireDataChannel;
     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.54.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",