@optimystic/db-p2p 0.0.1

package/src/storage/storage-repo.ts

@@ -0,0 +1,320 @@
+import type {
+	IRepo, MessageOptions, BlockId, CommitRequest, CommitResult, GetBlockResults, PendRequest, PendResult, ActionBlocks,
+	ActionId, BlockGets, ActionPending, PendSuccess, ActionTransform, ActionTransforms,
+	Transforms,
+	GetBlockResult,
+	PendValidationHook
+} from "@optimystic/db-core";
+import {
+	Latches, transformForBlockId, applyTransform, groupBy, concatTransform, emptyTransforms,
+	blockIdsForTransforms, transformsFromTransform
+} from "@optimystic/db-core";
+import { asyncIteratorToArray } from "../it-utility.js";
+import type { IBlockStorage } from "./i-block-storage.js";
+
+export type StorageRepoOptions = {
+	/** Optional hook to validate transactions in PendRequests */
+	validatePend?: PendValidationHook;
+};
+
+export class StorageRepo implements IRepo {
+	private readonly validatePend?: PendValidationHook;
+
+	constructor(
+		private readonly createBlockStorage: (blockId: BlockId) => IBlockStorage,
+		options?: StorageRepoOptions
+	) {
+		this.validatePend = options?.validatePend;
+	}
+
+	async get({ blockIds, context }: BlockGets, options?: MessageOptions): Promise<GetBlockResults> {
+		const distinctBlockIds = Array.from(new Set(blockIds));
+		const results = await Promise.all(distinctBlockIds.map(async (blockId) => {
+			const blockStorage = this.createBlockStorage(blockId);
+
+			// Ensure that all outstanding transactions in the context are committed
+			if (context) {
+				const latest = await blockStorage.getLatest();
+				const missing = latest
+					? context.committed.filter(c => c.rev > latest.rev)
+					: context.committed;
+				for (const { actionId, rev } of missing.sort((a, b) => a.rev - b.rev)) {
+					const pending = await blockStorage.getPendingTransaction(actionId);
+					if (pending) {
+						await this.internalCommit(blockId, actionId, rev, blockStorage);
+					}
+				}
+			}
+
+			const blockRev = await blockStorage.getBlock(context?.rev);
+			if (!blockRev) {
+				return [blockId, { state: {} } as GetBlockResult];
+			}
+
+			// Include pending action if requested
+			if (context?.actionId !== undefined) {
+				const pendingTransform = await blockStorage.getPendingTransaction(context.actionId);
+				if (!pendingTransform) {
+					throw new Error(`Pending action ${context.actionId} not found`);
+				}
+				const block = applyTransform(blockRev.block, pendingTransform);
+				return [blockId, {
+					block,
+					state: {
+						latest: await blockStorage.getLatest(),
+						pendings: [context.actionId]
+					}
+				}];
+			}
+
+			const pendings = await asyncIteratorToArray(blockStorage.listPendingTransactions());
+			return [blockId, {
+				block: blockRev.block,
+				state: {
+					latest: await blockStorage.getLatest(),
+					pendings
+				}
+			}];
+		}));
+		return Object.fromEntries(results);
+	}
+
+	async pend(request: PendRequest, _options?: MessageOptions): Promise<PendResult> {
+		// Validate transaction if present and validation hook is configured
+		if (this.validatePend && request.transaction && request.operationsHash) {
+			const validationResult = await this.validatePend(request.transaction, request.operationsHash);
+			if (!validationResult.valid) {
+				return {
+					success: false,
+					reason: validationResult.reason ?? 'Transaction validation failed'
+				};
+			}
+		}
+
+		const blockIds = blockIdsForTransforms(request.transforms);
+		const pendings: ActionPending[] = [];
+		const missing: ActionTransforms[] = [];
+
+		// Potential race condition: A concurrent commit operation could complete
+		// between the conflict checks (latest.rev, listPendingTransactions) and the
+		// savePendingTransaction call below. This pend operation might succeed based on
+		// stale information, but the subsequent commit for this pend would likely
+		// fail correctly later if a conflict arose. Locking here could make the initial
+		// check more accurate but adds overhead. The current approach prioritizes
+		// letting the commit be the final arbiter.
+		for (const blockId of blockIds) {
+			const blockStorage = this.createBlockStorage(blockId);
+			const transforms = transformForBlockId(request.transforms, blockId);
+
+			// First handle any pending actions
+			const pending = await asyncIteratorToArray(blockStorage.listPendingTransactions());
+			pendings.push(...pending.map(actionId => ({ blockId, actionId })));
+
+			// Handle any conflicting revisions
+			if (request.rev !== undefined || transforms.insert) {
+				const latest = await blockStorage.getLatest();
+				if (latest && latest.rev >= (request.rev ?? 0)) {
+					const transforms = await asyncIteratorToArray(blockStorage.listRevisions(request.rev ?? 0, latest.rev));
+					for (const actionRev of transforms) {
+						const transform = await blockStorage.getTransaction(actionRev.actionId);
+						if (!transform) {
+							throw new Error(`Missing action ${actionRev.actionId} for block ${blockId}`);
+						}
+						missing.push({
+							actionId: actionRev.actionId,
+							rev: actionRev.rev,
+							transforms: transformsFromTransform(transform, blockId)
+						});
+					}
+				}
+			}
+		}
+
+		if (missing.length) {
+			return {
+				success: false,
+				missing
+			};
+		}
+
+		if (pendings.length > 0) {
+			if (request.policy === 'f') {	// Fail on pending actions
+				return { success: false, pending: pendings };
+			} else if (request.policy === 'r') {	// Return populated pending actions
+				return {
+					success: false,
+					pending: await Promise.all(pendings.map(async action => {
+						const blockStorage = this.createBlockStorage(action.blockId);
+						return {
+							blockId: action.blockId,
+							actionId: action.actionId,
+							transform: (await blockStorage.getPendingTransaction(action.actionId))
+								?? (await blockStorage.getTransaction(action.actionId))!	// Possible that since enumeration, the action has been promoted
+						}
+					}))
+				};
+			}
+		}
+
+
+		// Simultaneously save pending action for each block
+		// Note: that this is not atomic, after we checked for conflicts and pending actions
+		// new pending or committed actions may have been added.  This is okay, because
+		// this check during pend is conservative.
+		await Promise.all(blockIds.map(blockId => {
+			const blockStorage = this.createBlockStorage(blockId);
+			const blockTransform = transformForBlockId(request.transforms, blockId);
+			return blockStorage.savePendingTransaction(request.actionId, blockTransform);
+		}));
+
+		return {
+			success: true,
+			pending: pendings,
+			blockIds
+		} as PendSuccess;
+	}
+
+	async cancel(actionRef: ActionBlocks, _options?: MessageOptions): Promise<void> {
+		await Promise.all(actionRef.blockIds.map(blockId => {
+			const blockStorage = this.createBlockStorage(blockId);
+			return blockStorage.deletePendingTransaction(actionRef.actionId);
+		}));
+	}
+
+	async commit(request: CommitRequest, options?: MessageOptions): Promise<CommitResult> {
+		const uniqueBlockIds = Array.from(new Set(request.blockIds)).sort();
+		const releases: (() => void)[] = [];
+
+		try {
+			// Acquire locks sequentially based on sorted IDs to prevent deadlocks
+			for (const id of uniqueBlockIds) {
+				const lockId = `StorageRepo.commit:${id}`;
+				const release = await Latches.acquire(lockId);
+				releases.push(release);
+			}
+
+			// --- Start of Critical Section ---
+
+			const blockStorages = request.blockIds.map(blockId => ({
+				blockId,
+				storage: this.createBlockStorage(blockId)
+			}));
+
+			// Check for stale revisions and collect missing actions
+			const missedCommits: { blockId: BlockId, transforms: ActionTransform[] }[] = [];
+			for (const { blockId, storage } of blockStorages) {
+				const latest = await storage.getLatest();
+				if (latest && latest.rev >= request.rev) {
+					const transforms: ActionTransform[] = [];
+					for await (const actionRev of storage.listRevisions(request.rev, latest.rev)) {
+						const transform = await storage.getTransaction(actionRev.actionId);
+						if (!transform) {
+							throw new Error(`Missing action ${actionRev.actionId} for block ${blockId}`);
+						}
+						transforms.push({
+							actionId: actionRev.actionId,
+							rev: actionRev.rev,
+							transform
+						});
+					}
+					missedCommits.push({ blockId, transforms });	// Push, even if transforms is empty, because we want to reject the older version
+				}
+			}
+
+			if (missedCommits.length) {
+				return { // Return directly, locks will be released in finally
+					success: false,
+					missing: perBlockActionTransformsToPerAction(missedCommits)
+				};
+			}
+
+			// Check for missing pending actions
+			const missingPends: { blockId: BlockId, actionId: ActionId }[] = [];
+			for (const { blockId, storage } of blockStorages) {
+				const pendingAction = await storage.getPendingTransaction(request.actionId);
+				if (!pendingAction) {
+					missingPends.push({ blockId, actionId: request.actionId });
+				}
+			}
+
+			if (missingPends.length) {
+				throw new Error(`Pending action ${request.actionId} not found for block(s): ${missingPends.map(p => p.blockId).join(', ')}`);
+			}
+
+			// Commit the action for each block
+			// This loop will execute atomically for all blocks due to the acquired locks
+			for (const { blockId, storage } of blockStorages) {
+				try {
+					// internalCommit will throw if it encounters an issue
+					await this.internalCommit(blockId, request.actionId, request.rev, storage);
+				} catch (err) {
+					// TODO: Recover as best we can. Rollback or handle partial commit? For now, return failure.
+					return {
+						success: false,
+						reason: err instanceof Error ? err.message : 'Unknown error during commit'
+					};
+				}
+			}
+		}
+		finally {
+			// Release locks in reverse order of acquisition
+			releases.reverse().forEach(release => release());
+		}
+
+		return { success: true };
+	}
+
+	private async internalCommit(blockId: BlockId, actionId: ActionId, rev: number, storage: IBlockStorage): Promise<void> {
+		// Note: This method is called within the locked critical section of commit()
+		// So, operations like getPendingTransaction, getLatest, getBlock, saveMaterializedBlock,
+		// saveRevision, promotePendingTransaction, setLatest are protected against
+		// concurrent commits for the *same blockId*.
+
+		const transform = await storage.getPendingTransaction(actionId);
+		// No need to check if !transform here, as the caller (commit) already verified this.
+		// If it's null here, it indicates a logic error or race condition bypassed the lock (unlikely).
+		if (!transform) {
+			throw new Error(`Consistency Error: Pending action ${actionId} disappeared for block ${blockId} within critical section.`);
+		}
+
+		// Get prior materialized block if it exists
+		const latest = await storage.getLatest();
+		const priorBlock = latest
+			? (await storage.getBlock(latest.rev))?.block
+			: undefined;
+
+		// Apply transform and save materialized block
+		// applyTransform handles undefined priorBlock correctly for inserts
+		const newBlock = applyTransform(priorBlock, transform);
+		if (newBlock) {
+			await storage.saveMaterializedBlock(actionId, newBlock);
+		}
+
+		// Save revision and promote action *before* updating latest
+		// This ensures that if the process crashes between these steps,
+		// the 'latest' pointer doesn't point to a revision that hasn't been fully recorded.
+		await storage.saveRevision(rev, actionId);
+		await storage.promotePendingTransaction(actionId);
+
+		// Update latest revision *last*
+		await storage.setLatest({ actionId, rev });
+	}
+}
+
+/** Converts list of missing actions per block into a list of missing actions across blocks. */
+function perBlockActionTransformsToPerAction(missing: { blockId: BlockId; transforms: ActionTransform[]; }[]) {
+	const missingFlat = missing.flatMap(({ blockId, transforms }) =>
+		transforms.map(transform => ({ blockId, transform }))
+	);
+	const missingByActionId = groupBy(missingFlat, ({ transform }) => transform.actionId);
+	return Object.entries(missingByActionId).map(([actionId, items]) =>
+		items.reduce((acc, { blockId, transform }) => {
+			concatTransform(acc.transforms, blockId, transform.transform);
+			return acc;
+		}, {
+			actionId: actionId as ActionId,
+			rev: items[0]!.transform.rev,	// Assumption: all missing actionIds share the same revision
+			transforms: emptyTransforms()
+		})
+	);
+}

