@serfab/cadre-core 0.12.0 → 1.0.0

package/dist/relay-addrs.js

@@ -3,34 +3,47 @@
  * setting — into the listen entry a node needs before it can hold a circuit-relay
  * slot, and validate the operator's entries while doing it.
  *
- * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen addr,
- * and the same `relayAddrs` list resolves to either shape depending on WHO is
- * listening ({@link RelayListenRoute}):
- *
- * | route          | listen entry                                | libp2p behaviour                                          |
- * | -------------- | ------------------------------------------- | --------------------------------------------------------- |
- * | `'configured'` | `<relayAddr>/p2p-circuit`, one per relay      | dial that relay from inside `listen()` and reserve, or throw |
- * | `'search'`     | a single bare `/p2p-circuit`                  | register a pending reservation; open no connection          |
- *
- * The CONTROL node takes the `'search'` route, and `CadreNode.start()` drives the
- * reservation explicitly (`relay-reservation.ts`) once the control database is up.
- * That ordering is the point: a configured circuit listener dials the relay from
- * inside `libp2p.start()`, so the control database was being built while a sibling
- * relay was already in this node's cohort — and a sibling that has not yet
- * replicated this node's `CadrePeer` row correctly refuses its control-DB streams,
- * which killed `start()` outright. See `cadre-node.ts` → `start()`.
- *
- * STRAND nodes keep the `'configured'` route (`strand-instance-manager.ts`): they
- * inherit the control node's `NetworkConfig`, nothing drives an explicit
- * reservation for them, and their relay connection cannot disturb a control-DB
- * bring-up (a strand node's protocol ids are namespaced `/optimystic/strand-<id>/…`,
- * so the relay is never in its cohort).
- *
- * `network.relayAddrs` is FAIL-FAST for the operator on both routes, just from
- * different places: a malformed entry throws here at config resolution, and on the
- * control node a first reservation attempt that does not land throws out of
- * `start()` (`RelayReservationFailedError`). Naming a relay that is down still
- * means the node does not come up.
+ * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen addr:
+ *
+ * | listen entry                        | libp2p behaviour                                                |
+ * | ----------------------------------- | --------------------------------------------------------------- |
+ * | `<relayAddr>/p2p-circuit`           | CONFIGURED: dial that relay from inside `listen()` and reserve, or throw |
+ * | bare `/p2p-circuit`                 | SEARCH: register a pending reservation; open no connection      |
+ *
+ * Every cadre-built node takes the SEARCH shape, and something explicit drives the
+ * reservation afterwards (`relay-reservation.ts`):
+ *
+ * - The CONTROL node resolves `relayAddrs` here to ONE bare entry (whichever relay
+ *   answers first fills it) and `CadreNode.start()` drives the reservation once the
+ *   control database is up. That ordering is the point: a configured circuit
+ *   listener dials the relay from inside `libp2p.start()`, so the control database
+ *   was being built while a sibling relay was already in this node's cohort — and a
+ *   sibling that has not yet replicated this node's `CadrePeer` row correctly refuses
+ *   its control-DB streams, which killed `start()` outright. See `cadre-node.ts` →
+ *   `start()`.
+ * - Each STRAND node resolves the same `relayAddrs` to one bare entry PER relay and
+ *   runs one reservation supervisor per relay (`strand-network-config.ts`,
+ *   `strand-instance-manager.ts`).
+ *
+ * The CONFIGURED shape is deliberately not producible from a `NetworkConfig` any
+ * more: it loses its address and never recovers when the relay restarts, when either
+ * side hangs up, and — with no network event at all — on libp2p's own reservation
+ * refresh, which removes the reservation before re-creating it while a configured
+ * listener republishes only from inside its own `listen()`. A hand-written
+ * `<relay>/p2p-circuit` entry in `network.listenAddrs` is rejected on the control
+ * node ({@link resolveListenAddrs}) and folded into the supervised relay set on a
+ * strand node.
+ *
+ * `network.relayAddrs` is FAIL-FAST for the operator by default: a malformed entry
+ * throws here at config resolution regardless of posture, and on the control node a
+ * first reservation attempt that does not land throws out of `start()`
+ * (`RelayReservationFailedError`). Naming a relay that is down still means the control
+ * node does not come up. `network.requireRelay: false` softens the second half only —
+ * for a node that must still boot with no network (a phone, a browser tab) — logging
+ * the failed attempt instead of throwing and leaving the retry supervisor running in
+ * the background; the malformed-entry check is unaffected. A strand node is
+ * fail-SOFT regardless of `requireRelay` (its supervisor keeps trying while the
+ * strand serves).
  *
  * The bare `/p2p-circuit` search listener cannot open a connection on its own:
  * libp2p fills a pending reservation from `RelayDiscovery`, which nominates a peer
