@fairfox/polly 0.63.0 → 0.65.0

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

@@ -51,6 +51,30 @@ import type { MeshSignalingClient } from "./mesh-signaling-client";
  * need TURN fallback for peers behind symmetric NATs should replace this
  * with their own ICE server list. */
 export declare const DEFAULT_ICE_SERVERS: RTCIceServer[];
+/** Polly issue #109: how long a slot can sit at `connectionState` in
+ * `new` or `connecting` before the watchdog tears it down so the
+ * recovery sweep can re-attempt. Healthy ICE completes in single-digit
+ * seconds; 30s is well past anything legitimate and short enough that
+ * a silent `createOffer`/`setLocalDescription` rejection no longer
+ * leaves an unrecoverable wedged slot. */
+export declare const SLOT_NEVER_CONNECTED_TIMEOUT_MS = 30000;
+/** Polly issue #110: how long a slot whose data channel is open and
+ * whose `connectionState` is `connected` can have no inbound bytes
+ * before the watchdog assumes the remote process is dead and tears
+ * the slot down. The ICE keepalive timer can take minutes to notice a
+ * remote SIGKILL or network partition; an application-layer
+ * liveness check that runs an order of magnitude faster keeps
+ * paired devices from sending sync traffic into the void after the
+ * remote daemon restarts. 120s is conservative — Automerge's idle
+ * cadence is well below this, so a healthy slot never crosses the
+ * threshold. */
+export declare const SLOT_IDLE_TIMEOUT_MS = 120000;
+/** Polly issue #109/#110: how often the watchdog evaluates teardown
+ * decisions across every slot. 5s is well below either threshold so
+ * teardown happens promptly after a deadline lapses without
+ * dominating runtime cost (one `connectionState` read per slot per
+ * tick). */
+export declare const SLOT_WATCHDOG_INTERVAL_MS = 5000;
 /** Options for constructing a {@link MeshWebRTCAdapter}. */
 export interface MeshWebRTCAdapterOptions {
     /** The signalling client the adapter uses to exchange SDP and ICE
@@ -154,6 +178,22 @@ export interface MeshWebRTCAdapterOptions {
      * `POLLY_104_DISABLE_FIX=1` falsification path. Production callers
      * should leave this at the default. */
     syncFragmentChunkSizeOverride?: number;
+    /** How long a slot can sit at `connectionState` in `new` or
+     * `connecting` before the watchdog tears it down. Defaults to
+     * {@link SLOT_NEVER_CONNECTED_TIMEOUT_MS}. Set to 0 to disable the
+     * gate. Polly issue #109. */
+    slotNeverConnectedTimeoutMs?: number;
+    /** How long a connected slot can have no inbound bytes before the
+     * watchdog tears it down as idle. Defaults to
+     * {@link SLOT_IDLE_TIMEOUT_MS}. Set to 0 to disable the gate.
+     * Polly issue #110. */
+    slotIdleTimeoutMs?: number;
+    /** How often the slot watchdog evaluates teardown decisions.
+     * Defaults to {@link SLOT_WATCHDOG_INTERVAL_MS}; tests override to
+     * tens of milliseconds. Set to 0 to disable the watchdog entirely
+     * (the pre-#109/#110 behaviour, kept only for migration and the
+     * falsification path). */
+    slotWatchdogIntervalMs?: number;
 }
 /** Payload of the polly-specific `"sync-progress"` event emitted by
  * {@link MeshWebRTCAdapter}. Consumers can subscribe via the adapter's
@@ -239,7 +279,10 @@ export interface TransportSnapshot {
  *   negotiation state.
  * - `fatal-error`: an exception was thrown while attempting to build
  *   the slot. The accompanying {@link SlotInitiationDecision.error}
- *   string carries the message.
+ *   string carries the message. This is also stamped when the slot
+ *   watchdog tears a wedged slot down (polly#109's silent throw, or
+ *   polly#110's idle-but-still-`connected` post-mortem), so the next
+ *   sweep tick finds no slot and retries.
  */
 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
@@ -478,6 +521,14 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * {@link sweepRunCount} so a stalled sweep is visible at a glance
      * via the snapshot's `sweep` block. */
     private lastSweepAt;
+    /** Watchdog interval (polly#109 + polly#110). Tears down slots that
+     * never reach `connected`, or that look connected but have not
+     * received bytes for {@link slotIdleTimeoutMs}, so the recovery
+     * sweep can re-attempt. Cleared in {@link disconnect}. */
+    private slotWatchdogTimer;
+    private readonly slotNeverConnectedTimeoutMs;
+    private readonly slotIdleTimeoutMs;
+    private readonly slotWatchdogIntervalMs;
     /** 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
@@ -543,6 +594,8 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
                 transport: TransportSnapshot | undefined;
                 lastSyncHandshakeAttempt: SyncHandshakeAttemptSnapshot;
                 handles: Record<string, HandleSyncSnapshot>;
+                createdAt: number;
+                lastInboundAt: number | undefined;
             };
         }>;
     };
@@ -664,6 +717,41 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * #106 item 7. */
     private startKnownPeersSweep;
     private stopKnownPeersSweep;
+    /** Close a slot's data channel and connection, remove it from the
+     * map, and emit `peer-disconnected` upward so Automerge stops
+     * routing through the dead pair. Used by both the polly#109
+     * `.catch` in {@link createInitiatingSlot} and the polly#109/#110
+     * watchdog in {@link sweepWedgedSlots}. */
+    private tearDownWedgedSlot;
+    /** Start the slot watchdog (polly#109 + polly#110). Walks every
+     * active slot every {@link slotWatchdogIntervalMs} and tears down
+     * the two named wedge shapes:
+     *
+     * - `connectionState` in `new`/`connecting` for longer than
+     *   {@link slotNeverConnectedTimeoutMs} (polly#109: silent
+     *   `createOffer`/`setLocalDescription` rejection, or a network
+     *   condition under which ICE never gathers).
+     *
+     * - `connectionState === "connected"` AND data channel `open` AND
+     *   no inbound bytes for {@link slotIdleTimeoutMs} (polly#110:
+     *   remote process killed without OS-layer FIN — ICE keepalives
+     *   take many minutes to fail, the slot sends sync traffic into
+     *   the void until then).
+     *
+     * Each teardown stamps `fatal-error` on the per-peer decision so
+     * the named gate is visible on the next snapshot, then emits
+     * `peer-disconnected` so Automerge stops routing through the dead
+     * slot. The next sweep tick re-evaluates and the recovery path
+     * creates a fresh slot. No-op when configured to 0. */
+    private startSlotWatchdog;
+    private stopSlotWatchdog;
+    private sweepWedgedSlots;
+    /** Decide whether a slot is wedged at the moment of inspection,
+     * returning the human-readable diagnosis when it is. Pulled out of
+     * {@link sweepWedgedSlots} so the per-slot decision stays under
+     * biome's cognitive-complexity ceiling and so a future test can
+     * exercise the gates directly. */
+    private classifyWedgedSlot;
     /**
      * Send a sync message to a specific remote peer. If no RTCPeerConnection
      * exists yet, the adapter initiates one by producing an SDP offer and

package/package.json

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