@optimystic/db-p2p 0.21.0 → 0.24.0

package/src/cohort-topic/reactivity-membership-gate.ts

@@ -1,77 +1,77 @@
-/**
- * Reactivity origination membership gate (`docs/reactivity.md` §Anchor, `docs/internals.md`
- * §Cohort-Topic Origination Bridge).
- *
- * Builds the `selfIsCohortMember(event)` predicate the change-notifier bridge gates each member commit
- * on: this node is responsible for a collection's reactivity-topic fan-out iff it sits in the FRET
- * cohort around `coord_0(H(currentTailId ‖ "reactivity"))`. The tail comes from `event.tailId` (the seam
- * ticket put the committed `CommitRequest.tailId` on the change event), so the decision is synchronous —
- * no async storage read, no per-collection registry. A tail-less event (a read-driven promotion) is
- * never a member; those never originate and are cert-gated out downstream anyway.
- *
- * Extracted from the node assembly so the encoding + coord derivation are unit-testable in isolation and
- * reusable by the future reactivity origination wiring.
- */
-
-import {
-	createReactivityTopicAnchor,
-	createTierAddressing,
-	createRingHash,
-	type ReactivityTopicAnchor,
-	type TierAddressing,
-	type CollectionChangeEvent,
-} from "@optimystic/db-core";
-import type { FretService } from "p2p-fret";
-
-// The pinned `BlockId` → raw tail-bytes encoding now lives in the reactivity surface so the origination
-// gate (here) and the subscriber-side subscribe factory import the SAME function — see `reactivity/
-// topic-bytes.ts` for the load-bearing rationale. Re-exported so this module's existing callers (tests,
-// node wiring) keep importing `reactivityTailBytes` from the gate.
-export { reactivityTailBytes } from "../reactivity/topic-bytes.js";
-import { reactivityTailBytes } from "../reactivity/topic-bytes.js";
-
-/** Construction inputs for {@link createReactivitySelfMembershipGate}. */
-export interface ReactivitySelfMembershipGateDeps {
-	/** FRET membership read — the cohort assembler around a served coord (returns peer-id strings). */
-	readonly fret: Pick<FretService, "assembleCohort">;
-	/** This node's peer-id string, compared against the assembled cohort. */
-	readonly selfPeerId: string;
-	/**
-	 * Requested cohort size `wantK`. MUST equal the cohort-topic host's `wantK`, so the gate checks the
-	 * exact cohort the host serves; a mismatch silently breaks origination.
-	 */
-	readonly wantK: number;
-	/**
-	 * Reactivity topic anchor. Default db-core's {@link createReactivityTopicAnchor} (256-bit SHA-256),
-	 * byte-identical to the host's internal `new RingHash()` and the subscriber-side anchor.
-	 */
-	readonly anchor?: ReactivityTopicAnchor;
-	/**
-	 * Tier addressing. Default `createTierAddressing(createRingHash())`. `coord_0` is fan-out independent
-	 * (`H(0x00 ‖ topicId)`), so the default fan-out is irrelevant to the tier-0 reactivity coord.
-	 */
-	readonly addressing?: TierAddressing;
-}
-
-/**
- * Build the synchronous `selfIsCohortMember(event)` gate for {@link attachCohortChangeBridge}.
- *
- * Returns `false` for a tail-less event; otherwise resolves `coord_0(H(event.tailId ‖ "reactivity"))`
- * via the shared anchor + tier addressing and returns whether `fret.assembleCohort(coord, wantK)`
- * includes this node's peer id. Pure aside from the live FRET read; membership churn between commits is
- * fine because reactivity is hint-only.
- */
-export function createReactivitySelfMembershipGate(
-	deps: ReactivitySelfMembershipGateDeps,
-): (event: CollectionChangeEvent) => boolean {
-	const anchor = deps.anchor ?? createReactivityTopicAnchor();
-	const addressing = deps.addressing ?? createTierAddressing(createRingHash());
-	return (event: CollectionChangeEvent): boolean => {
-		if (event.tailId === undefined) {
-			return false; // promotion / tail-less event never originates
-		}
-		const topicId = anchor.topicId(reactivityTailBytes(event.tailId));
-		const coord = addressing.coord0(topicId);
-		return deps.fret.assembleCohort(coord, deps.wantK).includes(deps.selfPeerId);
-	};
-}
+/**
+ * Reactivity origination membership gate (`docs/reactivity.md` §Anchor, `docs/internals.md`
+ * §Cohort-Topic Origination Bridge).
+ *
+ * Builds the `selfIsCohortMember(event)` predicate the change-notifier bridge gates each member commit
+ * on: this node is responsible for a collection's reactivity-topic fan-out iff it sits in the FRET
+ * cohort around `coord_0(H(currentTailId ‖ "reactivity"))`. The tail comes from `event.tailId` (the seam
+ * ticket put the committed `CommitRequest.tailId` on the change event), so the decision is synchronous —
+ * no async storage read, no per-collection registry. A tail-less event (a read-driven promotion) is
+ * never a member; those never originate and are cert-gated out downstream anyway.
+ *
+ * Extracted from the node assembly so the encoding + coord derivation are unit-testable in isolation and
+ * reusable by the future reactivity origination wiring.
+ */
+
+import {
+	createReactivityTopicAnchor,
+	createTierAddressing,
+	createRingHash,
+	type ReactivityTopicAnchor,
+	type TierAddressing,
+	type CollectionChangeEvent,
+} from "@optimystic/db-core";
+import type { FretService } from "p2p-fret";
+
+// The pinned `BlockId` → raw tail-bytes encoding now lives in the reactivity surface so the origination
+// gate (here) and the subscriber-side subscribe factory import the SAME function — see `reactivity/
+// topic-bytes.ts` for the load-bearing rationale. Re-exported so this module's existing callers (tests,
+// node wiring) keep importing `reactivityTailBytes` from the gate.
+export { reactivityTailBytes } from "../reactivity/topic-bytes.js";
+import { reactivityTailBytes } from "../reactivity/topic-bytes.js";
+
+/** Construction inputs for {@link createReactivitySelfMembershipGate}. */
+export interface ReactivitySelfMembershipGateDeps {
+	/** FRET membership read — the cohort assembler around a served coord (returns peer-id strings). */
+	readonly fret: Pick<FretService, "assembleCohort">;
+	/** This node's peer-id string, compared against the assembled cohort. */
+	readonly selfPeerId: string;
+	/**
+	 * Requested cohort size `wantK`. MUST equal the cohort-topic host's `wantK`, so the gate checks the
+	 * exact cohort the host serves; a mismatch silently breaks origination.
+	 */
+	readonly wantK: number;
+	/**
+	 * Reactivity topic anchor. Default db-core's {@link createReactivityTopicAnchor} (256-bit SHA-256),
+	 * byte-identical to the host's internal `new RingHash()` and the subscriber-side anchor.
+	 */
+	readonly anchor?: ReactivityTopicAnchor;
+	/**
+	 * Tier addressing. Default `createTierAddressing(createRingHash())`. `coord_0` is fan-out independent
+	 * (`H(0x00 ‖ topicId)`), so the default fan-out is irrelevant to the tier-0 reactivity coord.
+	 */
+	readonly addressing?: TierAddressing;
+}
+
+/**
+ * Build the synchronous `selfIsCohortMember(event)` gate for {@link attachCohortChangeBridge}.
+ *
+ * Returns `false` for a tail-less event; otherwise resolves `coord_0(H(event.tailId ‖ "reactivity"))`
+ * via the shared anchor + tier addressing and returns whether `fret.assembleCohort(coord, wantK)`
+ * includes this node's peer id. Pure aside from the live FRET read; membership churn between commits is
+ * fine because reactivity is hint-only.
+ */
+export function createReactivitySelfMembershipGate(
+	deps: ReactivitySelfMembershipGateDeps,
+): (event: CollectionChangeEvent) => boolean {
+	const anchor = deps.anchor ?? createReactivityTopicAnchor();
+	const addressing = deps.addressing ?? createTierAddressing(createRingHash());
+	return (event: CollectionChangeEvent): boolean => {
+		if (event.tailId === undefined) {
+			return false; // promotion / tail-less event never originates
+		}
+		const topicId = anchor.topicId(reactivityTailBytes(event.tailId));
+		const coord = addressing.coord0(topicId);
+		return deps.fret.assembleCohort(coord, deps.wantK).includes(deps.selfPeerId);
+	};
+}