@@ -44,19 +57,21 @@ import { circuitRelayTargetOrThrow } from './delegate-admission.js';
 /**
  * The direct listener a node keeps when it configures `relayAddrs` but no
  * `listenAddrs`. Without this, naming a relay would silently REPLACE the node's
- * direct TCP listener with a circuit-only one.
+ * direct TCP listener with a circuit-only one. Shared with the strand-node
+ * derivation (`strand-network-config.ts`), which applies the same rule.
  *
  * NOTE: mirrors `createLibp2pNode`'s own default listen addr in
  * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (`/ip4/0.0.0.0/tcp/<port>`,
  * and `CadreNode` passes `port: 0`) — that file is the source of truth. If it
  * ever changes its default, this constant has to follow.
  */
-const DEFAULT_DIRECT_LISTEN_ADDR = '/ip4/0.0.0.0/tcp/0';
+export const DEFAULT_DIRECT_LISTEN_ADDR = '/ip4/0.0.0.0/tcp/0';
 /**
  * libp2p's relay SEARCH listener: registers one pending reservation and dials
- * nothing. One entry covers every configured relay — the pending reservation is
- * per-listener, not per-relay, and `relay-reservation.ts` fills it with whichever
- * relay answers first.
+ * nothing. The pending reservation is per-LISTENER, not per-relay: the control
+ * node binds one entry for its whole relay list (`relay-reservation.ts` fills it
+ * with whichever relay answers first), a strand node binds one entry per relay so
+ * each relay's supervisor has a slot of its own to fill.
  */
 export const RELAY_SEARCH_LISTEN_ADDR = '/p2p-circuit';
 /**
@@ -66,6 +81,10 @@ export const RELAY_SEARCH_LISTEN_ADDR = '/p2p-circuit';
  * operator configuration, so a typo must fail loudly at start rather than
  * silently costing the node its reachability.
  *
+ * No node LISTENS on these any more (see the module doc); they are the validated
+ * form of `relayAddrs`, read by `CadreNode.circuitRelayTargets` for the delegate
+ * announce and by `strand-network-config.ts` for the per-relay supervisor list.
+ *
  * Deliberately unlike `extractCircuitRelayTargets` (`delegate-admission.ts`), which
  * SKIPS a bad entry: that one reads addresses discovered at runtime from peers, where
  * one bad entry must not be fatal.
@@ -74,24 +93,26 @@ export function relayCircuitAddrs(relayAddrs) {
     return dedupe(relayAddrs.map(circuitListenAddr));
 }
 /**
- * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
- * relay listen entry `route` calls for, deduplicated, order-stable (configured
- * entries first). Returns `undefined` when neither field is set, so callers keep
- * omitting `listenAddrs` and inherit db-p2p's default.
+ * The listen multiaddrs the CONTROL node binds: configured `listenAddrs` plus ONE
+ * bare `/p2p-circuit` search entry when `relayAddrs` names any relay, deduplicated,
+ * order-stable (configured entries first). Returns `undefined` when neither field
+ * is set, so callers keep omitting `listenAddrs` and inherit db-p2p's default.
  *
- * Every `relayAddrs` entry is validated on BOTH routes — the `'search'` route
- * discards the resolved circuit addrs, but an operator typo must fail at config
- * resolution either way.
+ * Every `relayAddrs` entry is validated even though the search entry discards the
+ * resolved circuit addrs — an operator typo must fail at config resolution. A
+ * hand-written `<relay>/p2p-circuit` entry in `listenAddrs` is rejected outright
+ * (see {@link rejectConfiguredCircuitListenAddrs}).
+ *
+ * Strand nodes derive their own listen set from the same config in
+ * `strand-network-config.ts` (`strandNodeAddrs`) — one search entry per relay,
+ * fixed direct ports made ephemeral.
  */
