@serfab/cadre-core 1.2.0 → 1.4.0

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
-import type { IRawStorage, Libp2pTransports } from '@optimystic/db-p2p';
+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';
 import type { StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
@@ -121,13 +121,13 @@ 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 cadre-core mints 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 strand arm of that charset
- * rule is intended but not yet checked — a strand id replicated in from another node
- * in the party reaches this callback verbatim; see
- * `tickets/backlog/bug-strand-scope-key-charset-unenforced`.
+ * 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;
+ * 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.
  *
  * **Called once per scope per runtime lifetime.** The scopes are the control database
  * (once per `CadreNode.start()`) and each strand id (once per `startStrand`).
@@ -366,6 +366,46 @@ export interface NetworkConfig {
    * ```
    */
   transports?: Libp2pTransports;
+  /**
+   * Crypto primitives for the Noise handshake and the encrypted connection that
+   * follows, threaded to both the control node and every strand's cohort node — every
+   * node pays the handshake, so one setting covers them all. When omitted, libp2p-noise
+   * picks its own default.
+   *
+   * React Native is the reason this exists: Metro resolves `@chainsafe/libp2p-noise`'s
+   * browser build, whose default is pure-JS crypto, and on Hermes (no JIT) that
+   * dominates connection setup on a slow phone. An app with native crypto supplies it
+   * here. It must implement every member of the interface; the usual shape spreads
+   * `noisePureJsCrypto` and overrides the hashing and ChaCha20-Poly1305 functions:
+   * ```typescript
+   * import { noisePureJsCrypto } from '@optimystic/db-p2p';
+   *
+   * network: {
+   *   noiseCrypto: { ...noisePureJsCrypto, hashSHA256: nativeSha256, chaCha20Poly1305Encrypt: …, chaCha20Poly1305Decrypt: … }
+   * }
+   * ```
+   *
+   * Only local primitives change — the wire protocol does not, so a node with native
+   * crypto interoperates with one without. See `@optimystic/db-p2p`'s
+   * `NodeOptions.noiseCrypto`.
+   */
+  noiseCrypto?: NoiseCryptoInterface;
+  /**
+   * libp2p's connection monitor — the liveness ping it runs on every connection — for
+   * the control node and every strand node, as {@link noiseCrypto} is. When omitted,
+   * cadre-core applies {@link DEFAULT_CONNECTION_MONITOR} rather than leaving libp2p's
+   * own defaults in place; an explicit value REPLACES that default wholesale, so `{}`
+   * is how an app asks for libp2p's stock behaviour back.
+   *
+   * Typed from `@optimystic/db-p2p`'s re-export of libp2p's `ConnectionMonitorInit`, so
+   * an app does not need a direct `libp2p` dependency, and handed to db-p2p's
+   * `NodeOptions.connectionMonitor` unchanged.
+   *
+   * An app that widens the ping deadline itself must raise `pingInterval` above it in
+   * the same object, or libp2p aborts the connection on the second overlapping ping —
+   * see {@link DEFAULT_CONNECTION_MONITOR} for why.
+   */
+  connectionMonitor?: Libp2pConnectionMonitorInit;
   /**
    * Optional async resolver returning the multiaddrs to embed in invites
    * (and other owner-address contexts). When unset, `libp2pNode.getMultiaddrs()`
@@ -447,6 +487,66 @@ export interface NetworkConfig {
   };
 }
 
+/**
+ * The connection-monitor settings every cadre node runs with when
+ * {@link NetworkConfig.connectionMonitor} is unset: a 30 second ping deadline in place
+ * of libp2p's 5 second one, and a 35 second gap between pings so a ping is never
+ * outstanding when the next one starts.
+ *
+ * WHY this is a default and not opt-in. libp2p's monitor pings every connection and,
+ * with its own `abortConnectionOnPingFailure: true`, aborts the connection on the FIRST
+ * timeout. A peer whose event loop is saturated by pure-JS Noise crypto — a slow phone
+ * under React Native, see {@link NetworkConfig.noiseCrypto} — misses that deadline while
+ * perfectly healthy; the other end aborts, the peer redials, and the new handshake
+ * saturates it further. Measured on gotchoices/sereus#13 at a Galaxy S7's crypto cost, a
+ * two-party bring-up failed 3 of 3 runs on stock settings, with 30 `aborting connection
+ * due to ping failure` entries in the relay's log for one run, and passed 4 of 4 in about
+ * 90 seconds once the deadline was widened on every node. The monitor runs on BOTH ends
+ * of a connection and either end's abort closes it for both, so a setting the phone alone
+ * applies does not cover the peer dropping it. That is what rules out scoping this to
+ * React Native.
+ *
+ * WHY `pingInterval` MOVES WITH THE DEADLINE, and is not left at libp2p's 10 seconds.
+ * The monitor opens a ping stream per connection per interval whether or not the previous
+ * ping has answered, and `/ipfs/ping/1.0.0` is registered by `@libp2p/ping` with
+ * `maxOutboundStreams: 1`. A second concurrent ping stream on one connection therefore
+ * fails in `Connection.newStream` with `TooManyOutboundProtocolStreamsError`, which
+ * reaches the monitor's own catch and aborts the connection exactly as a timeout does. A
+ * widened deadline alone is thus capped by the ping interval: measured against two local
+ * libp2p 3.1.3 nodes whose ping handler answered 600ms late, an interval of 300ms with a
+ * 900ms deadline aborted the connection, while a 900ms interval with the same deadline
+ * 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 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,
+ * so the worst case is those slots held about a minute longer than before; at that scale
+ * it is not a starvation risk.
+ *
+ * WHY THE DEADLINE IS PINNED rather than given room to adapt. `pingTimeout` is an
+ * adaptive-timeout init, and equal `minTimeout`/`maxTimeout` clamp it to one value on
+ * every libp2p version. Under libp2p 3.1.3, which sereus resolves today, it is already
+ * flat at `minTimeout`: `ConnectionMonitor` asks its `AdaptiveTimeout` for a deadline but
+ * never calls `cleanUp` to report how long the ping took, so the moving average the
+ * deadline derives from stays at zero. libp2p 3.3 does report ping durations back, and a
+ * ceiling above `pingInterval` would then let the deadline grow past the interval and put
+ * the overlapping-ping abort above straight back. Pinning both ends keeps the interval's
+ * margin true on the version bump instead of making it something to remember. It also
+ * sidesteps 3.3's other surprise: the monitor keeps one `AdaptiveTimeout` for all of a
+ * node's connections, so one slow peer would otherwise lengthen the deadline for every
+ * connection on that node.
+ */
+export const DEFAULT_CONNECTION_MONITOR = Object.freeze({
+  // Strictly greater than the deadline below, so the previous ping is always resolved or
+  // aborted before the next one opens a stream. `types.spec.ts` holds the two apart.
+  pingInterval: 35_000,
+  // Frozen at both levels, as `CONTROL_CLUSTER_POLICY` is: one object reaches every
+  // libp2p node this process builds, so a mutation anywhere would move the deadline
+  // for all of them.
+  pingTimeout: Object.freeze({ minTimeout: 30_000, maxTimeout: 30_000 })
+} satisfies Libp2pConnectionMonitorInit);
+
 /**
  * Hibernation configuration
  */
@@ -1231,13 +1331,19 @@ export interface CadreNodeEvents {
    * Carries the full {@link StrandRow} so the app can join without re-querying
    * the control DB.
    *
-   * **Fired exactly 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 party is normally offered while the embedding app is
-   * still inside its own `start()` await. The watcher then records the strand as
-   * seen and no later poll re-offers it, so a listener attached a moment late
-   * misses those strands for the life of the process.
+   * **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
+   * party is normally offered while the embedding app is still inside its own
+   * `start()` await. The watcher then records the strand as seen and no later poll
+   * re-offers it, so a listener attached a moment late misses those strands for the
+   * life of the process.
+   *
+   * One exception, and it does NOT produce a second event: when an `addStrand` that
+   * claims a discovered strand FAILS, the watcher is told to forget the strand so a
+   * later poll retries it. That claim left the sApp config registered, so the retry
+   * takes the auto-launch branch — what the app sees is `strand:error` per failed
+   * retry and `strand:started` when one succeeds.
    *
    * So an app that auto-joins discovered strands must **subscribe first, then
    * drain `CadreNode.getDiscoveredStrands()`** — the map of strands no local