@fairfox/polly 0.64.0 → 0.66.0

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

@@ -164,6 +164,56 @@ export interface CreateMeshClientOptions {
  * production call site is inside {@link createMeshClient}.
  */
 export declare function resolveIceServers(rtc: CreateMeshClientOptions["rtc"]): Promise<RTCIceServer[] | undefined>;
+/** Per-(docId, peerId) view into Automerge's `CollectionSynchronizer`.
+ * Built once per snapshot read and consulted from {@link buildHandleEntry}.
+ * Structured this way so the docSynchronizer lookup is paid once per
+ * docId, not once per (docId × peer). */
+interface PerPeerDocSyncView {
+    /** `true` iff Automerge's `CollectionSynchronizer.docSynchronizers`
+     * has an entry for this documentId. A handle that exists in
+     * `repo.handles` but has no corresponding `docSynchronizer` is the
+     * `addDocument`-was-never-called fingerprint — Automerge's
+     * NetworkSubsystem can never invoke `send` for it because no
+     * synchronizer is wired up. */
+    docSynchronizerExists: boolean;
+    /** `true` iff the docSynchronizer for this documentId has registered
+     * this peer in its internal peer list (`#peers`). `false` with
+     * `docSynchronizerExists: true` is the symmetric polly#107 gap: the
+     * synchronizer exists (`addDocument` ran) but `addPeer` was never
+     * called for this peer on this doc — typically because the handle
+     * was created AFTER `peer-candidate` fired and Automerge's
+     * `addDocument`-iterates-known-peers path missed it. `undefined`
+     * when no docSynchronizer exists. */
+    docSynchronizerKnowsPeer: boolean | undefined;
+    /** Automerge's `DocSynchronizer.peerStates[peerId]` — one of
+     * `"unknown"`, `"has"`, `"unavailable"`, `"wants"`. `"unknown"`
+     * with `lastSyncMessageOutAt` set means the local side sent its
+     * opening handshake but never advanced past it; this is the
+     * wedged-pair fingerprint #112 names. `undefined` when no
+     * docSynchronizer exists OR when the synchronizer exists but
+     * doesn't track this peer. */
+    peerDocumentStatus: string | undefined;
+}
+/** Minimal structural shape we lift off Automerge's hidden
+ * `Repo.synchronizer` / `CollectionSynchronizer` types. Kept narrow
+ * so a future Automerge bump that renames a private rip doesn't
+ * topple the snapshot path. */
+interface SynchronizerStructural {
+    docSynchronizers?: Record<string, {
+        hasPeer?: (peerId: string) => boolean;
+        peerStates?: Record<string, string>;
+    }>;
+}
+/** Internal — exported for direct unit-test coverage of the #112
+ * structural reader and snapshot wiring. Not part of the public API. */
+export declare const __test__: {
+    buildSyncView: (synchronizer: SynchronizerStructural | undefined, docId: string, peerId: string) => PerPeerDocSyncView;
+    EMPTY_SYNC_VIEW: PerPeerDocSyncView;
+    getCollectionSynchronizer: (repo: Repo) => SynchronizerStructural | undefined;
+    enrichPeerSlot: (peer: ReturnType<MeshWebRTCAdapter["getPeerStateSnapshot"]>["peers"][number], knownHandleIds: string[], repoHandles: Record<string, {
+        state: unknown;
+    } | undefined>, synchronizer: SynchronizerStructural | undefined) => MeshClientPeerStateSnapshot["peers"][number];
+};
 /** Polly#107 post-v0.60 instrumentation. Walks the lazy-wrapper log
  * and groups records by `docId`; emits one entry per `docId` that
  * appears in more than one record. Surfaces the "17 wrappers / 16
@@ -221,6 +271,31 @@ export interface MeshClientHandleSnapshot {
      * `"sync"` after handshake, `"request"` while the local side is
      * asking. */
     lastSyncMessageOutType: string | undefined;
+    /** #112 diagnostic. `true` iff Automerge's `CollectionSynchronizer`
+     * has a `docSynchronizer` entry for this document. A handle in
+     * `repo.handles` with no docSynchronizer is the
+     * `addDocument`-never-ran fingerprint: Automerge's NetworkSubsystem
+     * can never call `send` for it because no synchronizer is wired up. */
+    docSynchronizerExists: boolean;
+    /** #112 diagnostic. `true` iff the docSynchronizer for this document
+     * has this peer in its internal peer list. `false` with
+     * `docSynchronizerExists: true` is the symmetric polly#107 gap —
+     * the synchronizer exists but `addPeer` was never invoked on it for
+     * this peer, typically because the handle was created AFTER
+     * `peer-candidate` fired and Automerge's
+     * `addDocument`-iterates-peers path missed it. `undefined` when no
+     * docSynchronizer exists. */
+    docSynchronizerKnowsPeer: boolean | undefined;
+    /** #112 diagnostic. Automerge's
+     * `DocSynchronizer.peerStates[peerId]` — one of `"unknown"`,
+     * `"has"`, `"unavailable"`, `"wants"`. `"unknown"` together with a
+     * set `lastSyncMessageOutAt` is the wedged-pair fingerprint this
+     * ticket names: the opening handshake left the wire but the
+     * synchronizer never learned whether the remote has the doc, so
+     * `generateSyncMessage` quiesces. `undefined` when no
+     * docSynchronizer exists OR when the synchronizer does not track
+     * this peer. */
+    peerDocumentStatus: string | undefined;
 }
 /** Polly#107 H5 diagnostics: surfaces the `mesh-state` module
  * instance identity so a single snapshot read tells the operator
@@ -414,3 +489,4 @@ export interface MeshClient {
  * peer connections negotiate asynchronously in the background.
  */
 export declare function createMeshClient(options: CreateMeshClientOptions): Promise<MeshClient>;
+export {};

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.64.0",
+  "version": "0.66.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",