@serfab/cadre-core 1.7.0 → 1.8.0

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
+import type { CircuitRelayServerInit } from '@libp2p/circuit-relay-v2';
 import type { IRawStorage, Libp2pConnectionMonitorInit, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
 import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
 import type { PeerJoinBackfillConfig } from './peer-join-backfill.js';
@@ -123,10 +124,12 @@ export const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts> = {
  * Factory functions are useful for creating per-scope storage instances.
  *
  * **The argument is an opaque scope key.** Use it directly as a file name, directory
- * name or database name: every key stays within `[A-Za-z0-9._-]`, so no escaping is
- * needed and none should be assumed. Do not parse it; `controlStorageScope` /
- * `isControlStorageScope` (`storage-scope.ts`) are the supported way to mint and
- * recognize the control key. The control key holds the charset by base64url encoding;
+ * name or database name: every key stays within `[a-z0-9._-]`, so no escaping is
+ * needed and none should be assumed, and two different keys are two different names
+ * even on a filesystem that ignores case (Windows, macOS). Do not parse it;
+ * `controlStorageScope` / `isControlStorageScope` (`storage-scope.ts`) are the supported
+ * way to mint and recognize the control key. The control key holds the charset by
+ * lowercase hex encoding;
  * a strand's key — its strand id, which may have replicated in from another node in
  * the party — holds it because `StrandInstanceManager.startStrand` runs
  * `assertStrandScopeKey` on every launch and refuses a strand that fails it.
@@ -171,7 +174,7 @@ export interface StorageConfig {
    * the single-instance form cannot serve more than one party.
    *
    * The `scope` a factory receives is an opaque key already safe as a path or
-   * database-name segment (always within `[A-Za-z0-9._-]`), so each example below
+   * database-name segment (always within `[a-z0-9._-]`), so each example below
    * interpolates it directly.
    *
    * For Node.js environments, use FileRawStorage from @optimystic/db-p2p-storage-fs:
@@ -319,7 +322,8 @@ 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} — 14 s at its default) against a relay that is unreachable
+   * {@link linkRoundTripMs} plus two admission decisions — 18 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).
    *
@@ -342,6 +346,31 @@ export interface NetworkConfig {
    * better connectivity and uptime), false for transaction profile nodes.
    */
   enableRelay?: boolean;
