@fairfox/polly 0.55.0 → 0.57.0

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

@@ -219,6 +219,127 @@ export interface TransportSnapshot {
     /** `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`,
+ *   Automerge's NetworkSubsystem has not asked the adapter to send
+ *   anything. The polly#106 ladder named "no handle locally" as the
+ *   typical cause for this rung; the polly#107 failing-shape evidence
+ *   (fourteen `$meshState` handles pre-warmed in `ready` state,
+ *   `firstOutboundSendAt` still undefined long after peer-candidate
+ *   fires) shows that's a misleading ladder entry. Revised:
+ *
+ *     - If `repo.handles[docId]` is undefined or in a non-`ready`
+ *       state for every doc this peer should sync, the consumer
+ *       fix is real — pre-warm the handles via the documented
+ *       `$meshState(key, initial)` factory before the slot opens.
+ *
+ *     - If `repo.handles[docId]` is `ready` for every doc AND
+ *       `getPeerStateSnapshot().peers[…].slot.handles[docId]
+ *       .announcedToPeer` is `false`, the gate is BETWEEN Automerge's
+ *       NetworkSubsystem and the adapter — not on the consumer's
+ *       handle-construction path. This is the polly#107 surface;
+ *       post-#107 the mesh client hooks `peer-candidate` to invoke
+ *       the synchronizer's `reevaluateDocumentShare` so the
+ *       `addPeer`/`addDocument` ordering race that leaves a handle
+ *       un-announced gets closed by an idempotent re-evaluation.
+ *
+ *     - If `announcedToPeer` becomes `true` for every relevant doc
+ *       and `firstOutboundSendAt` is still undefined, the gap is in
+ *       polly's own send path — that's a polly bug, not an
+ *       Automerge or consumer one.
+ *
+ * - `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; polly#107 revised the
+ * `firstOutboundSendAt` rung to point at the polly⇄Automerge gate
+ * rather than the consumer. */
+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
@@ -242,6 +363,47 @@ export interface InFlightSyncSnapshot {
      * and this stays 0. */
     applyBacklog: number;
 }
+/** Per-handle per-peer sync bookkeeping. Closes the diagnostic gap
+ * between "handle exists in repo" (observable today via `repo.handles`)
+ * and "Automerge's NetworkSubsystem has actually told this peer about
+ * this handle" — the latter being the load-bearing question for the
+ * polly#107 failing shape, where fourteen pre-warmed handles sit in
+ * `ready` state and the peer slot is fully connected, yet Automerge
+ * has not asked the adapter to send a single sync message.
+ *
+ * Each field is stamped from the adapter's own wire path: `out` from
+ * {@link MeshWebRTCAdapter.send}, `in` from {@link dispatchMessage}'s
+ * deserialised view. Combined with the consumer's view of
+ * `repo.handles[documentId].state`, the mesh client's
+ * {@link createMeshClient}-returned `getPeerStateSnapshot` produces the
+ * full per-handle observability the polly#107 ticket asks for in
+ * item 7. */
+export interface HandleSyncSnapshot {
+    /** `performance.now()` of the most recent send through
+     * {@link MeshWebRTCAdapter.send} carrying this `documentId` for this
+     * peer. `undefined` means Automerge has never asked the adapter to
+     * send a sync message for this document — i.e. the handle is NOT
+     * "announced to peer" in the polly#107 sense, regardless of whether
+     * the handle is `ready` in `repo.handles`. */
+    lastSyncMessageOutAt: number | undefined;
+    /** `performance.now()` of the most recent inbound message dispatched
+     * upward for this `documentId` from this peer. `undefined` means we
+     * have never received a sync message for this document from this
+     * peer — they have not announced their copy of this handle to us. */
+    lastSyncMessageInAt: number | undefined;
+    /** Byte length of the most recent outbound sync message (the raw
+     * `RTCDataChannel.send` payload, which is the crypto-wrapped envelope
+     * — not the inner Automerge sync size). `undefined` until the first
+     * outbound send. Used by the polly#107 example's wire-level
+     * transcript to distinguish "Automerge generated an empty sync
+     * message" from "Automerge generated nothing at all". */
+    lastSyncMessageOutSize: number | undefined;
+    /** Type field of the most recent outbound message for this document
+     * to this peer. Typically `"sync"` once handshake has begun, or
+     * `"request"` while the local side is still asking. `undefined`
+     * until the first outbound send. */
+    lastSyncMessageOutType: string | undefined;
+}
 /**
  * Automerge-Repo NetworkAdapter backed by real WebRTC data channels.
  * Manages one RTCPeerConnection per remote peer and uses a supplied
@@ -301,6 +463,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
@@ -348,10 +525,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;
@@ -361,6 +541,8 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
                 pendingRemoteIceCount: number;
                 inFlightSync: InFlightSyncSnapshot | undefined;
                 transport: TransportSnapshot | undefined;
+                lastSyncHandshakeAttempt: SyncHandshakeAttemptSnapshot;
+                handles: Record<string, HandleSyncSnapshot>;
             };
         }>;
     };
@@ -378,6 +560,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
@@ -406,9 +599,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
@@ -428,7 +653,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;
     /**
@@ -521,6 +754,19 @@ 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
@@ -553,6 +799,15 @@ 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;
+    /** Stamp `handles[documentId].lastSyncMessageInAt` for the
+     * per-handle observability layer polly#107 adds. Pure observability;
+     * does not affect dispatch. */
+    private stampHandleInbound;
     private finishInFlightSyncApply;
     private emitSyncProgress;
     private handleSyncFragment;

package/package.json

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