@serfab/cadre-core 0.11.0 → 0.12.0

package/src/peer-record.ts

@@ -135,6 +135,39 @@ export function trailingPeerId(addr: Multiaddr): string | null {
   return p2p.length > 0 ? (p2p[p2p.length - 1].value ?? null) : null;
 }
 
+/**
+ * `addr` guaranteed to terminate in `/p2p/<peerId>` — the shape every dial path
+ * needs — or `null` when it cannot, because the address already terminates in a
+ * DIFFERENT peer id and therefore does not reach `peerId` at all.
+ *
+ * Three input shapes, matching what a `CadrePeer` record can legitimately carry:
+ *
+ * - no `/p2p/` component (`/ip4/1.2.3.4/tcp/4001`) — the suffix is appended;
+ * - a relay hop with the destination missing (`…/p2p/<relay>/p2p-circuit`) — the
+ *   last component is the circuit, not a peer id, so the suffix is appended and
+ *   the address becomes the full `…/p2p/<relay>/p2p-circuit/p2p/<peerId>`;
+ * - already terminating in `/p2p/<X>` — returned untouched when `X` is `peerId`,
+ *   dropped otherwise.
+ *
+ * This is deliberately the same rule libp2p applies internally in
+ * `calculateMultiaddrs` (append when the LAST component is not `p2p`) followed by
+ * its wrong-peer-id filter, so a normalized list matches what libp2p would have
+ * built anyway. Normalizing before the dial is what keeps a list from mixing
+ * suffixed and unsuffixed entries, which `getPeerAddress` rejects outright
+ * ("Multiaddrs must all have the same peer id or have no peer id") — taking the
+ * whole peer down with it, not just the odd address.
+ *
+ * Never use before signature verification: verification runs against the
+ * original on-record strings.
+ */
+export function withTrailingPeerId(addr: Multiaddr, peerId: string): Multiaddr | null {
+  const components = addr.getComponents();
+  if (components[components.length - 1]?.name !== 'p2p') {
+    return addr.encapsulate(`/p2p/${peerId}`);
+  }
+  return trailingPeerId(addr) === peerId ? addr : null;
+}
+
 /**
  * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
  * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate

package/src/relay-addrs.ts

@@ -1,111 +1,218 @@
-/**
- * Translate `network.relayAddrs` — the operator-facing "use these relay servers"
- * setting — into the mechanism this repo already has for reserving a circuit-relay
- * slot: a `…/p2p/<relayPeerId>/p2p-circuit` entry in the node's listen addrs.
- *
- * `@libp2p/circuit-relay-v2`'s transport is always present on the Node path
- * (`../optimystic/packages/db-p2p/src/libp2p-node.ts` pushes `circuitRelayTransport()`
- * unconditionally), and listening on a relay's circuit addr is what makes libp2p dial
- * that relay and hold a reservation. Everything downstream of the listen list —
- * the reservation itself, `CadreNode.circuitRelayTargets()` picking delegate-announce
- * targets, strand nodes inheriting the listen addrs, the `/p2p-circuit`-first address
- * publishing in `registerSelf` — then works unchanged.
- *
- * So `relayAddrs` is a second, friendlier door onto an existing mechanism:
- *
- *   effective listen addrs = listenAddrs ++ relayAddrs.map(a => a + '/p2p-circuit')
- *
- * NOTE: this is the FAIL-FAST route to a reservation — libp2p's transport manager
- * throws when a configured circuit listener cannot listen, so naming a relay that
- * is down means the node does not start. The fail-soft route is the bare
- * `/p2p-circuit` search listener driven by `relay-reservation.ts`. The two are
- * ALTERNATIVES, not layers: configuring `relayAddrs` on a node that already
- * reserves via the search listener adds the fatal listener back and the node
- * stops booting when its relay is down.
- */
-
-import { multiaddr, type Component } from '@multiformats/multiaddr';
-import { circuitRelayTargetOrThrow } from './delegate-admission.js';
-import type { NetworkConfig } from './types.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.
- *
- * 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';
-
-/**
- * The circuit-listen multiaddr for each configured relay: `<relayAddr>/p2p-circuit`.
- * An entry that already carries `/p2p-circuit` is passed through unchanged.
- * Throws on an entry that is unparsable or names no relay peerId — this is
- * operator configuration, so a typo must fail loudly at start rather than
- * silently costing the node its reachability.
- *
- * 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.
- */
-export function relayCircuitAddrs(relayAddrs: readonly string[]): string[] {
-  return dedupe(relayAddrs.map(circuitListenAddr));
-}
-
-/**
- * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
- * circuit-listen addr of every configured 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.
- */
-export function resolveListenAddrs(network: NetworkConfig | undefined): string[] | undefined {
-  const circuits = relayCircuitAddrs(network?.relayAddrs ?? []);
-  const listenAddrs = network?.listenAddrs;
-  if (!listenAddrs && circuits.length === 0) {
-    return undefined;
-  }
-  // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
-  // empty — but a relay named alongside it still gets its circuit listener, since
-  // acquiring one is the whole point of configuring a relay.
-  return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...circuits]);
-}
-
-/**
- * One entry of {@link relayCircuitAddrs}: the addr the node listens on for this relay.
- *
- * 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.
- */
-function circuitListenAddr(relayAddr: string): string {
-  const alreadyCircuit = parseComponents(relayAddr).some((c) => c.name === 'p2p-circuit');
-  const listenAddr = alreadyCircuit ? relayAddr : `${relayAddr}/p2p-circuit`;
-  try {
-    circuitRelayTargetOrThrow(listenAddr); // validates the relay peerId
-  } catch (err) {
-    throw new Error(
-      `network.relayAddrs entry names no relay peerId (expected <dial addr>/p2p/<relayPeerId>): ${relayAddr}`,
-      { cause: err }
-    );
-  }
-  return listenAddr;
-}
-
-/** Multiaddr components of `relayAddr`, with the config field named on a parse failure. */
-function parseComponents(relayAddr: string): Component[] {
-  try {
-    return multiaddr(relayAddr).getComponents();
-  } catch (err) {
-    throw new Error(`network.relayAddrs entry is not a valid multiaddr: ${relayAddr}`, { cause: err });
-  }
-}
-
-/** Exact-string dedupe, first occurrence wins, so the list is stable across restarts. */
-function dedupe(addrs: readonly string[]): string[] {
-  return [...new Set(addrs)];
-}
+/**
+ * Translate `network.relayAddrs` — the operator-facing "use these relay servers"
+ * 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.
+ *
+ * The bare `/p2p-circuit` search listener cannot open a connection on its own:
+ * libp2p fills a pending reservation from `RelayDiscovery`, which nominates a peer
+ * only once the relay-hop protocol id is in that peer's peer-store protocol list,
+ * and that list is written exclusively by IDENTIFY — which `@optimystic/db-p2p`
+ * namespaces per network, so a cadre node and a stock relay never identify each
+ * other. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
+ */
+
+import { multiaddr, type Component } from '@multiformats/multiaddr';
+import { circuitRelayTargetOrThrow } from './delegate-admission.js';
+import type { NetworkConfig } from './types.js';
+import type { RelayReservationState } from './relay-reservation.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.
+ *
+ * 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';
+
+/**
+ * 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.
+ */
+export const RELAY_SEARCH_LISTEN_ADDR = '/p2p-circuit';
+
+/**
+ * Which listener shape `network.relayAddrs` resolves to for this caller — see the
+ * table in the module doc. Defaults to `'configured'` everywhere except the
+ * control node's own libp2p options.
+ */
+export type RelayListenRoute = 'configured' | 'search';
+
+/**
+ * The circuit-listen multiaddr for each configured relay: `<relayAddr>/p2p-circuit`.
+ * An entry that already carries `/p2p-circuit` is passed through unchanged.
+ * Throws on an entry that is unparsable or names no relay peerId — this is
+ * operator configuration, so a typo must fail loudly at start rather than
+ * silently costing the node its reachability.
+ *
+ * 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.
+ */
+export function relayCircuitAddrs(relayAddrs: readonly string[]): string[] {
+  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.
+ *
+ * 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.
+ */
+export function resolveListenAddrs(
+  network: NetworkConfig | undefined,
+  route: RelayListenRoute = 'configured'
+): string[] | undefined {
+  const configured = relayCircuitAddrs(network?.relayAddrs ?? []);
+  const relayEntries = route === 'search'
+    ? (configured.length > 0 ? [RELAY_SEARCH_LISTEN_ADDR] : [])
+    : configured;
+  const listenAddrs = network?.listenAddrs;
+  if (route === 'search') {
+    rejectConfiguredCircuitListenAddrs(listenAddrs ?? []);
+  }
+  if (!listenAddrs && relayEntries.length === 0) {
+    return undefined;
+  }
+  // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
+  // empty — but a relay named alongside it still gets its listen entry, since
+  // acquiring a slot is the whole point of configuring a relay.
+  return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...relayEntries]);
+}
+
+/**
+ * Thrown out of `CadreNode.start()` when the boot-path reservation drive for
+ * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt.
+ *
+ * This is what keeps `network.relayAddrs` fail-fast now that the control node
+ * takes the `'search'` route: 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
+ * which the libp2p error omitted.
+ */
+export class RelayReservationFailedError extends Error {
+  constructor(
+    readonly relayAddrs: readonly string[],
+    readonly state: RelayReservationState
+  ) {
+    super(
+      `network.relayAddrs reservation failed (status: ${state.status}): ` +
+      `${state.error ?? 'no /p2p-circuit address appeared'} — relays: ${relayAddrs.join(', ')}`
+    );
+    this.name = 'RelayReservationFailedError';
+  }
+}
+
+/**
+ * A hand-written `<relay>/p2p-circuit` entry in `network.listenAddrs` is the
+ * CONFIGURED listener shape, and it is unusable on the `'search'` route: 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
+ * would see `UnsupportedListenAddressesError` from deep inside bring-up with nothing
+ * 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.
+ */
+function rejectConfiguredCircuitListenAddrs(listenAddrs: readonly string[]): void {
+  const configured = listenAddrs.filter(isConfiguredCircuitListenAddr);
+  if (configured.length > 0) {
+    throw new Error(
+      'network.listenAddrs names a relay directly ' +
+      `(${configured.join(', ')}), which a control node cannot listen on: libp2p would ` +
+      'dial that relay during control-database bring-up, when the node accepts no ' +
+      '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: string): boolean {
+  if (listenAddr === RELAY_SEARCH_LISTEN_ADDR) {
+    return false;
+  }
+  try {
+    return multiaddr(listenAddr).getComponents().some((c) => c.name === 'p2p-circuit');
+  } catch {
+    // Not our error to raise: libp2p reports an unparsable listen addr itself, and
+    // this helper only ever ADDS a denial.
+    return false;
+  }
+}
+
+/**
+ * One entry of {@link relayCircuitAddrs}: the addr the node listens on for this relay.
+ *
+ * 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.
+ */
+function circuitListenAddr(relayAddr: string): string {
+  const alreadyCircuit = parseComponents(relayAddr).some((c) => c.name === 'p2p-circuit');
+  const listenAddr = alreadyCircuit ? relayAddr : `${relayAddr}/p2p-circuit`;
+  try {
+    circuitRelayTargetOrThrow(listenAddr); // validates the relay peerId
+  } catch (err) {
+    throw new Error(
+      `network.relayAddrs entry names no relay peerId (expected <dial addr>/p2p/<relayPeerId>): ${relayAddr}`,
+      { cause: err }
+    );
+  }
+  return listenAddr;
+}
+
+/** Multiaddr components of `relayAddr`, with the config field named on a parse failure. */
+function parseComponents(relayAddr: string): Component[] {
+  try {
+    return multiaddr(relayAddr).getComponents();
+  } catch (err) {
+    throw new Error(`network.relayAddrs entry is not a valid multiaddr: ${relayAddr}`, { cause: err });
+  }
+}
+
+/** Exact-string dedupe, first occurrence wins, so the list is stable across restarts. */
+function dedupe(addrs: readonly string[]): string[] {
+  return [...new Set(addrs)];
+}