+  /**
+   * Settings for this machine's circuit-relay SERVER, handed to `@libp2p/circuit-relay-v2`'s
+   * `circuitRelayServer(...)` (through db-p2p's `NodeOptions.relayServerInit`) on the control
+   * node and on every strand node. Only meaningful while {@link enableRelay} is on.
+   *
+   * Omitted, a party-run relay FORWARDS WITHOUT LIMIT: `reservations.applyDefaultLimit` is
+   * `false`, where libp2p's own default caps every relayed connection at 128 KiB or two
+   * minutes and resets it — which cut off any database sync or chat history forwarded
+   * through a party's own always-on machine. The store also holds
+   * `PARTY_RELAY_MAX_RESERVATIONS` (128) reservations instead of libp2p's 15, and each lives
+   * `PARTY_RELAY_RESERVATION_TTL_MS` (2 h) unrefreshed. See `relay-server.ts`.
+   *
+   * A value is MERGED over those defaults, not substituted for them: `reservations` key by
+   * key, every other top-level key as given. Setting only `reservations.maxReservations`
+   * keeps the limit off; `reservations: { applyDefaultLimit: true }` is how to turn libp2p's
+   * cap back on.
+   *
+   * The accepted tradeoff of the unlimited default: once a slot is granted, nothing caps what
+   * is forwarded through it, and a holder that keeps refreshing keeps it indefinitely — the
+   * 2 h lifetime only reclaims a slot whose holder went away. On the control node a peer it
+   * cannot place as a party member is bounded by COUNT ({@link unauthorizedRelayReservationCap}).
+   * A strand node's relay server has no such budget (its peers are cross-party by design), so
+   * any peer that reaches it is bounded only by `maxReservations`.
+   */
+  relayServerInit?: CircuitRelayServerInit;
   /**
    * 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
@@ -413,16 +442,21 @@ export interface NetworkConfig {
    * How long ONE cohort peer gets to answer ONE read-path request, in milliseconds, for the
    * control node and every strand node — as {@link connectionMonitor} 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 COHORT_READ_DEADLINE_MS} (5000 ms), chosen for two
-   * parties reaching each other only through a relay; Optimystic's own default is 1000 ms.
+   * ride the same one. Omitted, the deadline is DERIVED from {@link linkRoundTripMs}: one
+   * request and its answer over an open circuit costs two link round trips, so 7 000 ms at the
+   * default declaration (`cohortReadDeadlineMs` in `link-budget.ts`; the plugin's
+   * {@link COHORT_READ_DEADLINE_MS} is the same number). Optimystic's own default is 1000 ms.
    *
-   * Raise it for a link slower still, lower it for a deployment that is all LAN and wants a
-   * departed peer to stop holding up a read sooner. The cost of a larger value is that a peer
-   * which is truly gone holds a read of a block missing locally for that long before the read
-   * is declined and retried, and a joining machine's first sync runs several such consults —
-   * so a change here should be weighed against
-   * {@link CadreNodeConfig.strandFirstSync}'s budget. The measurement behind the default, and
-   * what it costs, are on {@link COHORT_READ_DEADLINE_MS}.
+   * Set this only to break the derivation on purpose: an explicit value wins over whatever
+   * {@link linkRoundTripMs} would derive, so a deployment that is all LAN can make a departed
+   * peer stop holding up a read sooner without declaring a faster link (which would also
+   * shorten the dial budgets). A deployment on a slower link should raise
+   * {@link linkRoundTripMs} instead, which moves this and every dial budget together. The
+   * cost of a larger value is that a peer which is truly gone holds a read of a block missing
+   * locally for that long before the read is declined and retried, and a joining machine's
+   * first sync runs several such consults — so a change here should be weighed against
+   * {@link CadreNodeConfig.strandFirstSync}'s budget. The derivation, its history and what it
+   * costs are on {@link COHORT_READ_DEADLINE_MS}.
    *
    * Handed to db-p2p's `clusterPolicy.cohortQueryTimeoutMs` unchanged and NOT re-validated
    * here. Optimystic refuses a value that is not a finite number above zero, or is above its
@@ -441,11 +475,14 @@ export interface NetworkConfig {
    * 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, 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,
+   * reservation drive, the control-cohort dial budgets, and the per-peer cohort read deadline
+   * ({@link cohortQueryTimeoutMs}, unless set explicitly). It is also handed to Optimystic
+   * (`NodeOptions.linkRoundTripMs`), default included, which derives its own deadlines from it:
+   * its request dials and responses, its block pushes, and libp2p's `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`.
    *
    * The default covers the slowest link sereus supports, a 3-second round trip through a relay.
@@ -459,7 +496,8 @@ export interface NetworkConfig {
    * 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
    * zero, because every consumer multiplies it into a deadline where a zero means "give up at
-   * once" and a `NaN` means "never".
+   * once" and a `NaN` means "never". Optimystic refuses, in the same place, a value above its
+   * `MAX_LINK_ROUND_TRIP_MS` (about 1.66 days).
    */
   linkRoundTripMs?: number;
   /**
@@ -530,14 +568,19 @@ export interface NetworkConfig {
      * {@link dialTimeoutMs}. Each address is dialed on its own under this limit,
      * so an address that never answers cannot use up the time the peer's other
      * addresses needed. Defaults to
-     * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}.
+     * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}. A value given
+     * here replaces that whole derived budget, including its allowance for the
+     * called machine's admission decision (`relayedDialBudgetMs`).
      */
     perAddressDialTimeoutMs?: number;
     /**
-     * How often each running strand re-resolves its siblings' strand-network
-     * addresses into its own libp2p address book — a step of the reconcile pass,
-     * on its own much longer throttle. Defaults to `STRAND_PEER_ADDR_REFRESH_MS`
-     * (10 min); must stay well under the peerStore's one-hour address expiry.
+     * How long a running strand waits, after a sibling answers its strand-addr
+     * RPC, before asking that sibling again for its strand-network addresses — a
+     * step of the reconcile pass, scheduled per (sibling, strand). A sibling that
+     * did not answer is retried sooner, on `STRAND_PEER_ADDR_RETRY_MS` (or this
+     * interval, when it is set shorter). Defaults to
+     * `STRAND_PEER_ADDR_REFRESH_MS` (10 min); must stay well under the peerStore's
+     * one-hour address expiry.
      */
     strandAddrRefreshMs?: number;
   };
