@fairfox/polly 0.52.0 → 0.53.0

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

@@ -45,6 +45,7 @@
  *   signalling client.
  */
 import { type Message, NetworkAdapter, type PeerId, type PeerMetadata } from "@automerge/automerge-repo/slim";
+import type { MeshKeyring } from "./mesh-network-adapter";
 import type { MeshSignalingClient } from "./mesh-signaling-client";
 /** Standard STUN servers for NAT traversal. In production, callers who
  * need TURN fallback for peers behind symmetric NATs should replace this
@@ -64,8 +65,41 @@ export interface MeshWebRTCAdapterOptions {
      * one by sending an SDP offer through the signalling channel. Peers
      * not in this list can still connect by sending an offer *to* this
      * adapter. The natural source for this list is the keyring's
-     * knownPeers map keys. */
+     * knownPeers map keys.
+     *
+     * Used only when {@link keyringSource} is not supplied. With
+     * `keyringSource` set the adapter reads `knownPeers` live from the
+     * keyring on every initiation decision, which is the shape
+     * {@link createMeshClient} wires up so post-construction
+     * {@link applyPairingToken} calls take effect without the consumer
+     * having to call {@link MeshWebRTCAdapter.addKnownPeer} by hand. */
     knownPeerIds?: string[];
+    /** Live keyring source. When supplied, the adapter reads
+     * `knownPeers` from `keyringSource()` on every initiation decision
+     * instead of a Set captured at construction. Combined with the
+     * periodic re-sweep started in {@link MeshWebRTCAdapter.connect},
+     * this makes mutations to `keyring.knownPeers` — including the ones
+     * produced by {@link applyPairingToken} after the mesh client is up
+     * — visible to the dial path within at most one sweep interval. The
+     * crypto layer already re-reads the keyring on every send and
+     * receive; this option closes the same loop for the WebRTC adapter.
+     *
+     * Polly issue #103: without this, a long-lived daemon that pairs a
+     * new device after its mesh client is constructed never dials the
+     * new peer — the adapter's captured Set stays stale even though the
+     * keyring contains the new entry, and the lex-tie-break rule in
+     * {@link MeshWebRTCAdapter.shouldInitiateTo} can leave both peers
+     * waiting for the other to offer indefinitely. */
+    keyringSource?: () => MeshKeyring;
+    /** How often the adapter re-evaluates whether to dial peers in the
+     * signalling roster. The sweep is what catches peers that became
+     * authorised in the keyring after their `peer-joined` notification
+     * already fired — the adapter has no other event to hang the retry
+     * on, so it polls. Cheap: one Map lookup per present peer, fired at
+     * most once per interval. Defaults to 2000ms; tests override to
+     * shorten the failure budget. Set to 0 to disable the sweep
+     * (the captured-set behaviour, kept only for migration). */
+    knownPeersRefreshIntervalMs?: number;
     /** Optional ICE server list override. Defaults to {@link DEFAULT_ICE_SERVERS}. */
     iceServers?: RTCIceServer[];
     /** Optional data channel label. Defaults to "polly-mesh". Applications
@@ -90,8 +124,24 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
     /** 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
      * mesh client is long-lived across the pair ceremony) can register the
-     * new peer with {@link addKnownPeer} without restarting the client. */
+     * new peer with {@link addKnownPeer} without restarting the client.
+     *
+     * Used only in the captured-set fallback path — when no
+     * {@link keyringSource} is supplied. With `keyringSource` set, the
+     * authoritative source is the live keyring and this Set is unused. */
     private readonly knownPeers;
+    /** Live keyring source, or undefined when the adapter is operating in
+     * the captured-set fallback shape. See the JSDoc on
+     * {@link MeshWebRTCAdapterOptions.keyringSource}. */
+    private readonly keyringSource;
+    /** Interval handle for the periodic re-sweep that catches peers
+     * already in the signalling roster when the keyring grew. Cleared in
+     * {@link MeshWebRTCAdapter.disconnect}. */
+    private knownPeersRefreshTimer;
+    /** Sweep interval. Resolved from
+     * {@link MeshWebRTCAdapterOptions.knownPeersRefreshIntervalMs} at
+     * construction. Defaults to 2000ms; tests override to 100–250ms. */
+    private readonly knownPeersRefreshIntervalMs;
     /** Peers currently visible in the signalling roster — populated by
      * {@link handlePeersPresent} / {@link handlePeerJoined} and pruned by
      * {@link handlePeerLeft}. Read by {@link addKnownPeer} to decide
@@ -109,10 +159,18 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
     private ready;
     private readyResolver;
     /** The peers this adapter will dial. Backward-compatible read accessor
-     * for callers that previously iterated the `knownPeerIds` array; the
-     * underlying storage is now a Set so mutations through
-     * {@link addKnownPeer} are O(1) and survive without re-allocation. */
+     * for callers that previously iterated the `knownPeerIds` array. With
+     * a {@link MeshWebRTCAdapterOptions.keyringSource} configured, the
+     * value is read live from the keyring; otherwise it falls back to the
+     * captured Set populated through the constructor and
+     * {@link addKnownPeer}. */
     get knownPeerIds(): string[];
