@serfab/cadre-core 1.7.0 → 1.8.0

package/src/membership-connection-gater.ts

@@ -85,7 +85,10 @@
  *    infra outright, and admits peers it cannot place only within a bounded
  *    budget ({@link UnauthorizedReservationBudget}) — a member whose row is in
  *    flight always finds a slot under any sane cap, while outsiders cannot
- *    annex the party's relay capacity.
+ *    annex the party's relay capacity. COUNT and lifetime are the only bounds
+ *    on such a peer: a party-run relay forwards without libp2p's per-connection
+ *    data and duration limit by default (`relay-server.ts`), so what a granted
+ *    slot carries is not capped.
  *  - An `'admit-for-relay'` connection that is NOT reserving is dropped: it has
  *    {@link RELAY_ADMISSION_RESERVE_DEADLINE_MS} to get a reservation ADMITTED
  *    at that hook, after which the gate CLOSES the underlying connection so
@@ -160,6 +163,8 @@ import type { ConnectionGater, PeerId, MultiaddrConnection } from '@libp2p/inter
 import { SEED_PROTOCOL } from './seed-bootstrap.js';
 import { FORMATION_PROTOCOL } from './strand-formation-protocol.js';
 import { withDeadline } from './control-stream.js';
+import { PARTY_RELAY_RESERVATION_TTL_MS } from './relay-server.js';
+import { ADMISSION_DECISION_TIMEOUT_MS, relayAdmissionReserveDeadlineMs } from './link-budget.js';
 
 const log = debug('sereus:cadre:connection-gater');
 
