@optimystic/db-p2p 0.0.1

package/src/storage/restoration-coordinator-v2.ts

@@ -0,0 +1,191 @@
+import type { BlockId } from '@optimystic/db-core';
+import { hashKey } from 'p2p-fret';
+import { peerIdFromString } from '@libp2p/peer-id';
+import type { BlockArchive, RestoreCallback } from './struct.js';
+import { SyncClient } from '../sync/client.js';
+import type { IPeerNetwork } from '@optimystic/db-core';
+import type { ArachnodeFretAdapter } from './arachnode-fret-adapter.js';
+import { createLogger } from '../logger.js';
+
+/**
+ * Coordinates block restoration across discovered Arachnode storage rings.
+ *
+ * Queries rings in order of broader coverage (inner rings first):
+ * 1. Transaction ring peers (my ring)
+ * 2. Inner storage rings (Ring N-1, N-2, ..., Ring 0)
+ *
+ * Each ring is discovered dynamically via FRET neighbor snapshots.
+ */
+export class RestorationCoordinator {
+	private readonly metrics = {
+		totalRequests: 0,
+		successByRing: new Map<number, number>(),
+		failureByRing: new Map<number, number>(),
+		averageDurationMs: 0
+	};
+
+	constructor(
+		private readonly fretAdapter: ArachnodeFretAdapter,
+		private readonly peerNetwork: IPeerNetwork,
+		private readonly protocolPrefix: string
+	) {}
+
+	private readonly log = createLogger('storage:restoration')
+
+	/**
+	 * Restore a block by querying discovered storage rings.
+	 */
+	async restore(blockId: BlockId, rev?: number): Promise<BlockArchive | undefined> {
+		const startTime = Date.now();
+		this.metrics.totalRequests++;
+
+		// 1. Try my transaction ring peers first
+		const myPeers = await this.getMyRingPeers(blockId);
+		const myRingDepth = this.getMyRingDepth();
+
+		for (const peerId of myPeers) {
+			const archive = await this.queryPeer(peerId, blockId, rev);
+			if (archive) {
+				this.recordSuccess(myRingDepth, blockId, Date.now() - startTime);
+				return archive;
+			}
+		}
+
+		// 2. Try inner storage rings (broader coverage)
+		for (let ringDepth = myRingDepth - 1; ringDepth >= 0; ringDepth--) {
+			const storagePeers = this.fretAdapter.findPeersAtRing(ringDepth);
+
+			// Filter to peers responsible for this block's partition
+			const responsiblePeers = this.filterByPartition(storagePeers, blockId, ringDepth);
+
+		for (const peerIdStr of responsiblePeers) {
+				const archive = await this.queryPeer(peerIdStr, blockId, rev);
+				if (archive) {
+					this.recordSuccess(ringDepth, blockId, Date.now() - startTime);
+					return archive;
+				}
+			}
+		}
+
+		// No ring had the data
+		const duration = Date.now() - startTime;
+		this.log('restore failed for block %s after %dms', blockId, duration)
+		return undefined;
+	}
+
+	/**
+	 * Create a RestoreCallback function that uses this coordinator.
+	 */
+	createRestoreCallback(): RestoreCallback {
+		return async (blockId: BlockId, rev?: number) => {
+			return await this.restore(blockId, rev);
+		};
+	}
+
+	/**
+	 * Get peers in my transaction ring for a given block.
+	 */
+	private async getMyRingPeers(blockId: BlockId): Promise<string[]> {
+		const blockIdBytes = new TextEncoder().encode(blockId);
+		const coord = await hashKey(blockIdBytes);
+		return this.fretAdapter.getFret().assembleCohort(coord, 10);
+	}
+
+	/**
+	 * Get my own ring depth from Arachnode info.
+	 */
+	private getMyRingDepth(): number {
+		const myInfo = this.fretAdapter.getMyArachnodeInfo();
+		return myInfo?.ringDepth ?? 8; // Default to Ring 8
+	}
+
+	/**
+	 * Filter peers by partition responsibility.
+	 */
+	private filterByPartition(peers: string[], blockId: BlockId, ringDepth: number): string[] {
+		if (ringDepth === 0) {
+			return peers; // Ring 0 covers all blocks
+		}
+
+		const blockPrefix = this.extractBlockPrefix(blockId, ringDepth);
+
+		return peers.filter(peerId => {
+			const info = this.fretAdapter.getArachnodeInfo(peerId);
+			if (!info || !info.partition) return false;
+			return info.partition.prefixValue === blockPrefix;
+		});
+	}
+
+	/**
+	 * Extract prefix bits from block ID for partition matching.
+	 */
+	private extractBlockPrefix(blockId: BlockId, bits: number): number {
+		const bytes = new TextEncoder().encode(blockId);
+		// Hash the block ID to get uniform distribution
+		const hash = new Uint8Array(32);
+		for (let i = 0; i < Math.min(bytes.length, hash.length); i++) {
+			hash[i] = bytes[i]!;
+		}
+
+		// Extract first N bits
+		let value = 0;
+		for (let i = 0; i < bits; i++) {
+			const byteIndex = Math.floor(i / 8);
+			const bitIndex = 7 - (i % 8);
+			const bit = (hash[byteIndex]! >> bitIndex) & 1;
+			value = (value << 1) | bit;
+		}
+		return value;
+	}
+
+	/**
+	 * Query a specific peer for a block.
+	 */
+	private async queryPeer(peerIdStr: string, blockId: BlockId, rev?: number): Promise<BlockArchive | undefined> {
+		try {
+			const peerId = peerIdFromString(peerIdStr);
+			const client = new SyncClient(
+				peerId,
+				this.peerNetwork,
+				this.protocolPrefix
+			);
+
+			const response = await client.requestBlock({ blockId, rev });
+			return response.success ? response.archive : undefined;
+		} catch (error) {
+			this.log('queryPeer failed for %s - %o', peerIdStr, error)
+			return undefined;
+		}
+	}
+
+	/**
+	 * Record successful restoration from a ring.
+	 */
+	private recordSuccess(ringDepth: number, blockId: BlockId, durationMs: number): void {
+		const count = this.metrics.successByRing.get(ringDepth) ?? 0;
+		this.metrics.successByRing.set(ringDepth, count + 1);
+
+		// Update rolling average duration
+		const totalSuccesses = Array.from(this.metrics.successByRing.values())
+			.reduce((sum, c) => sum + c, 0);
+		const prevTotal = this.metrics.averageDurationMs * (totalSuccesses - 1);
+		this.metrics.averageDurationMs = (prevTotal + durationMs) / totalSuccesses;
+
+		console.log(
+			`[Ring ${ringDepth}] Successfully restored block ${blockId} in ${durationMs}ms`
+		);
+	}
+
+	/**
+	 * Get restoration metrics for monitoring.
+	 */
+	getMetrics(): {
+		totalRequests: number;
+		successByRing: Map<number, number>;
+		failureByRing: Map<number, number>;
+		averageDurationMs: number;
+	} {
+		return { ...this.metrics };
+	}
+}
+

