@optimystic/db-p2p 0.13.4 → 0.14.0

package/src/reactivity/notify-transport.ts

@@ -0,0 +1,144 @@
+/**
+ * Reactivity notify transport — the one-way `NotificationV1` delivery primitive (`docs/reactivity.md`
+ * §Propagation).
+ *
+ * Unlike the cohort-gossip transport (which *broadcasts* a frame to a FRET-assembled cohort), notify is
+ * **unicast**: the fan-out orchestration above this layer (the `reactivity-forwarder-host` ticket) decides
+ * who to dial and calls {@link ReactivityNotifyTransport.send} once per named target. This module owns only
+ * the framing + dial + inbound-decode plumbing — no fan-out, no role decision, no gossip.
+ *
+ * The db-core `NotificationV1` codec ({@link encodeNotificationV1} / {@link decodeNotificationV1}) does the
+ * length-prefixed JSON framing; this layer rides one self-delimiting frame each way over the notify
+ * protocol, reusing the cohort-topic {@link sendOneWay} / {@link readAllBounded} stream lifecycle so the
+ * two protocol families behave identically on the wire.
+ *
+ * Failure isolation is the load-bearing property: notify is fire-and-forget and hint-only, so a dead /
+ * unreachable target's rejection is swallowed (logged), never propagated to the caller's fan-out loop or a
+ * commit. There is no reply frame — a handler that tried to send one back would desync the dialer's
+ * {@link sendOneWay} (which closes after send).
+ */
+
+import type { NotificationV1, PeerRef } from "@optimystic/db-core";
+import { encodeNotificationV1, decodeNotificationV1 } from "@optimystic/db-core";
+import type { Libp2p } from "libp2p";
+import type { Connection, Stream } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+import { readAllBounded } from "p2p-fret";
+import { peerIdToBytes } from "../cohort-topic/peer-codec.js";
+import { sendOneWay, DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
+import { PROTOCOL_REACTIVITY_NOTIFY } from "./protocols.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-notify");
+
+/** One-way `NotificationV1` transport: unicast send, inbound subscribe, and the host's deliver seam. */
+export interface ReactivityNotifyTransport {
+	/**
+	 * Frame `n` ({@link encodeNotificationV1}) and dial `target` (peer-id string) over the notify protocol.
+	 * Fire-and-forget, failure-isolated: a dead/unreachable target's rejection is swallowed (logged), never
+	 * propagated to the caller's fan-out loop.
+	 */
+	send(target: string, n: NotificationV1): Promise<void>;
+	/** Subscribe to inbound notifications (after decode); returns an unsubscribe handle. */
+	onNotification(handler: (from: PeerRef, n: NotificationV1) => void): () => void;
+	/** Feed an inbound notify frame (called by the host's notify protocol handler). */
+	deliver(fromPeerId: string, frame: Uint8Array): void;
+}
+
+/** Construction options for {@link Libp2pReactivityNotifyTransport}. */
+export interface ReactivityNotifyTransportOptions {
+	/** Notify protocol ID; default {@link PROTOCOL_REACTIVITY_NOTIFY}. */
+	readonly notifyProtocol?: string;
+	/** Per-frame ceiling for the inbound decode bound. Default {@link DEFAULT_STREAM_MAX_BYTES}. */
+	readonly maxBytes?: number;
+	/** This node's peer-id string; when set, {@link Libp2pReactivityNotifyTransport.send} never dials self. */
+	readonly selfPeerId?: string;
+}
+
+/**
+ * libp2p-backed {@link ReactivityNotifyTransport}: {@link send} frames + dials a single target over
+ * `/optimystic/reactivity/1.0.0/notify` (fire-and-forget, failure-isolated); inbound frames arrive through
+ * the host's notify protocol handler ({@link registerNotifyHandler}), which calls {@link deliver}.
+ * Subscribers registered via {@link onNotification} see every decoded notification.
+ */
+export class Libp2pReactivityNotifyTransport implements ReactivityNotifyTransport {
+	private readonly handlers = new Set<(from: PeerRef, n: NotificationV1) => void>();
+	private readonly notifyProtocol: string;
+	private readonly maxBytes: number;
+	private readonly selfPeerId?: string;
+
+	constructor(private readonly node: Libp2p, options: ReactivityNotifyTransportOptions = {}) {
+		this.notifyProtocol = options.notifyProtocol ?? PROTOCOL_REACTIVITY_NOTIFY;
+		this.maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+		this.selfPeerId = options.selfPeerId;
+	}
+
+	send(target: string, n: NotificationV1): Promise<void> {
+		if (this.selfPeerId !== undefined && target === this.selfPeerId) {
+			// Never dial self; a co-located subscriber is delivered in-process by the forwarder host.
+			return Promise.resolve();
+		}
+		try {
+			const frame = encodeNotificationV1(n);
+			return sendOneWay(this.node, peerIdFromString(target), this.notifyProtocol, frame).catch((err: unknown) => {
+				// Best-effort, failure-isolated: a dead/unreachable target must not break the fan-out or a commit.
+				log("send to %s failed (swallowed): %o", target, err);
+			});
+		} catch (err) {
+			// Malformed notification or peer-id string: log + drop, never reject (reactivity is hint-only).
+			log("dropped a send to %s: %o", target, err);
+			return Promise.resolve();
+		}
+	}
+
+	onNotification(handler: (from: PeerRef, n: NotificationV1) => void): () => void {
+		this.handlers.add(handler);
+		return () => this.handlers.delete(handler);
+	}
+
+	/** Feed an inbound notify frame (called by the host's notify protocol handler). */
+	deliver(fromPeerId: string, frame: Uint8Array): void {
+		let n: NotificationV1;
+		try {
+			n = decodeNotificationV1(frame, this.maxBytes);
+		} catch (err) {
+			// A malformed frame must never throw out of a stream handler: log + drop.
+			log("dropped an undecodable inbound frame from %s: %o", fromPeerId, err);
+			return;
+		}
+		const from: PeerRef = { id: peerIdToBytes(fromPeerId) };
+		for (const handler of this.handlers) {
+			handler(from, n);
+		}
+	}
+}
+
+/**
+ * Register the inbound notify protocol handler: read one bounded frame and hand it to
+ * {@link ReactivityNotifyTransport.deliver}, then close. One-way — no reply frame (notify is strictly
+ * fire-and-forget; a reply would desync the dialer's {@link sendOneWay}). Mirrors the cohort-topic
+ * one-way handlers: a read error aborts the stream, and {@link ReactivityNotifyTransport.deliver}
+ * swallows a decode failure, so the handler never throws on the stream.
+ */
+export function registerNotifyHandler(
+	node: Libp2p,
+	protocol: string,
+	transport: ReactivityNotifyTransport,
+	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);
+				transport.deliver(connection.remotePeer.toString(), frame);
+				await stream.close();
+			} catch {
+				try {
+					stream.abort(new Error("reactivity notify stream handler error"));
+				} catch {
+					/* already aborted */
+				}
+			}
+		})();
+	});
+}