@@ -180,22 +185,6 @@ export const STRANGER_OPEN_PROTOCOLS: readonly string[] = [SEED_PROTOCOL, FORMAT
  */
 export const DEFAULT_ENROLLMENT_WINDOW_MS = 30 * 60 * 1000;
 
-/**
- * Deadline for one admission decision, after which the fail-open outcome is
- * used (connection admitted / reservation admitted).
- *
- * libp2p awaits `denyInboundEncryptedConnection` inside the inbound upgrade
- * WITHOUT racing its inbound-upgrade timeout signal (unlike the pre-encryption
- * `denyInboundConnection` hook), so a decision that never settles wedges that
- * upgrade forever — the connection-manager's inbound-upgrade slot is taken by
- * `acceptIncomingConnection` and released in the `finally` that never runs. The
- * real policy reads the control DB (`listAuthorizedMembers`), which can pull
- * over the network, so "never settles" is reachable. Bounding it here keeps the
- * fail-open contract honest: a slow decision admits rather than silently
- * failing closed (or not at all).
- */
-export const ADMISSION_DECISION_TIMEOUT_MS = 2_000;
-
 /**
  * How long an `'admit-for-relay'` connection may exist without a relay
  * reservation being ADMITTED at the `denyInboundRelayReservation` hook, after
@@ -204,8 +193,13 @@ export const ADMISSION_DECISION_TIMEOUT_MS = 2_000;
  * dials and requests in one drive; a strand node's configured circuit listener
  * does the same from inside its own `listen()`), so a connection idle past this
  * deadline is not reserving.
+ *
+ * Derived from the link ({@link relayAdmissionReserveDeadlineMs}): one link round trip for the
+ * request to arrive plus one admission decision on it. This is the value at the default
+ * declaration; `CadreNode` passes the one derived from the relay's OWN declaration, because the
+ * relay is the machine that decides.
  */
-export const RELAY_ADMISSION_RESERVE_DEADLINE_MS = 5_000;
+export const RELAY_ADMISSION_RESERVE_DEADLINE_MS = relayAdmissionReserveDeadlineMs();
 
 /**
  * Bound on the graceful close of an expired relay-only connection. It exists
@@ -218,6 +212,7 @@ export const RELAY_ADMISSION_RESERVE_DEADLINE_MS = 5_000;
  * Applied through {@link withDeadline}, not `AbortSignal.timeout`: the latter is
  * not reliably present on React Native/Hermes, which loads this same module.
  */
+// eslint-disable-next-line no-restricted-syntax -- link-independent: bounds a local connection close inside a timer callback, and expiry aborts the connection instead
 export const RELAY_ADMISSION_CLOSE_TIMEOUT_MS = 2_000;
 
 /**
@@ -228,31 +223,17 @@ export const RELAY_ADMISSION_CLOSE_TIMEOUT_MS = 2_000;
  * `network.unauthorizedRelayReservationCap` (0 refuses every unauthorized
  * reservation — the strict pre-seam posture).
  *
- * NOTE: this cap shares the relay server's own reservation store, whose default
- * size is 15 (`@libp2p/circuit-relay-v2`'s `DEFAULT_MAX_RESERVATION_STORE_SIZE`);
- * unplaced peers may therefore occupy up to this many of those slots, and the
- * rest are what members and delegates compete for. This module cannot read the
- * server's size, so the two are kept apart by hand — if either is raised, keep
- * this one well under the store's, or a fleet of unplaceable peers can crowd
- * genuine members out of the server's own store (which the gate cannot override).
+ * NOTE: this cap shares the relay server's own reservation store, whose
+ * party-run default size is `PARTY_RELAY_MAX_RESERVATIONS` (128,
+ * `relay-server.ts`); unplaced peers may therefore occupy up to this many of
+ * those slots, and the rest are what members and delegates compete for. The two
+ * are kept apart by hand — if this is raised, or an embedder shrinks the store
+ * through `network.relayServerInit.reservations.maxReservations`, keep this one
+ * well under the store's, or a fleet of unplaceable peers can crowd genuine
+ * members out of the server's own store (which the gate cannot override).
  */
 export const MAX_UNAUTHORIZED_RELAY_RESERVATIONS = 8;
 
-/**
- * How long one {@link UnauthorizedReservationBudget} entry occupies a slot
- * without a refresh. Mirrors the relay server's own default reservation TTL
- * (`@libp2p/circuit-relay-v2`'s `DEFAULT_MAX_RESERVATION_TTL`, 2 h): the server
- * holds an unrefreshed reservation exactly that long, and a live reserver
- * re-requests (re-hitting the admission hook, refreshing its entry) well before
- * expiry — so the live entry count tracks the server's own occupancy without
- * this module reaching into the server's reservation store.
- *
- * NOTE: a mirror, not a live coupling — if the relay server is ever configured
- * with a non-default `reservationTtl` (db-p2p's `relayServerInit`), update this
- * constant alongside it or the budget's occupancy drifts from the server's.
- */
-export const UNAUTHORIZED_RESERVATION_TTL_MS = 2 * 60 * 60 * 1000;
-
 /**
  * The connection-level outcome of the admission policy:
  *  - `'admit'` — a peer with a legitimate claim on the connection (member,
@@ -295,9 +276,13 @@ export interface InboundAdmissionPolicy {
  * Bounded budget of concurrent relay reservations for peers the membership
  * check could not place. `tryAdmit` is the whole surface: an already-admitted
  * peer refreshes its entry (a reservation refresh never double-counts), a new
- * peer takes a free slot or is refused. Entries expire after `ttlMs` (see
- * {@link UNAUTHORIZED_RESERVATION_TTL_MS} for why that mirrors the relay
- * server's own hold). Injectable `now` keeps expiry testable without fake
+ * peer takes a free slot or is refused. Entries expire after `ttlMs`, which
+ * `CadreNode` passes as the relay server's own resolved `reservationTtl`
+ * (`relay-server.ts`): the server holds an unrefreshed reservation exactly that
+ * long, and a live reserver re-requests (re-hitting the admission hook,
+ * refreshing its entry) well before expiry — so the live entry count tracks the
+ * server's own occupancy without this module reaching into the server's
+ * reservation store. Injectable `now` keeps expiry testable without fake
  * timers. Authorized members and delegates are never run through this — the
  * policy admits them before consulting the budget, and `release`s the slot such
  * a peer took while it was still unplaceable, so the boot-ordering window a
@@ -307,8 +292,9 @@ export class UnauthorizedReservationBudget {
   private readonly admitted = new Map<string, number>();
 
   constructor(
-    private readonly cap: number = MAX_UNAUTHORIZED_RELAY_RESERVATIONS,
-    private readonly ttlMs: number = UNAUTHORIZED_RESERVATION_TTL_MS
+    /** Most peers admitted at once — `network.unauthorizedRelayReservationCap`, resolved. */
+    readonly cap: number = MAX_UNAUTHORIZED_RELAY_RESERVATIONS,
+    private readonly ttlMs: number = PARTY_RELAY_RESERVATION_TTL_MS
   ) {}
 
   /** Number of live (unexpired at last prune) entries — test/diagnostic surface. */

