@serfab/cadre-core 0.11.0 → 0.12.0

package/dist/types.d.ts

@@ -98,12 +98,12 @@ export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeou
  * cadre-core disposes only its own cache wrapper — it never closes the store you
  * returned. Closing the underlying handle stays the embedder's job.
  *
- * **Prefer the factory form for any persistent backend.** One instance handed to
- * every scope also shares ONE cache wrapper (`wrapStorageWithCache` memoizes per
- * inner instance), and no scope solely owns it — so the first scope to stop retires
- * the wrapper the still-running scopes are reading through. See
- * `tickets/backlog/debt-storage-cache-wrap-unrefcounted.md`; an in-memory store is
- * unaffected, since it is never wrapped.
+ * Either form is safe with a persistent backend. One instance handed to every scope
+ * also shares ONE cache wrapper (`wrapStorageWithCache` memoizes per inner instance),
+ * which counts its holders: a scope stopping releases only its own claim, and the
+ * wrapper is retired when the last scope releases it. The factory form is still the
+ * better default for a different reason — it partitions each strand's data, which
+ * simplifies cleanup.
  */
 export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorage);
 /**
@@ -142,26 +142,48 @@ export interface StorageConfig {
 export interface NetworkConfig {
     listenAddrs?: string[];
     /**
-     * Addresses to advertise to peers instead of `listenAddrs` — for a node behind
+     * Addresses to advertise to peers **instead of** `listenAddrs` — for a node behind
      * NAT or a reverse proxy that is reachable at a different address than it binds
-     * (e.g. `mynode.example.com:4001` in front of a `0.0.0.0:4001` listener).
+     * (e.g. `mynode.example.com:4001` in front of a `0.0.0.0:4001` listener). Reaches
+     * libp2p's `addresses.announce` via `@optimystic/db-p2p`'s `NodeOptions.announceAddrs`,
+     * on this node's control node and on every strand node it runs.
      *
-     * Accepted (settable in `cadre.yaml`, via `CADRE_ANNOUNCE_ADDRS`, and through the
-     * Docker entrypoint) but **not yet applied**: libp2p only takes announce addresses
-     * at construction (`addresses.announce` / `addresses.appendAnnounce`), and
-     * `@optimystic/db-p2p`'s `NodeOptions` has no field for either — there is nothing
-     * in this repo to wire this into. `CadreNode.start()` warns when this is set,
-     * rather than pretending it works. Unblocked by the `announce-addrs-option`
-     * request filed against `@optimystic/db-p2p`; wiring lands here once this repo's
-     * dependency range moves to a version carrying it.
+     * **A non-empty value REPLACES the advertised set entirely.** Observed addresses,
+     * and the `/p2p-circuit` address earned from a {@link relayAddrs} reservation, are
+     * all dropped from what peers are told — so a node configured with both this and
+     * `relayAddrs` stops being reachable through its relay. `CadreNode.start()` warns
+     * when it sees that combination; it does not refuse it, since a node whose relay
+     * slot is decorative may legitimately want only the announced address.
      *
-     * Use {@link relayAddrs} for reachability behind NAT today (a reserved relay slot
-     * gives the node a real dialable circuit address), or `inviteAddressResolver` to
-     * substitute a reachable address into invite payloads specifically — neither
-     * changes what this node advertises on the wire, but both cover the operator need
-     * this field cannot yet.
+     * Reach for {@link appendAnnounceAddrs} instead in the common case — one publicly
+     * reachable address ADDED to everything else the node advertises. Or for
+     * {@link relayAddrs} alone, when the node has no stable public address to name and
+     * a relay reservation is what makes it dialable. (`inviteAddressResolver` is a
+     * narrower tool again: it substitutes a reachable address into invite payloads
+     * only, and changes nothing about what this node advertises on the wire.)
+     *
+     * An empty array means "unset" — it is dropped rather than forwarded, so it cannot
+     * land as an explicit empty announce set. An empty *entry* is a different thing and
+     * is rejected: a list of one blank string is non-empty, so it would replace every
+     * advertised address with nothing. Malformed entries are rejected on the same terms,
+     * both at node start — libp2p itself would not notice either until its first address
+     * lookup (see `announce-addrs.ts`), so this repo checks each entry up front.
      */
     announceAddrs?: string[];