package/src/reactivity/origination-manager.ts

@@ -0,0 +1,192 @@
+/**
+ * Reactivity — notification origination manager (db-p2p, wires to the cohort-topic substrate).
+ *
+ * Installs the substrate's {@link CohortTopicService.onLocalCommit} origination hook so a commit landing
+ * on a node that is a tail-cohort member for the collection's reactivity topic emits a signed
+ * {@link NotificationV1} (`docs/reactivity.md` §Notification origination). The local-change-notifier
+ * bridge ([local-change-notifier-bridge]) supplies the {@link CollectionChangeEvent} + pass-through
+ * {@link CommitCert}; this manager calls db-core's {@link buildNotificationV1} (which reuses the commit
+ * cert's threshold signature **unchanged** — reactivity never re-signs) and hands the result to the
+ * injected {@link emit} transport, which fans it out to direct subscribers and child cohorts.
+ *
+ * The cluster keys its commit votes by **peer-id string**; the cohort-topic membership verifier compares
+ * signers as the member-id **bytes** (UTF-8 of the peer-id string, base64url on the wire). So this
+ * manager supplies `encodeSigner = s ⇒ bytesToB64url(peerIdToBytes(s))`, the inverse the subscriber's
+ * {@link createNotificationVerifier} default (`b64urlToBytes`) consumes — closing the encoding loop end
+ * to end.
+ */
+
+import {
+	buildNotificationV1,
+	bytesToB64url,
+	b64urlToBytes,
+	reactivityTopicId,
+	BlockFillTracker,
+	type BlockFillTrackerInit,
+	type CohortTopicService,
+	type CollectionChangeEvent,
+	type CommitCert,
+	type NotificationV1,
+	type RotationHintV1,
+} from "@optimystic/db-core";
+import { peerIdToBytes } from "../cohort-topic/peer-codec.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("reactivity-origination");
+
+/** Per-collection origination context the manager resolves at emit time. */
+export interface OriginationCollectionContext {
+	/** Current tail block id the reactivity topic is anchored on (raw bytes). */
+	readonly tailId: Uint8Array;
+	/** Per-collection delta budget (bytes); `0` ⇒ omit `delta` (Edge / collection declines deltas). */
+	readonly deltaMaxBytes: number;
+	/** Optional bounded delta to attach (raw bytes). */
+	readonly delta?: Uint8Array;
+	/** Optional tail-rotation pre-announce (rotation ticket supplies it). */
+	readonly rotationHint?: RotationHintV1;
+}
+
+/** Construction inputs for a {@link ReactivityOriginationManager}. */
+export interface ReactivityOriginationManagerOptions {
+	/** The cohort-topic substrate whose `onLocalCommit` hook this manager installs. */
+	readonly service: CohortTopicService;
+	/**
+	 * Resolve the per-collection origination context (tail id, delta budget) for a change event. Returns
+	 * `undefined` to skip origination for this collection (e.g. this node is not the tail primary for it).
+	 */
+	readonly resolveContext: (event: CollectionChangeEvent) => OriginationCollectionContext | undefined;
+	/** Fan the built notification out to direct subscribers and child cohorts (the reactivity transport). */
+	readonly emit: (notification: NotificationV1) => void;
+	/**
+	 * Start the **outgoing** tail's drain when this manager observes a collection's tail id **change**
+	 * between commits (the authoritative, observable live-node rotation signal — the pre-announce
+	 * `rotationHint{ newTailId }` cannot be built on a live node because the successor tail id is not knowable
+	 * at the filling commit; see `docs/reactivity.md` §Tail rotation and the `6.5-block-id-derivation` gate).
+	 * The node binds this to {@link import("./forwarder-host.js").ReactivityForwarderHost.markRotated} so the
+	 * old cohort's recover serve begins redirecting. `oldTopicId` is the **previous** tail's reactivity topic
+	 * id (`reactivityTopicId` over the resolved tail bytes — the SAME encoding a subscriber subscribes under).
+	 * Absent ⇒ origination is unchanged (rotation observation is inert), preserving existing callers/tests.
+	 */
+	readonly markRotated?: (oldTopicId: Uint8Array, redirect: { newTailId: string; effectiveAtRevision: number }, now: number) => void;
+	/**
+	 * Per-collection {@link BlockFillTracker} tuning for the anticipatory **warm-up** signal. The warm-up is
+	 * best-effort and **signal-only** on a live node (the next `tailId` is not knowable, so no successor coord
+	 * is fabricated — the bias is logged, never acted on; `docs/reactivity.md` §Anticipatory warm-up). Defaults
+	 * to the db-core block-fill defaults.
+	 */
+	readonly blockFill?: BlockFillTrackerInit;
+	/** Wall clock (unix ms) stamped on each notification. Default `Date.now`. */
+	readonly clock?: () => number;
+}
+
+/** Installs and drives the reactivity origination hook on a {@link CohortTopicService}. */
+export class ReactivityOriginationManager {
+	private readonly service: CohortTopicService;
+	private readonly resolveContext: (event: CollectionChangeEvent) => OriginationCollectionContext | undefined;
+	private readonly emit: (notification: NotificationV1) => void;
+	private readonly markRotated?: (oldTopicId: Uint8Array, redirect: { newTailId: string; effectiveAtRevision: number }, now: number) => void;
+	private readonly blockFill?: BlockFillTrackerInit;
+	private readonly clock: () => number;
+
+	/** Last-seen reactivity tail anchor (base64url of the resolved tail bytes) per collection — the rotation signal. */
+	private readonly lastSeenTail = new Map<string, string>();
+	/** Per-collection block-fill tracker driving the anticipatory warm-up signal (signal-only on a live node). */
+	private readonly fillTrackers = new Map<string, BlockFillTracker>();
+
+	constructor(options: ReactivityOriginationManagerOptions) {
+		this.service = options.service;
+		this.resolveContext = options.resolveContext;
+		this.emit = options.emit;
+		this.markRotated = options.markRotated;
+		this.blockFill = options.blockFill;
+		this.clock = options.clock ?? ((): number => Date.now());
+	}
+
+	/** Install the origination hook (overwrites any prior `onLocalCommit`). */
+	install(): void {
+		this.service.onLocalCommit = (event, commitCert): void => this.originate(event, commitCert);
+	}
+
+	/** Build + emit the notification for one committed change; isolates throws so commit is never broken. */
+	private originate(event: CollectionChangeEvent, commitCert: CommitCert): void {
+		try {
+			const ctx = this.resolveContext(event);
+			if (ctx === undefined) {
+				return; // not the origination point for this collection (tail-less / non-member)
+			}
+			// Observe the tail (rotation detection + block-fill warm-up) BEFORE emit, fully isolated so neither
+			// ever blocks the notification — the delivery-critical path.
+			this.observeTail(event, ctx);
+			const notification = buildNotificationV1(event, commitCert, {
+				tailId: bytesToB64url(ctx.tailId),
+				timestamp: this.clock(),
+				deltaMaxBytes: ctx.deltaMaxBytes,
+				delta: ctx.delta,
+				rotationHint: ctx.rotationHint,
+				encodeSigner: (s) => bytesToB64url(peerIdToBytes(s)),
+			});
+			this.emit(notification);
+		} catch (err) {
+			log("origination failed for collection=%s rev=%d: %o", event.collectionId, event.rev, err);
+		}
+	}
+
+	/**
+	 * Track the collection's reactivity tail and drive the rotation + warm-up signals. Isolated so a fault
+	 * here never blocks the notification emit. Only reached for commits this node originates (a defined `ctx`),
+	 * so a tail-less (read-driven) commit never records or clears the last-seen tail (the early-return holds).
+	 */
+	private observeTail(event: CollectionChangeEvent, ctx: OriginationCollectionContext): void {
+		try {
+			this.trackBlockFill(event);
+			this.detectTailRotation(event, ctx);
+		} catch (err) {
+			log("rotation/warm-up observation failed for collection=%s rev=%d (isolated): %o", event.collectionId, event.rev, err);
+		}
+	}
+
+	/**
+	 * Feed the per-collection {@link BlockFillTracker} one commit. The `warmup` signal is **best-effort and
+	 * signal-only** on a live node: the next `tailId` is not knowable (block ids are random until
+	 * `6.5-block-id-derivation`), so the anticipatory pre-dial bias is logged, never fabricated into a
+	 * successor coord (`docs/reactivity.md` §Anticipatory warm-up). The `filling` signal cannot pre-announce a
+	 * hint on a live node for the same reason — it is logged only.
+	 */
+	private trackBlockFill(event: CollectionChangeEvent): void {
+		const key = event.collectionId;
+		let tracker = this.fillTrackers.get(key);
+		if (tracker === undefined) {
+			tracker = new BlockFillTracker(this.blockFill);
+			this.fillTrackers.set(key, tracker);
+		}
+		const signal = tracker.onCommit();
+		if (signal.kind === "warmup") {
+			log("block-fill warm-up for collection=%s (%d committed, %d remaining) — anticipatory pre-dial is signal-only on a live node (successor tail not knowable; gated on 6.5-block-id-derivation)", key, signal.count, signal.remaining);
+		} else if (signal.kind === "filling") {
+			log("block-fill filling commit for collection=%s (%d committed) — no live pre-announce (successor tail id not knowable; rotation observed on the next commit's tail-id change)", key, signal.count);
+		}
+	}
+
+	/**
+	 * Detect a tail rotation by comparing the resolved tail anchor against the last-seen one for the
+	 * collection. The first commit records the baseline (no rotation). On a **change**, the previous tail's
+	 * reactivity topic has rotated to this one: fire {@link markRotated} for the OLD topic so the old cohort's
+	 * recover serve begins redirecting to the new tree.
+	 *
+	 * **Encoding contract.** `ctx.tailId` is the reactivity tail anchor bytes the node resolved
+	 * (`reactivityTailBytes(event.tailId)` in production — the SAME utf8 encoding origination's membership gate
+	 * and a subscriber's `reactivityTopicId(reactivityTailBytes(tail))` use, NOT the double-hashing
+	 * `blockIdToBytes`). So `oldTopicId = reactivityTopicId(oldAnchorBytes)` is byte-identical to the topic a
+	 * subscriber subscribed under — a mismatch would silently never redirect.
+	 */
+	private detectTailRotation(event: CollectionChangeEvent, ctx: OriginationCollectionContext): void {
+		const key = event.collectionId;
+		const newTailB64 = bytesToB64url(ctx.tailId);
+		const lastTailB64 = this.lastSeenTail.get(key);
+		if (lastTailB64 !== undefined && lastTailB64 !== newTailB64) {
+			const oldTopicId = reactivityTopicId(b64urlToBytes(lastTailB64));
+			this.markRotated?.(oldTopicId, { newTailId: newTailB64, effectiveAtRevision: event.rev }, this.clock());
+		}
+		this.lastSeenTail.set(key, newTailB64);
+	}
+}

