@serfab/cadre-core 0.9.0 → 0.11.0

package/dist/relay-reservation.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Relay reservation for nodes that reserve through the SEARCH listen addr — the
+ * dial, the explicit reservation request, the retry loop that keeps it, and the
+ * (live) status derivation.
+ *
+ * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen
+ * address, and the two shapes are alternatives, not layers:
+ *
+ * | listen addr                                       | libp2p behaviour                                                                     | unreachable relay          |
+ * | ------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------- |
+ * | `<dial addr>/p2p/<relayPeerId>/p2p-circuit`        | CONFIGURED reservation: dial that exact relay and reserve, or fail                     | `listen()` throws          |
+ * | bare `/p2p-circuit`                                | SEARCH mode: register a pending reservation, to be filled by relay discovery           | nothing throws, no reserve |
+ *
+ * The configured shape is what `relay-addrs.ts` builds out of `network.relayAddrs`.
+ * It is **fail-fast by construction**: libp2p's transport manager throws
+ * `UnsupportedListenAddressesError` when any configured listen address fails to
+ * listen under the default `FATAL_ALL` fault tolerance, so naming a relay that is
+ * down means the node does not start. Good for a server; wrong for a browser tab,
+ * which must still boot (solo, undialable) when its relay is down.
+ *
+ * So a browser-shaped node listens on bare `/p2p-circuit` and needs someone to
+ * (a) dial the relay and (b) fill the pending reservation that listener created,
+ * then report whether one actually landed. That is this module. It is **fail-soft
+ * by construction**: nothing here throws.
+ *
+ * Do NOT "consolidate" the two by also setting `network.relayAddrs` on a node
+ * that reserves this way — that re-introduces the fatal configured listener
+ * alongside the search listener and the tab stops booting when the relay is down.
+ *
+ * ⚠️ WHY THE RESERVATION IS REQUESTED EXPLICITLY RATHER THAN LEFT TO DISCOVERY.
+ * libp2p fills a search listener's pending reservation from `RelayDiscovery`,
+ * which nominates a peer only once it can see the relay-hop protocol id in that
+ * peer's PEER-STORE protocol list — and that list is written exclusively by the
+ * IDENTIFY handshake. `@optimystic/db-p2p` gives every cadre node a
+ * network-namespaced identify protocol id (`/optimystic/control-<partyId>/id/1.0.0`)
+ * while the relay `ops/docker/libp2p-infra` deploys runs stock identify
+ * (`/ipfs/id/1.0.0`), so the two never identify each other, the peer store stays
+ * empty of protocols, and discovery never nominates the relay. The TCP/WebSocket
+ * connection itself is fine, which is why leaving it to discovery surfaced as a
+ * generic timeout.
+ *
+ * Identify is incidental to relaying, though: the reservation
+ * (`/libp2p/circuit/relay/0.2.0/hop`), a third peer's CONNECT through the relay,
+ * and the STOP handler on this node all use STOCK, un-namespaced protocol ids the
+ * deployed relay already serves. Discovery's only job is to GUESS which connected
+ * peer is a relay, and this module does not need to guess — it was handed the
+ * relay's address. So it asks the relay for a slot directly, via the
+ * circuit-relay transport's own reservation store.
+ *
+ * Status is derived from the node's LIVE multiaddrs on every read rather than
+ * cached at drive time: when a relay restarts or the connection drops, libp2p's
+ * listener clears its listening addrs and the circuit multiaddr disappears, so a
+ * cached snapshot would keep claiming `reserved` for a node nothing can dial.
+ *
+ * And because discovery is out of reach, nothing would ever ASK again either —
+ * so {@link driveRelayReservation} stays a single-shot primitive and
+ * {@link superviseRelayReservation} owns the retry cadence on top of it. That
+ * loop is what makes a lost reservation recover without a page reload.
+ */
+import type { Libp2p, PeerId } from '@libp2p/interface';
+/**
+ * Relay-reservation posture for a node that reserves through the SEARCH listen
+ * addr (bare `/p2p-circuit`) rather than a configured `network.relayAddrs` entry.
+ *  - `none`     — no relay addrs supplied; the node is undialable by design.
+ *  - `dialing`  — a drive is in flight.
+ *  - `reserved` — the node currently holds at least one `/p2p-circuit` addr.
+ *  - `retrying` — no reservation right now, but a {@link RelayReservationSupervisor}
+ *                 has the next attempt scheduled. Recoverable without a caller.
+ *  - `error`    — no reservation, and NOBODY IS GOING TO TRY AGAIN: no supervisor
+ *                 is running (or there is no node at all).
+ */
+export type RelayReservationStatus = 'none' | 'dialing' | 'reserved' | 'retrying' | 'error';
+export interface RelayReservationState {
+    status: RelayReservationStatus;
+    /** The relay multiaddrs this node was asked to reserve through. */
+    addrs: string[];
+    /** LIVE `/p2p-circuit` multiaddrs, recomputed on every read. */
+    circuitAddrs: string[];
+    error: string | null;
+    /**
+     * Epoch ms of the supervisor's next scheduled tick, or `null` when a drive is
+     * in flight, no supervisor is running, or no addrs were supplied. A UI can turn
+     * this into "reconnecting, next try in 8s" rather than showing a bare error for
+     * a node that is in fact recovering.
+     */
+    retryAtMs: number | null;
+}
+/** How long {@link driveRelayReservation} waits for a reservation to appear. */
+export declare const DEFAULT_RELAY_RESERVE_TIMEOUT_MS = 10000;
+export declare const DEFAULT_RELAY_RESERVE_POLL_MS = 250;
+export interface RelayReserveOptions {
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * The slice of `@libp2p/utils`' `Filter` (a cuckoo filter) that the reservation
+ * store uses to remember relays whose reservation request failed. `remove` is
+ * OPTIONAL on that interface, so every use here has to cope with its absence —
+ * see {@link clearRelayFilterEntry}.
+ */
+export interface RelayFilterLike {
+    has(item: Uint8Array): boolean;
+    remove?(item: Uint8Array): boolean;
+}
+/**
+ * The slice of `@libp2p/circuit-relay-v2`'s `ReservationStore` this module drives.
+ * Declared structurally because the class is internal to that package: naming only
+ * the members we call keeps the coupling small, explicit and greppable, and lets
+ * {@link findCircuitRelayTransport} duck-type rather than brand-match.
+ *
+ * `relayFilter` is optional because it is not required to DRIVE a reservation,
+ * only to RE-drive one (see {@link clearRelayFilterEntry}); a libp2p version that
+ * renames or drops it must degrade, not break.
+ */
+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 node's `/p2p-circuit` multiaddrs — the addresses a peer can dial it at
+ * while it holds a relay reservation. Empty means "not dialable via a relay
+ * right now", which is exactly what makes {@link resolveRelayReservationState}
+ * live rather than a stale snapshot.
+ */
+export declare function circuitMultiaddrs(node: Libp2p): string[];
+/**
+ * The running node's circuit-relay transport, or `null` when it has none.
+ *
+ * There is no public libp2p API for "reserve on THIS specific relay", so this
+ * reaches through `node.components.transportManager` — libp2p's internal layout.
+ * That coupling is deliberate and bounded: every step is optional-chained and the
+ * whole thing returns `null` rather than throwing, and a spec pins the seam so a
+ * libp2p upgrade that moves it fails loudly instead of silently reverting this
+ * module to the discovery wait that never fires.
+ */
+export declare function findCircuitRelayTransport(node: Libp2p): CircuitRelayTransportLike | null;
+/**
+ * Dial every relay in `addrs`, ask the first one that answers for a reservation
+ * slot, then wait until a `/p2p-circuit` address appears.
+ *
+ * Never throws — a dial rejection, a rejected reservation, a MALFORMED address,
+ * or a timeout all come back as an `error` string. A dial that throws does NOT
+ * cost the rest of the list: one dead relay among two must not cost the
+ * reservation on the live one, so every addr is dialed and the first error (in
+ * list order) is kept. A reservation that lands wins over any earlier error
+ * (`error: null`).
+ *
+ * `timeoutMs` bounds the WHOLE drive — dials, reservation requests and the wait
+ * share one deadline.
+ */
+export declare function driveRelayReservation(node: Libp2p, addrs: readonly string[], opts?: RelayReserveOptions): Promise<{
+    error: string | null;
+}>;
+/** Gap between liveness checks while a reservation is held. */
+export declare const DEFAULT_RELAY_CHECK_MS = 5000;
+/** Backoff before the first re-drive after a failed attempt. */
+export declare const DEFAULT_RELAY_MIN_BACKOFF_MS = 2000;
+/** Ceiling the backoff doubles up to. */
+export declare const DEFAULT_RELAY_MAX_BACKOFF_MS = 60000;
+export interface RelayReservationSupervisorOptions extends RelayReserveOptions {
+    /** Gap between liveness checks while a reservation is held. Default 5_000. */
+    checkMs?: number;
+    /** Backoff before the first re-drive after a failure. Default 2_000. */
+    minBackoffMs?: number;
+    /** Backoff ceiling. Default 60_000. */
+    maxBackoffMs?: number;
+}
+/**
+ * A running retry loop for one node + relay list. Obtained from
+ * {@link superviseRelayReservation}; its only imperative is {@link stop}.
+ */
+export interface RelayReservationSupervisor {
+    /**
+     * Resolves once the FIRST attempt has settled — so a caller can await startup
+     * exactly as it awaited a single {@link driveRelayReservation}, and the retries
+     * carry on in the background afterwards. Also resolves on {@link stop}, so an
+     * awaiting caller is never left hanging.
+     */
+    readonly firstAttempt: Promise<void>;
+    /** True while a drive is in flight. */
+    readonly driving: boolean;
+    /** Epoch ms of the next scheduled tick; `null` while a drive is running. */
+    readonly retryAtMs: number | null;
+    /** Reason the last drive produced no reservation; `null` once one is held. */
+    readonly lastError: string | null;
+    /**
+     * Idempotent. Clears the timer so no further drive is scheduled. A drive that
+     * is ALREADY in flight is not aborted — {@link driveRelayReservation} takes no
+     * signal — but its result is discarded and nothing follows it.
+     */
+    stop(): void;
+}
+/**
+ * Keep asking for a relay reservation until one is held, then keep watching that
+ * it still is — the thing that makes a lost reservation recover on its own.
+ *
+ * Needed because nothing else re-drives: libp2p re-fills a search listener's
+ * freed slot from relay DISCOVERY, and a cadre node's namespaced identify puts
+ * discovery permanently out of reach (see the module header). Without this loop a
+ * relay restart left a browser tab undialable until the user reloaded the page.
+ *
+ * Per tick:
+ *  - a reservation is held → reset the backoff, clear the error, re-check in
+ *    `checkMs`. No drive: a healthy node must not re-request every few seconds.
+ *  - otherwise → un-poison the reservation store's relay filter (see
+ *    {@link clearRelayFilterEntry}) and run ONE {@link driveRelayReservation}.
+ *    If that lands a reservation, rejoin the healthy path above; if not, sleep
+ *    the current backoff and double it up to `maxBackoffMs`.
+ *
+ * Starts immediately; the first tick runs before this returns.
+ */
+export declare function superviseRelayReservation(node: Libp2p, addrs: readonly string[], opts?: RelayReservationSupervisorOptions): RelayReservationSupervisor;
+/**
+ * Forget that `addr`'s peer ever failed a reservation request, so the next
+ * attempt is actually made rather than refused out of hand.
+ *
+ * `ReservationStore` records a peer in `relayFilter` when its reservation request
+ * fails with `DialError` or `UnsupportedProtocolError`, and NOTHING on that path
+ * ever clears it: the reset lives in `#checkReservationCount`, which only runs
+ * when a reservation is genuinely removed, and `#removeReservation` early-returns
+ * when there was never one. So a relay that was briefly not-a-relay (or died
+ * between our dial and the hop request) stays permanently rejected with
+ * `The relay was previously invalid` — measured, not inferred.
+ *
+ * Fails soft in every direction: no `relayFilter`, no `remove`, an addr with no
+ * peer id, a malformed addr — all mean "no un-poisoning", never a throw. The
+ * retry loop still recovers the common case without this, because a relay that is
+ * simply DOWN fails our own dial first and never reaches the filter.
+ *
+ * Returns whether an entry was actually removed (for specs; callers ignore it).
+ */
+export declare function clearRelayFilterEntry(store: RelayReservationStoreLike, addr: string): boolean;
+/**
+ * Derive the reservation posture, reading the node's circuit addrs LIVE. Pure
+ * apart from that read, so the precedence is testable on its own:
+ *
+ * | condition                | status                                          |
+ * | ------------------------ | ----------------------------------------------- |
+ * | no addrs supplied        | `none`                                          |
+ * | live circuit addrs held  | `reserved` (`error: null`)                      |
+ * | a drive is in flight     | `dialing`                                       |
+ * | a retry is scheduled     | `retrying`                                      |
+ * | otherwise                | `error`                                         |
+ *
+ * `reserved` is checked BEFORE `error` on purpose: the circuit addrs are read
+ * live, so a reservation that lands by ANY route supersedes a stale error string
+ * without a second drive.
+ *
+ * `retrying` sits between the two so that `error` carries a sharper meaning:
+ * NOBODY IS GOING TO TRY AGAIN. A lost reservation does come back on its own now,
+ * as long as a {@link RelayReservationSupervisor} is running — that loop is the
+ * only thing that re-drives, since libp2p re-fills a search listener's freed slot
+ * from relay DISCOVERY, which a cadre node's namespaced identify puts permanently
+ * out of reach (see the module header). So `error` means the supervisor was
+ * stopped, was never started, or there is no node at all.
+ *
+ * `retryAtMs` is the supervisor's next scheduled tick (`null` while a drive runs
+ * or when there is no supervisor); it both selects `retrying` and is passed
+ * through so a UI can count down to the next attempt.
+ */
+export declare function resolveRelayReservationState(node: Libp2p | null, addrs: readonly string[], lastError: string | null, driving: boolean, retryAtMs: number | null): RelayReservationState;