@serfab/cadre-core 1.5.0 → 1.7.0

package/src/strand-peer-observer.ts

@@ -0,0 +1,235 @@
+/**
+ * The strand peer book's OBSERVATION writer: on one strand libp2p node, every peer
+ * whose identify result names this strand's block-transfer protocol — a strand peer,
+ * never the circuit relay or a bootstrap node ({@link speaksBlockTransfer}, the
+ * same gate `PeerJoinBackfill` schedules on) — is reported with its dialable
+ * addresses, so `CadreNode` can merge an unsigned book entry for it
+ * (`strand-peer-book.ts`). That is what lets a restarted machine dial the peers it
+ * was talking to, instead of only the ones a formation once carried back.
+ *
+ * Dialable addresses are the peer's announced `listenAddrs` from the identify
+ * result, plus the open connection's `remoteAddr` when it is relayed
+ * (`/p2p-circuit`) — a relay-only peer announces its circuit listener, but the
+ * address this node actually reached it on is the one proven to work. Every
+ * address is bound to the peer id (`withTrailingPeerId`), ordered signaling-first
+ * and capped like a formation's list, so the book files it under the right peer.
+ *
+ * Throttled to one report per peer per {@link STRAND_PEER_OBSERVE_THROTTLE_MS}
+ * unless the address set changed, so a flapping relayed connection — identify
+ * fires on every reconnect, every 14 s at worst — does not rewrite the node-local
+ * slot each time. Best-effort throughout: nothing here throws into a libp2p event
+ * handler.
+ *
+ * Lifecycle: one observer per running strand, armed in
+ * `StrandInstanceManager.buildStrandRuntime` right after the libp2p node exists
+ * (the bootstrap dials that follow `libp2p.start()` are exactly the peers worth
+ * observing) and stopped in `releaseRuntime`, so a hibernation wake re-arms it on
+ * the rebuilt node. `start` also walks the peers already connected, because
+ * identify may have completed for an early peer before this object existed.
+ */
+import debug from 'debug';
+import type { Connection, IdentifyResult, Libp2p, PeerId } from '@libp2p/interface';
+import { multiaddr } from '@multiformats/multiaddr';
+import { speaksBlockTransfer } from './peer-join-backfill.js';
+import { isSignalingAddr, orderSignalingFirst, withTrailingPeerId } from './peer-record.js';
+import { MAX_STRAND_ADDRS } from './strand-formation-protocol.js';
+
+const log = debug('sereus:cadre:strand-peer-observer');
+
+/** Minimum gap between two reports of ONE peer with an unchanged address set. */
+export const STRAND_PEER_OBSERVE_THROTTLE_MS = 10 * 60 * 1000;
+
+/** One strand peer seen live: its strand transport peer id and the addresses it is dialable at. */
+export interface StrandPeerObservation {
+	peerId: string;
+	/** Bound to `peerId`, signaling-first, at most `MAX_STRAND_ADDRS`. */
+	addrs: string[];
+}
+
+export interface StrandPeerObserverDeps {
+	/** For logs (the strand id). */
+	label: string;
+	/** The strand's libp2p node. */
+	libp2p: Libp2p;
+	/** This strand network's `/optimystic/<networkName>` prefix — the block-transfer gate. */
+	protocolPrefix: string;
+	/** Called for every (throttled) observation; must not throw. */
+	onObserved: (observation: StrandPeerObservation) => void;
+}
+
+export interface StrandPeerObserverOptions {
+	/** Default {@link STRAND_PEER_OBSERVE_THROTTLE_MS}. */
+	throttleMs?: number;
+	/** Clock, for tests. Default `Date.now`. */
+	now?: () => number;
+}
+
+interface LastReport {
+	at: number;
+	/** The address set reported, canonicalised for comparison. */
+	key: string;
+}
+
+/**
+ * Anything that prints as a multiaddr. libp2p's identify result and peer store hand
+ * back its nested `@multiformats/multiaddr` copy, a structurally different type from
+ * this package's, so addresses are taken by their string form and re-parsed here.
+ */
+export interface AddrLike {
+	toString(): string;
+}
+
+/** One connected peer as the peer store knows it: what identify recorded, plus its open connections. */
+export interface ConnectedIdentifiedPeer {
+	peerId: PeerId;
+	protocols: string[];
+	/** The stored addresses: identify-announced, plus whatever else was merged in. */
+	addrs: AddrLike[];
+	connections: Connection[];
+}
+
+/**
+ * Every peer `libp2p` holds a connection to AND has already identified (it is in the
+ * peer store), grouped per peer. A connected peer whose identify has not finished is
+ * left out: its `peer:identify` event is still to come, and every listener that walks
+ * this list at start subscribes to that event too. Shared by the peer-book observer
+ * and the book swap (`strand-peer-book-swap.ts`), which both arm right after the
+ * node exists and may already have missed an early peer's identify.
+ */
+export async function connectedIdentifiedPeers(libp2p: Libp2p, label: string): Promise<ConnectedIdentifiedPeer[]> {
+	const byPeer = new Map<string, { peerId: PeerId; connections: Connection[] }>();
+	for (const connection of libp2p.getConnections()) {
+		const key = connection.remotePeer.toString();
+		const group = byPeer.get(key) ?? { peerId: connection.remotePeer, connections: [] };
+		group.connections.push(connection);
+		byPeer.set(key, group);
+	}
+	const identified = await Promise.all([...byPeer.values()].map(async ({ peerId, connections }): Promise<ConnectedIdentifiedPeer | undefined> => {
+		try {
+			const peer = await libp2p.peerStore.get(peerId);
+			return { peerId, protocols: peer.protocols, addrs: peer.addresses.map((a) => a.multiaddr), connections };
+		} catch (error) {
+			// NotFoundError: identify has not finished; the event handler will see it.
+			if ((error as Error).name !== 'NotFoundError') {
+				log('[%s] peer store read for %s failed — skipping it: %o', label, peerId.toString(), error);
+			}
+			return undefined;
+		}
+	}));
+	return identified.filter((peer): peer is ConnectedIdentifiedPeer => peer !== undefined);
+}
+
+export class StrandPeerObserver {
+	private readonly throttleMs: number;
+	private readonly now: () => number;
+	private readonly lastReports = new Map<string, LastReport>();
+	private readonly onPeerIdentify: (evt: CustomEvent<IdentifyResult>) => void;
+	private started = false;
+	private stopped = false;
+
+	constructor(private readonly deps: StrandPeerObserverDeps, options?: StrandPeerObserverOptions) {
+		this.throttleMs = options?.throttleMs ?? STRAND_PEER_OBSERVE_THROTTLE_MS;
+		this.now = options?.now ?? Date.now;
+		this.onPeerIdentify = (evt) => {
+			const { peerId, protocols, listenAddrs, connection } = evt.detail;
+			if (speaksBlockTransfer(protocols, this.deps.protocolPrefix)) {
+				this.observe(peerId, listenAddrs, [connection]);
+			}
+		};
+	}
+
+	/** Subscribe to `peer:identify` and report the peers already connected and identified. */
+	start(): void {
+		if (this.started || this.stopped) return;
+		this.started = true;
+		this.deps.libp2p.addEventListener('peer:identify', this.onPeerIdentify);
+		void this.observeConnectedPeers().then((seen) => {
+			log('[%s] started (%d peer(s) already connected)', this.deps.label, seen);
+		});
+	}
+
+	/** Unsubscribe; later identify results are ignored. */
+	stop(): void {
+		if (this.stopped) return;
+		this.stopped = true;
+		if (this.started) {
+			this.deps.libp2p.removeEventListener('peer:identify', this.onPeerIdentify);
+		}
+		this.lastReports.clear();
+		log('[%s] stopped', this.deps.label);
+	}
+
+	/**
+	 * Report every connected peer the peer store already knows speaks this strand's
+	 * protocol, with its stored addresses. A peer not yet in the store (identify has
+	 * not finished) is left to the `peer:identify` handler. Returns the number of
+	 * identified peers considered.
+	 *
+	 * NOTE: the stored addresses include what `CadreNode.mergeStrandPeerAddrs` merged
+	 * INTO the peer store from the book, so this walk can re-vouch a dead address the
+	 * book already held, until the peer's next `peer:identify` replaces the set with
+	 * what it announces now. Bounded by the address cap; if a dead address ever shows
+	 * up surviving across resumes, read only the peer store's identify-sourced
+	 * addresses here rather than shortening the age.
+	 */
+	private async observeConnectedPeers(): Promise<number> {
+		const peers = await connectedIdentifiedPeers(this.deps.libp2p, this.deps.label);
+		for (const { peerId, protocols, addrs, connections } of peers) {
+			if (!this.stopped && speaksBlockTransfer(protocols, this.deps.protocolPrefix)) {
+				this.observe(peerId, addrs, connections);
+			}
+		}
+		return peers.length;
+	}
+
+	/** Shape, throttle and report one peer. Never throws. */
+	private observe(peerId: PeerId, listenAddrs: AddrLike[], connections: Connection[]): void {
+		if (this.stopped) return;
+		const id = peerId.toString();
+		// Identify is about remotes, so self never arrives here; belt and braces, since
+		// a node must never file its own addresses as a peer to dial.
+		if (id === this.deps.libp2p.peerId.toString()) return;
+		try {
+			const addrs = dialableAddrs(id, listenAddrs, connections);
+			if (!this.shouldReport(id, addrs)) return;
+			log('[%s] observed strand peer %s at %d addr(s)', this.deps.label, id, addrs.length);
+			this.deps.onObserved({ peerId: id, addrs });
+		} catch (error) {
+			log('[%s] observing %s failed (ignored): %o', this.deps.label, id, error);
+		}
+	}
+
+	/** One report per peer per throttle window, unless the address set changed. */
+	private shouldReport(peerId: string, addrs: string[]): boolean {
+		const now = this.now();
+		const key = [...addrs].sort().join('\n');
+		const last = this.lastReports.get(peerId);
+		if (last && last.key === key && now - last.at < this.throttleMs) {
+			return false;
+		}
+		this.lastReports.set(peerId, { at: now, key });
+		return true;
+	}
+}
+
+/**
+ * The addresses to file for `peerId`: its announced listen addrs plus every relayed
+ * connection addr, each bound to `peerId`, de-duplicated, signaling-first, capped.
+ * Re-parsed through this package's own `multiaddr` (see {@link AddrLike}).
+ */
+export function dialableAddrs(peerId: string, listenAddrs: AddrLike[], connections: Connection[]): string[] {
+	const candidates = [
+		...listenAddrs.map((ma) => ma.toString()),
+		...connections.map((c) => c.remoteAddr.toString()).filter(isSignalingAddr)
+	];
+	const bound = new Set<string>();
+	for (const candidate of candidates) {
+		const addr = withTrailingPeerId(multiaddr(candidate), peerId);
+		if (addr === null) {
+			log('dropping addr %s — it names a peer other than %s', candidate, peerId);
+			continue;
+		}
+		bound.add(addr.toString());
+	}
+	return orderSignalingFirst([...bound]).slice(0, MAX_STRAND_ADDRS);
+}

