@optimystic/db-p2p 0.22.0 → 0.24.1

package/src/rn.ts

@@ -1,36 +1,39 @@
-export * from './cluster/client.js';
-export * from './cluster/cluster-policy.js';
-export * from './cluster/cluster-repo.js';
-export * from './cluster/service.js';
-export * from './protocol-client.js';
-export * from './repo/client.js';
-export * from './repo/cluster-coordinator.js';
-export * from './repo/coordinator-repo.js';
-export * from './repo/service.js';
-export * from './storage/block-storage.js';
-export * from './storage/raw-store-driver.js';
-export * from './storage/kv-raw-storage.js';
-export * from './storage/memory-store-driver.js';
-export * from './storage/memory-storage.js';
-export * from './storage/i-block-storage.js';
-export * from './storage/i-raw-storage.js';
-export * from './storage/struct.js';
-export * from './storage/storage-repo.js';
-export * from './storage/restoration-coordinator.js';
-export * from './storage/ring-selector.js';
-export * from './storage/storage-monitor.js';
-export * from './storage/arachnode-fret-adapter.js';
-export * from './sync/protocol.js';
-export * from './sync/client.js';
-export * from './sync/service.js';
-export * from './it-utility.js';
-export * from './libp2p-key-network.js';
-export * from './libp2p-node-rn.js';
-export * from './optimystic-node.js';
-export * from './routing/responsibility.js';
-export * from './routing/libp2p-known-peers.js';
-export * from './network/network-manager-service.js';
-export * from './network/get-network-manager.js';
-// Browser-safe peer signing seam. The rest of ./cohort-topic pulls node-heavy host.js,
-// so only peer-sig (@noble/curves + peer-id) is surfaced through the RN/browser entry.
-export * from './cohort-topic/peer-sig.js';
+export * from './cluster/client.js';
+export * from './cluster/cluster-policy.js';
+export * from './cluster/cluster-repo.js';
+export * from './cluster/service.js';
+export * from './protocol-client.js';
+export * from './repo/client.js';
+export * from './repo/cluster-coordinator.js';
+export * from './repo/coordinator-repo.js';
+export * from './repo/service.js';
+export * from './storage/block-storage.js';
+export * from './storage/raw-store-driver.js';
+export * from './storage/kv-raw-storage.js';
+export * from './storage/shared-cache-pool.js';
+export * from './storage/cached-store-driver.js';
+export * from './storage/cached-raw-storage.js';
+export * from './storage/memory-store-driver.js';
+export * from './storage/memory-storage.js';
+export * from './storage/i-block-storage.js';
+export * from './storage/i-raw-storage.js';
+export * from './storage/struct.js';
+export * from './storage/storage-repo.js';
+export * from './storage/restoration-coordinator.js';
+export * from './storage/ring-selector.js';
+export * from './storage/storage-monitor.js';
+export * from './storage/arachnode-fret-adapter.js';
+export * from './sync/protocol.js';
+export * from './sync/client.js';
+export * from './sync/service.js';
+export * from './it-utility.js';
+export * from './libp2p-key-network.js';
+export * from './libp2p-node-rn.js';
+export * from './optimystic-node.js';
+export * from './routing/responsibility.js';
+export * from './routing/libp2p-known-peers.js';
+export * from './network/network-manager-service.js';
+export * from './network/get-network-manager.js';
+// Browser-safe peer signing seam. The rest of ./cohort-topic pulls node-heavy host.js,
+// so only peer-sig (@noble/curves + peer-id) is surfaced through the RN/browser entry.
+export * from './cohort-topic/peer-sig.js';

package/src/rpc-deadline.ts

