@fairfox/polly 0.20.0 → 0.21.0

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

@@ -0,0 +1,102 @@
+/**
+ * mesh-state — Phase 2 wrappers exposing $meshState, $meshText, $meshCounter,
+ * and $meshList. These are the application-facing constructors for the
+ * strongest resilience tier in RFC-041: every device is a full Automerge
+ * replica, the server is *not on the data path at all*, and the application
+ * functions with zero server uptime once direct peer connections are
+ * established.
+ *
+ * Each primitive wraps the corresponding Phase 0 base ($crdtState, $crdtText,
+ * $crdtCounter, $crdtList) with three additions:
+ *
+ *   1. The `primitive` label is hard-coded to "meshState" so the
+ *      primitive-registry collision detection knows which family the key
+ *      belongs to.
+ *
+ *   2. A handle factory that resolves the application's logical key to an
+ *      Automerge DocumentId via a per-Repo key map, identical in shape to
+ *      the $peerState factory but registered against a separate Repo
+ *      configured for the mesh transport (signed and encrypted at the
+ *      network layer).
+ *
+ *   3. Signing and encryption are mandatory, not optional. Where $peerState
+ *      accepts encrypt/sign as opt-in flags (currently throwing in Phase 1),
+ *      $meshState requires every operation to be signed by the originating
+ *      peer's key and encrypted under the document's symmetric key. The
+ *      mechanism lives in the wrapping MeshNetworkAdapter that the Repo
+ *      uses for transport.
+ *
+ * The Repo itself is supplied by the application via {@link configureMeshState}
+ * or per-call via the `repo` option. In Phase 2 the production transport will
+ * be a WebRTC mesh adapter wrapping signing+encryption around an in-process
+ * RTCDataChannel; for tests and for the early Phase 2 cut, an in-memory
+ * loopback adapter pair satisfies the same contract.
+ */
+import type { Repo } from "@automerge/automerge-repo";
+import type { Access } from "./access";
+import { type SpecialisedPrimitive } from "./crdt-specialised";
+import { type CrdtPrimitive } from "./crdt-state";
+import type { Migrations, VersionedDoc } from "./schema-version";
+/** Common option shape across all four $mesh* primitives. */
+export interface MeshStateOptions {
+    /** Override the default Repo for this primitive. The Repo must be
+     * configured with the mesh transport (signing and encryption at the
+     * network layer). */
+    repo?: Repo;
+    /** Schema version target for the application. Migrations run on load. */
+    schemaVersion?: number;
+    /** Migration table keyed by target version. Required if schemaVersion is set. */
+    migrations?: Migrations;
+    /** Declarative read/write access. The mesh transport compiles this into
+     * a public-key set used by the signing layer to verify incoming ops. */
+    access?: Access;
+}
+/**
+ * Set the default Repo that the $mesh* primitives use when no `repo` option
+ * is supplied. Calling this with a new Repo clears the per-Repo key map so
+ * that tests start each scenario with a fresh document space.
+ *
+ * Production code typically calls this once at application startup with a
+ * Repo configured for the mesh transport. Tests call it before each
+ * scenario with an in-memory or loopback Repo.
+ */
+export declare function configureMeshState(repo: Repo): void;
+/**
+ * Reset the mesh-state subsystem to its initial unconfigured state.
+ * Intended for tests; production code should not call this.
+ */
+export declare function resetMeshState(): void;
+/**
+ * Create a peer-replicated state primitive backed by Automerge with a mesh
+ * transport. Every device holds a full replica; no central server holds a
+ * replica. Operations flow peer-to-peer through signed and encrypted
+ * messages on the underlying transport.
+ *
+ * @example
+ * ```ts
+ * const journal = $meshState<Journal>("journal", { entries: [] });
+ * await journal.loaded;
+ * journal.value = { entries: ["my private thoughts"] };
+ * ```
+ */
+export declare function $meshState<T extends VersionedDoc>(key: string, initialValue: T, options?: MeshStateOptions): CrdtPrimitive<T>;
+/**
+ * Create a peer-replicated text primitive backed by a mesh transport.
+ * Concurrent character-level edits from peers merge cleanly via Automerge's
+ * updateText splicing, and every operation is signed and encrypted before
+ * leaving the originating peer.
+ */
+export declare function $meshText(key: string, initialValue: string, options?: MeshStateOptions): SpecialisedPrimitive<string>;
+/**
+ * Create a peer-replicated counter primitive backed by a mesh transport.
+ * Concurrent increments commute, and every operation is signed and
+ * encrypted before leaving the originating peer.
+ */
+export declare function $meshCounter(key: string, initialValue: number, options?: MeshStateOptions): SpecialisedPrimitive<number>;
+/**
+ * Create a peer-replicated list primitive backed by a mesh transport.
+ * Phase 0 naive replacement applies to writes for now; Phase 1.1 will
+ * refine with structural diff-to-splice for concurrent insert/remove
+ * preservation.
+ */
+export declare function $meshList<T>(key: string, initialValue: T[], options?: MeshStateOptions): SpecialisedPrimitive<T[]>;

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

