@optimystic/db-p2p 0.11.3 → 0.12.0

package/src/network/network-manager-service.ts

@@ -169,7 +169,7 @@ export class NetworkManagerService implements Startable {
 			throw new Error('FRET service not available for seeding keys');
 		}
 		const coord = await hashKey(key);
-		const _neighbors = fret.getNeighbors(coord, 'both', 1);
+		fret.getNeighbors(coord, 'both', 1);
 	}
 
 	private toCacheKey(key: Uint8Array): string {

package/src/repo/cluster-coordinator.ts

@@ -1,5 +1,5 @@
 import { peerIdFromString } from "@libp2p/peer-id";
-import type { ClusterRecord, IKeyNetwork, RepoMessage, BlockId, ClusterPeers, MessageOptions, Signature, ClusterConsensusConfig } from "@optimystic/db-core";
+import type { ClusterRecord, IKeyNetwork, RepoMessage, BlockId, ClusterPeers, MessageOptions, ClusterConsensusConfig } from "@optimystic/db-core";
 import { base58btc } from "multiformats/bases/base58";
 import { sha256 } from "multiformats/hashes/sha2";
 import { ClusterClient } from "../cluster/client.js";
@@ -123,7 +123,7 @@ export class ClusterCoordinator {
 	 * Initiates a 2-phase transaction for a specific block ID.
 	 * Returns the cluster record and whether the local cluster already executed the operations.
 	 */
-	async executeClusterTransaction(blockId: BlockId, message: RepoMessage, options?: MessageOptions): Promise<{
+	async executeClusterTransaction(blockId: BlockId, message: RepoMessage, _options?: MessageOptions): Promise<{
 		record: ClusterRecord;
 		localExecuted: boolean;
 	}> {
@@ -298,7 +298,7 @@ export class ClusterCoordinator {
 	 * Validate that a small cluster size is legitimate by querying remote peers
 	 * for their network size estimates. Returns true if estimates roughly agree.
 	 */
-	private async validateSmallCluster(localSize: number, peers: ClusterPeers): Promise<boolean> {
+	private async validateSmallCluster(localSize: number, _peers: ClusterPeers): Promise<boolean> {
 		// If we have FRET and it shows confident estimate
 		if (this.fretService) {
 			try {
@@ -581,7 +581,7 @@ export class ClusterCoordinator {
 		});
 	}
 
-	private scheduleCommitRetry(messageHash: string, record: ClusterRecord, missingPeers: string[]): void {
+	private scheduleCommitRetry(messageHash: string, _record: ClusterRecord, missingPeers: string[]): void {
 		const state = this.transactions.get(messageHash);
 		if (!state) {
 			return;

package/src/repo/coordinator-repo.ts

@@ -187,8 +187,25 @@ export class CoordinatorRepo implements IRepo {
 	private async fetchBlockFromCluster(blockId: BlockId, context?: ActionContext): Promise<void> {
 		if (!this.clusterLatestCallback) return;
 
-		// Query cluster for the block
-		const clusterLatest = await this.queryClusterForLatest(blockId, context);
+		const blockIdBytes = new TextEncoder().encode(blockId);
+		const peers = await this.keyNetwork.findCluster(blockIdBytes);
+		const peerIds = peers ? Object.keys(peers) : [];
+		if (peerIds.length === 0) return;
+
+		// Solo-cluster short-circuit: the only responsible peer is us. There is no
+		// remote to sync from, so skip the callback entirely. Querying ourselves
+		// would dial self via SyncClient — pointless at best, and on nodes without
+		// listen addresses (e.g. solo WebSocket-only) the dial can hang.
+		if (
+			peerIds.length === 1
+			&& this.localPeerId
+			&& peerIds[0] === this.localPeerId.toString()
+		) {
+			log('cluster-fetch:solo-self-skip', { blockId });
+			return;
+		}
+
+		const clusterLatest = await this.queryClusterForLatest(peerIds, blockId, context);
 		if (clusterLatest) {
 			// Found on cluster - trigger restoration to sync the block
 			await this.storageRepo.get({ blockIds: [blockId], context: { committed: [clusterLatest], rev: clusterLatest.rev } });
@@ -199,14 +216,7 @@ export class CoordinatorRepo implements IRepo {
 	/**
 	 * Query cluster peers to find the maximum latest revision for a block.
 	 */
-	private async queryClusterForLatest(blockId: BlockId, context?: ActionContext): Promise<ActionRev | undefined> {
-		const blockIdBytes = new TextEncoder().encode(blockId);
-		const peers = await this.keyNetwork.findCluster(blockIdBytes);
-		if (!peers || Object.keys(peers).length === 0) {
-			return undefined;
-		}
-
-		const peerIds = Object.keys(peers);
+	private async queryClusterForLatest(peerIds: string[], blockId: BlockId, context?: ActionContext): Promise<ActionRev | undefined> {
 		let maxLatest: ActionRev | undefined;
 
 		// Add timeout wrapper to prevent hanging on unresponsive peers

package/src/repo/service.ts

@@ -63,7 +63,6 @@ export class RepoService implements Startable {
 	private readonly repo: IRepo
 	private readonly components: RepoServiceComponents
 	private running: boolean
-	private readonly k: number
 	/** Responsibility K - how many peers are responsible for a key (for redirect decisions) */
 	private readonly responsibilityK: number
 
@@ -76,7 +75,6 @@ export class RepoService implements Startable {
 		this.log = components.logger.forComponent(init.logPrefix ?? 'db-p2p:repo-service')
 		this.repo = components.repo
 		this.running = false
-		this.k = init.kBucketSize ?? 10
 		this.responsibilityK = init.responsibilityK ?? 1
 	}
 

package/src/routing/simple-cluster-coordinator.ts

@@ -57,13 +57,13 @@ export class ModuloCoordinator implements SimpleClusterCoordinator {
  * For very small clusters, just replicate everywhere
  */
 export class FullReplicationCoordinator implements SimpleClusterCoordinator {
-  async selectCoordinator(key: Uint8Array, peers: PeerId[]): Promise<PeerId> {
+  async selectCoordinator(_key: Uint8Array, peers: PeerId[]): Promise<PeerId> {
     // Always select first peer as primary
     if (peers.length === 0) throw new Error('No peers available')
     return peers[0]!
   }
 
-  async selectReplicas(key: Uint8Array, peers: PeerId[], replicationFactor: number): Promise<PeerId[]> {
+  async selectReplicas(_key: Uint8Array, peers: PeerId[], _replicationFactor: number): Promise<PeerId[]> {
     // Replicate to all peers in small clusters
     return [...peers]
   }

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

@@ -27,4 +27,14 @@ export interface IRawStorage {
 
 	// Promote a pending action to a committed action
 	promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void>;
+
+	/**
+	 * Approximate bytes currently stored by this backend.
+	 *
+	 * Used by `StorageMonitor` to feed real used-space figures into ring selection.
+	 * Implementations should return their best cheap estimate (e.g. on-disk size for
+	 * filesystem backends, tracked footprint for in-memory backends). The result is
+	 * advisory — `StorageMonitor` treats a missing implementation as 0.
+	 */
+	getApproximateBytesUsed?(): Promise<number>;
 }

package/src/storage/memory-storage.ts

@@ -142,4 +142,32 @@ export class MemoryRawStorage implements IRawStorage {
 			this.pendingActions.delete(key);
 		}
 	}
+
+	async getApproximateBytesUsed(): Promise<number> {
+		let total = 0;
+		for (const [blockId, meta] of this.metadata) {
+			total += blockId.length + jsonByteSize(meta);
+		}
+		for (const [key, actionId] of this.revisions) {
+			total += key.length + actionId.length;
+		}
+		for (const [key, transform] of this.pendingActions) {
+			total += key.length + jsonByteSize(transform);
+		}
+		for (const [key, transform] of this.actions) {
+			total += key.length + jsonByteSize(transform);
+		}
+		for (const [key, block] of this.materializedBlocks) {
+			total += key.length + jsonByteSize(block);
+		}
+		return total;
+	}
+}
+
+function jsonByteSize(value: unknown): number {
+	try {
+		return JSON.stringify(value)?.length ?? 0;
+	} catch {
+		return 0;
+	}
 }

package/src/storage/ring-selector.ts

@@ -42,11 +42,32 @@ export class RingSelector {
 			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;
+		// Estimate total network spare capacity by aggregating observed per-ring stats.
+		// See docs/arachnode.md §"Capacity Management and Ring Adjustment": ring selection
+		// should reflect observed network demand, not a hard-coded constant. We treat
+		// Σ (peerCount × avgCapacity) over known rings as a proxy for total network spare
+		// capacity, so `coverage` becomes our share of it. More peers (or richer peers) →
+		// smaller share → higher ring depth (more specialization). On bootstrap, when no
+		// ring stats are observed yet, we fall back to a conservative fixed estimate so
+		// first-boot behavior is deterministic.
+		const ringStats = this.fretAdapter.getRingStats();
+		let estimatedTotalData: number;
+		if (ringStats.length > 0) {
+			estimatedTotalData = ringStats.reduce(
+				(sum, stat) => sum + stat.peerCount * stat.avgCapacity,
+				0
+			);
+		} else {
+			const avgBlockSize = 100 * 1024; // 100KB typical block
+			const estimatedTotalBlocks = 1000; // Conservative estimate
+			estimatedTotalData = estimatedTotalBlocks * avgBlockSize;
+		}
+
+		// Guard against pathological zero-aggregate (e.g. all peers report 0 available);
+		// fall back to local capacity so coverage = 1.0 (ring 0).
+		if (estimatedTotalData <= 0) {
+			estimatedTotalData = capacity.available;
+		}
 
 		// Calculate what fraction of keyspace we can cover
 		const coverage = capacity.available / estimatedTotalData;

package/src/storage/storage-monitor.ts

@@ -28,22 +28,15 @@ export class StorageMonitor {
 		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);
+		// Only short-circuit the backend when used/available is explicitly supplied;
+		// a bare `totalBytes` is just the disk-size hint and should still let the
+		// backend report actual used bytes.
+		const rawUsed = usedOverride
+			?? (availableOverride !== undefined ? total - availableOverride : await this.estimateUsedSpace());
+		const used = Math.min(total, Math.max(0, rawUsed));
+		const available = availableOverride !== undefined
+			? Math.max(0, Math.min(total, availableOverride))
+			: Math.max(0, total - used);
 
 		return {
 			total,
@@ -53,7 +46,7 @@ export class StorageMonitor {
 	}
 
 	private async estimateUsedSpace(): Promise<number> {
-		return 0; // TODO: Implement actual space calculation
+		return (await this.storage.getApproximateBytesUsed?.()) ?? 0;
 	}
 }
 

package/src/storage/storage-repo.ts

@@ -1,7 +1,6 @@
 import type {
 	IRepo, MessageOptions, BlockId, CommitRequest, CommitResult, GetBlockResults, PendRequest, PendResult, ActionBlocks,
 	ActionId, BlockGets, ActionPending, PendSuccess, ActionTransform, ActionTransforms,
-	Transforms,
 	GetBlockResult,
 	PendValidationHook
 } from "@optimystic/db-core";
@@ -30,7 +29,7 @@ export class StorageRepo implements IRepo {
 		this.validatePend = options?.validatePend;
 	}
 
-	async get({ blockIds, context }: BlockGets, options?: MessageOptions): Promise<GetBlockResults> {
+	async get({ blockIds, context }: BlockGets, _options?: MessageOptions): Promise<GetBlockResults> {
 		const distinctBlockIds = Array.from(new Set(blockIds));
 		log('get blockIds=%d', distinctBlockIds.length);
 		const results = await Promise.all(distinctBlockIds.map(async (blockId) => {
@@ -191,7 +190,7 @@ export class StorageRepo implements IRepo {
 		}));
 	}
 
-	async commit(request: CommitRequest, options?: MessageOptions): Promise<CommitResult> {
+	async commit(request: CommitRequest, _options?: MessageOptions): Promise<CommitResult> {
 		log('commit actionId=%s rev=%d blockIds=%d', request.actionId, request.rev, request.blockIds.length);
 		const uniqueBlockIds = Array.from(new Set(request.blockIds)).sort();
 		const releases: (() => void)[] = [];

package/src/sync/service.ts

@@ -1,8 +1,7 @@
-import type { ComponentLogger, Startable, Stream } from '@libp2p/interface';
+import type { ComponentLogger, Startable } 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';
 import type { Uint8ArrayList } from 'uint8arraylist';
@@ -37,7 +36,7 @@ export class SyncService implements Startable {
 	private readonly registrar: { handle: (...args: any[]) => Promise<void>, unhandle: (...args: any[]) => Promise<void> };
 
 	constructor(
-		private readonly components: SyncServiceComponents,
+		components: SyncServiceComponents,
 		init: SyncServiceInit = {}
 	) {
 		this.log = components.logger.forComponent('db-p2p:sync-service');

package/src/testing/mesh-harness.ts

@@ -62,7 +62,7 @@ class MockMeshKeyNetwork implements IKeyNetwork {
 		private readonly failures: MeshFailureConfig = {}
 	) {}
 
-	async findCoordinator<T>(key: Uint8Array, options?: Partial<FindCoordinatorOptions>): Promise<PeerId> {
+	async findCoordinator(key: Uint8Array, options?: Partial<FindCoordinatorOptions>): Promise<PeerId> {
 		const excluded = new Set((options?.excludedPeers ?? []).map(p => p.toString()));
 		const sorted = this.sortedByDistance(key);
 		const pick = sorted.find(n => !excluded.has(n.peerId.toString()));