@@ -1,45 +1,45 @@
-/**
- * Per-RPC deadline knobs shared by the simple {@link ProtocolClient} subclasses
- * (cluster / sync / dispute). `dialTimeoutMs` bounds connecting; `responseTimeoutMs`
- * bounds waiting for the reply once connected (so a peer that connects then goes
- * silent throws {@link ResponseTimeoutError} instead of hanging the caller forever);
- * `signal` cancels the whole request. All optional.
- */
-export type RpcDeadlineOptions = {
-	signal?: AbortSignal;
-	dialTimeoutMs?: number;
-	responseTimeoutMs?: number;
-};
-
-/**
- * Default per-peer dial deadline. Matches `spread-on-churn.ts` `pushDialTimeoutMs`
- * (3000ms) — an unreachable peer fails the dial fast so the caller can re-pick a
- * different coordinator rather than blocking on a dead route.
- */
-export const DEFAULT_DIAL_TIMEOUT_MS = 3000;
-
-/**
- * Default per-peer response deadline. Matches `spread-on-churn.ts`
- * `pushResponseTimeoutMs` (10000ms) — a peer that connects then never writes a
- * reply is abandoned instead of hanging the caller forever.
- */
-export const DEFAULT_RESPONSE_TIMEOUT_MS = 10000;
-
-/**
- * Merge caller-supplied deadline options with the client-level defaults. An
- * explicitly-supplied value wins (including a deliberate `0`, which
- * {@link ProtocolClient.processMessage} reads as "no cap"); an absent key falls
- * back to the default so a caller that passes nothing still gets a deadline.
- * `signal` has no default — cancellation is always caller-driven.
- *
- * Unlike `BlockTransferClient` (which leaves its defaults to the owning
- * `SpreadOnChurnMonitor` config), these clients have many callers and no single
- * owning monitor, so the deadline default belongs here on the client.
- */
-export function withRpcDeadlineDefaults(options?: RpcDeadlineOptions): RpcDeadlineOptions {
-	return {
-		dialTimeoutMs: options?.dialTimeoutMs ?? DEFAULT_DIAL_TIMEOUT_MS,
-		responseTimeoutMs: options?.responseTimeoutMs ?? DEFAULT_RESPONSE_TIMEOUT_MS,
-		signal: options?.signal,
-	};
-}
+/**
+ * Per-RPC deadline knobs shared by the simple {@link ProtocolClient} subclasses
+ * (cluster / sync / dispute). `dialTimeoutMs` bounds connecting; `responseTimeoutMs`
+ * bounds waiting for the reply once connected (so a peer that connects then goes
+ * silent throws {@link ResponseTimeoutError} instead of hanging the caller forever);
+ * `signal` cancels the whole request. All optional.
+ */
+export type RpcDeadlineOptions = {
+	signal?: AbortSignal;
+	dialTimeoutMs?: number;
+	responseTimeoutMs?: number;
+};
+
+/**
+ * Default per-peer dial deadline. Matches `spread-on-churn.ts` `pushDialTimeoutMs`
+ * (3000ms) — an unreachable peer fails the dial fast so the caller can re-pick a
+ * different coordinator rather than blocking on a dead route.
+ */
+export const DEFAULT_DIAL_TIMEOUT_MS = 3000;
+
+/**
+ * Default per-peer response deadline. Matches `spread-on-churn.ts`
+ * `pushResponseTimeoutMs` (10000ms) — a peer that connects then never writes a
+ * reply is abandoned instead of hanging the caller forever.
+ */
+export const DEFAULT_RESPONSE_TIMEOUT_MS = 10000;
+
+/**
+ * Merge caller-supplied deadline options with the client-level defaults. An
+ * explicitly-supplied value wins (including a deliberate `0`, which
+ * {@link ProtocolClient.processMessage} reads as "no cap"); an absent key falls
+ * back to the default so a caller that passes nothing still gets a deadline.
+ * `signal` has no default — cancellation is always caller-driven.
+ *
+ * Unlike `BlockTransferClient` (which leaves its defaults to the owning
+ * `SpreadOnChurnMonitor` config), these clients have many callers and no single
+ * owning monitor, so the deadline default belongs here on the client.
+ */
+export function withRpcDeadlineDefaults(options?: RpcDeadlineOptions): RpcDeadlineOptions {
+	return {
+		dialTimeoutMs: options?.dialTimeoutMs ?? DEFAULT_DIAL_TIMEOUT_MS,
+		responseTimeoutMs: options?.responseTimeoutMs ?? DEFAULT_RESPONSE_TIMEOUT_MS,
+		signal: options?.signal,
+	};
+}

package/src/storage/arachnode-partition.ts

