@serfab/cadre-core 1.8.0 → 1.10.0

package/src/strand-formation-rejection.ts

@@ -0,0 +1,129 @@
+/**
+ * How a formation dial fails, as types a joining device can branch on without reading the
+ * human-facing wording: a responder's refusal carries a fixed {@link FormationRejectionCode}
+ * on the wire and surfaces as a {@link FormationRejectedError}; a dial that never got an
+ * answer surfaces as a {@link FormationUnreachableError}.
+ */
+
+/**
+ * Why a formation responder refused a join. Sent beside the free-text `reason` on every
+ * `approved: false` result frame (`FormationResultMessage.code`).
+ */
+export type FormationRejectionCode =
+  /**
+   * No invitation row for this token on THIS responder. Retryable: a sibling machine of the
+   * inviter may not have received the row yet. Leaks nothing — only a holder of the token can
+   * ask, and an unknown token means the same as one never minted.
+   */
+  | 'token-unknown'
+  /**
+   * The invitation expired, or every allowed use is recorded. The loser of a redemption race
+   * and a latecomer both get this code, so neither can tell the two apart.
+   */
+  | 'token-spent'
+  /** The joiner's consent signature does not verify (or `partyId` does not embed `peerKey`). */
+  | 'consent-invalid'
+  /** The responder's disclosure validator refused the disclosure. */
+  | 'disclosure-invalid'
+  | 'disclosure-too-large'
+  /** The invitation's outside approval hook answered no. */
+  | 'approval-refused'
+  /** The invitation's outside approval hook could not be reached or did not answer in time. */
+  | 'approval-unavailable'
+  /** The inviter's approval setup is wrong: a malformed answer, an unenrolled key, or a misconfigured hook. */
+  | 'approval-invalid'
+  /**
+   * The host strand is not running (or not yet replicated) on this responder, or issuing the
+   * joiner's membership invitation into it failed.
+   */
+  | 'host-strand-unavailable'
+  /** The host strand predates the per-party identity split and can never admit a joiner. */
+  | 'host-strand-must-be-recreated'
+  /** The responder is at its cap on concurrent formation sessions. */
+  | 'busy'
+  /** Provisioning outran the responder's budget; the invitation is left unspent. */
+  | 'provisioning-timeout'
+  /** The consent write failed for a reason other than a spent invitation. */
+  | 'conflict'
+  /** An unexpected responder-side failure. */
+  | 'internal';
+
+/**
+ * Which rejections are worth retrying — the single place that says so. A retry repeats the
+ * same redemption later (or against another of the inviter's machines); a final code means
+ * no retry of this invitation can succeed.
+ */
+export const FORMATION_REJECTION_RETRYABLE: Readonly<Record<FormationRejectionCode, boolean>> = {
+  'token-unknown': true,
+  'token-spent': false,
+  'consent-invalid': false,
+  'disclosure-invalid': false,
+  'disclosure-too-large': false,
+  'approval-refused': false,
+  'approval-unavailable': true,
+  'approval-invalid': false,
+  'host-strand-unavailable': true,
+  'host-strand-must-be-recreated': false,
+  'busy': true,
+  'provisioning-timeout': true,
+  'conflict': true,
+  'internal': true
+};
+
+/** Is `value` a code this build knows? Own keys only, so a peer's `'constructor'` does not pass. */
+export function isFormationRejectionCode(value: unknown): value is FormationRejectionCode {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(FORMATION_REJECTION_RETRYABLE, value);
+}
+
+/**
+ * The responder answered and refused the join.
+ *
+ * `code` is `'unrecognized'` when the frame carried no code or one this build does not know
+ * — formation runs between two parties on different versions — and such a rejection counts
+ * as retryable: retrying an unknown answer until the invitation expires is safe, while giving
+ * up on one that would have succeeded is not.
+ */
+export class FormationRejectedError extends Error {
+  readonly code: FormationRejectionCode | 'unrecognized';
+  readonly reason: string;
+  readonly retryable: boolean;
+
+  /** Both arguments come straight off the wire, so neither is trusted to have its declared type. */
+  constructor(code: unknown, reason: unknown) {
+    const text = typeof reason === 'string' ? reason : 'no reason provided';
+    super(`Formation rejected: ${text}`);
+    this.name = 'FormationRejectedError';
+    this.code = isFormationRejectionCode(code) ? code : 'unrecognized';
+    this.reason = text;
+    this.retryable = this.code === 'unrecognized' || FORMATION_REJECTION_RETRYABLE[this.code];
+  }
+}
+
+/**
+ * The dial ended before a result frame was read: no responder address parsed, every address
+ * failed to dial, a deadline passed, or the stream closed early. Always retryable. Keeps the
+ * underlying failure's message, and the failure itself as `cause`.
+ */
+export class FormationUnreachableError extends Error {
+  readonly retryable = true;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'FormationUnreachableError';
+  }
+}
+
+/**
+ * The responder approved the join, so the invitation's one-time token is spent, and then a
+ * step on the joining machine failed: persisting the party's membership identity, or
+ * remembering the join. Never retryable: the same invitation can only answer `token-spent`
+ * from now on, so recovery is fixing the local cause and redeeming a fresh invitation.
+ */
+export class FormationPostApprovalError extends Error {
+  readonly retryable = false;
+
+  constructor(readonly strandId: string, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'FormationPostApprovalError';
+  }
+}