package/src/storage/struct.ts

@@ -0,0 +1,34 @@
+import type { BlockId, IBlock, ActionId, ActionRev, ActionTransform, ActionTransforms } from "@optimystic/db-core";
+
+export type RevisionRange = [
+	/** Inclusive start */
+	startRev: number,
+	/** Exclusive end, or open-ended if undefined */
+	endRev?: number,
+];
+
+export type BlockMetadata = {
+	// Revision ranges that are present in storage
+	ranges: RevisionRange[];
+	/** Latest revision - present if the repo is not empty */
+	latest?: ActionRev;
+};
+
+export type ArchiveRevisions = Record<number, { action: ActionTransform, block?: IBlock }>;
+
+export type BlockArchive = {
+	blockId: BlockId;
+	/** Revisions in this archive */
+	revisions: ArchiveRevisions;
+	/** Explicit range covered by this archive since revisions may be sparse */
+	range: RevisionRange;
+	/** Pending actions - present if this range is open-ended */
+	pending?: Record<ActionId, ActionTransforms>;
+}
+
+/** Should return a BlockRepo with the given rev (materialized) if given,
+ * else (no rev) at least the latest revision and any given pending transactions */
+export type RestoreCallback = (blockId: BlockId, rev?: number) => Promise<BlockArchive | undefined>;
+
+
+