@@ -656,9 +699,10 @@ export interface ControlNetworkConfig {
  *
  * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
  * corroboration yardstick declared from the machines enrolled in this party
- * ({@link resolveRepairYardstick}) and, if the host set one, its own per-peer read
- * deadline in place of {@link COHORT_READ_DEADLINE_MS}. Both arrive in one named
- * declarations object, because both are plain numbers meaning unrelated things;
+ * ({@link resolveRepairYardstick}) and, if the host set one or declared its link, a
+ * per-peer read deadline in place of {@link COHORT_READ_DEADLINE_MS}
+ * (`declaredCohortReadDeadlineMs` in `link-budget.ts` settles which). Both arrive in one
+ * named declarations object, because both are plain numbers meaning unrelated things;
  * declaring neither returns the frozen base constant unchanged. A network picks the
  * derived numbers up when its libp2p node is built, which for a strand is every wake
  * from hibernation.
@@ -722,6 +766,22 @@ export interface CadreNodeConfig {
   /** Which strands to participate in */
   strandFilter?: StrandFilter;
 
+  /**
+   * Run every strand {@link strandFilter} admits, including ones no app on this machine
+   * has claimed with `addStrand`, as a **storage replica**: the strand's own libp2p node,
+   * storage and `Strand` membership schema, storing and serving its blocks, without the
+   * app's schema (no sApp config needed, none of the app's code or schema runs). This is
+   * how an always-on machine keeps a copy of every shared workspace its party runs, so a
+   * lost phone loses nothing that had reached it.
+   *
+   * The strand is still announced as `strand:discovered` (once) and stays in
+   * `getDiscoveredStrands()` until an app claims it. A replica is always a joiner.
+   *
+   * Default: `profile === 'storage'` — always-on machines host replicas, phones
+   * (`'transaction'`) keep today's announce-only behaviour.
+   */
+  hostUnclaimedStrands?: boolean;
+
   /** Storage configuration (only for storage profile) */
   storage?: StorageConfig;
 
@@ -950,11 +1010,12 @@ export interface CadreNodeConfig {
   };
 
   /**
-   * 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.
+   * Node-local record of the strands this node joined from ANOTHER party and has not yet
+   * published to the party-wide `JoinedStrand` table (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 this party's control database does not
+   * name, offered on every start as `strand:discovered` until an owner machine's
+   * reconcile pass publishes it — 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
@@ -1082,6 +1143,12 @@ export interface StrandInstance {
 
   /** Activity tracking */
   connectedPeers: number;
+  /**
+   * When the strand last saw activity: the app's (`recordStrandActivity`), a requested wake
+   * (`wakeStrand`), or a peer delivering a gated joiner's `Strand.Header`. Always a fresh
+   * `Date`. Bringing the runtime up is NOT activity — a check-in window decides whether to
+   * re-hibernate by whether this changed since before its resume.
+   */
   lastActivity: Date;
   nextCheckIn?: Date;
 
@@ -1508,6 +1575,12 @@ export interface CadreNodeEvents {
    * be idempotent (guard on an in-flight set, not only on
    * `getStrands().has(id)` — the strand manager tracks an instance only once
    * `addStrand` has resolved).
+   *
+   * On a node that hosts storage replicas ({@link CadreNodeConfig.hostUnclaimedStrands},
+   * the default for `profile: 'storage'`) the event still fires once, and the node launches
+   * the strand as a replica right after it — so there `getStrands().has(id)` soon turns
+   * true for a strand no app has claimed; an unclaimed instance has no `sAppInfo`. A
+   * launch that fails is retried by the watcher without a second `strand:discovered`.
    */
   'strand:discovered': { strandId: string; strand: StrandRow };
   'control:connected': void;
@@ -1886,7 +1959,11 @@ export interface WakeRequest {
 export interface WakeAck {
   /** Whether the receiver honored the wake (member + participated strand). */
   accepted: boolean;
-  /** The strand's status after the wake (present when `accepted`). */
+  /**
+   * The strand's status when the receiver accepted the wake (present when `accepted`). The
+   * receiver replies before the wake runs, so `hibernating` or `idle` here means "a wake was
+   * started", not "the strand is now up".
+   */
   status?: StrandStatus;
   /** Reason for rejection (non-member, unknown strand, malformed frame). */
   reason?: string;
@@ -1915,17 +1992,32 @@ export interface StrandAddrRequest {
   delegatePeerId?: string;
 }
 
+/**
+ * How a strand-addr responder handled a {@link StrandAddrRequest}. Carried so the
+ * asker can tell "I have nothing" from "I could not answer" — the two need
+ * different retry timing, and an empty address list alone cannot say which.
+ *
+ * - `ok` — looked up; `multiaddrs` is the truth, possibly empty (strand not running here).
+ * - `unavailable` — the responder could not answer: over its concurrency cap, the
+ *   request was unreadable, or its own lookup threw (e.g. a control-database read failed).
+ * - `refused` — the requester is not an authorized member in the responder's
+ *   current view (possibly because its `CadrePeer` row has not replicated there yet);
+ *   any `delegatePeerId` it carried was NOT recorded.
+ */
+export type StrandAddrStatus = 'ok' | 'unavailable' | 'refused';
+
 /**
  * Response to a {@link StrandAddrRequest}, carrying the responder's strand-node
  * multiaddrs, returned on the same stream.
  */
 export interface StrandAddrResponse {
-  /** Echoes the requested strand id (empty on a reject/error reply). */
+  /** How the responder handled the request; a reply without one is malformed. */
+  status: StrandAddrStatus;
+  /** Echoes the requested strand id; always empty on an `unavailable` reply. */
   strandId: string;
   /**
    * Dialable strand-network multiaddr strings (signaling/`p2p-circuit` first);
-   * empty when the responder is a non-member, or does not currently run that
-   * strand, or the exchange failed.
+   * empty unless `status` is `ok` and the responder runs that strand.
    */
   multiaddrs: string[];
 }