@optimystic/db-p2p 0.22.0 → 0.24.0

package/src/matchmaking/protocols.ts

@@ -1,51 +1,51 @@
-/**
- * Matchmaking libp2p protocol IDs (`docs/matchmaking.md` §Seeker query).
- *
- * Matchmaking is an application layered **above** the cohort-topic substrate, so it owns its own protocol
- * family rather than riding the cohort-topic protocols (which carry only substrate concerns — register,
- * gossip, promote, membership, sign). Exactly one protocol lives here today:
- *
- * - `query` — `QueryV1` → `QueryReplyV1`, the seeker's request-reply RPC against a cohort for the
- *             providers/seekers it locally holds (the serve side is `query-transport.ts`; the seeker
- *             walk client is the follow-on `matchmaking-query-rpc-seeker-walk`).
- *
- * The default (network-agnostic) ID omits the network segment; {@link makeMatchmakingProtocols} mirrors
- * FRET's `makeProtocols(networkName)` so a named network namespaces its matchmaking protocols the same way
- * FRET namespaces its routing protocols (and the cohort-topic / reactivity families namespace via their own
- * `make*Protocols`). Production wires the network-agnostic default, matching the cohort-topic + reactivity
- * families' production default.
- */
-
-/** Base path for the matchmaking protocol family. */
-export const MATCHMAKING_BASE = "/optimystic/matchmaking/1.0.0" as const;
-
-/** `QueryV1` / `QueryReplyV1` — a seeker's query for a cohort's locally-held provider/seeker registrations. */
-export const PROTOCOL_MATCHMAKING_QUERY = `${MATCHMAKING_BASE}/query` as const;
-
-/** The matchmaking protocol IDs in registration order. */
-export interface MatchmakingProtocols {
-	readonly query: string;
-}
-
-/** Default (network-agnostic) protocol IDs, matching `docs/matchmaking.md`. */
-export const DEFAULT_MATCHMAKING_PROTOCOLS: MatchmakingProtocols = {
-	query: PROTOCOL_MATCHMAKING_QUERY,
-};
-
-/**
- * Namespaced matchmaking protocol IDs for `networkName` (mirrors FRET's `makeProtocols`, which inserts the
- * network segment even for `"default"` → `/optimystic/default/...`). Note this does NOT equal
- * {@link DEFAULT_MATCHMAKING_PROTOCOLS}: the canonical, network-agnostic IDs omit the segment entirely
- * (`/optimystic/matchmaking/1.0.0/...`); use those unless you need per-network namespacing.
- */
-export function makeMatchmakingProtocols(networkName = "default"): MatchmakingProtocols {
-	const base = `/optimystic/${networkName}/matchmaking/1.0.0`;
-	return {
-		query: `${base}/query`,
-	};
-}
-
-/** All matchmaking protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
-export function matchmakingProtocolList(p: MatchmakingProtocols): string[] {
-	return [p.query];
-}
+/**
+ * Matchmaking libp2p protocol IDs (`docs/matchmaking.md` §Seeker query).
+ *
+ * Matchmaking is an application layered **above** the cohort-topic substrate, so it owns its own protocol
+ * family rather than riding the cohort-topic protocols (which carry only substrate concerns — register,
+ * gossip, promote, membership, sign). Exactly one protocol lives here today:
+ *
+ * - `query` — `QueryV1` → `QueryReplyV1`, the seeker's request-reply RPC against a cohort for the
+ *             providers/seekers it locally holds (the serve side is `query-transport.ts`; the seeker
+ *             walk client is the follow-on `matchmaking-query-rpc-seeker-walk`).
+ *
+ * The default (network-agnostic) ID omits the network segment; {@link makeMatchmakingProtocols} mirrors
+ * FRET's `makeProtocols(networkName)` so a named network namespaces its matchmaking protocols the same way
+ * FRET namespaces its routing protocols (and the cohort-topic / reactivity families namespace via their own
+ * `make*Protocols`). Production wires the network-agnostic default, matching the cohort-topic + reactivity
+ * families' production default.
+ */
+
+/** Base path for the matchmaking protocol family. */
+export const MATCHMAKING_BASE = "/optimystic/matchmaking/1.0.0" as const;
+
+/** `QueryV1` / `QueryReplyV1` — a seeker's query for a cohort's locally-held provider/seeker registrations. */
+export const PROTOCOL_MATCHMAKING_QUERY = `${MATCHMAKING_BASE}/query` as const;
+
+/** The matchmaking protocol IDs in registration order. */
+export interface MatchmakingProtocols {
+	readonly query: string;
+}
+
+/** Default (network-agnostic) protocol IDs, matching `docs/matchmaking.md`. */
+export const DEFAULT_MATCHMAKING_PROTOCOLS: MatchmakingProtocols = {
+	query: PROTOCOL_MATCHMAKING_QUERY,
+};
+
+/**
+ * Namespaced matchmaking protocol IDs for `networkName` (mirrors FRET's `makeProtocols`, which inserts the
+ * network segment even for `"default"` → `/optimystic/default/...`). Note this does NOT equal
+ * {@link DEFAULT_MATCHMAKING_PROTOCOLS}: the canonical, network-agnostic IDs omit the segment entirely
+ * (`/optimystic/matchmaking/1.0.0/...`); use those unless you need per-network namespacing.
+ */
+export function makeMatchmakingProtocols(networkName = "default"): MatchmakingProtocols {
+	const base = `/optimystic/${networkName}/matchmaking/1.0.0`;
+	return {
+		query: `${base}/query`,
+	};
+}
+
+/** All matchmaking protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
+export function matchmakingProtocolList(p: MatchmakingProtocols): string[] {
+	return [p.query];
+}

package/src/matchmaking/provider-manager.ts

@@ -1,95 +1,95 @@
-/**
- * Matchmaking — provider manager (db-p2p, wires to the cohort-topic substrate).
- *
- * Drives a db-core {@link MatchmakingProvider}'s lifecycle against the participant-facing
- * {@link CohortTopicService}: register at cohort-topic tier **T2 (functional)** with a profile-based
- * TTL, renew to keep the record alive, and withdraw by ceasing renewal (`docs/matchmaking.md`
- * §Provider registration).
- *
- * Self-throttling maps onto the substrate as follows (an honest gap surfaced for the reviewer): the
- * cohort-topic `RenewV1` carries **no** `appPayload` and **no** `ttl` field — a renewal is a pure
- * keep-alive touch. So a capacity change ("signal full", `capacityBudget = 0`) is realized by
- * **re-registering** with the new signed payload (which updates the cohort record's `appState`), not
- * by a renewal. Likewise immediate withdrawal (`RenewV1` TTL = 0 in the matchmaking doc) has no wire
- * realization yet — {@link withdraw} stops renewing and lets the record age out by TTL. Per the
- * §Provider self-throttling GROUNDING resolution, withdrawal is an **optimization, not correctness**,
- * so passive TTL expiry is acceptable; an immediate-tombstone renew is a documented cohort-topic
- * follow-on.
- */
-
-import { Tier, providerTtlForProfile, type CohortTopicService, type MatchmakingProvider, type NodeProfile, type RegistrationHandle } from "@optimystic/db-core";
-
-/** Construction inputs for a {@link MatchmakingProviderManager}. */
-export interface MatchmakingProviderManagerOptions {
-	/** Participant-facing cohort-topic substrate API. */
-	readonly service: CohortTopicService;
-	/** The provider state/decision object this manager drives. */
-	readonly provider: MatchmakingProvider;
-	/** Provider TTL (ms). Default: derived from {@link profile} via `providerTtlForProfile`. */
-	readonly ttlMs?: number;
-	/** Node profile used to derive the TTL when {@link ttlMs} is absent (Core 90 s / Edge 60 s). */
-	readonly profile?: NodeProfile;
-}
-
-/** Wires one matchmaking provider to the cohort-topic substrate at tier T2. */
-export class MatchmakingProviderManager {
-	private readonly service: CohortTopicService;
-	private readonly provider: MatchmakingProvider;
-	private readonly ttlMs: number;
-	private handle?: RegistrationHandle;
-
-	constructor(options: MatchmakingProviderManagerOptions) {
-		this.service = options.service;
-		this.provider = options.provider;
-		this.ttlMs = options.ttlMs ?? (options.profile !== undefined ? providerTtlForProfile(options.profile) : undefined) ?? DEFAULT_PROVIDER_TTL_MS;
-	}
-
-	/** The live registration handle, or `undefined` before the first {@link register}. */
-	get registration(): RegistrationHandle | undefined {
-		return this.handle;
-	}
-
-	/** Register (or re-register) the provider at tier T2 with the current signed payload. */
-	async register(): Promise<RegistrationHandle> {
-		const appPayload = await this.provider.appPayloadBytes();
-		this.handle = await this.service.register({
-			topicId: this.provider.topicId,
-			tier: Tier.T2,
-			appPayload,
-			ttl: this.ttlMs,
-		});
-		return this.handle;
-	}
-
-	/** Run one renewal cycle (keep-alive touch). No-op before the first {@link register}. */
-	async renew(): Promise<void> {
-		if (this.handle === undefined) {
-			return;
-		}
-		await this.service.renew(this.handle);
-	}
-
-	/** Set the live capacity budget and push it by re-registering (`RenewV1` cannot carry payload). */
-	async setCapacity(budget: number): Promise<RegistrationHandle> {
-		this.provider.setCapacity(budget);
-		return this.register();
-	}
-
-	/** Signal "available but at capacity" (`capacityBudget = 0`) and push it by re-registering. */
-	async signalFull(): Promise<RegistrationHandle> {
-		this.provider.signalFull();
-		return this.register();
-	}
-
-	/** Withdraw: stop renewing and send a best-effort signed tombstone so the cohort frees the record
-	 * immediately; TTL expiry is the fallback (the immediate tombstone is an optimization, not correctness). */
-	async withdraw(): Promise<void> {
-		this.provider.markWithdrawn();
-		if (this.handle !== undefined) {
-			await this.service.withdraw(this.handle);
-		}
-	}
-}
-
-/** Fallback provider TTL when neither an explicit `ttlMs` nor a `profile` is supplied (Core default). */
-const DEFAULT_PROVIDER_TTL_MS = 90_000;
+/**
+ * Matchmaking — provider manager (db-p2p, wires to the cohort-topic substrate).
+ *
+ * Drives a db-core {@link MatchmakingProvider}'s lifecycle against the participant-facing
+ * {@link CohortTopicService}: register at cohort-topic tier **T2 (functional)** with a profile-based
+ * TTL, renew to keep the record alive, and withdraw by ceasing renewal (`docs/matchmaking.md`
+ * §Provider registration).
+ *
+ * Self-throttling maps onto the substrate as follows (an honest gap surfaced for the reviewer): the
+ * cohort-topic `RenewV1` carries **no** `appPayload` and **no** `ttl` field — a renewal is a pure
+ * keep-alive touch. So a capacity change ("signal full", `capacityBudget = 0`) is realized by
+ * **re-registering** with the new signed payload (which updates the cohort record's `appState`), not
+ * by a renewal. Likewise immediate withdrawal (`RenewV1` TTL = 0 in the matchmaking doc) has no wire
+ * realization yet — {@link withdraw} stops renewing and lets the record age out by TTL. Per the
+ * §Provider self-throttling GROUNDING resolution, withdrawal is an **optimization, not correctness**,
+ * so passive TTL expiry is acceptable; an immediate-tombstone renew is a documented cohort-topic
+ * follow-on.
+ */
+
+import { Tier, providerTtlForProfile, type CohortTopicService, type MatchmakingProvider, type NodeProfile, type RegistrationHandle } from "@optimystic/db-core";
+
+/** Construction inputs for a {@link MatchmakingProviderManager}. */
+export interface MatchmakingProviderManagerOptions {
+	/** Participant-facing cohort-topic substrate API. */
+	readonly service: CohortTopicService;
+	/** The provider state/decision object this manager drives. */
+	readonly provider: MatchmakingProvider;
+	/** Provider TTL (ms). Default: derived from {@link profile} via `providerTtlForProfile`. */
+	readonly ttlMs?: number;
+	/** Node profile used to derive the TTL when {@link ttlMs} is absent (Core 90 s / Edge 60 s). */
+	readonly profile?: NodeProfile;
+}
+
+/** Wires one matchmaking provider to the cohort-topic substrate at tier T2. */
+export class MatchmakingProviderManager {
+	private readonly service: CohortTopicService;
+	private readonly provider: MatchmakingProvider;
+	private readonly ttlMs: number;
+	private handle?: RegistrationHandle;
+
+	constructor(options: MatchmakingProviderManagerOptions) {
+		this.service = options.service;
+		this.provider = options.provider;
+		this.ttlMs = options.ttlMs ?? (options.profile !== undefined ? providerTtlForProfile(options.profile) : undefined) ?? DEFAULT_PROVIDER_TTL_MS;
+	}
+
+	/** The live registration handle, or `undefined` before the first {@link register}. */
+	get registration(): RegistrationHandle | undefined {
+		return this.handle;
+	}
+
+	/** Register (or re-register) the provider at tier T2 with the current signed payload. */
+	async register(): Promise<RegistrationHandle> {
+		const appPayload = await this.provider.appPayloadBytes();
+		this.handle = await this.service.register({
+			topicId: this.provider.topicId,
+			tier: Tier.T2,
+			appPayload,
+			ttl: this.ttlMs,
+		});
+		return this.handle;
+	}
+
+	/** Run one renewal cycle (keep-alive touch). No-op before the first {@link register}. */
+	async renew(): Promise<void> {
+		if (this.handle === undefined) {
+			return;
+		}
+		await this.service.renew(this.handle);
+	}
+
+	/** Set the live capacity budget and push it by re-registering (`RenewV1` cannot carry payload). */
+	async setCapacity(budget: number): Promise<RegistrationHandle> {
+		this.provider.setCapacity(budget);
+		return this.register();
+	}
+
+	/** Signal "available but at capacity" (`capacityBudget = 0`) and push it by re-registering. */
+	async signalFull(): Promise<RegistrationHandle> {
+		this.provider.signalFull();
+		return this.register();
+	}
+
+	/** Withdraw: stop renewing and send a best-effort signed tombstone so the cohort frees the record
+	 * immediately; TTL expiry is the fallback (the immediate tombstone is an optimization, not correctness). */
+	async withdraw(): Promise<void> {
+		this.provider.markWithdrawn();
+		if (this.handle !== undefined) {
+			await this.service.withdraw(this.handle);
+		}
+	}
+}
+
+/** Fallback provider TTL when neither an explicit `ttlMs` nor a `profile` is supplied (Core default). */
+const DEFAULT_PROVIDER_TTL_MS = 90_000;

