@freqhole/reliquary 0.0.0

package/dist/automerge/iroh-network-adapter.d.ts

@@ -0,0 +1,178 @@
+import { NetworkAdapter, type Message, type PeerId, type PeerMetadata } from "@automerge/automerge-repo";
+import type { BiStreamLike, ConnectionSummary, EndpointState, IrohNetworkAdapterOptions, MiddenStreamNode } from "./types.js";
+export type { BiStreamLike, ConnectionSummary, EndpointState, IrohNetworkAdapterOptions, MiddenStreamNode };
+/** ALPN protocol identifier for automerge-repo sync over iroh. */
+export declare const SYNC_ALPN = "iroh/automerge-repo/1";
+/**
+ * automerge-repo NetworkAdapter that uses iroh QUIC streams for transport.
+ *
+ * usage:
+ *   const adapter = new IrohNetworkAdapter({
+ *     getNode: () => getMiddenNode(),
+ *     getIdentity: () => getStoredIdentity(),
+ *     onIdentityChange: (cb) => subscribeToIdentityChanges(cb),
+ *   });
+ *   const repo = new Repo({ network: [broadcastAdapter, adapter] });
+ *   // later, to connect to a peer:
+ *   await adapter.addPeer("abc123...def");
+ */
+export declare class IrohNetworkAdapter extends NetworkAdapter {
+    private readonly opts;
+    private readonly syncAlpn;
+    private midden;
+    private streams;
+    private readLoops;
+    private _ready;
+    private _readyPromise;
+    private _resolveReady;
+    private _disconnected;
+    private _acceptLoopRunning;
+    private identityUnsub;
+    /** peers explicitly added via addPeer() that we should stay connected to. */
+    private intendedPeers;
+    /** per-peer reconnection state tracking attempt count and pending timer. */
+    private reconnectState;
+    /** listeners for connection state changes. */
+    private connectionStateListeners;
+    /** peers that exceeded max reconnection attempts. */
+    private failedPeers;
+    /** external handlers registered for non-sync ALPNs via registerAlpnHandler(). */
+    private alpnHandlers;
+    /** listeners notified when a peer stream is established. */
+    private peerConnectListeners;
+    /** listeners notified when a peer stream is removed. */
+    private peerDisconnectListeners;
+    private _stopped;
+    private _endpointState;
+    private endpointStateListeners;
+    constructor(opts: IrohNetworkAdapterOptions);
+    isReady(): boolean;
+    whenReady(): Promise<void>;
+    /**
+     * called by the Repo to start the adapter.
+     *
+     * marks the adapter ready (so automerge-repo can use it immediately)
+     * and begins transport setup if an identity already exists.
+     */
+    connect(peerId: PeerId, peerMetadata?: PeerMetadata): void;
+    /**
+     * send a message to a peer.
+     *
+     * CBOR-encodes the message and writes it as a length-delimited frame
+     * to the peer's QUIC stream.
+     */
+    send(message: Message): void;
+    /**
+     * disconnect from all peers and stop accepting connections.
+     */
+    disconnect(): void;
+    /**
+     * connect to a peer by node ID.
+     *
+     * opens a bidirectional QUIC stream to the peer on the automerge sync
+     * ALPN, starts a read loop, and emits a peer-candidate event so
+     * automerge-repo begins syncing with this peer.
+     */
+    addPeer(nodeId: string): Promise<void>;
+    /**
+     * dial a peer with a short retry loop for the initial connection attempt.
+     *
+     * discovery (relay-assisted address exchange) can lag a peer's node-id
+     * registration by a second or so right after both endpoints come
+     * online - dialing during that window fails with "no addressing
+     * information available" even though the peer is reachable moments
+     * later. retry a handful of times with a short fixed delay before
+     * giving up; this is a much tighter loop than the general reconnect
+     * backoff below, which is for peers that were connected and then
+     * dropped.
+     */
+    private openBiWithRetry;
+    /**
+     * stop maintaining a connection to a peer.
+     *
+     * removes the peer from intendedPeers, cancels any pending reconnection,
+     * and closes any existing stream. use this when you intentionally want
+     * to stop connecting to a peer (as opposed to a transient failure).
+     */
+    forgetPeer(nodeId: string): void;
+    /** check whether we have an active stream to a peer (transport-level connectivity check). */
+    isConnected(nodeId: string): boolean;
+    /**
+     * get a summary of the current connection state.
+     * used by the UI to show stoplight-style indicators.
+     */
+    getConnectionSummary(): ConnectionSummary;
+    /**
+     * subscribe to connection state changes.
+     * fires whenever a peer connects, disconnects, starts reconnecting,
+     * or gives up. returns an unsubscribe function.
+     */
+    onConnectionStateChange(handler: () => void): () => void;
+    /**
+     * subscribe to peer connect events. fires when a stream is
+     * successfully established with a peer. returns an unsubscribe function.
+     */
+    onPeerConnect(handler: (peerId: string) => void): () => void;
+    /**
+     * subscribe to peer disconnect events. fires when a peer's stream
+     * is removed (closed or errored). returns an unsubscribe function.
+     */
+    onPeerDisconnect(handler: (peerId: string) => void): () => void;
+    /**
+     * retry connection to all failed peers.
+     * re-adds them to intendedPeers and starts fresh reconnection attempts.
+     */
+    retryFailedPeers(): void;
+    /** get the current iroh endpoint state for UI display. */
+    getEndpointState(): EndpointState;
+    /** subscribe to endpoint state changes; returns an unsubscribe function. */
+    onEndpointStateChange(handler: (state: EndpointState) => void): () => void;
+    /**
+     * stop all P2P transport gracefully.
+     * closes all peer streams and cancels reconnections, but preserves
+     * intendedPeers so restart() can reconnect them. the node reference is
+     * dropped so restart() creates a fresh one via getNode().
+     */
+    stop(): void;
+    /**
+     * restart the P2P transport after stop().
+     * re-initializes the node and reconnects all remembered peers.
+     */
+    restart(): Promise<void>;
+    /**
+     * register a handler for incoming streams with a specific ALPN.
+     * the accept loop will dispatch matching streams to this handler
+     * instead of closing them. used to support additional protocols
+     * alongside automerge sync without forking this adapter.
+     */
+    registerAlpnHandler(alpn: string, handler: (stream: BiStreamLike) => void): void;
+    /**
+     * get the midden stream node, initializing it lazily if needed.
+     * exposed for use by protocol handlers that need to open outbound
+     * streams on a different ALPN.
+     */
+    getNode(): Promise<MiddenStreamNode>;
+    private checkIdentityAndStart;
+    private initialize;
+    private ensureMidden;
+    private startAcceptLoop;
+    private registerStream;
+    private startReadLoop;
+    private removePeer;
+    /**
+     * schedule a reconnection attempt for a peer using exponential backoff
+     * with random jitter.
+     */
+    private scheduleReconnect;
+    /**
+     * attempt to reconnect to a peer. called by the scheduled timer from
+     * scheduleReconnect(). on failure, schedules the next attempt.
+     */
+    private attemptReconnect;
+    /** notify all connection state listeners. */
+    private emitConnectionStateChange;
+    private setEndpointState;
+    /** cancel and remove any pending reconnect timer for a peer. */
+    private clearReconnectState;
+}
+//# sourceMappingURL=iroh-network-adapter.d.ts.map

package/dist/automerge/iroh-network-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iroh-network-adapter.d.ts","sourceRoot":"","sources":["../../src/automerge/iroh-network-adapter.ts"],"names":[],"mappings":"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"}