package/src/cohort-topic/size-estimator.ts

@@ -1,16 +1,16 @@
-import type { ISizeEstimator } from "@optimystic/db-core";
-import type { FretService } from "p2p-fret";
-
-/**
- * FRET-backed {@link ISizeEstimator}: feeds `d_max` from FRET's network-size estimate
- * (`FretService.getNetworkSizeEstimate`). A clean, total binding — db-core's `d_max` computer applies
- * the low-confidence clamp itself, so this adapter only forwards FRET's `(size_estimate, confidence)`.
- */
-export class FretSizeEstimator implements ISizeEstimator {
-	constructor(private readonly fret: FretService) {}
-
-	estimate(): { nEst: number; confidence: number } {
-		const { size_estimate, confidence } = this.fret.getNetworkSizeEstimate();
-		return { nEst: size_estimate, confidence };
-	}
-}
+import type { ISizeEstimator } from "@optimystic/db-core";
+import type { FretService } from "p2p-fret";
+
+/**
+ * FRET-backed {@link ISizeEstimator}: feeds `d_max` from FRET's network-size estimate
+ * (`FretService.getNetworkSizeEstimate`). A clean, total binding — db-core's `d_max` computer applies
+ * the low-confidence clamp itself, so this adapter only forwards FRET's `(size_estimate, confidence)`.
+ */
+export class FretSizeEstimator implements ISizeEstimator {
+	constructor(private readonly fret: FretService) {}
+
+	estimate(): { nEst: number; confidence: number } {
+		const { size_estimate, confidence } = this.fret.getNetworkSizeEstimate();
+		return { nEst: size_estimate, confidence };
+	}
+}