package/src/matchmaking/query-handler.ts

@@ -1,88 +1,88 @@
-/**
- * Matchmaking — cohort-side `QueryV1` handler (db-p2p, wires the substrate store to the query reply).
- *
- * `docs/matchmaking.md` §Seeker query / §Capability filter. When a seeker dials a cohort with a
- * {@link QueryV1}, the cohort returns its **locally-known direct registrations** for the topic, with the
- * capability filter applied. This handler is the thin db-p2p binding: it reads the cohort's local
- * {@link RegistrationRecord}s, decodes each one's `appState` into a provider/seeker payload, and hands
- * them to the pure db-core {@link evaluateQuery} (filter + truncation + entry building). It then
- * attaches the substrate's `topicTraffic` snapshot, the `cohortEpoch`, and the cohort **primary's**
- * single-member reply signature (NOT a threshold signature — the reply is advisory; the seeker
- * re-validates each entry's `registrationSig` via `verifyProviderEntry`).
- *
- * The handler is transport-light on purpose: the records, traffic, epoch, and signer are all injected,
- * so it unit-tests without a live libp2p stack (mock-tier e2e is a documented follow-on). The FRET host
- * supplies `records = store.listByTopic(topicId)`, `topicTraffic` from the cohort `TrafficCounters`,
- * the current `cohortEpoch`, and a `sign` bound to this node's peer key.
- */
-
-import {
-	bytesToB64url,
-	decodeMatchAppPayload,
-	evaluateQuery,
-	queryReplySigningPayload,
-	type LocalProviderRegistration,
-	type LocalSeekerRegistration,
-	type QueryReplyV1,
-	type QueryV1,
-	type RegistrationRecord,
-	type TopicTrafficV1,
-} from "@optimystic/db-core";
-import { bytesToPeerIdString } from "../cohort-topic/peer-codec.js";
-
-/** Everything the {@link handleMatchmakingQuery} needs from the cohort substrate, all injected. */
-export interface CohortQueryContext {
-	/** The cohort's local registration records for the queried topic (e.g. `store.listByTopic(topicId)`). */
-	readonly records: readonly RegistrationRecord[];
-	/** The substrate's current traffic barometer for the topic (from the cohort `TrafficCounters`). */
-	readonly topicTraffic: TopicTrafficV1;
-	/** The current cohort epoch (32 bytes). */
-	readonly cohortEpoch: Uint8Array;
-	/** Sign the canonical reply image with the cohort primary's peer key; resolves the base64url signature. */
-	readonly sign: (payload: Uint8Array) => Promise<string>;
-	/** Optional logger for records whose `appState` fails to decode (skipped, not fatal). */
-	readonly log?: (formatter: string, ...args: unknown[]) => void;
-}
-
-/** Build the advisory {@link QueryReplyV1} for `query` from the cohort's local registrations. */
-export async function handleMatchmakingQuery(query: QueryV1, ctx: CohortQueryContext): Promise<QueryReplyV1> {
-	const providers: LocalProviderRegistration[] = [];
-	const seekers: LocalSeekerRegistration[] = [];
-
-	for (const rec of ctx.records) {
-		if (rec.appState === undefined) {
-			continue;
-		}
-		const participantId = bytesToPeerIdString(rec.participantId);
-		let payload;
-		try {
-			payload = decodeMatchAppPayload(rec.appState);
-		} catch (err) {
-			// A record whose appState isn't a matchmaking payload (or is malformed) is not ours to serve;
-			// skip it rather than fail the whole reply. Logged so it is never silently swallowed.
-			ctx.log?.("matchmaking query handler: skipping undecodable record for %s: %o", participantId, err);
-			continue;
-		}
-		if (payload.kind === "match-provider") {
-			providers.push({ participantId, attachedAt: rec.attachedAt, payload });
-		} else {
-			seekers.push({ participantId, attachedAt: rec.attachedAt, payload });
-		}
-	}
-
-	const evaluated = evaluateQuery(query, providers, seekers);
-	const unsigned: Omit<QueryReplyV1, "signature"> = {
-		v: 1,
-		truncated: evaluated.truncated,
-		cohortEpoch: bytesToB64url(ctx.cohortEpoch),
-		topicTraffic: ctx.topicTraffic,
-	};
-	if (evaluated.providers !== undefined) {
-		unsigned.providers = evaluated.providers;
-	}
-	if (evaluated.seekers !== undefined) {
-		unsigned.seekers = evaluated.seekers;
-	}
-	const signature = await ctx.sign(queryReplySigningPayload(unsigned));
-	return { ...unsigned, signature };
-}
+/**
+ * Matchmaking — cohort-side `QueryV1` handler (db-p2p, wires the substrate store to the query reply).
+ *
+ * `docs/matchmaking.md` §Seeker query / §Capability filter. When a seeker dials a cohort with a
+ * {@link QueryV1}, the cohort returns its **locally-known direct registrations** for the topic, with the
+ * capability filter applied. This handler is the thin db-p2p binding: it reads the cohort's local
+ * {@link RegistrationRecord}s, decodes each one's `appState` into a provider/seeker payload, and hands
+ * them to the pure db-core {@link evaluateQuery} (filter + truncation + entry building). It then
+ * attaches the substrate's `topicTraffic` snapshot, the `cohortEpoch`, and the cohort **primary's**
+ * single-member reply signature (NOT a threshold signature — the reply is advisory; the seeker
+ * re-validates each entry's `registrationSig` via `verifyProviderEntry`).
+ *
+ * The handler is transport-light on purpose: the records, traffic, epoch, and signer are all injected,
+ * so it unit-tests without a live libp2p stack (mock-tier e2e is a documented follow-on). The FRET host
+ * supplies `records = store.listByTopic(topicId)`, `topicTraffic` from the cohort `TrafficCounters`,
+ * the current `cohortEpoch`, and a `sign` bound to this node's peer key.
+ */
+
+import {
+	bytesToB64url,
+	decodeMatchAppPayload,
+	evaluateQuery,
+	queryReplySigningPayload,
+	type LocalProviderRegistration,
+	type LocalSeekerRegistration,
+	type QueryReplyV1,
+	type QueryV1,
+	type RegistrationRecord,
+	type TopicTrafficV1,
+} from "@optimystic/db-core";
+import { bytesToPeerIdString } from "../cohort-topic/peer-codec.js";
+
+/** Everything the {@link handleMatchmakingQuery} needs from the cohort substrate, all injected. */
+export interface CohortQueryContext {
+	/** The cohort's local registration records for the queried topic (e.g. `store.listByTopic(topicId)`). */
+	readonly records: readonly RegistrationRecord[];
+	/** The substrate's current traffic barometer for the topic (from the cohort `TrafficCounters`). */
+	readonly topicTraffic: TopicTrafficV1;
+	/** The current cohort epoch (32 bytes). */
+	readonly cohortEpoch: Uint8Array;
+	/** Sign the canonical reply image with the cohort primary's peer key; resolves the base64url signature. */
+	readonly sign: (payload: Uint8Array) => Promise<string>;
+	/** Optional logger for records whose `appState` fails to decode (skipped, not fatal). */
+	readonly log?: (formatter: string, ...args: unknown[]) => void;
+}
+
+/** Build the advisory {@link QueryReplyV1} for `query` from the cohort's local registrations. */
+export async function handleMatchmakingQuery(query: QueryV1, ctx: CohortQueryContext): Promise<QueryReplyV1> {
+	const providers: LocalProviderRegistration[] = [];
+	const seekers: LocalSeekerRegistration[] = [];
+
+	for (const rec of ctx.records) {
+		if (rec.appState === undefined) {
+			continue;
+		}
+		const participantId = bytesToPeerIdString(rec.participantId);
+		let payload;
+		try {
+			payload = decodeMatchAppPayload(rec.appState);
+		} catch (err) {
+			// A record whose appState isn't a matchmaking payload (or is malformed) is not ours to serve;
+			// skip it rather than fail the whole reply. Logged so it is never silently swallowed.
+			ctx.log?.("matchmaking query handler: skipping undecodable record for %s: %o", participantId, err);
+			continue;
+		}
+		if (payload.kind === "match-provider") {
+			providers.push({ participantId, attachedAt: rec.attachedAt, payload });
+		} else {
+			seekers.push({ participantId, attachedAt: rec.attachedAt, payload });
+		}
+	}
+
+	const evaluated = evaluateQuery(query, providers, seekers);
+	const unsigned: Omit<QueryReplyV1, "signature"> = {
+		v: 1,
+		truncated: evaluated.truncated,
+		cohortEpoch: bytesToB64url(ctx.cohortEpoch),
+		topicTraffic: ctx.topicTraffic,
+	};
+	if (evaluated.providers !== undefined) {
+		unsigned.providers = evaluated.providers;
+	}
+	if (evaluated.seekers !== undefined) {
+		unsigned.seekers = evaluated.seekers;
+	}
+	const signature = await ctx.sign(queryReplySigningPayload(unsigned));
+	return { ...unsigned, signature };
+}