package/src/sync/client.ts

@@ -0,0 +1,42 @@
+import type { PeerId } from '@libp2p/interface';
+import type { IPeerNetwork } from '@optimystic/db-core';
+import { ProtocolClient } from '../protocol-client.js';
+import { buildSyncProtocol, type SyncRequest, type SyncResponse } from './protocol.js';
+
+/**
+ * Client for sending sync requests to remote peers.
+ *
+ * Used by storage tiers to request missing blocks from other nodes in the network.
+ * Extends ProtocolClient for consistent error handling and timeout behavior.
+ */
+export class SyncClient extends ProtocolClient {
+	private readonly protocol: string;
+
+	constructor(
+		peerId: PeerId,
+		peerNetwork: IPeerNetwork,
+		protocolPrefix: string = ''
+	) {
+		super(peerId, peerNetwork);
+		this.protocol = buildSyncProtocol(protocolPrefix);
+	}
+
+	/**
+	 * Request a block from the remote peer.
+	 *
+	 * @param request - Sync request specifying block and options
+	 * @returns Response with archive if successful
+	 * @throws Error if request fails or times out
+	 */
+	async requestBlock(request: SyncRequest): Promise<SyncResponse> {
+		return await this.processMessage<SyncResponse>(request, this.protocol);
+	}
+
+	/**
+	 * Get the protocol string used by this client.
+	 */
+	getProtocol(): string {
+		return this.protocol;
+	}
+}
+