@@ -1,74 +1,74 @@
-import type { ArachnodeInfo } from './arachnode-fret-adapter.js';
-
-/**
- * An Arachnode ring partition: the first `prefixBits` bits of a hashed coordinate must equal
- * `prefixValue` for a key to fall inside it. Structurally identical to `ArachnodeInfo.partition`.
- */
-export interface RingPartition {
-	prefixBits: number;
-	prefixValue: number;
-}
-
-/**
- * Extract the first `bits` bits of a hashed coordinate as an integer (MSB-first).
- *
- * The single source of truth for the block/peer prefix comparison Arachnode uses to decide
- * responsibility. `RingSelector.calculatePartition` (peer side) and `RestorationCoordinator`
- * (block side) both route through this, so a peer's advertised partition and a block's derived
- * prefix are computed the same way — otherwise "this peer owns this block's slice" would silently
- * stop meaning what it says.
- */
-export function extractPrefix(coord: Uint8Array, bits: number): number {
-	let value = 0;
-	for (let i = 0; i < bits; i++) {
-		const byteIndex = Math.floor(i / 8);
-		const bitIndex = 7 - (i % 8);
-		const bit = (coord[byteIndex]! >> bitIndex) & 1;
-		value = (value << 1) | bit;
-	}
-	return value;
-}
-
-/**
- * Does `partition` cover the key at `coord`? Ring 0 (an undefined partition) covers the whole
- * keyspace, so it always returns true.
- */
-export function partitionCovers(partition: RingPartition | undefined, coord: Uint8Array): boolean {
-	if (!partition) {
-		return true;
-	}
-	return extractPrefix(coord, partition.prefixBits) === partition.prefixValue;
-}
-
-/**
- * Is the node described by `info` a currently-serving responsible holder for the key at `coord`?
- *
- * **Fail-toward-old-holder.** A node mid-move (`status === 'moving'`) advertises its *target*
- * `partition`, but it keeps serving its *old* range (`moveFrom`) until it releases. So a moving
- * node covers the key if EITHER its old range or its target range covers it — it is still counted
- * as a serving holder for everything it served before the move until it transitions to `active` at
- * the new ring. This is what keeps a shed key covered through Phases A–B and across a mid-handoff
- * crash. See `docs/arachnode-ring-handoff.md` § Part 3.
- */
-export function isServingHolder(info: ArachnodeInfo, coord: Uint8Array): boolean {
-	if (info.status === 'moving' && info.moveFrom) {
-		return partitionCovers(info.moveFrom.partition, coord) || partitionCovers(info.partition, coord);
-	}
-	return partitionCovers(info.partition, coord);
-}
-
-/**
- * Does the node described by `info` qualify toward *another* mover's Phase-B replication floor for
- * the key at `coord`?
- *
- * A qualifying holder must still cover the key **after its own advertised move** — i.e. its
- * *target* `partition` (the one it currently advertises) must cover it. A concurrent mover that is
- * shedding the same sub-range advertises a target that does NOT cover the key, so it is excluded:
- * two adjacent movers can never both count the other, so at most one reaches "confirmed" on the
- * shared overlap and the other rolls back. For a non-moving (`active`) node, the advertised
- * partition IS its serving range, so this reduces to plain partition coverage. See
- * `docs/arachnode-ring-handoff.md` § Part 3 (concurrent moves).
- */
-export function qualifiesForFloor(info: ArachnodeInfo, coord: Uint8Array): boolean {
-	return partitionCovers(info.partition, coord);
-}
+import type { ArachnodeInfo } from './arachnode-fret-adapter.js';
+
+/**
+ * An Arachnode ring partition: the first `prefixBits` bits of a hashed coordinate must equal
+ * `prefixValue` for a key to fall inside it. Structurally identical to `ArachnodeInfo.partition`.
+ */
+export interface RingPartition {
+	prefixBits: number;
+	prefixValue: number;
+}
+
+/**
+ * Extract the first `bits` bits of a hashed coordinate as an integer (MSB-first).
+ *
+ * The single source of truth for the block/peer prefix comparison Arachnode uses to decide
+ * responsibility. `RingSelector.calculatePartition` (peer side) and `RestorationCoordinator`
+ * (block side) both route through this, so a peer's advertised partition and a block's derived
+ * prefix are computed the same way — otherwise "this peer owns this block's slice" would silently
+ * stop meaning what it says.
+ */
+export function extractPrefix(coord: Uint8Array, bits: number): number {
+	let value = 0;
+	for (let i = 0; i < bits; i++) {
+		const byteIndex = Math.floor(i / 8);
+		const bitIndex = 7 - (i % 8);
+		const bit = (coord[byteIndex]! >> bitIndex) & 1;
+		value = (value << 1) | bit;
+	}
+	return value;
+}
+
+/**
+ * Does `partition` cover the key at `coord`? Ring 0 (an undefined partition) covers the whole
+ * keyspace, so it always returns true.
+ */
+export function partitionCovers(partition: RingPartition | undefined, coord: Uint8Array): boolean {
+	if (!partition) {
+		return true;
+	}
+	return extractPrefix(coord, partition.prefixBits) === partition.prefixValue;
+}
+
+/**
+ * Is the node described by `info` a currently-serving responsible holder for the key at `coord`?
+ *
+ * **Fail-toward-old-holder.** A node mid-move (`status === 'moving'`) advertises its *target*
+ * `partition`, but it keeps serving its *old* range (`moveFrom`) until it releases. So a moving
+ * node covers the key if EITHER its old range or its target range covers it — it is still counted
+ * as a serving holder for everything it served before the move until it transitions to `active` at
+ * the new ring. This is what keeps a shed key covered through Phases A–B and across a mid-handoff
+ * crash. See `docs/arachnode-ring-handoff.md` § Part 3.
+ */
+export function isServingHolder(info: ArachnodeInfo, coord: Uint8Array): boolean {
+	if (info.status === 'moving' && info.moveFrom) {
+		return partitionCovers(info.moveFrom.partition, coord) || partitionCovers(info.partition, coord);
+	}
+	return partitionCovers(info.partition, coord);
+}
+
+/**
+ * Does the node described by `info` qualify toward *another* mover's Phase-B replication floor for
+ * the key at `coord`?
+ *
+ * A qualifying holder must still cover the key **after its own advertised move** — i.e. its
+ * *target* `partition` (the one it currently advertises) must cover it. A concurrent mover that is
+ * shedding the same sub-range advertises a target that does NOT cover the key, so it is excluded:
+ * two adjacent movers can never both count the other, so at most one reaches "confirmed" on the
+ * shared overlap and the other rolls back. For a non-moving (`active`) node, the advertised
+ * partition IS its serving range, so this reduces to plain partition coverage. See
+ * `docs/arachnode-ring-handoff.md` § Part 3 (concurrent moves).
+ */
+export function qualifiesForFloor(info: ArachnodeInfo, coord: Uint8Array): boolean {
+	return partitionCovers(info.partition, coord);
+}