+    /**
+     * Addresses to advertise **in addition to** `listenAddrs` — the field most
+     * deployments actually want, since it makes a node reachable at a public address
+     * without discarding the observed and `/p2p-circuit` addresses it would otherwise
+     * advertise. Reaches libp2p's `addresses.appendAnnounce` via
+     * `@optimystic/db-p2p`'s `NodeOptions.appendAnnounceAddrs`.
+     *
+     * **Ignored while {@link announceAddrs} is non-empty** — that is libp2p's own
+     * precedence, applied upstream; this repo does not merge the two locally. Set one
+     * or the other, not both.
+     *
+     * Empty-array, blank-entry and malformed-entry handling all match {@link announceAddrs}.
+     */
+    appendAnnounceAddrs?: string[];
     /**
      * Circuit-relay servers this node reserves a slot on, so peers can reach it
      * from behind NAT. Each entry is the relay's DIRECT dial multiaddr ending in
@@ -169,18 +191,26 @@ export interface NetworkConfig {
      * `/p2p-circuit` suffix (one is appended for you; an entry that already has
      * one is passed through unchanged).
      *
-     * This is sugar for a circuit entry in {@link listenAddrs}: `relay-addrs.ts`
-     * resolves the two into one listen list, and listening on a relay's circuit
-     * addr is what makes libp2p dial it and hold the reservation. A relay named
-     * here therefore also becomes a delegate-announce target, so this node's
-     * strand nodes may reserve on it too (see `delegate-admission.ts`).
+     * On the CONTROL node this adds libp2p's bare `/p2p-circuit` SEARCH listener to
+     * {@link listenAddrs} (`relay-addrs.ts`) and `CadreNode.start()` drives the
+     * reservation itself once the control database is up — the ordering matters,
+     * because a listener that dials its relay from inside `libp2p.start()` put a
+     * sibling in this node's cohort before its own database existed, and a sibling
+     * that had not yet replicated this node's membership row refused the bring-up.
+     * STRAND nodes inherit the older per-relay `<relay>/p2p-circuit` listener, which
+     * has no such ordering hazard. A relay named here also becomes a
+     * delegate-announce target, so this node's strand nodes may reserve on it too
+     * (see `delegate-admission.ts`).
      *
      * Setting this gives the node a listener even when `listenAddrs` is `[]` —
      * that is the point of naming a relay, but note that React Native hosts
      * (`reference-app-rn`'s `cadre-phone.ts`) deliberately do NOT listen, and
      * must not acquire a listener by accident.
      *
-     * A malformed entry throws at node start rather than being silently dropped.
+     * FAIL-FAST both ways: a malformed entry throws at node start rather than being
+     * silently dropped, and a first reservation attempt that lands no
+     * `/p2p-circuit` address throws `RelayReservationFailedError` out of `start()`.
+     * The fail-soft posture over the same machinery is `CadreNode.reserveRelays()`.
      */
     relayAddrs?: string[];
     /**
@@ -189,6 +219,16 @@ export interface NetworkConfig {
      * better connectivity and uptime), false for transaction profile nodes.
      */
     enableRelay?: boolean;