package/src/types.ts

@@ -10,7 +10,9 @@ import type { SeedTrustPolicy } from './seed-trust-policy.js';
 import type { KeyStore, KeyId } from './key-store.js';
 import type { TrustedOwnerStore, TrustSource } from './trusted-owner-store.js';
 import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
+import type { StrandPeerBookStore } from './strand-peer-book.js';
 import type { EnrolledMachineStore } from './enrolled-machine-store.js';
+import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { RevocableTable } from './control-authorization.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
@@ -317,7 +319,7 @@ export interface NetworkConfig {
    * It buys a node that BOOTS, not a node that boots fast: `start()` still waits
    * out that first attempt, which costs the drive's whole timeout
    * (`DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, four link round trips at
-   * {@link linkRoundTripMs} — 8 s at its default) against a relay that is unreachable
+   * {@link linkRoundTripMs} — 14 s at its default) against a relay that is unreachable
    * rather than merely refusing (`relay-reservation.ts` polls to the deadline, in
    * case libp2p's own discovery lands a reservation independently).
    *
@@ -434,22 +436,25 @@ export interface NetworkConfig {
    * The round trip this node assumes between itself and another machine, in milliseconds, for
    * the control node and every strand node — as {@link cohortQueryTimeoutMs} is, and for the
    * same reason: the setting describes the LINK, and a phone's control node and its strand
-   * nodes ride the same one. Omitted takes {@link DECLARED_LINK_ROUND_TRIP_MS} (2000 ms).
+   * nodes ride the same one. Omitted takes {@link DECLARED_LINK_ROUND_TRIP_MS} (3500 ms).
    *
    * This is NOT a timeout. It is the one stated assumption that cadre's own dial and
    * reservation deadlines are DERIVED from, each by the number of round trips that operation
    * was measured to cost: a peer-join catch-up's dial to one peer, its push response, one relay
-   * reservation drive, and the control-cohort dial budgets. Reaching another machine through a
-   * relay costs a fixed number of exchanges, so a deadline written as milliseconds has a link
-   * speed above which it can never open a connection — which is the defect this declaration
-   * exists to make impossible to reintroduce one budget at a time. The counts, the measurement
-   * behind them, and the ceiling that no declaration here can lift are in `link-budget.ts`.
+   * reservation drive, the control-cohort dial budgets, and libp2p's own `dialTimeout` and
+   * `inboundUpgradeTimeout` on every node. Reaching another machine through a relay costs a
+   * fixed number of exchanges, so a deadline written as milliseconds has a link speed above
+   * which it can never open a connection — which is the defect this declaration exists to make
+   * impossible to reintroduce one budget at a time. The counts, the measurement behind them,
+   * and what still fails at the supported link are in `link-budget.ts`.
    *
-   * Raise it for a link slower than the relayed phone-to-phone band sereus assumes; the cost is
-   * the ordinary cost of longer deadlines, a peer that is genuinely gone holding each operation
-   * that much longer before it is abandoned and retried. Above about 2500 it buys nothing: two
-   * libp2p budgets that sereus cannot reach abandon the connection first
-   * (`tickets/blocked/how-slow-a-relayed-link-does-sereus-carry`).
+   * The default covers the slowest link sereus supports, a 3-second round trip through a relay.
+   * Raise it for a link slower still; the cost is the ordinary cost of longer deadlines, a peer
+   * that is genuinely gone holding each operation that much longer before it is abandoned and
+   * retried. Lower it only if EVERY machine of the party is that close: this node is also the
+   * listener for connections other machines open to it, and its `inboundUpgradeTimeout` comes
+   * from this value, so a node declaring a faster link than its peers discards their
+   * half-built connections — silently, from the dialer's side.
    *
    * Refused where the libp2p node is built — inside `CadreNode.start()` for the control
    * network, inside `CadreNode.addStrand` for a strand — if it is not a finite number above
@@ -569,6 +574,12 @@ export interface NetworkConfig {
  * kept it (the same pair aborted at a 200ms stall only when the deadline was 300ms). An
  * interval strictly above the deadline is what makes the 30 seconds real.
  *
+ * WHAT THE LINK NEEDS OF IT. One ping opens a fresh stream and echoes over it: a protocol
+ * negotiation plus the echo, two link round trips by `link-budget.ts`'s counts (a `newStream`
+ * over a relayed circuit measured 3016 ms at 1500 ms one-way). At the slowest link sereus
+ * supports, a 3-second relayed round trip, that is about 6 s — well inside the 30 s deadline,
+ * which exists for the phone's CPU rather than the link.
+ *
  * WHAT IT COSTS. A dead peer is reclaimed 30 to 65 seconds after it stops answering — the
  * deadline, plus up to one interval of waiting for the ping that will fail — where
  * libp2p's defaults took about 5 to 15 seconds. `db-p2p` caps a node at 16 connections,
@@ -807,11 +818,11 @@ export interface CadreNodeConfig {
    * `timeoutMs` bounds how long {@link CadreNode.addStrand} waits before rejecting with
    * `StrandAwaitingFirstSyncError` (retryable — the launch stays up and keeps probing);
    * `pollIntervalMs` is the probe cadence. Omit for the defaults (`DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`,
-   * 120 s — sized for a machine joining through a relay on a slow link; that constant's doc
-   * comment carries the measurement behind the number and what the budget costs, and is the
-   * only copy of it; `DEFAULT_STRAND_FIRST_SYNC_POLL_MS`, 500 ms). There is
-   * deliberately no way to disable the gate: a machine that already holds the Header is never
-   * gated, so nothing that works today is blocked by it.
+   * sized for a machine re-attaching through a relay on a slow link, the slowest attach
+   * measured; that constant's doc comment carries the number, the measurement behind it and
+   * what the budget costs, and is the only copy of them; `DEFAULT_STRAND_FIRST_SYNC_POLL_MS`,
+   * 500 ms). There is deliberately no way to disable the gate: a machine whose store already
+   * holds the Header is never gated, so nothing that works today is blocked by it.
    */
   strandFirstSync?: StrandFirstSyncConfig;
 
@@ -938,6 +949,54 @@ export interface CadreNodeConfig {
     store?: EnrolledMachineStore;
   };
 
+  /**
+   * Node-local record of the strands this node joined from ANOTHER party (see
+   * `joined-strand-store.ts`): id, type and the closed strand's read secret, recorded
+   * by `formStrand` and by a joining (not `founder: true`) `addStrand` whose row is
+   * not in this party's control database, and re-offered on every start as `strand:discovered` — so an embedding
+   * app keeps no list of its own.
+   *
+   * Absent ⇒ a `KeyStoreJoinedStrandStore` over {@link keyStore} when one is
+   * configured (the record carries a secret, and the KeyStore is where every platform
+   * already keeps secrets), else an in-memory store that warns once and forgets every
+   * join on restart. An embedder that passes {@link privateKey} rather than a
+   * `keyStore` injects a durable store here, e.g.
+   * `new KeyStoreJoinedStrandStore(new FileKeyStore(dir), partyId)`.
+   */
+  joinedStrands?: {
+    /** Its `partyId` must match `controlNetwork.partyId`; start() fails closed on a mismatch. */
+    store?: JoinedStrandStore;
+  };
+
+  /**
+   * Node-local strand peer book (see `strand-peer-book.ts`): per strand, the strand
+   * peers this node has met — the other parties' strand transport peers a formation
+   * carried back, and every strand peer observed on a live connection — with their
+   * last-known addresses. Read on every launch, hibernation resume and periodic
+   * address refresh, so a restarted machine dials the peers it was talking to before
+   * anything else, instead of coming back up alone (gotchoices/sereus#18). Sibling
+   * of {@link bootstrapPeers} — same NON-replicated, per-party, injected-backend
+   * shape — and, like it, nothing here is trust-bearing: dial hints only, each
+   * bound to its peer id. Entries age out after 14 days (`STRAND_PEER_MAX_AGE_MS`,
+   * overridable per store via `StrandPeerBookOptions.maxAgeMs`).
+   *
+   * Absent ⇒ an in-memory store is created at start() (ephemeral: the book dies
+   * with the process, and a cross-party strand whose only contact was the other
+   * party does not re-mesh after a restart until a fresh formation). Every
+   * reference embedder injects a durable backend over the same slot kind as its
+   * bootstrap-peer store. A new platform needs no new store class: supply a
+   * `DurableSlot` and inject `PersistentStrandPeerBookStore.open(slot, partyId)`.
+   */
+  strandPeers?: {
+    /**
+     * Injected store instance — e.g. a `FileStrandPeerBookStore` from the
+     * Node-only subpath `@serfab/cadre-core/strand-peer-book-file`, persisted in
+     * the node's state directory. Its `partyId` must match
+     * `controlNetwork.partyId`; start() fails closed on a mismatch.
+     */
+    store?: StrandPeerBookStore;
+  };
+
   /**
    * Platform push-delivery for suspended mobile peers. When present, the node's
    * server fan-out can deliver strand-wake data messages over the platform push
@@ -1385,6 +1444,10 @@ export interface CadreNodeEvents {
    * re-admits this party, so a second removal is reported again — and a
    * hibernation wake rebuilds the gate, which may re-emit for a strand still
    * revoked.
+   *
+   * For a strand joined from another party, the node also forgets its remembered
+   * join (see {@link CadreNodeConfig.joinedStrands}): it keeps running this session
+   * and is not re-offered after the next start.
    */
   'strand:revoked': { strandId: string };
   /**
@@ -1418,6 +1481,12 @@ export interface CadreNodeEvents {
    * Carries the full {@link StrandRow} so the app can join without re-querying
    * the control DB.
    *
+   * Also emitted for a strand this node joined from ANOTHER party, which no control
+   * row names: the node remembers every such join (see
+   * {@link CadreNodeConfig.joinedStrands}) and offers it here on each start, as a row
+   * with `FounderOwnerKey: null` carrying the closed strand's `MemberPrivateKey`. That
+   * row is the product of the formation's consent, so claiming it needs no second one.
+   *
    * **Fired once per strand per session, and it can fire before your listener is
    * attached.** The strand watcher's first poll runs inside `CadreNode.start()`
    * (100 ms after the watcher starts), so every strand already stored for this