@@ -0,0 +1,132 @@
+/**
+ * mesh-webrtc-adapter — Phase 2 browser-side WebRTC transport for Polly's
+ * $meshState primitive. Extends Automerge's NetworkAdapter base class and
+ * uses real native RTCPeerConnection / RTCDataChannel instances to carry
+ * sync messages between peers.
+ *
+ * This is the "base" transport that MeshNetworkAdapter wraps with its
+ * sign-then-encrypt envelope. The stack is:
+ *
+ *   $meshState
+ *     └─ Repo
+ *          └─ MeshNetworkAdapter (sign + encrypt)
+ *                └─ MeshWebRTCAdapter (real data channels)
+ *                      └─ MeshSignalingClient (SDP/ICE relay)
+ *                            └─ signalingServer (Elysia plugin on the host app)
+ *
+ * Because WebRTC lives in browsers, this module is browser-only. It
+ * assumes global RTCPeerConnection, RTCDataChannel, and WebSocket types
+ * are available. Under bun:test the classes cannot be exercised
+ * end-to-end — the first validation path is either Playwright running a
+ * real browser, a Puppeteer harness, or a human testing a browser-side
+ * example app that consumes the adapter.
+ *
+ * What this module does at runtime:
+ *
+ * - Constructs a MeshWebRTCAdapter with a signalling client and a local
+ *   peer id. No data channels exist at construction time.
+ *
+ * - When Automerge's NetworkSubsystem calls connect(peerId) on the
+ *   adapter, it starts listening for signals from remote peers and is
+ *   ready to build peer connections as they are discovered.
+ *
+ * - When a remote peer sends an SDP offer via the signalling channel,
+ *   the adapter builds a fresh RTCPeerConnection, accepts the offer,
+ *   produces an answer, sends it back through signalling, and wires the
+ *   received data channel to emit Automerge Message events upward.
+ *
+ * - When the local repo calls send(message), the adapter looks up the
+ *   peer connection for message.targetId and writes the serialised
+ *   bytes to its data channel. If no connection exists yet, the adapter
+ *   creates one by sending an SDP offer through signalling. Outgoing
+ *   messages are queued until the channel is open.
+ *
+ * - Disconnect tears down every peer connection and closes the
+ *   signalling client.
+ */
+import { type Message, NetworkAdapter, type PeerId, type PeerMetadata } from "@automerge/automerge-repo";
+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
+ * with their own ICE server list. */
+export declare const DEFAULT_ICE_SERVERS: RTCIceServer[];
+/** Options for constructing a {@link MeshWebRTCAdapter}. */
+export interface MeshWebRTCAdapterOptions {
+    /** The signalling client the adapter uses to exchange SDP and ICE
+     * candidates with other peers. Typically constructed once per
+     * application and shared across any adapters that need it. */
+    signaling: MeshSignalingClient;
+    /** The local peer id. Must match the peer id the signalling client
+     * registered with. */
+    peerId: string;
+    /** Peer ids to connect to on startup. When `connect()` is called, the
+     * adapter iterates this list and initiates a WebRTC connection to each
+     * 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. */
+    knownPeerIds?: string[];
+    /** Optional ICE server list override. Defaults to {@link DEFAULT_ICE_SERVERS}. */
+    iceServers?: RTCIceServer[];
+    /** Optional data channel label. Defaults to "polly-mesh". Applications
+     * that share a signalling server between multiple meshes may want
+     * distinct labels per mesh. */
+    dataChannelLabel?: string;
+}
+/**
+ * Automerge-Repo NetworkAdapter backed by real WebRTC data channels.
+ * Manages one RTCPeerConnection per remote peer and uses a supplied
+ * {@link MeshSignalingClient} for SDP/ICE exchange.
+ */
+export declare class MeshWebRTCAdapter extends NetworkAdapter {
+    readonly signaling: MeshSignalingClient;
+    readonly iceServers: RTCIceServer[];
+    readonly dataChannelLabel: string;
+    readonly knownPeerIds: string[];
+    private readonly slots;
+    private ready;
+    private readyResolver;
+    constructor(options: MeshWebRTCAdapterOptions);
+    isReady(): boolean;
+    whenReady(): Promise<void>;
+    /**
+     * Start the adapter. Wires the signalling client's onSignal callback
+     * to the adapter's dispatch, opens the signalling connection if it
+     * is not already open, and marks the adapter ready.
+     */
+    connect(peerId: PeerId, peerMetadata?: PeerMetadata): void;
+    disconnect(): void;
+    /**
+     * Send a sync message to a specific remote peer. If no RTCPeerConnection
+     * exists yet, the adapter initiates one by producing an SDP offer and
+     * sending it through the signalling channel; the outgoing bytes are
+     * queued until the data channel is open.
+     */
+    send(message: Message): void;
+    /**
+     * Entry point the signalling client calls when it receives a signal
+     * from a remote peer. Dispatches on the payload `kind` to either
+     * accept an offer (building an answer), apply an answer, or add an
+     * ICE candidate. Exposed publicly so the caller that constructs the
+     * signalling client can wire the onSignal callback directly to this
+     * method.
+     */
+    handleSignal(fromPeerId: string, rawPayload: unknown): void;
+    private createInitiatingSlot;
+    private initiateOffer;
+    private handleOffer;
+    private handleAnswer;
+    private handleIceCandidate;
+    private wireConnection;
+    private wireDataChannel;
+    private dispatchMessage;
+    /** Pack an Automerge Message into binary for transmission over the
+     * data channel. The format mirrors MeshNetworkAdapter's internal
+     * serialisation: a length-prefixed JSON header followed by the raw
+     * data bytes. Returns a Uint8Array<ArrayBuffer> so the result is
+     * directly usable by RTCDataChannel.send under TypeScript's strict
+     * buffer-source typing. */
+    private serialiseMessage;
+    /** Inverse of {@link serialiseMessage}. */
+    private deserialiseMessage;
+}

package/dist/src/shared/lib/message-bus.js

@@ -2,27 +2,37 @@ var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
+function __accessProp(key) {
+  return this[key];
+}
 var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
   if (entry)
     return entry;
   entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
   __moduleCache.set(from, entry);
   return entry;
 };
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -259,7 +269,9 @@ class BroadcastChannelSyncAdapter {
   channel = null;
   listeners = [];
   constructor(channelName = "polly-sync") {
-    if (typeof BroadcastChannel !== "undefined") {
+    if (typeof BroadcastChannel === "undefined") {
+      console.warn("[SyncAdapter] BroadcastChannel not available");
+    } else {
       this.channel = new BroadcastChannel(channelName);
       this.channel.onmessage = (event) => {
         if (event.data.type === "STATE_SYNC") {
@@ -268,8 +280,6 @@ class BroadcastChannelSyncAdapter {
           });
         }
       };
-    } else {
-      console.warn("[SyncAdapter] BroadcastChannel not available");
     }
   }
   broadcast(message) {
@@ -1529,4 +1539,4 @@ export {
   MessageBus
 };
 
-//# debugId=183F35797010AB4564756E2164756E21
+//# debugId=7BE490ECD586102364756E2164756E21