+    /** True iff `remotePeerId` is currently in the authoritative
+     * knownPeers source — the live keyring when one was supplied, or
+     * the captured Set otherwise. Centralises the membership check so
+     * {@link shouldInitiateTo} and the JSDoc on
+     * {@link MeshWebRTCAdapterOptions.keyringSource} agree on the rule. */
+    private hasKnownPeer;
     /** Callback for incoming blob messages. Set by the blob store.
      *  Called with the sender's peer ID, the raw header object, and the
      *  binary payload (chunk data). */
@@ -124,6 +182,43 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * RTCPeerConnection and data channel. Exposed for tests that assert
      * "exactly one channel per pair" after discovery settles. */
     peerSlotCount(): number;
+    /** Snapshot of the adapter's per-peer state at the moment of the
+     * call. Returned values are plain data — strings and booleans only —
+     * so consumers can log, assert on, or render them without retaining
+     * references into the adapter's internals.
+     *
+     * Polly issue #103 asked for an inspection surface so a consumer
+     * harness can answer "is the mesh layer in a known good state" from
+     * outside polly. This method is that surface. The fields mirror the
+     * three layers of the WebRTC connection lifecycle so a "stuck"
+     * connection can be diagnosed without reaching for the browser
+     * devtools: the SDP signalling state, the ICE checking state, and
+     * the unified RTCPeerConnection connection state. A `dataChannel`
+     * field reports whether the data channel — the thing the mesh
+     * actually carries bytes over — is open.
+     *
+     * Peers visible in the signalling roster but not yet dialled appear
+     * with `slot: undefined`, so a consumer can tell "we know about this
+     * peer in signalling but the WebRTC adapter has not started an
+     * offer yet" from "we have a slot in some negotiation state". */
+    getPeerStateSnapshot(): {
+        localPeerId: string;
+        knownPeerIds: string[];
+        presentPeerIds: string[];
+        peers: Array<{
+            peerId: string;
+            knownInKeyring: boolean;
+            presentInSignalling: boolean;
+            slot: undefined | {
+                signalingState: string;
+                iceConnectionState: string;
+                connectionState: string;
+                dataChannelState: string;
+                pendingSendCount: number;
+                pendingRemoteIceCount: number;
+            };
+        }>;
+    };
     /** Handle the signalling server's `peer-joined` notification: a new
      * peer has appeared on the relay. If the peer is in `knownPeerIds`
      * and we do not already have a slot for it, and the tie-break rule
@@ -152,8 +247,22 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      * new entry. Calling this method propagates that into the adapter's
      * own allowlist; if the peer is already in the signalling roster and
      * the tie-break rule names us as the initiator, an SDP offer fires
-     * immediately. No-op if the peer is already known. */
+     * immediately. No-op if the peer is already known.
+     *
+     * When a {@link MeshWebRTCAdapterOptions.keyringSource} is configured
+     * the adapter already reads `knownPeers` live and the periodic sweep
+     * picks up the new entry within
+     * {@link MeshWebRTCAdapterOptions.knownPeersRefreshIntervalMs} on its
+     * own, so explicit calls to this method are not required for
+     * correctness — but remain supported for callers that want the
+     * "dial now if present" prompt without waiting for the next sweep. */
     addKnownPeer(remotePeerId: string): void;
+    /** Re-evaluate every peer currently in the signalling roster and
+     * 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. */
+    refreshKnownPeers(): void;
     private shouldInitiateTo;
     whenReady(): Promise<void>;
     /**
@@ -170,6 +279,13 @@ export declare class MeshWebRTCAdapter extends NetworkAdapter {
      */
     connect(peerId: PeerId, peerMetadata?: PeerMetadata): void;
     disconnect(): void;