-export function resolveListenAddrs(network, route = 'configured') {
-    const configured = relayCircuitAddrs(network?.relayAddrs ?? []);
-    const relayEntries = route === 'search'
-        ? (configured.length > 0 ? [RELAY_SEARCH_LISTEN_ADDR] : [])
-        : configured;
+export function resolveListenAddrs(network) {
+    const relayEntries = relayCircuitAddrs(network?.relayAddrs ?? []).length > 0
+        ? [RELAY_SEARCH_LISTEN_ADDR]
+        : [];
     const listenAddrs = network?.listenAddrs;
-    if (route === 'search') {
-        rejectConfiguredCircuitListenAddrs(listenAddrs ?? []);
-    }
+    rejectConfiguredCircuitListenAddrs(listenAddrs ?? []);
     if (!listenAddrs && relayEntries.length === 0) {
         return undefined;
     }
@@ -100,12 +121,210 @@ export function resolveListenAddrs(network, route = 'configured') {
     // acquiring a slot is the whole point of configuring a relay.
     return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...relayEntries]);
 }
+/**
+ * The `wsPort` value passed purely to turn `@optimystic/db-p2p`'s WebSocket transport
+ * ON. It is never bound, so it is deliberately `0` rather than a port scraped from a
+ * listen entry.
+ *
+ * WHY it is a switch and not a port: `createLibp2pNode`
+ * (`../optimystic/packages/db-p2p/src/libp2p-node.ts`) feeds `wsPort` into BOTH its
+ * default transports and its default listen addrs, and `createLibp2pNodeBase`
+ * (`libp2p-node-base.ts:490-491`) falls back to those two defaults INDEPENDENTLY:
+ *
+ * ```ts
+ * const listenAddrs = options.listenAddrs ?? defaults.listenAddrs;
+ * const transports  = options.transports  ?? defaults.transports;
+ * ```
+ *
+ * `cadre-core` always supplies explicit `listenAddrs` alongside it, so the synthesized
+ * `/ip4/<wsHost>/tcp/<wsPort>/ws` default ADDRESS is discarded while the `webSockets()`
+ * transport it added survives. A scraped port would also be a lie whenever a config
+ * names several WebSocket addresses on different ports, and the strand path rewrites
+ * fixed ports to `0` regardless (`strand-network-config.ts`).
+ *
+ * NOTE: db-p2p's own doc comment on `wsPort` (`libp2p-node-base.ts:170-172`) says it is
+ * "Ignored when `transports`/`listenAddrs` are explicitly provided" — true of the
+ * address half, NOT of the transport half, which is the half this depends on. Re-verify
+ * empirically rather than trusting that comment: `test/listen-transport-options.spec.ts`
+ * boots a real node and asserts a `/ws` multiaddr appears. If db-p2p ever makes the
+ * comment true of both halves, it needs an explicit `enableWebSockets` switch and this
+ * constant becomes unusable.
+ */
+const WS_TRANSPORT_SWITCH_PORT = 0;
+/**
+ * The transport-derived libp2p options `listenAddrs` implies, and the gate that stops a
+ * listen address the node has no transport for from being SILENTLY dropped.
+ *
+ * libp2p's transport manager sorts configured listen addresses by which transport claims
+ * them, discards the unclaimed ones, and raises `UnsupportedListenAddressesError` only
+ * when EVERY address was discarded. Pair a TCP address with a WebSocket one — which is
+ * exactly what the shipped configs do — and the TCP address carries the start while the
+ * missing WebSocket listener is never reported. Two halves of `NetworkConfig` that have
+ * to agree (`listenAddrs`, and the transports the node will actually have) were never
+ * checked against each other; this is that check, and it covers both node kinds because
+ * both derive their listen set from the same config here ({@link resolveListenAddrs}) or
+ * in `strand-network-config.ts`, and both call this on the result.
+ *
+ * The two transport classes are handled differently, on purpose:
+ *
+ * - **WebSocket is DERIVED.** It is the one non-TCP transport the shipped configs need
+ *   (the React Native reference app's companion drone; `cadre start --ws-port`), and
+ *   `@optimystic/db-p2p` already knows how to add it. `cadre-core` grows no dependency
+ *   and decides no transport policy — it flips db-p2p's own switch
+ *   ({@link WS_TRANSPORT_SWITCH_PORT}).
+ * - **Everything else is REFUSED.** Deriving `/quic-v1`, `/webrtc` or `/webtransport`
+ *   would mean importing transport packages into every `cadre-core` consumer including
+ *   the React Native and browser bundles (against the cross-platform rule in
+ *   `AGENTS.md`) and duplicating policy `libp2p-node.ts` owns. So name the address, name
+ *   the transport it needs, and refuse to start — matching how `network.relayAddrs` and
+ *   `network.announceAddrs` already treat an operator typo.
+ *
+ * Returns `{}` unconditionally when `network.transports` is set: a programmatic embedder
+ * supplying transport factories owns the policy, and the factories are opaque — nothing
+ * can be inferred from them. That is what keeps the RN phone, the web app, and the
+ * integration-test harness unaffected.
+ *
+ * NOTE: pairing this with {@link resolveListenAddrs} is a CONVENTION, not a structure —
+ * a third libp2p-node build site could resolve listen addrs and forget to call this,
+ * putting the original bug back on that path. Both existing sites are covered
+ * (`cadre-node.ts` → `buildControlNodeOptions`, `strand-network-config.ts` →
+ * `strandNodeAddrs`), and they are the only two `createLibp2pNode` callers in this repo
+ * that derive their listen set from a `NetworkConfig` — the other callers
+ * (`integration-tests/src/harness/test-party.ts`, `quereus-plugin-sereus`'s `connect.ts`
+ * and `connect-browser.ts`) pass no `listenAddrs` at all, or pass their own transports
+ * with it. If a third CONFIG-derived site appears, fold the two functions into one that
+ * returns listen addrs and transport options together, so forgetting becomes impossible
+ * rather than merely unlikely.
+ *
+ * @param listenAddrs the ALREADY-resolved listen set — the output of
+ *   {@link resolveListenAddrs}, or the strand derivation, after any per-node rewriting —
+ *   so the check reads what this node will actually bind.
+ * @throws {UnbindableListenAddressError} when a listen entry names a transport outside
+ *   {tcp, ws/wss, p2p-circuit}.
+ */
+export function resolveTransportOptions(network, listenAddrs) {
+    if (network?.transports) {
+        return {};
+    }
+    const kinds = (listenAddrs ?? []).map((addr) => [addr, listenTransportKind(addr)]);
+    const unsupported = kinds.filter(([, kind]) => kind === 'unsupported').map(([addr]) => addr);
+    if (unsupported.length > 0) {
+        throw new UnbindableListenAddressError(unsupported);
+    }
+    return kinds.some(([, kind]) => kind === 'websockets') ? { wsPort: WS_TRANSPORT_SWITCH_PORT } : {};
+}
+/**
+ * Thrown at config resolution when `network.listenAddrs` names an address none of the
+ * default transports can bind. Names each offending address alongside the libp2p
+ * transport package it would need — what the operator has without this is a node that
+ * starts and silently never listens there.
+ */
+export class UnbindableListenAddressError extends Error {
+    constructor(listenAddrs) {
+        super('network.listenAddrs names an address this node has no transport for: ' +
+            `${listenAddrs.map((a) => `${a} — ${unbindableReason(a)}`).join('; ')}. ` +
+            'Default transports bind TCP (including /unix/<path>), WebSocket (/ws, /wss) and circuit-relay addresses only. ' +
+            'Either drop the address, or supply the transport programmatically via network.transports.');
+        this.listenAddrs = listenAddrs;
+        this.name = 'UnbindableListenAddressError';
+    }
+}
+/**
+ * Which default transport claims `listenAddr`, or `'unsupported'` when none does.
+ *
+ * Classification is a multiaddr COMPONENT question, not a string question, so this
+ * parses and reads the transport stack — the component names left once the addressing
+ * and security layers are dropped. That stack is outermost-LAST
+ * (`/ip4/…/tcp/443/tls/ws` → `['tcp', 'ws']`), which is why its terminal entry decides.
+ *
+ * An unparsable entry is `'ignored'` and passes through untouched, following
+ * `isConfiguredCircuitListenAddr` below and `ephemeralPortListenAddr`
+ * (`strand-network-config.ts`): libp2p reports a bad listen addr itself, and this check
+ * must only ever ADD a denial.
+ */
+function listenTransportKind(listenAddr) {
+    let stack;
+    try {
+        stack = transportStack(listenAddr);
+    }
+    catch {
+        return 'ignored';
+    }
+    const outermost = stack.at(-1);
+    if (outermost === undefined) {
+        // Nothing but addressing components — a bare `/ip4/1.2.3.4`. No transport claims
+        // it, so it is dropped by exactly the same silent path this check exists to close.
+        return 'unsupported';
+    }
+    if (outermost === 'p2p-circuit') {
+        return 'circuit';
+    }
+    if (outermost === 'ws' || outermost === 'wss') {
+        return 'websockets';
+    }
+    // Only a BARE tcp or unix stack is TCP. `@libp2p/tcp` binds both — its `listenFilter`
+    // accepts an exact TCP match OR a `/unix/<path>` address (a named pipe on Windows) —
+    // and nothing layered on top of either, which is why `/tcp/<port>/<anything else>` is
+    // NOT waved through merely because a `tcp` component happens to appear.
+    return stack.length === 1 && (outermost === 'tcp' || outermost === 'unix') ? 'tcp' : 'unsupported';
+}
+/**
+ * Component names of `listenAddr` with the addressing and security layers removed, so
+ * what remains names transports. Host components (`ip4`, `dns4`, …) and the layers that
+ * ride inside a transport without being one (`tls`, `sni`, `certhash`, `p2p`) say
+ * nothing about which transport has to be configured.
+ */
+function transportStack(listenAddr) {
+    return multiaddr(listenAddr).getComponents()
+        .map((component) => component.name)
+        .filter((name) => !NON_TRANSPORT_COMPONENTS.has(name));
+}
+/** Components that address or secure a connection rather than name its transport. */
+const NON_TRANSPORT_COMPONENTS = new Set([
+    'ip4', 'ip6', 'ip6zone', 'dns', 'dns4', 'dns6', 'dnsaddr',
+    'tls', 'sni', 'certhash', 'p2p', 'noise'
+]);
+/**
+ * Why `listenAddr` cannot be bound, phrased for the operator: the libp2p package that
+ * would make it bindable where one is known, and otherwise what is wrong with it.
+ *
+ * Read OUTERMOST-first (`/udp/…/quic-v1/webtransport` needs `@libp2p/webtransport`,
+ * not the `@libp2p/quic` it rides on), matching how `listenTransportKind` decides.
+ */
+function unbindableReason(listenAddr) {
+    let stack;
+    try {
+        stack = transportStack(listenAddr);
+    }
+    catch {
+        return 'not a parsable multiaddr';
+    }
+    if (stack.length === 0) {
+        return 'it names no transport component';
+    }
+    const pkg = [...stack].reverse().map((name) => TRANSPORT_PACKAGES[name]).find((p) => p !== undefined);
+    return pkg === undefined ? 'needs an unrecognized transport' : `needs ${pkg}`;
+}
+/**
+ * The libp2p package each unbindable transport component comes from. Naming the package
+ * is the actionable half of the refusal — the operator either drops the address or wires
+ * that package in through `network.transports`.
+ */
+const TRANSPORT_PACKAGES = {
+    'quic': '@libp2p/quic',
+    'quic-v1': '@libp2p/quic',
+    'webtransport': '@libp2p/webtransport',
+    'webrtc': '@libp2p/webrtc',
+    'webrtc-direct': '@libp2p/webrtc'
+};
 /**
  * Thrown out of `CadreNode.start()` when the boot-path reservation drive for
- * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt.
+ * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt,
+ * UNLESS `network.requireRelay` is explicitly `false` (see `driveControlRelayReservation`,
+ * which logs and returns instead on that posture).
  *
- * This is what keeps `network.relayAddrs` fail-fast now that the control node
- * takes the `'search'` route: libp2p's own `UnsupportedListenAddressesError` used
+ * This is what keeps `network.relayAddrs` fail-fast by default now that the control node
+ * listens on the bare search entry: libp2p's own `UnsupportedListenAddressesError` used
  * to abort start from inside `listen()`, and an operator who names a relay is
  * telling the node it has no other reachability — coming up undialable is worse
  * than not coming up. Names the relays and the reservation's own reason, both of
@@ -122,7 +341,7 @@ export class RelayReservationFailedError extends Error {
 }
 /**
  * A hand-written `<relay>/p2p-circuit` entry in `network.listenAddrs` is the
- * CONFIGURED listener shape, and it is unusable on the `'search'` route: libp2p
+ * CONFIGURED listener shape, and it is unusable on the control node: libp2p
  * dials that relay from inside `listen()`, the bring-up quiet period
  * (`membership-connection-gater.ts`) denies exactly that dial, `listen()` fails, and
  * the transport manager's default `FATAL_ALL` aborts `libp2p.start()`. The operator
@@ -130,7 +349,10 @@ export class RelayReservationFailedError extends Error {
  * naming the cause, so name it here instead.
  *
  * `network.relayAddrs` is the exact replacement — same relay, and the reservation is
- * driven after bring-up, which is the whole point of the route.
+ * driven after bring-up, which is the whole point of the search shape. (A strand node
+ * built directly from such a config folds the entry into its supervised relay set
+ * instead — `strand-network-config.ts` — but the control node's resolution runs first
+ * on every machine, so in production the entry never reaches a strand node.)
  */
 function rejectConfiguredCircuitListenAddrs(listenAddrs) {
     const configured = listenAddrs.filter(isConfiguredCircuitListenAddr);
@@ -141,8 +363,12 @@ function rejectConfiguredCircuitListenAddrs(listenAddrs) {
             'connections. Move the relay to network.relayAddrs, which reserves after bring-up.');
     }
 }