package/src/sync/protocol.ts

@@ -0,0 +1,71 @@
+import type { BlockId } from '@optimystic/db-core';
+import type { BlockArchive } from '../storage/struct.js';
+
+/**
+ * Request to sync a specific block or revision from a peer.
+ *
+ * This protocol is used for block restoration across storage tiers,
+ * allowing nodes to request missing blocks from cluster peers or storage rings.
+ */
+export interface SyncRequest {
+	/** Block ID to retrieve */
+	blockId: BlockId;
+
+	/**
+	 * Optional specific revision to retrieve.
+	 * If undefined, retrieve the latest available revision.
+	 */
+	rev?: number;
+
+	/**
+	 * If true, include pending transactions in the response.
+	 * Typically true when requesting latest state, false for historical revisions.
+	 */
+	includePending?: boolean;
+
+	/**
+	 * Maximum number of revisions to return.
+	 * Prevents excessive response sizes.
+	 * @default 100
+	 */
+	maxRevisions?: number;
+
+	/**
+	 * Optional hint about which tier is requesting (for logging/metrics).
+	 * Values: 'ring-zulu', 'ring-0', 'ring-N', etc.
+	 */
+	requestingTier?: string;
+}
+
+/**
+ * Response containing block archive data.
+ */
+export interface SyncResponse {
+	/** True if the peer has the requested data */
+	success: boolean;
+
+	/** Block archive if found */
+	archive?: BlockArchive;
+
+	/** Error message if unsuccessful */
+	error?: string;
+
+	/** Peer ID of responder (for tracking/metrics) */
+	responderId?: string;
+}
+
+/** Sync protocol prefix - namespaced under db-p2p */
+export const SYNC_PROTOCOL_PREFIX = '/db-p2p/sync/';
+
+/** Sync protocol version */
+export const SYNC_PROTOCOL_VERSION = '1.0.0';
+
+/**
+ * Builds the full protocol string for the sync protocol.
+ *
+ * @param protocolPrefix - Optional prefix (e.g., '/optimystic/testnet')
+ * @returns Full protocol string
+ */
+export const buildSyncProtocol = (protocolPrefix: string = ''): string =>
+	`${protocolPrefix}${SYNC_PROTOCOL_PREFIX}${SYNC_PROTOCOL_VERSION}`;
+

