@serfab/cadre-core 1.6.0 → 1.8.0

package/src/strand-formation-protocol.ts

@@ -19,16 +19,22 @@
  */
 
 import debug from 'debug';
-import { multiaddr } from '@multiformats/multiaddr';
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
 import type { Libp2p } from '@libp2p/interface';
 import type { StrandFormationDisclosure, StrandMembershipInvite } from './types.js';
-import { type ControlStream, writeFrame, withTimeout } from './control-stream.js';
+import { type ControlStream, writeFrame, withDeadline, withTimeout } from './control-stream.js';
 import { canonicalJson } from './canonical-json.js';
 import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
 import { verifyFormationConsent } from './peer-authorization.js';
 // seed-bootstrap imports neither this protocol nor the manager/solicitation layers,
 // so this import introduces no cycle.
 import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
+import {
+  formationDeadlines,
+  resolveProvisionTimeoutMs,
+  responderClampReserveMs,
+  splitProvisionBudget
+} from './strand-formation-deadlines.js';
 
 const log = debug('sereus:cadre:formation-proto');
 
@@ -47,66 +53,16 @@ export const INVALID_TOKEN_REASON = 'Invalid token';
 /** Maximum formation message size (1MB). */
 const MAX_FORMATION_MSG_SIZE = 1024 * 1024;
 
-/** Default whole-session timeout (ms). */
-const DEFAULT_SESSION_TIMEOUT_MS = 30_000;
-/** Default per-step (single read/write) timeout (ms). */
-const DEFAULT_STEP_TIMEOUT_MS = 5_000;
-/**
- * Default provisioning budget (ms) — distinct from {@link DEFAULT_STEP_TIMEOUT_MS} because
- * `provisionStrand` is real work (DB writes, and an outbound approval-hook HTTP call when
- * the invite carries a `ValidationUrl`), not a bare wire read/write.
- *
- * Ordering is deliberate — each layer must be able to fail and report before the layer above
- * it gives up:
- *
- *   approval hook (10 s, `formation-approval.ts`)
- *     < responder provisioning (12 s)
- *     < initiator await-response (15 s)
- *     < session (30 s)
- *
- * The 3 s margin between responder provisioning and initiator await-response is the wire
- * latency budget for the result frame to travel back.
- *
- * The last {@link PROVISION_SETTLE_GRACE_MS} of this budget is a settle grace, so the default
- * WORK budget (12 s − 2 s = 10 s) EQUALS the hook's own 10 s: a dead hook races 'Formation
- * approval unavailable, retry' against 'Formation provisioning timed out'. Both are retryable
- * and both leave the invite unspent, so the race is benign.
- */
-const DEFAULT_PROVISION_TIMEOUT_MS = 12_000;
-/**
- * Settle grace (ms), carved OUT of `provisionTimeoutMs` — never added on top, so the budget
- * ladder above is untouched. The listener aborts the provisioning hook when the work budget
- * ({@link splitProvisionBudget}) expires, then waits up to this grace for the work to settle
- * anyway: once the `FormationUsage` insert has been issued nothing can un-spend it (the table
- * is append-only), so a provisioning that lands late is ADOPTED and reported as a real
- * approval rather than lying "timed out" over a spent invite. A hook that observes the
- * abort before writing leaves the invite unspent.
- */
-const PROVISION_SETTLE_GRACE_MS = 2_000;
-/**
- * Wire-latency margin (ms) added to the responder's provisioning budget to get the
- * initiator's await-response budget — the travel time for the result frame to come back
- * after the responder finishes (see {@link DEFAULT_PROVISION_TIMEOUT_MS}).
- * `StrandFormationManager` reuses this constant so a CONFIGURED budget preserves the same
- * margin the defaults do, instead of applying the same number to both sides and racing the
- * initiator's own timeout against the responder's clean rejection reply. The responder's
- * clamp ({@link provisionCeilingMs}) holds the same margin back, so the ordering survives a
- * budget large enough that BOTH roles get clamped.
- *
- * NOTE: 3 s is a fixed assumption about how long the result frame takes to travel back. If
- * formation ever runs over paths where that frame can take longer (a slow circuit relay, a
- * congested mobile link), the margin is too thin and the initiator's timeout races the
- * responder's reply again — raise it, or derive it from an observed round-trip.
- */
-export const PROVISION_RESPONSE_TRAVEL_MARGIN_MS = 3_000;
-/** Default initiator await-response budget (ms); see {@link DEFAULT_PROVISION_TIMEOUT_MS}. */
-const DEFAULT_INITIATOR_PROVISION_TIMEOUT_MS = DEFAULT_PROVISION_TIMEOUT_MS + PROVISION_RESPONSE_TRAVEL_MARGIN_MS;
 /**
  * Default cap on concurrent inbound formation sessions.
- * NOTE: a longer provisioning budget holds a session's slot longer, so a slow hook can
- * exhaust this cap and make the listener reject fresh joiners with 'Too many concurrent
- * formation sessions'. Fine at the current default; revisit if `provisionTimeoutMs` is
- * raised well above its default or this cap is lowered.
+ *
+ * NOTE: a session holds its slot for its whole provisioning budget, 171 s at the default
+ * declared link ({@link formationDeadlines}), so a slow hook or commit holds slots for
+ * minutes. Only a caller holding a valid token AND a valid consent signature reaches
+ * provisioning — a stranger is cut at the contact wait (7 s at the default) or at the first
+ * validation read — so the exposure is one invitee opening many sessions with one token. If
+ * invitation tokens are ever published where untrusted parties can read them, cap in-flight
+ * sessions per token rather than lowering this.
  */
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 100;
 