package/src/storage/ring-selector.ts

@@ -0,0 +1,155 @@
+import { hashPeerId } from 'p2p-fret';
+import type { StorageMonitor } from './storage-monitor.js';
+import type { ArachnodeInfo, ArachnodeFretAdapter } from './arachnode-fret-adapter.js';
+
+export interface RingSelectorConfig {
+	/** Minimum storage capacity in bytes */
+	minCapacity: number;
+
+	/** Thresholds for ring transitions */
+	thresholds: {
+		/** Move to outer ring when used > this % */
+		moveOut: number;
+		/** Move to inner ring when used < this % */
+		moveIn: number;
+	};
+}
+
+/**
+ * Determines appropriate ring depth based on storage capacity and network demand.
+ *
+ * Ring depth represents keyspace partitioning:
+ * - Ring 0: Full keyspace (1 partition)
+ * - Ring N: 2^N partitions
+ *
+ * A node selects its ring based on: available_capacity / estimated_neighborhood_demand
+ */
+export class RingSelector {
+	constructor(
+		private readonly fretAdapter: ArachnodeFretAdapter,
+		private readonly storageMonitor: StorageMonitor,
+		private readonly config: RingSelectorConfig
+	) {}
+
+	/**
+	 * Determine appropriate ring depth based on capacity and demand.
+	 */
+	async determineRing(): Promise<number> {
+		const capacity = await this.storageMonitor.getCapacity();
+
+		if (capacity.available < this.config.minCapacity) {
+			// Not enough capacity for any ring
+			return -1;
+		}
+
+		// Estimate total network size from FRET
+		// We use a simple heuristic: assume average block size and typical data distribution
+		const avgBlockSize = 100 * 1024; // 100KB typical block
+		const estimatedTotalBlocks = 1000; // Conservative estimate
+		const estimatedTotalData = estimatedTotalBlocks * avgBlockSize;
+
+		// Calculate what fraction of keyspace we can cover
+		const coverage = capacity.available / estimatedTotalData;
+
+		// Ring depth: 0 = full keyspace, N = 2^N partitions
+		// If coverage = 0.01 (1%), we need ~100 partitions ≈ Ring 7
+		// If coverage = 1.0 (100%), we can handle full keyspace = Ring 0
+		const ringDepth = Math.max(0, Math.ceil(-Math.log2(Math.max(0.001, coverage))));
+
+		return Math.min(ringDepth, 16); // Cap at Ring 16 (65536 partitions)
+	}
+
+	/**
+	 * Calculate partition for a given ring depth and peer ID.
+	 */
+	async calculatePartition(
+		ringDepth: number,
+		peerId: string
+	): Promise<{ prefixBits: number, prefixValue: number } | undefined> {
+		if (ringDepth === 0) {
+			return undefined; // Full keyspace, no partition
+		}
+
+		// Hash peer ID to get coordinate
+		const coord = await hashPeerId({ toString: () => peerId } as any);
+
+		// Extract prefix bits from coordinate
+		const prefixBits = ringDepth;
+		const prefixValue = this.extractPrefix(coord, prefixBits);
+
+		return { prefixBits, prefixValue };
+	}
+
+	/**
+	 * Create Arachnode info for this node.
+	 */
+	async createArachnodeInfo(peerId: string): Promise<ArachnodeInfo> {
+		const capacity = await this.storageMonitor.getCapacity();
+		const ringDepth = await this.determineRing();
+		const partition = ringDepth >= 0
+			? await this.calculatePartition(ringDepth, peerId)
+			: undefined;
+
+		return {
+			ringDepth: Math.max(0, ringDepth),
+			partition,
+			capacity: {
+				total: capacity.total,
+				used: capacity.used,
+				available: capacity.available
+			},
+			status: 'active'
+		};
+	}
+
+	/**
+	 * Monitor capacity and determine if ring transition is needed.
+	 */
+	async shouldTransition(): Promise<{
+		shouldMove: boolean;
+		direction?: 'in' | 'out';
+		newRingDepth?: number
+	}> {
+		const capacity = await this.storageMonitor.getCapacity();
+		const usedPercent = capacity.used / capacity.total;
+
+		if (usedPercent > this.config.thresholds.moveOut) {
+			// Move to outer ring (more granular partition)
+			const currentRingDepth = await this.determineRing();
+			return {
+				shouldMove: true,
+				direction: 'out',
+				newRingDepth: currentRingDepth + 1
+			};
+		}
+
+		if (usedPercent < this.config.thresholds.moveIn) {
+			// Move to inner ring (broader coverage)
+			const currentRingDepth = await this.determineRing();
+			if (currentRingDepth > 0) {
+				return {
+					shouldMove: true,
+					direction: 'in',
+					newRingDepth: currentRingDepth - 1
+				};
+			}
+		}
+
+		return { shouldMove: false };
+	}
+
+	/**
+	 * Extract first N bits from byte array as a number.
+	 */
+	private extractPrefix(bytes: 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 = (bytes[byteIndex]! >> bitIndex) & 1;
+			value = (value << 1) | bit;
+		}
+		return value;
+	}
+}
+