package/src/reactivity/protocols.ts

@@ -0,0 +1,61 @@
+/**
+ * Reactivity libp2p protocol IDs (`docs/reactivity.md` §Propagation / §Notification origination).
+ *
+ * The reactivity family rides the same FRET/libp2p node as the cohort-topic substrate it is layered on:
+ *
+ * - `notify`            — `NotificationV1` fan-out down the reactivity tree (one-way, fire-and-forget).
+ * - `push-state-gossip` — `PushStateGossipV1` intra-cohort push-state convergence (one-way). Declared
+ *                         here so one place owns the family; the `reactivity-pushstate-gossip` ticket
+ *                         consumes it.
+ * - `recover`           — `RecoverRequestV1`/`RecoverReplyV1` backfill/resume recovery RPC
+ *                         (request-reply, one frame each way). Consumed by `reactivity-recover-rpc-transport`.
+ *
+ * The default (network-agnostic) IDs omit the network segment; {@link makeReactivityProtocols} mirrors
+ * FRET's `makeProtocols(networkName)` so a named network namespaces its reactivity protocols the same way
+ * FRET namespaces its routing protocols (and the cohort-topic family namespaces via
+ * {@link import("../cohort-topic/protocols.js").makeCohortTopicProtocols}).
+ */
+
+/** Base path for the reactivity protocol family. */
+export const REACTIVITY_BASE = "/optimystic/reactivity/1.0.0" as const;
+
+/** `NotificationV1` — change-notification fan-out down the reactivity tree (one-way). */
+export const PROTOCOL_REACTIVITY_NOTIFY = `${REACTIVITY_BASE}/notify` as const;
+/** `PushStateGossipV1` — intra-cohort push-state convergence (one-way) [used by reactivity-pushstate-gossip]. */
+export const PROTOCOL_REACTIVITY_PUSH_STATE_GOSSIP = `${REACTIVITY_BASE}/push-state-gossip` as const;
+/** `RecoverRequestV1`/`RecoverReplyV1` — backfill/resume recovery RPC (request-reply) [used by reactivity-recover-rpc-transport]. */
+export const PROTOCOL_REACTIVITY_RECOVER = `${REACTIVITY_BASE}/recover` as const;
+
+/** The reactivity protocol IDs in registration order. */
+export interface ReactivityProtocols {
+	readonly notify: string;
+	readonly pushStateGossip: string;
+	readonly recover: string;
+}
+
+/** Default (network-agnostic) protocol IDs, matching `docs/reactivity.md`. */
+export const DEFAULT_REACTIVITY_PROTOCOLS: ReactivityProtocols = {
+	notify: PROTOCOL_REACTIVITY_NOTIFY,
+	pushStateGossip: PROTOCOL_REACTIVITY_PUSH_STATE_GOSSIP,
+	recover: PROTOCOL_REACTIVITY_RECOVER,
+};
+
+/**
+ * Namespaced reactivity 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_REACTIVITY_PROTOCOLS}: the canonical, network-agnostic IDs omit the segment entirely
+ * (`/optimystic/reactivity/1.0.0/...`); use those unless you need per-network namespacing.
+ */
+export function makeReactivityProtocols(networkName = "default"): ReactivityProtocols {
+	const base = `/optimystic/${networkName}/reactivity/1.0.0`;
+	return {
+		notify: `${base}/notify`,
+		pushStateGossip: `${base}/push-state-gossip`,
+		recover: `${base}/recover`,
+	};
+}
+
+/** All reactivity protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
+export function reactivityProtocolList(p: ReactivityProtocols): string[] {
+	return [p.notify, p.pushStateGossip, p.recover];
+}