+    /**
+     * Cap on concurrent circuit-relay reservations this node's relay server grants to
+     * peers it cannot (yet) recognize as authorized members — the boot-ordering window
+     * where a genuine member reserves its relay slot before its membership row has
+     * replicated here (see `membership-connection-gater.ts` → "The relay-reservation
+     * seam"). Authorized members and announced delegate peers are never counted against
+     * it. Default `MAX_UNAUTHORIZED_RELAY_RESERVATIONS` (8); 0 refuses every
+     * unauthorized reservation. Only meaningful while {@link enableRelay} is on.
+     */
+    unauthorizedRelayReservationCap?: number;
     /**
      * Custom libp2p transports. When omitted, the default transports from
      * `@optimystic/db-p2p` are used (TCP + circuit relay for Node.js).
@@ -211,6 +251,11 @@ export interface NetworkConfig {
      * (and other owner-address contexts). When unset, `libp2pNode.getMultiaddrs()`
      * is used. Hosts behind NAT supply this to substitute their DDNS hostname
      * and externally-mapped port — see `@serfab/cadre-host`'s NatService.
+     *
+     * Returned addresses need NOT carry a `/p2p/<peerId>` suffix: `CadreNode`
+     * appends its own before publishing or dialing any of them, so a resolver
+     * cannot leave a sibling with the mixed suffixed/unsuffixed list that
+     * `libp2p.dial` rejects. Returning them already suffixed is equally fine.
      */
     inviteAddressResolver?: () => Promise<string[]>;
     /**
@@ -323,8 +368,8 @@ export interface CadreNodeConfig {
      * Pluggable secure store for node key material. When set, the node loads its
      * identity from `keyStore` under {@link identityKeyId}, generating + persisting
      * a fresh Ed25519 key on first run (protobuf bytes are the canonical stored
-     * form). Mutually exclusive with {@link privateKey}. Absent ⇒ legacy behavior
-     * (use `privateKey`, else libp2p generates an ephemeral key).
+     * form). Mutually exclusive with {@link privateKey}. Absent ⇒ use `privateKey`
+     * when set, else libp2p generates an ephemeral key.
      *
      * In the single-key reference model the owner signing key is *derived from*
      * the node identity (see {@link CadreNode.getIdentityOwnerKey}), so

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA+MF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;GAWG;AACH,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA4PF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;GAWG;AACH,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,+BAA+B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -67,7 +67,7 @@
     "@libp2p/tcp": "^11.0.10",
     "@libp2p/webrtc": "6.0.14",
     "@libp2p/websockets": "^10.1.3",
-    "@optimystic/db-p2p-storage-fs": "^0.24.0",
+    "@optimystic/db-p2p-storage-fs": "^0.27.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -80,12 +80,12 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.1",
-    "@optimystic/db-core": "^0.24.0",
-    "@optimystic/db-p2p": "^0.24.0",
-    "@optimystic/quereus-plugin-crypto": "^0.24.0",
-    "@optimystic/quereus-plugin-optimystic": "^0.24.0",
-    "@quereus/quereus": "^4.14.0",
-    "@serfab/quereus-plugin-sereus": "^0.11.0",
+    "@optimystic/db-core": "^0.27.0",
+    "@optimystic/db-p2p": "^0.27.0",
+    "@optimystic/quereus-plugin-crypto": "^0.27.0",
+    "@optimystic/quereus-plugin-optimystic": "^0.27.0",
+    "@quereus/quereus": "^4.18.0",
+    "@serfab/quereus-plugin-sereus": "^0.12.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"

package/src/announce-addrs.ts

@@ -0,0 +1,93 @@
+/**
+ * Translate `network.announceAddrs` / `network.appendAnnounceAddrs` — the operator-facing
+ * "advertise these addresses" settings — into the two `@optimystic/db-p2p` `NodeOptions`
+ * fields of the same names, which reach libp2p's `addresses.announce` /
+ * `addresses.appendAnnounce`.
+ *
+ * Two jobs, both of which the control node and every strand node need identically, hence
+ * one module rather than the same conditional spread written twice:
+ *
+ * - **Empty means unset.** libp2p treats `announce: []` as "no override", and forwarding
+ *   `[]` would still be forwarding a field. An empty config array is dropped so it cannot
+ *   land as an explicit empty announce set.
+ * - **Validate the multiaddrs here, at start.** libp2p does NOT validate announce addrs
+ *   at construction: `AddressManager` stores them as raw strings and only parses them on
+ *   the first `getAnnounceAddrs()`. A typo therefore produces a node that starts
+ *   cleanly, then throws `InvalidMultiaddrError` out of every `getMultiaddrs()` call —
+ *   including an UNHANDLED one from the debounced peer-store update libp2p runs on
+ *   `transport:listening`. Verified against libp2p's `address-manager` (its constructor
+ *   does `announce.map(ma => ma.toString())`; `getAnnounceAddrs()` does `multiaddr(a)`).
+ *   Parsing each entry up front converts that into a loud failure at node start, which is
+ *   what {@link relayCircuitAddrs} already does for `network.relayAddrs`.
+ *
+ *   Parsing alone is not enough, though: `''` and `'/'` both parse into a component-less
+ *   multiaddr, and a set holding only those is non-empty by the rule above — so it would
+ *   replace every advertised address with nothing at all. An entry naming no address is
+ *   therefore rejected alongside one that fails to parse.
+ */
+
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
+import type { NetworkConfig } from './types.js';
+
+/**
+ * The announce fields to spread into `createLibp2pNode` options. A field is present
+ * only when the operator configured a non-empty list for it, so a node that configures
+ * neither passes neither.
+ */
+export interface ResolvedAnnounceAddrs {
+  announceAddrs?: string[];
+  appendAnnounceAddrs?: string[];
+}
+
+/**
+ * Resolve both announce fields off a `NetworkConfig`. Throws — naming the offending
+ * config field and entry — when any entry is not a parsable multiaddr.
+ */
+export function resolveAnnounceAddrs(network: NetworkConfig | undefined): ResolvedAnnounceAddrs {
+  const announceAddrs = configuredAddrs('network.announceAddrs', network?.announceAddrs);
+  const appendAnnounceAddrs = configuredAddrs('network.appendAnnounceAddrs', network?.appendAnnounceAddrs);
+  return {
+    ...(announceAddrs && { announceAddrs }),
+    ...(appendAnnounceAddrs && { appendAnnounceAddrs })
+  };
+}
+
+/**
+ * Whether this node's advertised set will be REPLACED rather than extended — i.e.
+ * whether {@link ResolvedAnnounceAddrs.announceAddrs} is in play at all. The single
+ * predicate behind `CadreNode.start()`'s operator warning, kept here so the warning
+ * and the forwarding agree on what "set" means (non-empty, not merely present).
+ */
+export function replacesAdvertisedAddrs(network: NetworkConfig | undefined): boolean {
+  return (network?.announceAddrs?.length ?? 0) > 0;
+}
+
+/** The entries to forward for one announce field, or `undefined` when it is unset or empty. */
+function configuredAddrs(field: string, addrs: readonly string[] | undefined): string[] | undefined {
+  if (!addrs || addrs.length === 0) {
+    return undefined;
+  }
+  return addrs.map((addr) => validated(field, addr));
+}
+
+/** `addr` unchanged, having proved it names a real address — config field named on failure. */
+function validated(field: string, addr: string): string {
+  if (parsed(field, addr).getComponents().length === 0) {
+    // `''` and `'/'` PARSE: both yield a component-less multiaddr that stringifies to
+    // `/`. Forwarded, they make an announce set that is non-empty but names nothing —
+    // which by the replacement rule above costs the node every address it would
+    // otherwise advertise, silently. A templated `cadre.yaml` whose address variable went
+    // unsubstituted is the realistic way in, so it is rejected rather than forwarded.
+    throw new Error(`${field} entry names no address: ${JSON.stringify(addr)}`);
+  }
+  return addr;
+}
+
+/** `addr` as a multiaddr, with the config field named on a parse failure. */
+function parsed(field: string, addr: string): Multiaddr {
+  try {
+    return multiaddr(addr);
+  } catch (err) {
+    throw new Error(`${field} entry is not a valid multiaddr: ${addr}`, { cause: err });
+  }
+}