package/src/sync/service.ts

@@ -0,0 +1,229 @@
+import type { ComponentLogger, Startable, Stream } from '@libp2p/interface';
+import type { IRepo } from '@optimystic/db-core';
+import { buildSyncProtocol, type SyncRequest, type SyncResponse } from './protocol.js';
+import { pipe } from 'it-pipe';
+import { fromString as u8FromString } from 'uint8arrays/from-string';
+import { toString as u8ToString } from 'uint8arrays/to-string';
+import * as lp from 'it-length-prefixed';
+
+export interface SyncServiceInit {
+	protocolPrefix?: string;
+}
+
+export interface SyncServiceComponents {
+	logger: ComponentLogger;
+	registrar: { handle: (...args: any[]) => Promise<void>, unhandle: (...args: any[]) => Promise<void> };
+	repo: IRepo;
+}
+
+type Logger = ReturnType<ComponentLogger['forComponent']>;
+
+/**
+ * Service for handling incoming sync requests from other cluster peers.
+ *
+ * Listens on the sync protocol and responds to block requests by:
+ * 1. Extracting the block from local storage
+ * 2. Building a BlockArchive with requested revisions
+ * 3. Sending the response back to the requester
+ *
+ * This is the server-side of the block restoration mechanism.
+ */
+export class SyncService implements Startable {
+	private running = false;
+	private readonly log: Logger;
+	private readonly protocol: string;
+	private readonly repo: IRepo;
+	private readonly registrar: { handle: (...args: any[]) => Promise<void>, unhandle: (...args: any[]) => Promise<void> };
+
+	constructor(
+		private readonly components: SyncServiceComponents,
+		init: SyncServiceInit = {}
+	) {
+		this.log = components.logger.forComponent('db-p2p:sync-service');
+		this.protocol = buildSyncProtocol(init.protocolPrefix ?? '');
+		this.repo = components.repo;
+		this.registrar = components.registrar;
+	}
+
+	async start(): Promise<void> {
+		if (this.running) return;
+
+		await this.registrar.handle(this.protocol, async (data: any) => {
+			await this.handleSyncRequest(data.stream);
+		});
+
+		this.running = true;
+		this.log('Sync service started on protocol %s', this.protocol);
+	}
+
+	async stop(): Promise<void> {
+		if (!this.running) return;
+		await this.registrar.unhandle(this.protocol);
+		this.running = false;
+		this.log('Sync service stopped');
+	}
+
+	/**
+	 * Handle an incoming sync request stream.
+	 */
+	private async handleSyncRequest(stream: Stream): Promise<void> {
+		try {
+			// Read request using length-prefixed protocol
+			const request = await this.readRequest(stream);
+
+			this.log(
+				'[Ring Zulu] Received sync request for block %s revision %s',
+				request.blockId,
+				request.rev ?? 'latest'
+			);
+
+			// Build archive from local storage
+			const archive = await this.buildArchive(
+				request.blockId,
+				request.rev,
+				request.includePending,
+				request.maxRevisions
+			);
+
+			// Send response
+			const response: SyncResponse = archive
+				? {
+					success: true,
+					archive,
+					responderId: stream.id
+				}
+				: {
+					success: false,
+					error: 'Block not found in local storage'
+				};
+
+			await this.sendResponse(stream, response);
+
+			this.log(
+				'[Ring Zulu] %s sync request for block %s',
+				response.success ? 'Fulfilled' : 'Failed',
+				request.blockId
+			);
+		} catch (error) {
+			this.log.error('Error handling sync request:', error);
+
+			// Try to send error response
+			try {
+				const errorResponse: SyncResponse = {
+					success: false,
+					error: error instanceof Error ? error.message : 'Unknown error'
+				};
+				await this.sendResponse(stream, errorResponse);
+			} catch (sendError) {
+				this.log.error('Failed to send error response:', sendError);
+			}
+		} finally {
+			try {
+				await stream.close();
+			} catch (closeError) {
+				// Ignore close errors
+			}
+		}
+	}
+
+	/**
+	 * Read and parse a sync request from the stream.
+	 */
+	private async readRequest(stream: Stream): Promise<SyncRequest> {
+		const messages: Uint8Array[] = [];
+
+		await pipe(
+			stream.source,
+			lp.decode,
+			async (source) => {
+				for await (const msg of source) {
+					messages.push(msg.subarray());
+				}
+			}
+		);
+
+		if (messages.length === 0) {
+			throw new Error('No request received');
+		}
+
+		const json = u8ToString(messages[0]!, 'utf8');
+		return JSON.parse(json) as SyncRequest;
+	}
+
+	/**
+	 * Send a sync response to the stream.
+	 */
+	private async sendResponse(stream: Stream, response: SyncResponse): Promise<void> {
+		const json = JSON.stringify(response);
+		const bytes = u8FromString(json, 'utf8');
+
+		await pipe(
+			[bytes],
+			lp.encode,
+			stream.sink
+		);
+	}
+
+	/**
+	 * Build a block archive from local storage.
+	 *
+	 * @param blockId - Block to retrieve
+	 * @param rev - Optional specific revision
+	 * @param includePending - Whether to include pending transactions
+	 * @param maxRevisions - Maximum number of revisions to include
+	 * @returns BlockArchive if found, undefined otherwise
+	 */
+	private async buildArchive(
+		blockId: string,
+		rev?: number,
+		_includePending?: boolean,
+		_maxRevisions?: number
+	): Promise<import('../storage/struct.js').BlockArchive | undefined> {
+		try {
+			// Get the block from local storage
+			const context = rev !== undefined
+				? { rev, committed: [], pending: [] }
+				: undefined;
+
+			const result = await this.repo.get({
+				blockIds: [blockId],
+				context
+			});
+
+			const blockResult = result[blockId];
+			if (!blockResult || !blockResult.state.latest) {
+				return undefined;
+			}
+
+			const latest = blockResult.state.latest;
+
+			// Return minimal archive with just the requested block
+			const archive: import('../storage/struct.js').BlockArchive = {
+				blockId,
+				revisions: {
+					[latest.rev]: {
+						action: {
+							actionId: latest.actionId,
+							transform: { insert: blockResult.block }
+						},
+						block: blockResult.block
+					}
+				},
+				range: [latest.rev, latest.rev + 1]
+			};
+
+			return archive;
+		} catch (error) {
+			this.log.error('Error building archive for block %s:', blockId, error);
+			return undefined;
+		}
+	}
+}
+
+/**
+ * Factory function for creating a SyncService.
+ * Follows the libp2p service pattern.
+ */
+export const syncService = (init: SyncServiceInit = {}) =>
+	(components: SyncServiceComponents) => new SyncService(components, init);
+