package/src/storage/storage-monitor.ts

@@ -0,0 +1,59 @@
+import type { IRawStorage } from './i-raw-storage.js';
+
+export interface StorageCapacity {
+	total: number;
+	used: number;
+	available: number;
+}
+
+export interface StorageMonitorConfig {
+	totalBytes?: number;
+	usedBytes?: number;
+	availableBytes?: number;
+}
+
+/**
+ * Monitors storage capacity for ring selection.
+ * Provides estimates based on storage backend or supplied overrides.
+ */
+export class StorageMonitor {
+	constructor(
+		private readonly storage: IRawStorage,
+		private readonly config: StorageMonitorConfig = {}
+	) {}
+
+	async getCapacity(): Promise<StorageCapacity> {
+		const defaultTotal = 10 * 1024 * 1024 * 1024; // 10GB default
+		const total = this.config.totalBytes ?? defaultTotal;
+		const usedOverride = this.config.usedBytes;
+		const availableOverride = this.config.availableBytes;
+
+		if (
+			usedOverride !== undefined ||
+			availableOverride !== undefined ||
+			this.config.totalBytes !== undefined
+		) {
+			const used = usedOverride ?? Math.max(0, total - (availableOverride ?? total));
+			const available = availableOverride ?? Math.max(0, total - used);
+			return {
+				total,
+				used: Math.min(total, Math.max(0, used)),
+				available: Math.max(0, Math.min(total, available))
+			};
+		}
+
+		const used = await this.estimateUsedSpace();
+		const available = Math.max(0, total - used);
+
+		return {
+			total,
+			used,
+			available
+		};
+	}
+
+	private async estimateUsedSpace(): Promise<number> {
+		return 0; // TODO: Implement actual space calculation
+	}
+}
+