@@ -380,62 +336,6 @@ export function isValidResponderCreatesResult(response: FormationResultMessage):
   return true;
 }
 
-/**
- * Ceiling for a resolved provisioning budget.
- *
- * The session budget also has to cover the wire step that PRECEDES provisioning (the
- * responder's contact read, the initiator's dial-connect), so a whole step is held back
- * rather than triggering only on a literal overrun.
- *
- * `reserveMs` is the EXTRA room only the responder holds back, so its own budget still
- * lands strictly before the initiator's larger await-response budget even when both are
- * clamped — without it, any configured budget at or above `sessionTimeoutMs -
- * stepTimeoutMs` clamps both roles onto the same number and the responder's clean
- * rejection races the initiator's timeout again. Capped at half the remaining room (like
- * {@link splitProvisionBudget}) so a small session config still spends most of it working.
- */
-function provisionCeilingMs(sessionTimeoutMs: number, stepTimeoutMs: number, reserveMs: number): number {
-  const roomMs = sessionTimeoutMs - stepTimeoutMs;
-  return Math.max(1, roomMs - Math.min(reserveMs, Math.floor(roomMs / 2)));
-}
-
-/**
- * Resolve a caller-supplied provisioning budget: `0`/negative means "unset" (use
- * `defaultMs`). If the result would let provisioning outlive the session — no result
- * frame is ever sent, exactly the failure this budget exists to prevent — clamp it to
- * {@link provisionCeilingMs} and log a warning.
- */
-function resolveProvisionTimeoutMs(
-  configured: number | undefined,
-  defaultMs: number,
-  sessionTimeoutMs: number,
-  stepTimeoutMs: number,
-  role: string,
-  reserveMs = 0
-): number {
-  const requested = configured && configured > 0 ? configured : defaultMs;
-  const ceilingMs = provisionCeilingMs(sessionTimeoutMs, stepTimeoutMs, reserveMs);
-  if (requested >= ceilingMs) {
-    log(
-      '%s provisionTimeoutMs %dms leaves no room under sessionTimeoutMs %dms (step %dms, reserve %dms); clamping to %dms',
-      role, requested, sessionTimeoutMs, stepTimeoutMs, reserveMs, ceilingMs
-    );
-    return ceilingMs;
-  }
-  return requested;
-}
-
-/**
- * Split a resolved provisioning budget into the WORK budget and the trailing settle grace.
- *
- * The grace is carved OUT of the budget (see {@link PROVISION_SETTLE_GRACE_MS}), and capped at
- * half of it so a small configured budget still spends at least half its time doing work.
- */
-function splitProvisionBudget(provisionTimeoutMs: number): { workMs: number; graceMs: number } {
-  const graceMs = Math.min(PROVISION_SETTLE_GRACE_MS, Math.floor(provisionTimeoutMs / 2));
-  return { workMs: provisionTimeoutMs - graceMs, graceMs };
-}
-
 // ── Responder (listener) ─────────────────────────────────────────────────────
 
 export interface FormationListenerOptions {
@@ -471,14 +371,22 @@ export interface FormationListenerOptions {
    * per-strand address lookup.
    */
   resolveStrandAddrs?(strandId: string): string[];
+  /**
+   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * every deadline below takes its default ({@link formationDeadlines}). The default
+   * declaration when omitted.
+   */
+  linkRoundTripMs?: number;
+  /** Whole-session budget; default `sessionMs` of the derived ladder. */
   sessionTimeoutMs?: number;
+  /** Budget for the contact-frame read; default `awaitContactMs` of the derived ladder. */
   stepTimeoutMs?: number;
   /**
-   * Budget for the `provisionStrand` hook call — distinct from `stepTimeoutMs` because
-   * provisioning is real work, not a bare wire read/write. Default 12 s; `0`/unset uses
-   * the default; a value that would outlive the session is clamped ({@link
-   * provisionCeilingMs}). See {@link DEFAULT_PROVISION_TIMEOUT_MS} for the full ordering
-   * rationale.
+   * Budget for the `provisionStrand` hook call, work plus settle grace — distinct from
+   * `stepTimeoutMs` because provisioning is real work, not a bare wire read. Default
+   * `provisionWorkMs + provisionGraceMs` of the derived ladder (171 s at the default
+   * declaration); `0`/unset uses the default; a value that would outlive the session is
+   * clamped ({@link resolveProvisionTimeoutMs}). See {@link formationDeadlines} for the ordering.
    */
   provisionTimeoutMs?: number;
   maxConcurrentSessions?: number;
@@ -493,7 +401,7 @@ export interface FormationListenerOptions {
 export class FormationListener {
   private readonly options: FormationListenerOptions;
   private readonly sessionTimeoutMs: number;
-  private readonly stepTimeoutMs: number;
+  private readonly awaitContactMs: number;
   private readonly provisionWorkMs: number;
   private readonly provisionGraceMs: number;
   private readonly maxConcurrentSessions: number;
@@ -503,13 +411,14 @@ export class FormationListener {
 
   constructor(options: FormationListenerOptions) {
     this.options = options;
-    this.sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
-    this.stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+    const deadlines = formationDeadlines(options.linkRoundTripMs);
+    this.sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
+    this.awaitContactMs = options.stepTimeoutMs ?? deadlines.awaitContactMs;
     const split = splitProvisionBudget(resolveProvisionTimeoutMs(
-      options.provisionTimeoutMs, DEFAULT_PROVISION_TIMEOUT_MS,
-      this.sessionTimeoutMs, this.stepTimeoutMs, 'FormationListener',
-      PROVISION_RESPONSE_TRAVEL_MARGIN_MS
-    ));
+      options.provisionTimeoutMs, deadlines.provisionWorkMs + deadlines.provisionGraceMs,
+      this.sessionTimeoutMs, this.awaitContactMs + deadlines.validationMs, 'FormationListener',
+      responderClampReserveMs(deadlines, this.awaitContactMs)
+    ), deadlines.provisionGraceMs);
     this.provisionWorkMs = split.workMs;
     this.provisionGraceMs = split.graceMs;
     this.maxConcurrentSessions = options.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
@@ -520,21 +429,22 @@ export class FormationListener {
     return this.activeSessions;
   }
 
-  register(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): void {
+  /** Register the formation handler on `node`. Rejects when libp2p refuses the registration. */
+  async register(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
     if (this.registered.has(node)) {
       log('node already registered');
       return;
     }
-    void node.handle(protocolId, async (rawStream: unknown, _connection: unknown) => {
+    await node.handle(protocolId, async (rawStream: unknown, _connection: unknown) => {
       await this.handleStream(rawStream as ControlStream);
     });
     this.registered.add(node);
     log('formation listener registered (%s)', protocolId);
   }
 
-  unregister(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): void {
+  async unregister(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
     if (!this.registered.has(node)) return;
-    void node.unhandle(protocolId);
+    await node.unhandle(protocolId);
     this.registered.delete(node);
     log('formation listener unregistered (%s)', protocolId);
   }
@@ -559,8 +469,8 @@ export class FormationListener {
   }
 
   /**
-   * Run the provisioning hook under its WORK budget — the configured provisioning budget minus
-   * the trailing settle grace ({@link splitProvisionBudget}, {@link PROVISION_SETTLE_GRACE_MS}).
+   * Run the provisioning hook under its WORK budget — the provisioning budget minus the
+   * trailing settle grace ({@link splitProvisionBudget}).
    *
    * When the work budget expires the hook's signal is aborted, then
    * {@link settleWithinGrace} waits out the grace for the aborted work to settle anyway.
@@ -600,11 +510,16 @@ export class FormationListener {
    * inside the grace its outcome is ADOPTED — the joiner is told the truth (approved, or the
    * hook's own rejection reason) rather than "timed out" over a spent invite.
    *
-   * NOTE: one window stays open — a work budget that expires after the `FormationUsage`
-   * insert was issued AND a commit that outlasts the grace. The joiner is told 'timed out'
-   * while its one-time invite is in fact spent, and since every retry mints a fresh keypair
-   * no recovery path can match it. Nothing can un-spend an append-only row, so the late-settle
-   * logging below is the observability for it; widen the grace only if it is seen in the wild.
+   * The grace is derived to contain one seat read plus one commit at the declared link
+   * ({@link formationDeadlines}), which is exactly what runs after the insert attempt passes
+   * its abort check, so at that link the late outcome lands inside it.
+   *
+   * NOTE: a commit that outlasts even the derived grace (a link slower than declared, or a
+   * configured `provisionTimeoutMs` whose half-cap shrank the grace) still tells the joiner
+   * 'timed out' while its one-time invite is in fact spent, and since every retry mints a
+   * fresh keypair no recovery path can match it. Nothing can un-spend an append-only row, so
+   * the late-settle logging below is the observability for it; if it is seen in the wild,
+   * raise the declared link rather than this grace.
    */
   private async settleWithinGrace(
     id: number,
@@ -706,7 +621,7 @@ export class FormationListener {
 
     try {
       const reader = new FrameReader(stream);
-      const contact = await withTimeout(this.stepTimeoutMs, `Formation await-contact#${id}`, () => reader.read<FormationContactMessage>());
+      const contact = await withTimeout(this.awaitContactMs, `Formation await-contact#${id}`, () => reader.read<FormationContactMessage>());
       log('formation session #%d contact: token=%s party=%s', id, contact.token, contact.partyId);
 
       if (!this.isJoinerConsentValid(id, contact)) {
@@ -777,12 +692,24 @@ export interface FormationDialOptions {
   responderAddrs: string[];
   /** Validate the responder's result; a false return aborts the formation. */
   validateResponse(response: FormationResultMessage): Promise<boolean>;
+  /**
+   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * every deadline below takes its default ({@link formationDeadlines}). The default
+   * declaration when omitted.
+   */
+  linkRoundTripMs?: number;
+  /** Whole-session budget; default `sessionMs` of the derived ladder. */
   sessionTimeoutMs?: number;
-  stepTimeoutMs?: number;
   /**
-   * Budget for the `await-response` read only (the responder's provisioning + reply travel
-   * time) — `dial-connect` keeps using `stepTimeoutMs`. Default 15 s; `0`/unset uses the
-   * default. See {@link DEFAULT_PROVISION_TIMEOUT_MS} for the full ordering rationale.
+   * Budget for `dial-connect`: opening the connection, through a relay if need be, and
+   * negotiating the formation protocol. Default `dialMs` of the derived ladder.
+   */
+  dialTimeoutMs?: number;
+  /**
+   * Budget for the `await-response` read only (the responder's provisioning plus the reply's
+   * travel time). Default `initiatorAwaitResponseMs` of the derived ladder; `0`/unset uses
+   * the default; a value that would outlive the session is clamped. See
+   * {@link formationDeadlines} for the ordering.
    */
   provisionTimeoutMs?: number;
   protocolId?: string;
@@ -806,6 +733,32 @@ export interface FormationDialResult {
   strandAddrs: string[];
 }
 
+/**
+ * Open the formation stream under the dial deadline, cancelling the dial when it expires.
+ *
+ * The deadline's signal goes into `dialProtocol`, so an expired dial is abandoned by libp2p
+ * rather than left running. A dial that settles in the same tick the deadline fires loses
+ * the race to the timeout rejection and would leave its stream open with nobody to close
+ * it, so a stream that arrives after the signal aborted is reset here — the same treatment
+ * `exchangeFrame` (`control-stream.ts`) gives a stream dialed past its deadline. A late
+ * rejection is the abort itself, or reaches the caller through the awaited copy, so the
+ * handler below only stops it being reported as unhandled.
+ */
+function openFormationStream(node: Libp2p, addr: Multiaddr, protocolId: string, dialTimeoutMs: number): Promise<ControlStream> {
+  return withDeadline(dialTimeoutMs, 'Formation dial-connect', (signal) => {
+    const pending = node.dialProtocol(addr, protocolId, { signal });
+    void pending.then(
+      (stream) => {
+        if (signal.aborted) {
+          (stream as unknown as ControlStream).abort(new Error('Formation dial-connect resolved after its deadline'));
+        }
+      },
+      () => { /* surfaced through the awaited copy, or the abort itself */ }
+    );
+    return pending as unknown as Promise<ControlStream>;
+  });
+}
+
 /**
  * Initiator side of the native formation protocol. Dials the responder, sends the
  * contact (carrying the real disclosure/token/cadre), validates the responder's
@@ -817,17 +770,17 @@ export async function dialFormation(node: Libp2p, options: FormationDialOptions)
     throw new Error('No responder addresses available for formation');
   }
   const protocolId = options.protocolId ?? FORMATION_PROTOCOL;
-  const sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
-  const stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+  const deadlines = formationDeadlines(options.linkRoundTripMs);
+  const sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
+  const dialTimeoutMs = options.dialTimeoutMs ?? deadlines.dialMs;
   const provisionTimeoutMs = resolveProvisionTimeoutMs(
-    options.provisionTimeoutMs, DEFAULT_INITIATOR_PROVISION_TIMEOUT_MS,
-    sessionTimeoutMs, stepTimeoutMs, 'dialFormation'
+    options.provisionTimeoutMs, deadlines.initiatorAwaitResponseMs,
+    sessionTimeoutMs, dialTimeoutMs, 'dialFormation'
   );
   const addr = multiaddr(options.responderAddrs[0]);
 
   return withTimeout(sessionTimeoutMs, 'Formation dial', async () => {
-    const rawStream = await withTimeout(stepTimeoutMs, 'Formation dial-connect', async () => node.dialProtocol(addr, protocolId));
-    const stream = rawStream as unknown as ControlStream;
+    const stream = await openFormationStream(node, addr, protocolId, dialTimeoutMs);
     try {
       const reader = new FrameReader(stream);
       writeFrame(stream, options.contact);