package/src/peer-dial.ts

@@ -24,8 +24,9 @@
  */
 
 import debug from 'debug';
-import type { Connection } from '@libp2p/interface';
-import type { Multiaddr } from '@multiformats/multiaddr';
+import type { Connection, PeerId } from '@libp2p/interface';
+import { peerIdFromString } from '@libp2p/peer-id';
+import type { Component, Multiaddr } from '@multiformats/multiaddr';
 import { withDeadline } from './control-stream.js';
 import { relayedDialBudgetMs } from './link-budget.js';
 
@@ -33,8 +34,9 @@ const log = debug('sereus:cadre:peer-dial');
 
 /**
  * Default limit on ONE address's dial attempt, in ms, at the DEFAULT declared link round trip:
- * `RELAYED_DIAL_ROUND_TRIPS` (4) x `DECLARED_LINK_ROUND_TRIP_MS` (3500 ms) = 14 000 ms. It was
- * a fixed 8000 ms before it was derived.
+ * `RELAYED_DIAL_ROUND_TRIPS` (4) x `DECLARED_LINK_ROUND_TRIP_MS` (3500 ms) plus the called
+ * machine's `ADMISSION_DECISION_TIMEOUT_MS` (2000 ms) = 16 000 ms (`relayedDialBudgetMs`). It
+ * was a fixed 8000 ms before it was derived.
  *
  * It has to cover the slowest address that should succeed, because an attempt
  * that needs longer fails the same way on every retry. That is a relayed dial on
@@ -117,9 +119,28 @@ export const DEFAULT_PEER_DIAL_BUDGET: Readonly<PeerDialBudget> = {
 
 /** The slice of a libp2p node {@link dialPeerAddrs} uses. */
 export interface AddrDialer {
+	/** This node's id, to recognise an address that relays through this node ({@link relaysThrough}). */
+	readonly peerId: PeerId;
 	dial(addr: Multiaddr, options: { signal: AbortSignal }): Promise<Connection>;
 }
 