-/** `<something>/p2p-circuit` — the configured shape, as opposed to the bare search addr. */
-function isConfiguredCircuitListenAddr(listenAddr) {
+/**
+ * `<something>/p2p-circuit` — the configured shape, as opposed to the bare search
+ * addr. An unparsable entry is `false`: libp2p reports a bad listen addr itself,
+ * and this helper only ever ADDS a denial (or, on the strand path, a supervisor).
+ */
+export function isConfiguredCircuitListenAddr(listenAddr) {
     if (listenAddr === RELAY_SEARCH_LISTEN_ADDR) {
         return false;
     }
@@ -156,13 +382,14 @@ function isConfiguredCircuitListenAddr(listenAddr) {
     }
 }
 /**
- * One entry of {@link relayCircuitAddrs}: the addr the node listens on for this relay.
+ * One entry of {@link relayCircuitAddrs}: this relay's addr in the configured shape.
  *
  * NOTE: an entry carrying components AFTER `/p2p-circuit` — a full relayed DIAL addr,
- * `…/p2p/<relay>/p2p-circuit/p2p/<someone else>` — is passed through as written and
- * would be listened on verbatim. It validates (the relay it names is real), so only an
- * operator who pastes a peer's relayed address into `relayAddrs` hits it; if that turns
- * out to be a common paste, truncate at the `/p2p-circuit` component here.
+ * `…/p2p/<relay>/p2p-circuit/p2p/<someone else>` — is passed through as written. It
+ * validates (the relay it names is real), and every consumer reads only the relay
+ * peer id and the dial prefix before `/p2p-circuit`, so the tail is ignored rather
+ * than harmful; if that paste turns out to be common, truncate at the `/p2p-circuit`
+ * component here so the resolved list is canonical.
  */
 function circuitListenAddr(relayAddr) {
     const alreadyCircuit = parseComponents(relayAddr).some((c) => c.name === 'p2p-circuit');

package/dist/relay-addrs.js.map

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

package/dist/relay-reservation.d.ts

@@ -16,7 +16,7 @@
  * module. It is **fail-soft by construction**: nothing here throws.
  *
  * EVERY cadre CONTROL node now takes that route — `network.relayAddrs` resolves
- * to the bare search entry (`relay-addrs.ts` → `RelayListenRoute`) and
+ * to the bare search entry (`relay-addrs.ts` → `resolveListenAddrs`) and
  * `CadreNode.start()` drives this module once the control database is up. The
  * configured shape would dial the relay from inside `libp2p.start()`, putting a
  * sibling in this node's cohort before its own control database existed, and a
@@ -28,8 +28,30 @@
  * a `RelayReservationFailedError` out of `start()` when the first attempt lands
  * nothing (fail-fast, the operator asked for this relay), while a node that calls
  * `CadreNode.reserveRelays()` itself gets a non-`reserved` status and stays up
- * (fail-soft, the browser-tab posture). Configuring both is now redundant, not
- * fatal. STRAND nodes still take the configured shape — see `relay-addrs.ts`.
+ * (fail-soft, the browser-tab posture). `network.requireRelay: false` gives a
+ * CONFIGURED relay the fail-soft posture too, for a node that must boot with no
+ * network at all — same drive, same supervisor, only the throw is dropped.
+ * Configuring both is now redundant, not fatal.
+ *
+ * STRAND nodes take the same route, ONE supervisor PER RELAY
+ * (`strand-instance-manager.ts` → `buildStrandRuntime`): each configured relay
+ * gets its own bare `/p2p-circuit` listener (`strand-network-config.ts`) and its
+ * own {@link superviseRelayReservation} over just that relay's addr, fail-soft
+ * like the browser tab. The configured shape they used to take
+ * (`<relay>/p2p-circuit`, reserved from inside `libp2p.start()`) is gone from
+ * cadre-built nodes entirely, because it loses its address and never recovers in
+ * three situations — the relay restarts, either side hangs up the relay
+ * connection, and libp2p's OWN reservation refresh (which removes the reservation
+ * before re-creating it, and a configured listener republishes only from inside
+ * its own `listen()`). The last one needs no network event at all: at the relay
+ * default TTL of two hours every configured-shape node went undialable ~1 h 55 min
+ * after reserving. A search listener republishes on `relay:created-reservation`
+ * for its own pending id, which the refresh re-queues, and the supervisor covers
+ * the other two.
+ *
+ * Because a strand node runs one supervisor per relay, "is the reservation held"
+ * is asked PER RELAY ({@link circuitMultiaddrsVia}): relay X's supervisor must not
+ * be satisfied by relay Y's circuit addr, or it would never re-drive X.
  *
  * ⚠️ WHY THE RESERVATION IS REQUESTED EXPLICITLY RATHER THAN LEFT TO DISCOVERY.
  * libp2p fills a search listener's pending reservation from `RelayDiscovery`,
@@ -60,6 +82,19 @@
  * 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.
+ *
+ * One measured refinement to "out of reach": libp2p 3.1.3's `connection.newStream`
+ * records every protocol OUR OWN outbound stream negotiated into the peer store, so
+ * the explicit reservation request writes the relay-hop protocol id against the
+ * relay itself. From then on, discovery CAN refill a freed slot on its own — but
+ * only when the relay answers at that moment (a hangup while the relay stays up;
+ * measured at ~25 ms). A relay that is down when the slot frees fails that one
+ * discovery attempt, which poisons the store's `relayFilter` against it, and
+ * nothing in libp2p tries again: a relay RESTART still needs the supervisor, which
+ * un-poisons the filter before every attempt ({@link clearRelayFilterEntry}). Two
+ * mechanisms in production, one guarantee; the specs disable discovery's half
+ * (`forgetRelayProtocol` in `relay-reservation.spec.ts`) so they prove the
+ * supervisor's.
  */
 import type { Libp2p, PeerId } from '@libp2p/interface';
 /**
@@ -133,6 +168,20 @@ export interface CircuitRelayTransportLike {
  * live rather than a stale snapshot.
  */
 export declare function circuitMultiaddrs(node: Libp2p): string[];
+/**
+ * The node's `/p2p-circuit` multiaddrs THROUGH the relays `addrs` name — the ones
+ * whose `/p2p/<relayPeerId>/p2p-circuit` component names one of them. This is the
+ * "held" question a supervisor over a SUBSET of the node's relays has to ask: a
+ * strand node runs one supervisor per relay, and relay X's supervisor must not be
+ * satisfied by relay Y's addr, or a lost X is never re-driven.
+ *
+ * Falls back to EVERY circuit addr when any entry names no relay peer id (no
+ * `/p2p/` component, or unparsable): such an addr can still be dialed and reserved
+ * through, but the addr it earns cannot be attributed to it, so "any circuit addr"
+ * is the only answer that does not mark a live reservation as lost. The control
+ * node passes its whole relay list, so its answer is the same either way.
+ */
+export declare function circuitMultiaddrsVia(node: Libp2p, addrs: readonly string[]): string[];
 /**
  * The running node's circuit-relay transport, or `null` when it has none.
  *
@@ -174,6 +223,19 @@ export interface RelayReservationSupervisorOptions extends RelayReserveOptions {
     minBackoffMs?: number;
     /** Backoff ceiling. Default 60_000. */
     maxBackoffMs?: number;
+    /**
+     * Awaited before every drive AFTER the first — never before the first attempt,
+     * which the caller has typically prepared for already. A hook that throws or
+     * rejects is logged and the drive still runs: the hook is preparation, and a
+     * failed preparation must not cost the attempt itself.
+     *
+     * What a strand node uses it for: re-announcing its delegate peer id to the relay
+     * about to be re-dialed. A party control node running the relay server admits a
+     * strand node on an in-memory delegate grant, and a relay restart drops every
+     * grant it held — so a re-drive that did not re-announce first would be denied
+     * at the relay's connection gate.
+     */
+    beforeRedrive?: () => Promise<void> | void;
 }
 /**
  * A running retry loop for one node + relay list. Obtained from
@@ -217,6 +279,12 @@ export interface RelayReservationSupervisor {
  *    If that lands a reservation, rejoin the healthy path above; if not, sleep
  *    the current backoff and double it up to `maxBackoffMs`.
  *
+ * "Held" is judged PER RELAY — a circuit addr through one of `addrs`' relays
+ * ({@link circuitMultiaddrsVia}) — so several loops over one node, one relay each
+ * (a strand node), each re-drive exactly the relay they own. Every drive after the
+ * first is preceded by the optional `beforeRedrive` hook
+ * ({@link RelayReservationSupervisorOptions}).
+ *
  * Starts immediately; the first tick runs before this returns.
  */
 export declare function superviseRelayReservation(node: Libp2p, addrs: readonly string[], opts?: RelayReservationSupervisorOptions): RelayReservationSupervisor;