package/src/cohort-topic/stream-util.ts

@@ -1,87 +1,135 @@
-/**
- * Cohort-topic libp2p stream helpers.
- *
- * The cohort-topic protocols exchange a single self-delimiting cohort frame each way (the db-core wire
- * codec already length-prefixes the body), so request/response is one `send` + one bounded read. This
- * mirrors FRET's `rpc/maybe-act.ts` exactly and reuses FRET's exported `readAllBounded`, keeping the
- * stream lifecycle (open → send → close-write → read → close) consistent across both protocol families.
- */
-
-import type { Libp2p } from "libp2p";
-import type { Connection, PeerId, Stream } from "@libp2p/interface";
-import { readAllBounded } from "p2p-fret";
-
-/** Default per-frame ceiling — matches FRET's 512 KiB maybe-act bound. */
-export const DEFAULT_STREAM_MAX_BYTES = 512 * 1024;
-
-/** Open `protocol` to `peer`, send `frame`, and read the bounded reply frame. */
-export async function requestResponse(
-	node: Libp2p,
-	peer: PeerId,
-	protocol: string,
-	frame: Uint8Array,
-	maxBytes = DEFAULT_STREAM_MAX_BYTES,
-): Promise<Uint8Array> {
-	const conns = node.getConnections(peer);
-	let stream: Stream | undefined;
-	try {
-		stream = conns.length > 0 ? await conns[0]!.newStream([protocol]) : await node.dialProtocol(peer, [protocol]);
-		stream.send(frame);
-		await stream.close();
-		return await readAllBounded(stream, maxBytes);
-	} finally {
-		if (stream != null) {
-			try {
-				await stream.close();
-			} catch {
-				/* already closed */
-			}
-		}
-	}
-}
-
-/** Open `protocol` to `peer` and send `frame` without awaiting a reply (fire-and-forget gossip). */
-export async function sendOneWay(node: Libp2p, peer: PeerId, protocol: string, frame: Uint8Array): Promise<void> {
-	const conns = node.getConnections(peer);
-	let stream: Stream | undefined;
-	try {
-		stream = conns.length > 0 ? await conns[0]!.newStream([protocol]) : await node.dialProtocol(peer, [protocol]);
-		stream.send(frame);
-		await stream.close();
-	} finally {
-		if (stream != null) {
-			try {
-				await stream.close();
-			} catch {
-				/* already closed */
-			}
-		}
-	}
-}
-
-/** Register a request/response handler for `protocol`: read one bounded frame, reply with one frame. */
-export function handleRequestResponse(
-	node: Libp2p,
-	protocol: string,
-	handle: (frame: Uint8Array, from: PeerId) => Promise<Uint8Array | undefined>,
-	maxBytes = DEFAULT_STREAM_MAX_BYTES,
-): void {
-	void node.handle(protocol, (stream: Stream, connection: Connection) => {
-		void (async (): Promise<void> => {
-			try {
-				const frame = await readAllBounded(stream, maxBytes);
-				const reply = await handle(frame, connection.remotePeer);
-				if (reply !== undefined) {
-					stream.send(reply);
-				}
-				await stream.close();
-			} catch {
-				try {
-					stream.abort(new Error("cohort-topic stream handler error"));
-				} catch {
-					/* already aborted */
-				}
-			}
-		})();
-	});
-}
+/**
+ * Single-frame libp2p stream helpers, shared by cohort-topic, matchmaking, and reactivity.
+ *
+ * These protocols exchange a single self-delimiting cohort frame each way (the db-core wire codec
+ * already length-prefixes the body), so request/response is one `send` + one bounded read. This
+ * mirrors FRET's `rpc/maybe-act.ts` and reuses FRET's exported `readAllBounded`, keeping the stream
+ * lifecycle (open → send → close-write → read → close) consistent across both protocol families.
+ *
+ * {@link openStream} deliberately duplicates FRET's `rpc/protocols.ts#openRpcStream` connection
+ * selection, because FRET does not export that helper (its package `exports` map exposes only the
+ * root entry, so there is no deep import either).
+ * NOTE: if FRET ever exports `openRpcStream`, delete {@link openStream} and call it instead — the
+ * divergence between the two copies is exactly what let the missing `runOnLimitedConnection` flag
+ * hide here. Same applies to `libp2p-key-network.ts#connect`, which is a third copy.
+ */
+
+import type { Libp2p } from "libp2p";
+import type { Connection, PeerId, Stream } from "@libp2p/interface";
+import { readAllBounded } from "p2p-fret";
+
+/** Default per-frame ceiling — matches FRET's 512 KiB maybe-act bound. */
+export const DEFAULT_STREAM_MAX_BYTES = 512 * 1024;
+
+/**
+ * libp2p refuses to open a protocol stream over a *limited* (circuit-relay) connection unless the
+ * caller opts in, so every peer reachable only through a relay — the steady state for browsers and
+ * NATed peers — depends on this flag. It is a harmless no-op on a direct connection.
+ *
+ * NOTE: accepted tradeoff — FRET's `openRpcStream` and `libp2p-key-network.ts#connect` also set
+ * `negotiateFully: false`; deliberately not set here. It saves a round trip but defers an
+ * unsupported-protocol failure from stream-open to the first read, which would turn
+ * {@link sendOneWay} against a peer lacking the protocol into a silent no-op. Revisit if
+ * stream-open latency shows up in a profile.
+ */
+const STREAM_OPTIONS = { runOnLimitedConnection: true } as const;
+
+/** True for a circuit-relay ("limited") connection: libp2p stamps one with per-circuit `limits`;
+ * sniffing `/p2p-circuit` in the multiaddr covers transports that leave `limits` unpopulated. */
+function isLimitedConnection(c: Connection): boolean {
+	if ((c as { limits?: unknown }).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.
+ */
+async function openStream(node: Libp2p, peer: PeerId, protocol: string): Promise<Stream> {
+	const open = node.getConnections(peer).filter(c => c?.status === "open" && typeof c?.newStream === "function");
+	const chosen = open.find(c => !isLimitedConnection(c)) ?? open[0];
+	return chosen ? await chosen.newStream([protocol], STREAM_OPTIONS) : await node.dialProtocol(peer, [protocol], STREAM_OPTIONS);
+}
+
+/**
+ * Open `protocol` to `peer`, send `frame`, and read the bounded reply frame.
+ *
+ * NOTE: takes no `AbortSignal`, so a caller cannot set its own deadline. Bounded today anyway —
+ * `readAllBounded` self-times-out at 5s and `dialProtocol` falls back to libp2p's default dial
+ * timeout (~30s) — so an unresponsive peer is slow, not hung. If a caller ever needs a tighter
+ * deadline (`membership-source.fetch` walks candidate peers *sequentially*, so its worst case is
+ * peers × dial-timeout), thread a signal through {@link openStream} the way
+ * `libp2p-key-network.ts#connect` does.
+ */
+export async function requestResponse(
+	node: Libp2p,
+	peer: PeerId,
+	protocol: string,
+	frame: Uint8Array,
+	maxBytes = DEFAULT_STREAM_MAX_BYTES,
+): Promise<Uint8Array> {
+	let stream: Stream | undefined;
+	try {
+		stream = await openStream(node, peer, protocol);
+		stream.send(frame);
+		await stream.close();
+		return await readAllBounded(stream, maxBytes);
+	} finally {
+		if (stream != null) {
+			try {
+				await stream.close();
+			} catch {
+				/* already closed */
+			}
+		}
+	}
+}
+
+/** Open `protocol` to `peer` and send `frame` without awaiting a reply (fire-and-forget gossip). */
+export async function sendOneWay(node: Libp2p, peer: PeerId, protocol: string, frame: Uint8Array): Promise<void> {
+	let stream: Stream | undefined;
+	try {
+		stream = await openStream(node, peer, protocol);
+		stream.send(frame);
+		await stream.close();
+	} finally {
+		if (stream != null) {
+			try {
+				await stream.close();
+			} catch {
+				/* already closed */
+			}
+		}
+	}
+}
+
+/** Register a request/response handler for `protocol`: read one bounded frame, reply with one frame. */
+export function handleRequestResponse(
+	node: Libp2p,
+	protocol: string,
+	handle: (frame: Uint8Array, from: PeerId) => Promise<Uint8Array | undefined>,
+	maxBytes = DEFAULT_STREAM_MAX_BYTES,
+): void {
+	void node.handle(protocol, (stream: Stream, connection: Connection) => {
+		void (async (): Promise<void> => {
+			try {
+				const frame = await readAllBounded(stream, maxBytes);
+				const reply = await handle(frame, connection.remotePeer);
+				if (reply !== undefined) {
+					stream.send(reply);
+				}
+				await stream.close();
+			} catch {
+				try {
+					stream.abort(new Error("cohort-topic stream handler error"));
+				} catch {
+					/* already aborted */
+				}
+			}
+		})();
+	});
+}