+/**
+ * Thrown by {@link dialPeerAddrs} when it was given addresses but every one reaches the peer by
+ * relaying through this node, so none was dialed.
+ *
+ * This is where a relay lands for a peer that holds a reservation on it (a phone, or any node that
+ * cannot listen): the address that peer publishes is `/<relay transport>/p2p/<relay>/p2p-circuit/p2p/<peer>`,
+ * and dialing it from the relay itself fails with libp2p's `Can not dial self`. Nothing this node
+ * does can repair it; once the peer's connection drops, only the peer can reconnect. Callers log it
+ * as that rather than as a dial failure.
+ */
+export class SelfRelayOnlyError extends Error {
+	constructor(label: string) {
+		super(`${label}: every candidate address relays through this node; only the peer can reconnect`);
+		this.name = 'SelfRelayOnlyError';
+	}
+}
+
 /** One candidate's outcome, kept so the thrown error can name every attempt. */
 interface AddrAttemptFailure {
 	addr: Multiaddr;
@@ -131,23 +152,31 @@ interface AddrAttemptFailure {
  * first connection that forms. Direct addresses are tried before relayed ones
  * ({@link directBeforeRelayed}); otherwise the given order is kept.
  *
+ * Addresses that relay through this node are dropped first ({@link relaysThrough}):
+ * dialing one could only fail with `Can not dial self`. When that leaves nothing
+ * of a non-empty list, this throws {@link SelfRelayOnlyError} without dialing.
+ *
  * Addresses naming a transport this node lacks are not filtered out first: a
  * one-address `dial()` rejects those at once (`NoValidAddressesError`), so they
  * cost a log line, not time.
  *
- * Throws when no address connects — see {@link tryAddrsInTurn} for the error.
+ * Otherwise throws when no address connects — see {@link tryAddrsInTurn} for the error.
  *
  * @param label Names the dial in timeout messages and logs, e.g.
  *   `reconcileControlCohort dial of sibling <peerId>`; each attempt reads
  *   `<label> via <addr>`.
  */
-export function dialPeerAddrs(
+export async function dialPeerAddrs(
 	dialer: AddrDialer,
 	addrs: readonly Multiaddr[],
 	budget: PeerDialBudget,
 	label: string,
 ): Promise<Connection> {
-	return tryAddrsInTurn(directBeforeRelayed(addrs), budget, label, (addr, signal) => dialer.dial(addr, { signal }));
+	const dialable = withoutSelfRelayed(dialer, addrs, label);
+	if (addrs.length > 0 && dialable.length === 0) {
+		throw new SelfRelayOnlyError(label);
+	}
+	return tryAddrsInTurn(directBeforeRelayed(dialable), budget, label, (addr, signal) => dialer.dial(addr, { signal }));
 }
 
 /**
@@ -221,6 +250,51 @@ export function directBeforeRelayed(addrs: readonly Multiaddr[]): Multiaddr[] {
 	return [...addrs.filter((addr) => !relayed(addr)), ...addrs.filter(relayed)];
 }
 
+/** `addrs` without those that relay through `dialer` itself, each dropped one logged. */
+function withoutSelfRelayed(dialer: AddrDialer, addrs: readonly Multiaddr[], label: string): Multiaddr[] {
+	return addrs.filter((addr) => {
+		if (!relaysThrough(addr, dialer.peerId)) {
+			return true;
+		}
+		log('%s: skipping %s — it relays through this node', label, addr.toString());
+		return false;
+	});
+}
+
+/**
+ * Whether `addr` reaches its target by relaying through `relay` at any hop.
+ *
+ * A circuit address names its relay in the `p2p` component immediately before
+ * the `p2p-circuit` marker (`/<transport>/p2p/<relay>/p2p-circuit/p2p/<target>`),
+ * so the components are walked rather than the text searched: the target's id
+ * after the marker, a bare `/p2p-circuit` naming no relay, and a multi-hop chain
+ * each read correctly that way. Same rule as db-p2p's `routesThroughRelay`, which
+ * its package does not export.
+ */
+function relaysThrough(addr: Multiaddr, relay: PeerId): boolean {
+	const components = addr.getComponents();
+	return components.some((component, i) => component.name === 'p2p-circuit' && namesPeer(components[i - 1], relay));
+}
+
+/**
+ * Whether `component` is a `p2p` component naming `peer`. Compared as canonical
+ * strings because a multiaddr keeps a peer id in whichever form it was written
+ * (base58 or CIDv1). `PeerId.equals` is avoided because test doubles supply the
+ * dialer's `peerId` with `toString` only.
+ */
+function namesPeer(component: Component | undefined, peer: PeerId): boolean {
+	if (component?.name !== 'p2p' || component.value === undefined) {
+		return false;
+	}
+	const expected = peer.toString();
+	try {
+		return peerIdFromString(component.value).toString() === expected;
+	} catch (err) {
+		log('cannot read %s as a peer id; treating it as not this node: %o', component.value, err);
+		return false;
+	}
+}
+
 function allAttemptsFailed(label: string, failures: AddrAttemptFailure[]): Error {
 	if (failures.length === 0) {
 		return new Error(`${label}: no candidate addresses`);

package/src/peer-join-backfill.ts

@@ -63,11 +63,12 @@ import { peerJoinPushBudget } from './link-budget.js';
 // `packages/integration-tests/src/scenarios/relayed-dial-cost-by-latency.integration.ts`.
 //
 // It does NOT work at every speed. Above the declared link, libp2p's own dial and
-// inbound-upgrade limits — derived from the same declaration — abandon the connection before
-// any deadline here is consulted, and the listener's one makes that failure look like an absent
-// peer rather than a timeout. That is also what happens when the machine being caught up
-// declared a FASTER link than this one, since its limit is the listener's. See
-// `link-budget.ts` ("libp2p's own two limits", "What still fails at the supported link").
+// inbound-upgrade limits — which Optimystic derives from the same declaration — abandon the
+// connection before any deadline here is consulted, and the listener's one makes that failure
+// look like an absent peer rather than a timeout. That is also what happens when the machine
+// being caught up declared a FASTER link than this one, since its limit is the listener's. See
+// `link-budget.ts` ("Optimystic's deadlines, from the same declaration", "What still fails at
+// the supported link").
 //
 // RETRY, and why it backs off. A run whose PUSH FAILED — the transport threw, which is what
 // a dial or response deadline expiring looks like here — re-arms on a doubling backoff
@@ -176,7 +177,8 @@ export interface PeerJoinBackfillConfig {
   maxChunkBlocks?: number;
   /**
    * Per-push dial deadline, ms. Default {@link peerJoinPushBudget}'s `dialTimeoutMs` — four link
-   * round trips at the declared link, 14 000 ms as shipped. NOT a fixed number: a relayed dial
+   * round trips at the declared link plus the called machine's admission decision, 16 000 ms as
+   * shipped. NOT a fixed number: a relayed dial
    * costs a fixed number of exchanges, so a host on a slower link moves this (and every other
    * cadre dial budget) by declaring `NetworkConfig.linkRoundTripMs`. Naming it here still wins
    * over the derived value — `link-budget.ts` has the counts and the measurement.

package/src/push-fanout.ts

@@ -198,6 +198,12 @@ export class PushFanoutService {
    * double-wake). Only a dial/transport REJECTION means the phone is suspended
    * and unreachable over the control network, which is the one case that falls
    * through to FCM/APNs.
+   *
+   * NOTE: the platform push waits for the whole direct dial to fail, up to
+   * `DEFAULT_WAKE_DIAL_BUDGET_MS` (46 s at the default declared link). A suspended
+   * phone typically fails its relay address fast and spends the rest on its direct
+   * one. If that delay shows up, start the platform push in parallel with the dial,
+   * or after its first attempt.
    */
   private async wakePeer(peerId: string, strandId: string, reason: string): Promise<void> {
     // A wake of either kind is now being attempted → arm the cooldown up front.

package/src/relay-reservation.ts

@@ -143,7 +143,9 @@ export interface RelayReservationState {
 /**
  * How long {@link driveRelayReservation} waits for a reservation to appear, at the DEFAULT
  * declared link round trip: `RELAY_RESERVATION_ROUND_TRIPS` (4) x `DECLARED_LINK_ROUND_TRIP_MS`
- * (3500 ms) = 14 000 ms, where it was a fixed 10_000 before it was derived.
+ * (3500 ms), plus 2 x `ADMISSION_DECISION_TIMEOUT_MS` (2000 ms) for a party-run relay's
+ * connection and reservation decisions, = 18 000 ms (`relayReservationBudgetMs`), where it was a
+ * fixed 10_000 before it was derived.
  *
  * Counted rather than chosen because this one deadline bounds the whole drive — dial the relay,
  * request the reservation, wait — and each of those costs a fixed number of exchanges, not a

package/src/relay-server.ts

@@ -0,0 +1,98 @@
+/**
+ * The circuit-relay SERVER a party-run node runs — whether it runs one, and with which
+ * `@libp2p/circuit-relay-v2` init — resolved once from `NetworkConfig` for both node
+ * kinds: the control node (`cadre-node.ts` → `buildControlNodeOptions`) and every strand
+ * node (`strand-instance-manager.ts` → `buildStrandRuntime`). One function decides both
+ * answers so the two build sites cannot drift apart.
+ *
+ * WHY cadre sets an init at all. libp2p's server defaults `applyDefaultLimit` to true,
+ * which stamps every reservation with `Limit { data: 128 KiB, duration: 2 min }`; libp2p
+ * marks each connection relayed under it "limited" and resets it once either cap is
+ * reached, and db-p2p's database protocols refuse a limited connection outright (they do
+ * not set `runOnLimitedConnection`). A party-run relay exists to carry that party's own
+ * database traffic, so the cap cut off every sync and chat history forwarded through it
+ * (gotchoices/sereus#19). The dedicated relays (`ops/docker/libp2p-infra`, and the
+ * `startDedicatedRelay` test fixture that stands in for it) already turn the limit off;
+ * this is the same policy for the party-run kind.
+ */
+
+import type { CircuitRelayServerInit, ServerReservationStoreInit } from '@libp2p/circuit-relay-v2';
+import type { NetworkConfig, NodeProfile } from './types.js';
+
+/**
+ * Default size of a party-run relay's reservation store, raised from libp2p's 15.
+ *
+ * A NAT'd machine reserves one slot for its control node and one for each strand it
+ * serves, all on the same relay (`strand-network-config.ts` hands strand nodes the
+ * control node's `network.relayAddrs`), so the store needs
+ * `NAT'd machines × (1 + strands each)` slots. At libp2p's 15, three phones serving four
+ * strands each already fill it. 128 covers, for example, ten NAT'd machines serving eleven
+ * strands each with the unauthorized-reservation budget's 8 slots
+ * (`MAX_UNAUTHORIZED_RELAY_RESERVATIONS`) still free on top — one party's worth, where the
+ * dedicated relay's 500 is sized for many parties. A reservation costs the server a map
+ * entry and a timer, not a connection's worth of state, so the headroom is cheap.
+ */
+export const PARTY_RELAY_MAX_RESERVATIONS = 128;
+
+/**
+ * How long a party-run relay holds a reservation that is not refreshed: libp2p's own
+ * default (2 h), set EXPLICITLY so that cadre, not a libp2p constant it cannot import,
+ * owns the value the unauthorized-reservation budget has to agree with (see
+ * {@link ResolvedRelayServer.init}).
+ */
+export const PARTY_RELAY_RESERVATION_TTL_MS = 2 * 60 * 60 * 1000;
+
+/**
+ * The reservation-store settings every party-run relay resolves unless the caller
+ * overrides them one key at a time through `network.relayServerInit.reservations`.
+ * `applyDefaultLimit: false` is the point of this module — see the module doc.
+ */
+const PARTY_RELAY_RESERVATION_DEFAULTS = {
+  applyDefaultLimit: false,
+  maxReservations: PARTY_RELAY_MAX_RESERVATIONS,
+  reservationTtl: PARTY_RELAY_RESERVATION_TTL_MS
+} as const satisfies ServerReservationStoreInit;
+
+/** Reservation settings with the three keys cadre always resolves made definite. */
+export type ResolvedRelayReservations = ServerReservationStoreInit
+  & Required<Pick<ServerReservationStoreInit, keyof typeof PARTY_RELAY_RESERVATION_DEFAULTS>>;
+
+/** What {@link resolveRelayServer} decides for one node. */
+export interface ResolvedRelayServer {
+  /** Does this node run the relay server? Passed as db-p2p's `relay`. */
+  enabled: boolean;
+  /**
+   * The server's init, passed as db-p2p's `relayServerInit` when {@link enabled}: the
+   * party-run defaults with the caller's `network.relayServerInit` merged over them.
+   * `reservations.reservationTtl` is always set, which is what lets the control node's
+   * unauthorized-reservation budget expire its entries on the server's own clock.
+   */
+  init: CircuitRelayServerInit & { reservations: ResolvedRelayReservations };
+}
+
+/**
+ * Resolve the relay server for a node built from `network` with `profile`.
+ *
+ * `enabled`: an explicit `network.enableRelay` wins; otherwise storage-profile nodes run
+ * the server (they are the machines with the connectivity and uptime to be a relay).
+ *
+ * `init`: MERGED, not replaced. `reservations` is merged key by key over the party-run
+ * defaults, so a caller who sets only `maxReservations` does not silently get the data
+ * limit back; every other top-level key is taken from the caller as given. A key set to
+ * `undefined` counts as unset, so the default beneath it holds.
+ */
+export function resolveRelayServer(network: NetworkConfig | undefined, profile: NodeProfile): ResolvedRelayServer {
+  const override = network?.relayServerInit;
+  return {
+    enabled: network?.enableRelay ?? (profile === 'storage'),
+    init: {
+      ...override,
+      reservations: { ...PARTY_RELAY_RESERVATION_DEFAULTS, ...definedEntries(override?.reservations) }
+    }
+  };
+}
+
+/** `obj` without its `undefined`-valued keys, so spreading it never erases a default. */
+function definedEntries<T extends object>(obj: T | undefined): Partial<T> {
+  return Object.fromEntries(Object.entries(obj ?? {}).filter(([, value]) => value !== undefined)) as Partial<T>;
+}