package/src/storage/cached-raw-storage.ts

@@ -0,0 +1,180 @@
+import type { BlockId, ActionId } from "@optimystic/db-core";
+import type { IRawStorage } from "./i-raw-storage.js";
+import type { RawStoreDriver } from "./raw-store-driver.js";
+import { KvRawStorage } from "./kv-raw-storage.js";
+import { CachedStoreDriver } from "./cached-store-driver.js";
+import type { SharedCachePool } from "./shared-cache-pool.js";
+import { encodeJson, decodeJson, encodeActionId, decodeActionId } from "./raw-store-codec.js";
+
+/**
+ * Presents a plain {@link IRawStorage} as a {@link RawStoreDriver}, so the
+ * {@link CachedStoreDriver} (and the `KvRawStorage` kernel above it) can wrap a backend
+ * that does NOT expose its driver — the composition {@link CachedRawStorage} uses.
+ *
+ * Every value crossing this adapter is re-encoded to bytes on read and re-decoded on
+ * write, on top of whatever (de)serialization the inner storage does itself. For a
+ * kernel-backed inner storage that is a double codec pass per COLD miss — cache hits
+ * never reach this adapter. Wrapping the backend's `RawStoreDriver` directly with
+ * `CachedStoreDriver` avoids the double pass entirely; prefer that when the driver is
+ * reachable, and this adapter when only the `IRawStorage` surface is.
+ */
+export class RawStorageDriverAdapter implements RawStoreDriver {
+	/**
+	 * Optional passthroughs wired only when the inner storage provides them, mirroring
+	 * `KvRawStorage`'s constructor: feature-detection above must observe the inner
+	 * storage's true capability. `IRawStorage` has no `close`/`approximateBytesUsed`
+	 * driver names — they map from `listBlockIds`/`getApproximateBytesUsed`.
+	 */
+	listBlockIds?: () => AsyncIterable<BlockId>;
+	approximateBytesUsed?: () => Promise<number>;
+
+	constructor(private readonly inner: IRawStorage) {
+		if (inner.listBlockIds) {
+			this.listBlockIds = () => inner.listBlockIds!();
+		}
+		if (inner.getApproximateBytesUsed) {
+			this.approximateBytesUsed = () => inner.getApproximateBytesUsed!();
+		}
+	}
+
+	// --- metadata ---
+
+	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
+		const meta = await this.inner.getMetadata(blockId);
+		return meta === undefined ? undefined : encodeJson(meta);
+	}
+
+	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
+		await this.inner.saveMetadata(blockId, decodeJson(value));
+	}
+
+	// --- revisions ---
+
+	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
+		const actionId = await this.inner.getRevision(blockId, rev);
+		return actionId === undefined ? undefined : encodeActionId(actionId);
+	}
+
+	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
+		await this.inner.saveRevision(blockId, rev, decodeActionId(value));
+	}
+
+	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
+		// `listRevisions` derives direction from bound order (start > end ⇒ descending);
+		// map (lo, hi, reverse) back onto that. Drain before yielding — the inner
+		// iterable already drained per its own contract, but the consumer's awaits must
+		// not straddle OUR loop over it either.
+		const startRev = reverse ? hi : lo;
+		const endRev = reverse ? lo : hi;
+		const drained: [number, Uint8Array][] = [];
+		for await (const { rev, actionId } of this.inner.listRevisions(blockId, startRev, endRev)) {
+			drained.push([rev, encodeActionId(actionId)]);
+		}
+		yield* drained;
+	}
+
+	// --- pending ---
+
+	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		const transform = await this.inner.getPendingTransaction(blockId, actionId);
+		return transform === undefined ? undefined : encodeJson(transform);
+	}
+
+	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.inner.savePendingTransaction(blockId, actionId, decodeJson(value));
+	}
+
+	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.inner.deletePendingTransaction(blockId, actionId);
+	}
+
+	async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
+		const drained: ActionId[] = [];
+		for await (const id of this.inner.listPendingTransactions(blockId)) {
+			drained.push(id);
+		}
+		yield* drained;
+	}
+
+	// --- transactions ---
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		const transform = await this.inner.getTransaction(blockId, actionId);
+		return transform === undefined ? undefined : encodeJson(transform);
+	}
+
+	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.inner.saveTransaction(blockId, actionId, decodeJson(value));
+	}
+
+	// --- materialized ---
+
+	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		const block = await this.inner.getMaterializedBlock(blockId, actionId);
+		return block === undefined ? undefined : encodeJson(block);
+	}
+
+	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.inner.saveMaterializedBlock(blockId, actionId, decodeJson(value));
+	}
+
+	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.inner.saveMaterializedBlock(blockId, actionId, undefined);
+	}
+
+	// --- promote ---
+
+	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.inner.promotePendingTransaction(blockId, actionId);
+	}
+}
+
+/**
+ * Write-through cached view over a plain {@link IRawStorage} — the wrapper form for a
+ * backend whose {@link RawStoreDriver} is not reachable. Composition:
+ *
+ * ```
+ * KvRawStorage kernel → CachedStoreDriver → RawStorageDriverAdapter → inner IRawStorage
+ * ```
+ *
+ * All caching semantics (write-through coherence, proven-absence negatives, list
+ * completeness, promote mirroring) live in {@link CachedStoreDriver}; see its class doc
+ * and docs/storage.md "Write-through raw-storage cache" for the invariants this relies
+ * on — including the single-process-owner precondition.
+ *
+ * Prefer wrapping the backend's driver directly — `new KvRawStorage(new
+ * CachedStoreDriver(driver))` — when the driver is available: it skips this adapter's
+ * extra codec pass on cold misses. Do not wrap `MemoryRawStorage` in production wiring
+ * (already in-memory; the cache adds bookkeeping with nothing to save) — tests do, to
+ * prove semantics are identical through the full composition.
+ *
+ * By default the cache joins the process-wide shared pool (`defaultCachePool()`), so
+ * every workspace's cache competes inside ONE memory budget; pass a specific
+ * {@link SharedCachePool} only for isolation (tests) or host-specific sizing, and a
+ * `label` to make this store recognizable in the pool's `stats()`.
+ */
+export class CachedRawStorage extends KvRawStorage {
+	private readonly cacheDriver: CachedStoreDriver;
+
+	constructor(inner: IRawStorage, pool?: SharedCachePool, label?: string) {
+		const cacheDriver = new CachedStoreDriver(new RawStorageDriverAdapter(inner), pool, label);
+		super(cacheDriver);
+		this.cacheDriver = cacheDriver;
+	}
+
+	/** Drop every cached entry. Always safe — the cache is clean (write-through, never write-behind). */
+	clearCache(): void {
+		this.cacheDriver.clear();
+	}
+
+	/**
+	 * Release this storage's cache registration with the shared pool (drops all entries,
+	 * retires the store id). Call when the workspace departs; a skipped dispose leaks only
+	 * cold entries the pool will evict under pressure, but the polite release keeps a
+	 * long-lived process's occupancy honest. `IRawStorage` itself has no close, so this is
+	 * the wrapper's own lifecycle method.
+	 */
+	async dispose(): Promise<void> {
+		await this.cacheDriver.close();
+	}
+}