@optimystic/db-p2p 1.0.0-beta.3 → 1.0.0

package/dist/src/network/relay-reservation.d.ts

@@ -0,0 +1,170 @@
+import type { Libp2p } from 'libp2p';
+import type { PeerId } from '@libp2p/interface';
+/** The bare "search" circuit listen address: one pending slot, filled by whoever asks for it. */
+export declare const CIRCUIT_SEARCH_LISTEN_ADDR = "/p2p-circuit";
+/** A relay this node must keep a reservation on itself. */
+export interface SupervisedRelay {
+    /** Where to dial the relay: the listen entry without its trailing `/p2p-circuit`. */
+    readonly dialAddr: string;
+    /** The relay's peer id in the form `PeerId.toString()` produces, whatever spelling the listen entry used. */
+    readonly peerId: string;
+}
+/** What {@link planRelayListenAddrs} hands back: the addresses libp2p listens on, and the relays to supervise. */
+export interface RelayListenPlan {
+    readonly listenAddrs: string[];
+    readonly supervisedRelays: SupervisedRelay[];
+}
+/**
+ * Split a node's listen addresses into what libp2p should listen on and which relays this node
+ * must supervise.
+ *
+ * A relay-naming circuit listen address — exactly one `p2p-circuit` component, last, with a `p2p`
+ * component (the relay's peer id) immediately before it — becomes one bare
+ * {@link CIRCUIT_SEARCH_LISTEN_ADDR} entry plus one supervised relay. libp2p keeps listen addresses
+ * as a plain array with no de-duplication, so N such entries give N bare listeners and N pending
+ * slots. Two entries naming one relay (by peer id, whatever the spelling) give one of each; the
+ * first entry's dial address wins. Everything else passes through untouched: a host's own bare
+ * `/p2p-circuit` (the host owns that reservation), TCP and WebSocket entries, and anything
+ * malformed or multi-hop, which libp2p rejects itself.
+ */
+export declare function planRelayListenAddrs(listenAddrs: readonly string[]): RelayListenPlan;
+/**
+ * The slice of `@libp2p/utils`' cuckoo `Filter` the reservation store remembers failed relays in.
+ * `remove` is optional on that interface, so its absence must degrade, never throw.
+ */
+export interface RelayFilterLike {
+    has(item: Uint8Array): boolean;
+    remove?(item: Uint8Array): boolean;
+}
+/**
+ * The slice of `@libp2p/circuit-relay-v2`'s transport-side `ReservationStore` this module drives.
+ * Structural, because the class is internal to that package: naming only the members used keeps
+ * the coupling small and greppable, and lets {@link findCircuitRelayTransport} duck-type it.
+ */
+export interface RelayReservationStoreLike {
+    addRelay(peerId: PeerId, type: 'discovered' | 'configured'): Promise<unknown>;
+    hasReservation(peerId: PeerId): boolean;
+    relayFilter?: RelayFilterLike;
+}
+/** The slice of libp2p's circuit-relay transport that owns the reservation store. */
+export interface CircuitRelayTransportLike {
+    reservationStore: RelayReservationStoreLike;
+}
+/**
+ * The running node's circuit-relay transport, or `null` when it has none.
+ *
+ * NOTE: the ONE place this package reaches libp2p internals for relay reservations, pinned against
+ * `libp2p` 3.1.3 and `@libp2p/circuit-relay-v2` 4.1.3 by `test/relay-reservation-seam.spec.ts`,
+ * which must fail loudly if an upgrade moves any of it. There is no public route: the `Libp2p`
+ * interface has no `listen`, and nothing public exposes the reservation store. `node.components`
+ * is a real public field on libp2p's node class, just not on the interface; `transportManager`
+ * is a component; the circuit-relay transport is the one whose `reservationStore` has `addRelay`
+ * and `hasReservation`. What the store does on 4.1.3, read from
+ * `node_modules/@libp2p/circuit-relay-v2/src/transport/`: `listener.ts` publishes a `configured`
+ * reservation only from inside `listen()` and ignores it on `relay:created-reservation`, while a
+ * bare listener publishes any `discovered` reservation carrying its pending id; and
+ * `reservation-store.ts` drops a reservation on `connection:close`, re-queues the pending id only
+ * for `discovered` ones, removes-then-recreates on refresh, and adds a relay whose request failed
+ * with `DialError` or `UnsupportedProtocolError` to the private `relayFilter`, refusing it
+ * afterwards with "The relay was previously invalid" until the filter is reset.
+ */
+export declare function findCircuitRelayTransport(node: Libp2p): CircuitRelayTransportLike | null;
+/**
+ * Fail node creation, before anything starts, when a listen address names a relay but no transport
+ * could ever reserve on it. libp2p would reject the bare `/p2p-circuit` entry itself during
+ * `start()`, with a generic unsupported-listen-address error; this names the actual omission.
+ */
+export declare function assertCircuitRelayTransport(node: Libp2p, relays: readonly SupervisedRelay[]): void;
+/**
+ * Fail node creation, before anything is built, when a listen address names a relay but
+ * `announceAddrs` is set. libp2p advertises ONLY the announce set then (the readme's "replaces the
+ * advertised set entirely"), so the circuit address through the relay could never appear in
+ * `node.getMultiaddrs()`, nobody could learn it, and every supervisor drive would time out waiting
+ * for it: node creation would reject after a full drive deadline with a message about publishing
+ * rather than about the configuration. `appendAnnounceAddrs` keeps the listener addresses and is fine.
+ */
+export declare function assertRelayAddrsAdvertisable(relays: readonly SupervisedRelay[], announceAddrs: readonly string[] | undefined): void;
+/**
+ * Forget that a relay ever failed a reservation request, so the next request is actually made
+ * rather than refused with "The relay was previously invalid".
+ *
+ * The store resets its filter when a reservation is removed while a pending slot exists, which a
+ * bare listener always has, so this is a belt-and-braces step: the poisoning path this guards is a
+ * failed request from libp2p's own relay discovery while the relay was down. Fails soft in every
+ * direction; returns whether an entry was actually removed (for specs).
+ */
+export declare function clearRelayFilterEntry(store: RelayReservationStoreLike, relayPeerId: PeerId): boolean;
+/** Deadline for one drive: dial, reservation request and the wait for the address share it. */
+export declare const DEFAULT_RELAY_DRIVE_TIMEOUT_MS = 10000;
+/** Gap between liveness checks while the reservation is held; a fallback in case an event is missed. */
+export declare const DEFAULT_RELAY_CHECK_MS = 5000;
+/** Backoff before the first retry after a failed drive. */
+export declare const DEFAULT_RELAY_MIN_BACKOFF_MS = 1000;
+/**
+ * Backoff ceiling. It bounds recovery time after a long relay outage, because nothing else
+ * reconnects a lone phone to its relay; a WebSocket dial every 30 s during an outage is cheap.
+ */
+export declare const DEFAULT_RELAY_MAX_BACKOFF_MS = 30000;
+/** How often a drive re-reads the address list while waiting for the address to be published. */
+export declare const DEFAULT_RELAY_POLL_MS = 100;
+export interface RelayReservationSupervisorOptions {
+    /** Default {@link DEFAULT_RELAY_DRIVE_TIMEOUT_MS}. */
+    driveTimeoutMs?: number;
+    /** Default {@link DEFAULT_RELAY_CHECK_MS}. */
+    checkMs?: number;
+    /** Default {@link DEFAULT_RELAY_MIN_BACKOFF_MS}. */
+    minBackoffMs?: number;
+    /** Default {@link DEFAULT_RELAY_MAX_BACKOFF_MS}. */
+    maxBackoffMs?: number;
+    /** Default {@link DEFAULT_RELAY_POLL_MS}. */
+    pollMs?: number;
+}
+/** A running supervisor for one node and one relay. Obtained from {@link superviseRelayReservation}. */
+export interface RelayReservationSupervisor {
+    readonly relay: SupervisedRelay;
+    /**
+     * Settles once the first drive has: `null` when the reservation was held, otherwise the reason
+     * it was not. Also settles on {@link stop}, so an awaiting caller is never left hanging.
+     */
+    readonly firstDrive: Promise<string | null>;
+    /** Whether the node currently advertises a circuit address through this relay. Read live. */
+    readonly held: boolean;
+    /** True while a drive is in flight. */
+    readonly driving: boolean;
+    /** Epoch ms of the next scheduled check or retry; `null` while driving or once stopped. */
+    readonly retryAtMs: number | null;
+    /** Reason the last drive produced no reservation; `null` once one is held. */
+    readonly lastError: string | null;
+    /**
+     * Idempotent. Clears the pending timer, removes both event listeners, aborts an in-flight dial,
+     * and discards the result of an in-flight reservation request without starting anything after it.
+     */
+    stop(): void;
+}
+/**
+ * Keep asking `relay` for a reservation until one is held, then keep watching that it still is.
+ *
+ * Drives run on: the first tick, right away; libp2p's `self:peer:update` (the listener withdrew or
+ * added addresses); `peer:connect` for this relay (a dial by anything on this node reconnected it,
+ * which turns a partner's dial through the relay into an immediate re-reserve, and resets the
+ * backoff); a liveness poll every `checkMs` while held; and a doubling backoff from `minBackoffMs`
+ * to `maxBackoffMs` after a failed drive. Drives are serialized per relay: a trigger that arrives
+ * mid-drive does nothing by itself, because every drive ends with the same re-check and reschedule.
+ *
+ * `HadEnoughRelaysError` from the reservation store means this node's pending slot was already
+ * filled with a reservation on a different relay (libp2p's relay discovery, see the accepted
+ * tradeoff in `libp2p-node-base.ts`); it is logged once per episode and retried at the backoff cap, since it
+ * recovers on its own only if that other reservation drops.
+ */
+export declare function superviseRelayReservation(node: Libp2p, relay: SupervisedRelay, opts?: RelayReservationSupervisorOptions): RelayReservationSupervisor;
+/** Every supervisor a node runs, with the two operations the node factory needs. */
+export interface RelayReservationSupervisors {
+    readonly supervisors: readonly RelayReservationSupervisor[];
+    /** Resolves once every first drive held its reservation; rejects naming every relay that did not. */
+    awaitFirstDrives(): Promise<void>;
+    /** Stops every supervisor. Idempotent. */
+    stop(): void;
+}
+/** One {@link superviseRelayReservation} per relay, started immediately. */
+export declare function superviseRelayReservations(node: Libp2p, relays: readonly SupervisedRelay[], opts?: RelayReservationSupervisorOptions): RelayReservationSupervisors;
+//# sourceMappingURL=relay-reservation.d.ts.map

package/dist/src/network/relay-reservation.d.ts.map

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