package/src/strand-fret-addrs.ts

@@ -0,0 +1,145 @@
+/**
+ * Reading the signed address records a running strand node's FRET routing table holds,
+ * as per-peer addresses ready for that node's own address book (`peer-addr-book.ts`).
+ *
+ * Why a strand node needs this. libp2p's peerStore hides every address one hour after
+ * it was first observed (the `NOTE:` on `mergePeerAddrs`), and FRET does not re-apply
+ * the records it holds: it hands a record to the peerStore when a neighbour's snapshot
+ * delivers it or a saved table is imported, and the peerStore refuses a record whose
+ * sequence number it already has. So a strand node that has been up for more than an
+ * hour would have no address for a peer whose connection then drops, although FRET
+ * still holds that peer's record. `CadreNode.refreshStrandPeerAddrs` re-merges the
+ * records on every pass, which is what keeps another party's strand nodes dialable;
+ * own-party siblings are re-resolved separately, over the strand-addr RPC.
+ *
+ * How long a record is available here is FRET's rule, not this module's: while FRET
+ * holds the entry, and at most 14 days after the record was last confirmed (a peer
+ * connected at export time counts as confirmed then).
+ *
+ * Every record is opened and verified here rather than taken on FRET's word. A record
+ * is self-certifying, the table is reached through a structural type rather than an
+ * interface this package depends on, and the address book write is attributed from what
+ * the record proves, not from the id the table filed it under.
+ */
+
+import debug from 'debug';
+import { PeerRecord, RecordEnvelope } from '@libp2p/peer-record';
+import { peerIdFromPublicKey } from '@libp2p/peer-id';
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
+import { fromString as uint8ArrayFromString } from 'uint8arrays';
+import { withTrailingPeerId } from './peer-record.js';
+
+const log = debug('sereus:cadre:strand-fret-addrs');
+
+/** The slice of FRET's exported routing table read here (`SerializedTable` in `p2p-fret`). */
+interface FretTableSlice {
+  entries: ReadonlyArray<{
+    id: string;
+    /** `envelope` is the base64url of a marshaled libp2p record envelope. */
+    addressRecord?: { envelope: string };
+  }>;
+}
+
+/** The slice of FRET's libp2p service called here. */
+interface FretTableSource {
+  exportTable(): FretTableSlice;
+}
+
+/**
+ * The slice of a strand's libp2p node this module touches. Structurally satisfied by
+ * `Libp2p`; db-p2p registers FRET as `services.fret`.
+ */
+export interface FretAddrHost {
+  peerId: { toString(): string };
+  services?: Record<string, unknown>;
+}
+
+/** What one read of a strand node's FRET table yields. */
+export interface FretPeerAddrs {
+  /** Peer id → the addresses its record lists, each bound to that peer. Table order. */
+  peers: Map<string, Multiaddr[]>;
+  /**
+   * Records left out because they did not decode, did not verify, or were not signed
+   * by and about the peer the table filed them under.
+   */
+  rejected: number;
+}
+
+/**
+ * The addresses of every peer `host`'s FRET table holds a usable signed record for,
+ * `host` itself excluded. A node with no FRET service (a db-p2p build without it, a
+ * test double) reads as an empty table. One bad record never costs the others: it is
+ * counted in `rejected` and skipped.
+ *
+ * Throws only what `exportTable()` throws, which a caller treats like any other
+ * failure of a pass over a node that may be mid-teardown.
+ */
+export async function strandFretPeerAddrs(host: FretAddrHost): Promise<FretPeerAddrs> {
+  const result: FretPeerAddrs = { peers: new Map(), rejected: 0 };
+  const fret = host.services?.fret;
+  if (!isFretTableSource(fret)) {
+    return result;
+  }
+  const selfId = host.peerId.toString();
+  for (const entry of fret.exportTable().entries) {
+    if (entry.id === selfId || entry.addressRecord === undefined) {
+      continue;
+    }
+    const addrs = await verifiedRecordAddrs(entry.id, entry.addressRecord.envelope);
+    if (addrs === null) {
+      result.rejected++;
+    } else if (addrs.length > 0) {
+      result.peers.set(entry.id, addrs);
+    }
+  }
+  return result;
+}
+
+function isFretTableSource(service: unknown): service is FretTableSource {
+  return typeof service === 'object' && service !== null
+    && typeof (service as { exportTable?: unknown }).exportTable === 'function';
+}
+
+/**
+ * The addresses one record lists, bound to `peerId`; null when the record must not be
+ * used. `openAndCertify` proves only that the envelope's own key signed it, so the
+ * signer and the peer the payload describes are each held against `peerId` here:
+ * without that, any peer could sign a record rewriting another peer's addresses.
+ */
+async function verifiedRecordAddrs(peerId: string, envelope: string): Promise<Multiaddr[] | null> {
+  try {
+    const opened = await RecordEnvelope.openAndCertify(uint8ArrayFromString(envelope, 'base64url'), PeerRecord.DOMAIN);
+    const record = PeerRecord.createFromProtobuf(opened.payload);
+    const signer = peerIdFromPublicKey(opened.publicKey).toString();
+    const subject = record.peerId.toString();
+    if (signer !== peerId || subject !== peerId) {
+      log('skipping the address record filed under %s: signed by %s about %s', peerId, signer, subject);
+      return null;
+    }
+    return bindToPeer(record.multiaddrs.map((addr) => addr.toString()), peerId);
+  } catch (error) {
+    log('skipping the address record filed under %s: %o', peerId, error);
+    return null;
+  }
+}
+
+/**
+ * A record names its peer once, in `peerId`, so its addresses carry no trailing
+ * `/p2p/<peerId>` and a relay-only peer's circuit address ends at the relay hop
+ * (`…/p2p/<relay>/p2p-circuit`). Each is given the suffix that makes it a complete
+ * dial target; one already terminating in a different peer id does not reach this peer
+ * and is dropped.
+ *
+ * Takes strings because `@libp2p/peer-record` carries its own `@multiformats/multiaddr`
+ * copy, a structurally different type from the one `withTrailingPeerId` takes.
+ */
+function bindToPeer(addrs: string[], peerId: string): Multiaddr[] {
+  const bound: Multiaddr[] = [];
+  for (const addr of addrs) {
+    const withPeer = withTrailingPeerId(multiaddr(addr), peerId);
+    if (withPeer !== null) {
+      bound.push(withPeer);
+    }
+  }
+  return bound;
+}

