@optimystic/db-p2p 0.24.1 → 0.25.0

package/src/logger.ts

@@ -1,27 +1,27 @@
-import debug from 'debug'
-
-const BASE_NAMESPACE = 'optimystic:db-p2p'
-
-/**
- * Build a `debug` logger under `optimystic:db-p2p:<subNamespace>`, optionally suffixed with the
- * owning node's peer id (`:<first 12 chars>`) so lines from several nodes sharing one process —
- * every integration test — are attributable. Omit `peerId` and the namespace is byte-for-byte the
- * un-suffixed one, so callers that don't know their peer id are unaffected.
- *
- * NOTE: 12 chars matches the truncation the rest of this package already uses in log payloads, but
- * every Ed25519 peer id starts with the constant `12D3KooW`, so only ~4 base58 characters actually
- * distinguish nodes (~11M combinations — ample for the handful of nodes a test process runs).
- * Widen this only if a run ever needs to match a namespace against a full peer id.
- *
- * NOTE: only the two classes the diagnosability ticket named pass a peer id today
- * (`Libp2pKeyPeerNetwork`, `CoordinatorRepo`); the package's other ~30 `createLogger` call sites
- * still log under a flat namespace. Thread a peer id through any of them if a future diagnosis
- * needs per-node attribution from that subsystem — the mechanism is already here.
- */
-export function createLogger(subNamespace: string, peerId?: string): debug.Debugger {
-	const suffix = peerId ? `:${peerId.substring(0, 12)}` : ''
-	return debug(`${BASE_NAMESPACE}:${subNamespace}${suffix}`)
-}
-
-export const verbose = typeof process !== 'undefined'
-	&& (process.env.OPTIMYSTIC_VERBOSE === '1' || process.env.OPTIMYSTIC_VERBOSE === 'true');
+import debug from 'debug'
+
+const BASE_NAMESPACE = 'optimystic:db-p2p'
+
+/**
+ * Build a `debug` logger under `optimystic:db-p2p:<subNamespace>`, optionally suffixed with the
+ * owning node's peer id (`:<first 12 chars>`) so lines from several nodes sharing one process —
+ * every integration test — are attributable. Omit `peerId` and the namespace is byte-for-byte the
+ * un-suffixed one, so callers that don't know their peer id are unaffected.
+ *
+ * NOTE: 12 chars matches the truncation the rest of this package already uses in log payloads, but
+ * every Ed25519 peer id starts with the constant `12D3KooW`, so only ~4 base58 characters actually
+ * distinguish nodes (~11M combinations — ample for the handful of nodes a test process runs).
+ * Widen this only if a run ever needs to match a namespace against a full peer id.
+ *
+ * NOTE: only a few call sites pass a peer id today (`Libp2pKeyPeerNetwork`, `CoordinatorRepo`, and
+ * the three `peer-address-book` sinks); the package's other ~30 `createLogger` call sites
+ * still log under a flat namespace. Thread a peer id through any of them if a future diagnosis
+ * needs per-node attribution from that subsystem — the mechanism is already here.
+ */
+export function createLogger(subNamespace: string, peerId?: string): debug.Debugger {
+	const suffix = peerId ? `:${peerId.substring(0, 12)}` : ''
+	return debug(`${BASE_NAMESPACE}:${subNamespace}${suffix}`)
+}
+
+export const verbose = typeof process !== 'undefined'
+	&& (process.env.OPTIMYSTIC_VERBOSE === '1' || process.env.OPTIMYSTIC_VERBOSE === 'true');

package/src/network/open-protocol-stream.ts

