@fairfox/polly 0.20.1 → 0.22.0

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;
+}