package/src/strand-instance-manager.ts

@@ -4,9 +4,7 @@ import { createLibp2pNode, type IRawStorage } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { StrandDatabase } from './strand-database.js';
 import { PeerJoinBackfill, type PeerJoinBackfillConfig } from './peer-join-backfill.js';
-import { StrandPeerObserver, type StrandPeerObservation } from './strand-peer-observer.js';
-import { StrandPeerBookSwap } from './strand-peer-book-swap.js';
-import type { StrandPeerBookStore } from './strand-peer-book.js';
+import { strandNetworkStatePersistence, type StrandNetworkStateStore } from './strand-network-state.js';
 import {
   StrandRevocationEnforcer,
   createRevocationConnectionGater,
@@ -45,7 +43,7 @@ import { DEFAULT_CONNECTION_MONITOR, resolveStrandClusterSize, strandClusterPoli
 import { strandNodeAddrs } from './strand-network-config.js';
 import { resolveRelayServer } from './relay-server.js';
 import { superviseRelayReservation, type RelayReservationSupervisor } from './relay-reservation.js';
-import { declaredCohortReadDeadlineMs, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
+import { declaredCohortReadDeadlineMs, optimysticDialLimits, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
 
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
@@ -274,26 +272,14 @@ export interface StartStrandConfig {
   announceDelegateToRelay?: (strandId: string, relayAddr: string, delegatePeerId: string) => Promise<void>;
 
   /**
-   * Called when the strand's libp2p node identifies a STRAND peer — one whose
-   * identify result names this strand's block-transfer protocol, so never the
-   * circuit relay or a bootstrap node — with the addresses it is dialable at
-   * (`strand-peer-observer.ts`). Throttled per peer; must not throw. `CadreNode`
-   * wires it to the node-local strand peer book, which is what lets a restarted
-   * machine dial the peers it was talking to. Absent ⇒ nothing is observed.
-   * Retained with the launch config, so a hibernation wake re-arms it on the
-   * rebuilt node.
+   * The node-local strand network state (`strand-network-state.ts`): this strand's
+   * slice of it is handed to db-p2p as `persistence`, so the strand node saves its
+   * FRET routing table (with each peer's signed address record) on every connection
+   * and re-imports it when it is next built. Absent ⇒ nothing is saved and the node
+   * starts with an empty table. `CadreNode` passes its store. Retained with the launch
+   * config, so a hibernation wake rebuilds the node over the same state.
    */
-  onStrandPeerIdentified?: (strandId: string, observation: StrandPeerObservation) => void;
-
-  /**
-   * The node-local strand peer book the book SWAP reads and writes
-   * (`strand-peer-book-swap.ts`): the strand node signs its own addresses with
-   * {@link privateKey}, exchanges signed entries with every strand peer it identifies,
-   * and files what verifies. Absent ⇒ no swap runs — a peer that dials this node's
-   * swap handler gets no answer. `CadreNode` passes its book store. Retained with the
-   * launch config, so a hibernation wake re-arms the swap on the rebuilt node.
-   */
-  strandPeerBook?: StrandPeerBookStore;
+  networkState?: StrandNetworkStateStore;
 }
 
 /**
@@ -428,24 +414,6 @@ export class StrandInstanceManager {
    * missed writes).
    */
   private backfills: Map<string, PeerJoinBackfill> = new Map();
-  /**
-   * The per-strand peer-book observation writer (`strand-peer-observer.ts`), keyed
-   * by strand id. Same lifecycle rationale as {@link backfills}: started in
-   * `buildStrandRuntime` right after the libp2p node exists, stopped and dropped in
-   * `releaseRuntime`, so quiesce → resume re-arms it on the rebuilt node. Only
-   * present when the launch config supplied `onStrandPeerIdentified`.
-   */
-  private peerObservers: Map<string, StrandPeerObserver> = new Map();
-
-  /**
-   * Per-strand strand peer book SWAP driver ({@link StrandPeerBookSwap}) — the signed
-   * exchange of book entries between strand peers. Same lifetime as the peer-book
-   * observer above: armed in `buildStrandRuntime` right after the libp2p node exists
-   * (its protocol handler must be registered before an early peer dials it), stopped
-   * and dropped in `releaseRuntime`. Only present when the launch config supplied
-   * `strandPeerBook`.
-   */
-  private peerBookSwaps: Map<string, StrandPeerBookSwap> = new Map();
   /**
    * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
    * id. Same lifecycle rationale as {@link backfills}: created in
@@ -821,6 +789,18 @@ export class StrandInstanceManager {
           enableRingZulu: config.profile === 'storage'
         },
         ...(config.privateKey && { privateKey: config.privateKey }),
+        // Built per runtime, not per launch: the adapter stops saving once the strand's
+        // state is forgotten, and a rebuilt runtime is what starts it saving again.
+        //
+        // NOTE: the saved state also restores which peers db-p2p saw serving the strand,
+        // and it counts them in the cohort until FRET finds them unreachable. A node built
+        // while every other member is offline therefore fails its first writes ("Failed to
+        // get super-majority") — for 4-6 s on loopback, the window a running node already
+        // sees when a member drops. If apps report failed sends after relaunching alone on
+        // a slow relayed link, retry the write in the app or raise it upstream (db-p2p's
+        // remembered-serving fallback); dropping `persistence` brings back the split
+        // restart.
+        ...(config.networkState && { persistence: strandNetworkStatePersistence(config.networkState, strandId) }),
         ...(config.network?.transports && { transports: config.network.transports }),
         ...(config.network?.noiseCrypto && { noiseCrypto: config.network.noiseCrypto }),
         // Unconditional, and the same default the control node takes: every node of
@@ -832,6 +812,9 @@ export class StrandInstanceManager {
         // node is also the listener for every other member's strand node, and Optimystic
         // derives that listener's limit from this (`link-budget.ts`).
         linkRoundTripMs: resolveLinkRoundTripMs(config.network?.linkRoundTripMs),
+        // The same dial limits as the control node: a strand node dials the same machines,
+        // through the same relays and gates.
+        ...optimysticDialLimits(config.network?.linkRoundTripMs),
         // Listen entries plus the WebSocket transport switch they imply — a strand node
         // announces nothing the operator configured (`strand-network-config.ts`), and
         // spreads AFTER `transports` above because the switch is a no-op whenever the
@@ -851,48 +834,6 @@ export class StrandInstanceManager {
 
       instance.libp2pNode = node;
 
-      // The peer-book observation writer, armed BEFORE the database bring-up below
-      // (unlike the backfill) because the bootstrap dials that follow `libp2p.start()`
-      // land during that bring-up, and they are exactly the peers worth remembering:
-      // identify for an early peer may already have fired by the time anything after
-      // the database initializes runs. Registered in the map immediately so the
-      // failure rollback (releaseRuntime) stops it like every other runtime component.
-      const onStrandPeerIdentified = config.onStrandPeerIdentified;
-      if (onStrandPeerIdentified) {
-        const observer = new StrandPeerObserver({
-          label: strandId,
-          libp2p: node,
-          protocolPrefix,
-          onObserved: (observation) => onStrandPeerIdentified(strandId, observation)
-        });
-        this.peerObservers.set(strandId, observer);
-        observer.start();
-      }
-
-      // The strand peer book SWAP, armed at the same moment and for the same reason as
-      // the observer: a peer that dials this node's swap handler before it is registered
-      // fails its exchange and sits out a ten-minute throttle. The own entry is signed
-      // now and re-signed on every address change, which covers the relay reservation
-      // landing below (`self:peer:update` fires when the circuit addr is added), so no
-      // separate post-relay step is needed. Registered in the map immediately so the
-      // failure rollback (releaseRuntime) stops it like every other runtime component.
-      //
-      // NOTE: this is a third `peer:identify` listener per running strand, beside the
-      // observer's and the backfill's — see the backfill's NOTE below for when to fold
-      // them into one dispatcher.
-      if (config.strandPeerBook) {
-        const swap = new StrandPeerBookSwap({
-          strandId,
-          libp2p: node,
-          protocolPrefix,
-          store: config.strandPeerBook,
-          privateKey: config.privateKey,
-          linkRoundTripMs: config.network?.linkRoundTripMs
-        });
-        this.peerBookSwaps.set(strandId, swap);
-        swap.start();
-      }
-
       // One reservation supervisor PER RELAY, started now so the first attempts
       // overlap the database bring-up below (the relay is never in a strand's
       // Optimystic cohort — its protocol ids are namespaced `/optimystic/strand-<id>/…`
@@ -1106,20 +1047,6 @@ export class StrandInstanceManager {
       backfill.stop();
       this.backfills.delete(instance.strandId);
     }
-    // The peer-book observer goes with the node it listened on; a resume re-arms
-    // one on the rebuilt node.
-    const peerObserver = this.peerObservers.get(instance.strandId);
-    if (peerObserver) {
-      peerObserver.stop();
-      this.peerObservers.delete(instance.strandId);
-    }
-    // The book swap likewise: unsubscribed and its handler unregistered while the node is
-    // still up; a resume re-arms one, which re-signs the own entry over the new addresses.
-    const peerBookSwap = this.peerBookSwaps.get(instance.strandId);
-    if (peerBookSwap) {
-      this.peerBookSwaps.delete(instance.strandId);
-      await peerBookSwap.stop();
-    }
     // The revoked-peer enforcer goes with the runtime it gated: a resume
     // rebuilds it with a fresh (initially empty, fail-open) snapshot.
     const revocationEnforcer = this.revocationEnforcers.get(instance.strandId);

package/src/strand-network-state-file.ts

@@ -0,0 +1,40 @@
+/**
+ * Node-only file-backed {@link StrandNetworkStateStore}: one JSON file per party
+ * under a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated network
+ * state of every strand this node runs (each strand node's saved FRET routing
+ * table, with its peers' signed address records).
+ *
+ * Nothing but the file itself lives here: the envelope, load policy, per-entry
+ * check and the serialised snapshot writes are cross-platform in
+ * `PersistentStrandNetworkStateStore` / `node-local-snapshot.ts`, and the file is a
+ * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of the
+ * package's cross-platform default entry (`./index.js`) — import it from the
+ * dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileStrandNetworkStateStore } from '@serfab/cadre-core/strand-network-state-file';
+ * ```
+ *
+ * Same isolation pattern as `bootstrap-peer-store-file.ts` / `key-store-file.ts`.
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentStrandNetworkStateStore } from './strand-network-state.js';
+import type { StrandNetworkStateStore } from './strand-network-state.js';
+
+/** Base name of the store file: `<dir>/strand-network.<encoded partyId>.json`. */
+const SLOT_NAME = 'strand-network';
+
+/**
+ * File-backed {@link StrandNetworkStateStore}. Open via {@link open}, which loads
+ * the existing file and returns the cross-platform store over it; an absent,
+ * corrupt, or wrong-party file is a cold start (no saved state) while a
+ * present-but-unreadable file throws. Those rules and their reasoning live on
+ * `NodeLocalSnapshot.open`.
+ */
+export const FileStrandNetworkStateStore = {
+	/** Load (or cold-start) the party's strand network state from a file in `dir`. */
+	async open(dir: string, partyId: string): Promise<StrandNetworkStateStore> {
+		return PersistentStrandNetworkStateStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+	}
+};