@@ -0,0 +1,87 @@
+/**
+ * The single place in `db-p2p` that opens a libp2p protocol stream.
+ *
+ * libp2p refuses to open a protocol stream over a *limited* (circuit-relay) connection unless the
+ * caller opts in with `runOnLimitedConnection: true`. Omitting it produces no compile error and no
+ * obvious failure — only "that peer never answers" — so every peer reachable only through a relay
+ * (the steady state for browsers, phones, and NATed peers) silently drops out. The flag is
+ * deliberately NOT an option here: a new call site gets relay support without its author needing to
+ * know the flag exists, and `test/dial-options-single-site.spec.ts` fails the build if a second
+ * source file calls `dialProtocol` / `newStream` directly.
+ *
+ * NOTE: accepted tradeoff — this duplicates FRET's `rpc/protocols.ts#openRpcStream` (exported since
+ * `p2p-fret@1.0.0-beta.3`) rather than delegating to it. FRET's helper pins `negotiateFully: false`
+ * with no way to opt out, and `cohort-topic/stream-util.ts` deliberately does not set that option
+ * (see the NOTE at its call sites); adopting FRET's would silently reverse a decision a human
+ * already made. It also has no hook for the pre-dial check `libp2p-key-network.ts#connect` runs.
+ * Revisit — and delete this module in favour of `openRpcStream` — if FRET ever parameterizes
+ * `negotiateFully`.
+ *
+ * Imports here are type-only on purpose: this module is reachable from the react-native entry
+ * (`src/rn.ts`) via `libp2p-key-network.ts`, which must not pull node-specific code.
+ */
+
+import type { Libp2p } from "libp2p";
+import type { Connection, PeerId, Stream } from "@libp2p/interface";
+
+export interface OpenProtocolStreamOptions {
+	/** Forwarded to libp2p so a caller's deadline cancels both the connection reuse and the dial. */
+	signal?: AbortSignal;
+	/**
+	 * Omit for libp2p's default (full multistream-select negotiation at stream-open).
+	 * Pass `false` to save the round trip, accepting that an unsupported-protocol failure is
+	 * deferred to the first read — only safe when the caller always reads a reply.
+	 */
+	negotiateFully?: boolean;
+	/**
+	 * Runs immediately before a FRESH dial, and never on the connection-reuse path.
+	 * Throwing aborts the open. This is the seam for checks that are only meaningful when no
+	 * connection exists yet (see `libp2p-key-network.ts#assertNotSelfRelayOnly`).
+	 */
+	beforeDial?: () => Promise<void> | void;
+}
+
+/**
+ * True for a circuit-relay ("limited") connection: libp2p stamps one with per-circuit `limits`
+ * (data/duration caps); sniffing `/p2p-circuit` in the remote multiaddr covers transports and
+ * versions that leave `limits` unpopulated.
+ */
+export function isLimitedConnection(c: Connection): boolean {
+	if (c.limits != null) return true;
+	return c.remoteAddr?.toString?.().includes("/p2p-circuit") ?? false;
+}
+
+/**
+ * Open `protocol` to `peer`, reusing a healthy existing connection when there is one.
+ *
+ * Skips connections libp2p has not yet evicted from its index but that are no longer open, and
+ * prefers a direct connection over a relayed one — a relayed connection can be reset once the
+ * relay's per-circuit cap or reservation lapses, and after DCUtR upgrades a link to direct both
+ * briefly coexist. Falls back to the relayed connection when it is the only open path.
+ */
+export async function openProtocolStream(
+	node: Libp2p,
+	peer: PeerId,
+	protocol: string,
+	options?: OpenProtocolStreamOptions,
+): Promise<Stream> {
+	// Before touching connections: a caller that has already given up is owed its own reason,
+	// not whatever libp2p would report several layers down.
+	options?.signal?.throwIfAborted();
+
+	const conns = node.getConnections?.(peer) ?? [];
+	const open = conns.filter(c => c?.status === "open" && typeof c?.newStream === "function");
+	const chosen = open.find(c => !isLimitedConnection(c)) ?? open[0];
+
+	// Keys are OMITTED rather than set to `undefined` when the caller did not supply them, so
+	// libp2p applies its own defaults instead of seeing an explicit `undefined`.
+	const streamOptions = {
+		runOnLimitedConnection: true,
+		...(options?.negotiateFully !== undefined ? { negotiateFully: options.negotiateFully } : {}),
+		...(options?.signal !== undefined ? { signal: options.signal } : {}),
+	};
+
+	if (chosen) return await chosen.newStream([protocol], streamOptions);
+	await options?.beforeDial?.();
+	return await node.dialProtocol(peer, [protocol], streamOptions);
+}

package/src/network/register-protocol-handler.ts