+    /** Start the periodic re-sweep that catches peers added to the
+     * 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. */
+    private startKnownPeersSweep;
+    private stopKnownPeersSweep;
     /**
      * 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/dist/tools/test/src/visual/index.js

@@ -6135,12 +6135,23 @@ __export(exports_assert, {
   CallTracker: () => CallTracker,
   AssertionError: () => AssertionError
 });
-var __create2, __getProtoOf2, __defProp2, __getOwnPropNames2, __hasOwnProp2, __toESM2 = (mod, isNodeMode, target) => {
+function __accessProp2(key) {
+  return this[key];
+}
+var __create2, __getProtoOf2, __defProp2, __getOwnPropNames2, __hasOwnProp2, __toESMCache_node2, __toESMCache_esm2, __toESM2 = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node2 ??= new WeakMap : __toESMCache_esm2 ??= new WeakMap, cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create2(__getProtoOf2(mod)) : {};
   let to = isNodeMode || !mod || !mod.__esModule ? __defProp2(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames2(mod))
     if (!__hasOwnProp2.call(to, key))
-      __defProp2(to, key, { get: () => mod[key], enumerable: true });
+      __defProp2(to, key, { get: __accessProp2.bind(mod, key), enumerable: true });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 }, __commonJS2 = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports), require_shams, require_shams2, require_es_object_atoms, require_es_errors, require_eval, require_range, require_ref, require_syntax, require_type, require_uri, require_abs, require_floor, require_max, require_min, require_pow, require_round, require_isNaN, require_sign, require_gOPD, require_gopd, require_es_define_property, require_has_symbols, require_Reflect_getPrototypeOf, require_Object_getPrototypeOf, require_implementation, require_function_bind, require_functionCall, require_functionApply, require_reflectApply, require_actualApply, require_call_bind_apply_helpers, require_get, require_get_proto, require_hasown, require_get_intrinsic, require_call_bound, require_is_arguments, require_is_regex, require_safe_regex_test, require_generator_function, require_is_generator_function, require_is_callable, require_for_each, require_possible_typed_array_names, require_available_typed_arrays, require_define_data_property, require_has_property_descriptors, require_set_function_length, require_applyBind, require_call_bind, require_which_typed_array, require_is_typed_array, require_types, require_isBuffer, require_inherits_browser, require_inherits, require_util, require_errors, require_assertion_error, require_isArguments, require_implementation2, require_object_keys, require_implementation3, require_polyfill, require_implementation4, require_polyfill2, require_callBound, require_define_properties, require_shim, require_object_is, require_implementation5, require_polyfill3, require_shim2, require_is_nan, require_comparisons, require_assert, assert, AssertionError, CallTracker, deepEqual, deepStrictEqual, doesNotMatch, doesNotReject, doesNotThrow, equal, fail, ifError, match, notDeepEqual, notDeepStrictEqual, notEqual, notStrictEqual, ok, rejects, strict, strictEqual, throws, assert_default;
 var init_assert = __esm(() => {
@@ -9108,26 +9119,41 @@ var exports_zlib = {};
 __export(exports_zlib, {
   default: () => export_default
 });
+function __accessProp3(key) {
+  return this[key];
+}
+function __exportSetter2(name, newValue) {
+  this[name] = __returnValue2.bind(null, newValue);
+}
 var __create3, __getProtoOf3, __defProp3, __getOwnPropNames3, __hasOwnProp3, __reExport = (target, mod, secondTarget) => {
-  for (let key of __getOwnPropNames3(mod))
+  var keys = __getOwnPropNames3(mod);
+  for (let key of keys)
     if (!__hasOwnProp3.call(target, key) && key !== "default")
-      __defProp3(target, key, { get: () => mod[key], enumerable: true });
+      __defProp3(target, key, { get: __accessProp3.bind(mod, key), enumerable: true });
   if (secondTarget) {
-    for (let key of __getOwnPropNames3(mod))
+    for (let key of keys)
       if (!__hasOwnProp3.call(secondTarget, key) && key !== "default")
-        __defProp3(secondTarget, key, { get: () => mod[key], enumerable: true });
+        __defProp3(secondTarget, key, { get: __accessProp3.bind(mod, key), enumerable: true });
     return secondTarget;
   }
-}, __toESM3 = (mod, isNodeMode, target) => {
+}, __toESMCache_node3, __toESMCache_esm3, __toESM3 = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node3 ??= new WeakMap : __toESMCache_esm3 ??= new WeakMap, cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create3(__getProtoOf3(mod)) : {};
   let to = isNodeMode || !mod || !mod.__esModule ? __defProp3(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames3(mod))
     if (!__hasOwnProp3.call(to, key))
-      __defProp3(to, key, { get: () => mod[key], enumerable: true });
+      __defProp3(to, key, { get: __accessProp3.bind(mod, key), enumerable: true });
+  if (canCache)
+    cache.set(mod, to);
   return to;
-}, __commonJS3 = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports), __export2 = (target, all) => {
+}, __commonJS3 = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports), __returnValue2 = (v) => v, __export2 = (target, all) => {
   for (var name in all)
-    __defProp3(target, name, { get: all[name], enumerable: true, configurable: true, set: (newValue) => all[name] = () => newValue });
+    __defProp3(target, name, { get: all[name], enumerable: true, configurable: true, set: __exportSetter2.bind(all, name) });
 }, require_zstream, require_common, require_trees, require_adler32, require_crc32, require_messages, require_deflate, require_inffast, require_inftrees, require_inflate, require_constants, require_binding, require_lib, exports_zlib2, import_browserify_zlib, export_default;
 var init_zlib = __esm(() => {
   __create3 = Object.create;
@@ -13991,4 +14017,4 @@ export {
   assertSafeUpdateMode
 };
 
-//# debugId=A8F0CA1BEDC12C8F64756E2164756E21
+//# debugId=51DC7226BD2C4BE464756E2164756E21