@@ -0,0 +1,85 @@
+/**
+ * The single place in `db-p2p` that registers a libp2p protocol handler.
+ *
+ * The mirror image of `./open-protocol-stream.ts`. Opening a stream over a *limited* (circuit-relay)
+ * connection needs BOTH sides to opt in, and libp2p checks each side against its own options:
+ *
+ * - the dialer's `newStream` / `dialProtocol` options (`libp2p/src/connection.ts`, outbound path), and
+ * - the options the *answering* peer passed when it registered the handler
+ *   (`libp2p/src/connection.ts`, incoming path — it reads back
+ *   `registrar.getHandler(protocol).options.runOnLimitedConnection`).
+ *
+ * Miss either one and libp2p throws `LimitedConnectionError`. On the answering side it does so
+ * *after* multistream-select has already acknowledged the protocol, so the dialer's stream open
+ * appears to succeed and the stream is then reset with no reply — indistinguishable, from the
+ * dialer's seat, from a peer that simply does not hold the data. Every peer reachable only through
+ * a capped relay (phones, browsers, machines behind a home router) silently drops out.
+ *
+ * `openProtocolStream` fixed the dialling half; this fixes the answering half. As there, the flag is
+ * deliberately NOT an option: a new protocol gets relay support without its author needing to know
+ * the flag exists, and `test/dial-options-single-site.spec.ts` fails the build if a second source
+ * file calls `.handle(...)` directly.
+ *
+ * Accepting the stream is necessary but not sufficient. A stock relay also caps the *whole* relayed
+ * connection — `applyDefaultLimit: true` stamps `Limit { data: 128 KiB, duration: 2 min }` on every
+ * reservation — so a relay-only peer now answers, but the circuit is reset once either cap is hit,
+ * which one cohort frame (`DEFAULT_STREAM_MAX_BYTES`, 512 KiB) can do on its own. Lifting that is
+ * the relay operator's knob, not this one: see `NodeOptions.relayServerInit` in `libp2p-node-base.ts`.
+ *
+ * Imports here are type-only on purpose: this module is reachable from the react-native entry
+ * (`src/rn.ts`), which must not pull node-specific code.
+ */
+
+import type { StreamHandler, StreamHandlerOptions, StreamMiddleware } from "@libp2p/interface";
+
+/**
+ * Anything that can register a libp2p protocol handler.
+ *
+ * Both shapes in this package satisfy it: a `Libp2p` node (`node.handle(...)`) and the `registrar`
+ * component the service classes are constructed with (`components.registrar.handle(...)`).
+ */
+export interface ProtocolRegistrar {
+	handle(protocol: string, handler: StreamHandler, options?: StreamHandlerOptions): Promise<void>;
+}
+
+/**
+ * The per-protocol settings that legitimately vary. `runOnLimitedConnection` is absent on purpose —
+ * it is a constant of this helper, not a caller's choice.
+ */
+export interface RegisterProtocolHandlerOptions {
+	/** Concurrent inbound streams allowed per connection. Omit for libp2p's default (32). */
+	maxInboundStreams?: number;
+	/** Concurrent outbound streams allowed per connection. Omit for libp2p's default (64). */
+	maxOutboundStreams?: number;
+	/** Stream middleware, run around the handler. Omit for none. */
+	middleware?: StreamMiddleware[];
+	/** Replace an existing registration for this protocol instead of rejecting. */
+	force?: true;
+	/** Forwarded to libp2p so a caller's deadline cancels the registration. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Register `handler` for `protocol`, accepting streams over limited (relay) connections.
+ *
+ * Rejects if the registrar rejects — a duplicate protocol id, or an aborted signal. Callers that
+ * register fire-and-forget (`void registerProtocolHandler(...)`) keep that behaviour; see the NOTE
+ * in `libp2p-node-base.ts` about the reactivity handlers.
+ */
+export async function registerProtocolHandler(
+	target: ProtocolRegistrar,
+	protocol: string,
+	handler: StreamHandler,
+	options?: RegisterProtocolHandlerOptions,
+): Promise<void> {
+	// Keys are OMITTED rather than set to `undefined` when the caller did not supply them, so
+	// libp2p applies its own defaults instead of seeing an explicit `undefined`.
+	await target.handle(protocol, handler, {
+		runOnLimitedConnection: true,
+		...(options?.maxInboundStreams !== undefined ? { maxInboundStreams: options.maxInboundStreams } : {}),
+		...(options?.maxOutboundStreams !== undefined ? { maxOutboundStreams: options.maxOutboundStreams } : {}),
+		...(options?.middleware !== undefined ? { middleware: options.middleware } : {}),
+		...(options?.force !== undefined ? { force: options.force } : {}),
+		...(options?.signal !== undefined ? { signal: options.signal } : {}),
+	});
+}