@peerbit/blocks 4.2.5 → 4.2.6

package/src/remote.ts

@@ -3,10 +3,12 @@ import { TypedEventEmitter } from "@libp2p/interface";
 import {
 	type GetOptions,
 	type Blocks as IBlocks,
-	checkDecodeBlock,
 	cidifyString,
 	codecCodes,
+	codecMap,
+	defaultHasher,
 	stringifyCid,
+	verifyBlockBytes,
 } from "@peerbit/blocks-interface";
 import { Cache } from "@peerbit/cache";
 import { PublicSignKey } from "@peerbit/crypto";
@@ -18,6 +20,8 @@ import {
 	dontThrowIfDeliveryError,
 } from "@peerbit/stream";
 import {
+	BACKGROUND_MESSAGE_PRIORITY,
+	FOREGROUND_READ_MESSAGE_PRIORITY,
 	type PeerRefs,
 	type RequestTransportContext,
 	SilentDelivery,
@@ -29,6 +33,14 @@ import { AbortError } from "@peerbit/time";
 import { CID } from "multiformats";
 import { type Block } from "multiformats/block";
 import PQueue from "p-queue";
+import {
+	BoundedEagerBlockCache,
+	type EagerBlockCache,
+	type EagerBlocksSetting,
+	MAX_EAGER_BLOCK_CID_LENGTH,
+	type NormalizedEagerBlocksOptions,
+	normalizeEagerBlocksOptions,
+} from "./eager-cache.js";
 import type { BlockStore } from "./interface.js";
 
 export const logger = loggerFn("peerbit:transport:blocks");
@@ -70,23 +82,46 @@ type BlockMessageContext = {
 type InFlightRead = {
 	promise: Promise<Block<any, any, any, 1> | undefined>;
 	addProviders: (providers: string[]) => void;
+	promotePriority: (priority: number | undefined) => void;
 };
 
 type RemoteReadOptions = Exclude<GetOptions["remote"], boolean | undefined> & {
 	hasher?: any;
 };
 
-/**
- * Shared shape of the TS eager-block cache (`Cache<Uint8Array>`) and the
- * native-backed one (`RustEagerBlockCache`).
- */
-type EagerBlockCache = {
-	add(cid: string, bytes: Uint8Array): void;
-	get(cid: string): Uint8Array | null | undefined;
-	del(cid: string): unknown;
-	clear(): void;
+export type EagerBlockCacheTelemetry = {
+	entries: number;
+	bytes: number;
+	peakEntries: number;
+	peakBytes: number;
+	evictions: number;
+	expirations: number;
+	pendingEntries: number;
+	pendingBytes: number;
+	peakPendingEntries: number;
+	peakPendingBytes: number;
+	admitted: number;
+	hits: number;
+	rejectedCid: number;
+	rejectedCodec: number;
+	rejectedSize: number;
+	rejectedPending: number;
+	rejectedIntegrity: number;
+	rejectedLifecycle: number;
+	limits: NormalizedEagerBlocksOptions;
 };
 
+type EagerAdmissionCounters = Omit<
+	EagerBlockCacheTelemetry,
+	| "entries"
+	| "bytes"
+	| "peakEntries"
+	| "peakBytes"
+	| "evictions"
+	| "expirations"
+	| "limits"
+>;
+
 export class RemoteBlocks implements IBlocks {
 	localStore: BlockStore;
 
@@ -117,8 +152,27 @@ export class RemoteBlocks implements IBlocks {
 		data: BlockMessage,
 		context?: BlockMessageContext,
 	) => any;
-	private _resolvers: Map<string, (data: Uint8Array) => Promise<void>>;
+	private _resolvers: Map<
+		string,
+		(data: Uint8Array, providerHash?: string) => Promise<void>
+	>;
 	private _blockCache?: EagerBlockCache;
+	private _eagerBlocksOptions?: NormalizedEagerBlocksOptions;
+	private _eagerValidationQueue?: PQueue;
+	private _eagerAdmission: EagerAdmissionCounters = {
+		pendingEntries: 0,
+		pendingBytes: 0,
+		peakPendingEntries: 0,
+		peakPendingBytes: 0,
+		admitted: 0,
+		hits: 0,
+		rejectedCid: 0,
+		rejectedCodec: 0,
+		rejectedSize: 0,
+		rejectedPending: 0,
+		rejectedIntegrity: 0,
+		rejectedLifecycle: 0,
+	};
 	private _providerCache?: Cache<string[]>;
 	private _rustProviderCache?: RustBlockProviderCache;
 	private readonly rustExchange?: RustBlockExchange;
@@ -127,6 +181,7 @@ export class RemoteBlocks implements IBlocks {
 	private readonly maxRequeryOnReachable: number;
 
 	private _loadFetchQueue: PQueue;
+	private _backgroundLoadFetchQueue: PQueue;
 	private _readFromPeersPromises: Map<string, InFlightRead>;
 	private _deferredStoredNotificationCids?: Set<string>;
 	private _deferredStoredNotificationTimer?: ReturnType<typeof setTimeout>;
@@ -143,7 +198,7 @@ export class RemoteBlocks implements IBlocks {
 			localTimeout?: number;
 			messageProcessingConcurrency?: number;
 			publicKey: PublicSignKey;
-			eagerBlocks?: boolean | { cacheSize?: number };
+			eagerBlocks?: EagerBlocksSetting;
 			/**
 			 * Optional provider resolver used when `remote: true` is used without `remote.from`.
 			 *
@@ -219,8 +274,19 @@ export class RemoteBlocks implements IBlocks {
 		const localTimeout = options?.localTimeout || 1000;
 		this.publicKeyHash = options.publicKey.hashcode();
 		this.rustExchange = options.rust?.exchange;
+		const messageProcessingConcurrency =
+			options?.messageProcessingConcurrency || 10;
 		this._loadFetchQueue = new PQueue({
-			concurrency: options?.messageProcessingConcurrency || 10,
+			concurrency: messageProcessingConcurrency,
+		});
+		// A provider handler includes the response publication. When every handler
+		// is publishing bulk/background blocks under backpressure, a single priority
+		// queue cannot preempt that already-active work. Admit at most N-1 background
+		// handlers so foreground reads can use the reserved slot whenever the
+		// configured concurrency is at least two. Foreground-only traffic can still
+		// use the full configured concurrency.
+		this._backgroundLoadFetchQueue = new PQueue({
+			concurrency: Math.max(1, messageProcessingConcurrency - 1),
 		});
 		this.localStore = options?.local;
 		const localPutKnownManyColumns = (
@@ -314,13 +380,23 @@ export class RemoteBlocks implements IBlocks {
 		this._resolvers = new Map();
 		this._readFromPeersPromises = new Map();
 		if (options?.eagerBlocks) {
-			const eagerBlocksMax =
-				typeof options.eagerBlocks === "boolean"
-					? 1e3
-					: (options.eagerBlocks.cacheSize ?? 1e3);
+			this._eagerBlocksOptions = normalizeEagerBlocksOptions(
+				options.eagerBlocks,
+			);
+			this._eagerValidationQueue = new PQueue({
+				concurrency: this._eagerBlocksOptions.validationConcurrency,
+			});
 			this._blockCache = this.rustExchange
-				? this.rustExchange.createEagerCache({ max: eagerBlocksMax, ttl: 1e4 })
-				: new Cache<Uint8Array>({ max: eagerBlocksMax, ttl: 1e4 });
+				? this.rustExchange.createEagerCache({
+						maxEntries: this._eagerBlocksOptions.maxEntries,
+						maxBytes: this._eagerBlocksOptions.maxBytes,
+						ttlMs: this._eagerBlocksOptions.ttlMs,
+					})
+				: new BoundedEagerBlockCache({
+						maxEntries: this._eagerBlocksOptions.maxEntries,
+						maxBytes: this._eagerBlocksOptions.maxBytes,
+						ttlMs: this._eagerBlocksOptions.ttlMs,
+					});
 		}
 		type ProviderCacheOptions = {
 			maxEntries?: number;
@@ -357,28 +433,40 @@ export class RemoteBlocks implements IBlocks {
 		) => {
 			try {
 				if (message instanceof BlockRequest && this.localStore) {
-					this._loadFetchQueue
-						.add(() => this.handleFetchRequest(message, localTimeout, context))
-						.catch((e) => {
-							try {
-								dontThrowIfDeliveryError(e);
-							} catch (error) {
-								logger.error("Got error for libp2p block transport: ", error);
-							}
-						});
+					const priority =
+						context?.transport?.requestPriority ?? BACKGROUND_MESSAGE_PRIORITY;
+					const queueSignal = this.closeController.signal;
+					const run = () =>
+						this._loadFetchQueue.add(
+							() =>
+								queueSignal.aborted
+									? undefined
+									: this.handleFetchRequest(message, localTimeout, context),
+							{
+								priority,
+							},
+						);
+					const scheduled =
+						priority >= FOREGROUND_READ_MESSAGE_PRIORITY
+							? run()
+							: this._backgroundLoadFetchQueue.add(
+									() => (queueSignal.aborted ? undefined : run()),
+									{ priority },
+								);
+					scheduled.catch((e) => {
+						if (queueSignal.aborted) return;
+						try {
+							dontThrowIfDeliveryError(e);
+						} catch (error) {
+							logger.error("Got error for libp2p block transport: ", error);
+						}
+					});
 				} else if (message instanceof BlockResponse) {
-					// TODO make sure we are not storing too much bytes in ram (like filter large blocks)
-					if (context?.from) {
-						this.rememberProvider(message.cid, context.from);
-					}
-					let resolver = this._resolvers.get(message.cid);
+					const resolver = this._resolvers.get(message.cid);
 					if (!resolver) {
-						if (options.eagerBlocks) {
-							// wait for the resolve to exist
-							this._blockCache!.add(message.cid, message.bytes);
-						}
+						this.queueEagerBlock(message.cid, message.bytes, context?.from);
 					} else {
-						await resolver(message.bytes);
+						await resolver(message.bytes, context?.from);
 					}
 				}
 			} catch (error) {
@@ -392,6 +480,170 @@ export class RemoteBlocks implements IBlocks {
 		return this.localStore.getNativeLogBlockStoreHandle?.();
 	}
 
+	/** Snapshot of bounded eager-response admission and retention state. */
+	getEagerBlockCacheTelemetry(): EagerBlockCacheTelemetry | undefined {
+		if (!this._blockCache || !this._eagerBlocksOptions) return undefined;
+		return {
+			...this._blockCache.stats(),
+			...this._eagerAdmission,
+			limits: { ...this._eagerBlocksOptions },
+		};
+	}
+
+	/** Primarily useful for diagnostics and deterministic tests. */
+	waitForEagerBlockValidation(): Promise<void> {
+		return this._eagerValidationQueue?.onIdle() ?? Promise.resolve();
+	}
+
+	private queueEagerBlock(
+		cidString: string,
+		incomingBytes: Uint8Array,
+		providerHash?: string,
+	): void {
+		const limits = this._eagerBlocksOptions;
+		const queue = this._eagerValidationQueue;
+		const cache = this._blockCache;
+		if (!limits || !queue || !cache) return;
+
+		const generationSignal = this.closeController.signal;
+		if (generationSignal.aborted) {
+			this._eagerAdmission.rejectedLifecycle += 1;
+			return;
+		}
+		if (!cidString || cidString.length > MAX_EAGER_BLOCK_CID_LENGTH) {
+			this._eagerAdmission.rejectedCid += 1;
+			return;
+		}
+
+		let cidObject: CID;
+		let canonicalCid: string;
+		try {
+			cidObject = cidifyString(cidString);
+			canonicalCid = stringifyCid(cidObject);
+			if (
+				cidObject.multihash.code !== defaultHasher.code ||
+				canonicalCid.length > MAX_EAGER_BLOCK_CID_LENGTH
+			) {
+				throw new Error("unsupported eager block cid");
+			}
+		} catch {
+			this._eagerAdmission.rejectedCid += 1;
+			return;
+		}
+		// Logical DAG-CBOR decoding can materialize even hash-valid attacker-
+		// controlled object graphs and expand a small wire payload by orders of
+		// magnitude. Eager admission therefore verifies only raw bytes; all other
+		// codecs remain available through the requested-response path.
+		if (cidObject.code !== codecMap.raw.code) {
+			this._eagerAdmission.rejectedCodec += 1;
+			return;
+		}
+		const codec = codecMap.raw;
+
+		const byteLength = incomingBytes.byteLength;
+		if (
+			byteLength > limits.maxBlockBytes ||
+			byteLength > limits.maxBytes ||
+			byteLength > limits.maxPendingBytes
+		) {
+			this._eagerAdmission.rejectedSize += 1;
+			return;
+		}
+		if (
+			this._eagerAdmission.pendingEntries >= limits.maxPendingEntries ||
+			this._eagerAdmission.pendingBytes + byteLength > limits.maxPendingBytes
+		) {
+			this._eagerAdmission.rejectedPending += 1;
+			return;
+		}
+
+		// The decoder commonly returns a subarray into the complete network frame.
+		// Copy exactly the block bytes before queuing so no larger backing buffer or
+		// response object remains retained while integrity validation is pending.
+		const bytes = new Uint8Array(byteLength);
+		bytes.set(incomingBytes);
+		this._eagerAdmission.pendingEntries += 1;
+		this._eagerAdmission.pendingBytes += byteLength;
+		this._eagerAdmission.peakPendingEntries = Math.max(
+			this._eagerAdmission.peakPendingEntries,
+			this._eagerAdmission.pendingEntries,
+		);
+		this._eagerAdmission.peakPendingBytes = Math.max(
+			this._eagerAdmission.peakPendingBytes,
+			this._eagerAdmission.pendingBytes,
+		);
+
+		let released = false;
+		const releaseReservation = () => {
+			if (released) return;
+			released = true;
+			this._eagerAdmission.pendingEntries -= 1;
+			this._eagerAdmission.pendingBytes -= byteLength;
+		};
+		const validateAndAdmit = async () => {
+			try {
+				if (generationSignal.aborted) {
+					this._eagerAdmission.rejectedLifecycle += 1;
+					return;
+				}
+				try {
+					await this.validateEagerBlock(cidObject, bytes, codec);
+				} catch {
+					this._eagerAdmission.rejectedIntegrity += 1;
+					return;
+				}
+				if (generationSignal.aborted) {
+					this._eagerAdmission.rejectedLifecycle += 1;
+					return;
+				}
+				const resolver =
+					this._resolvers.get(canonicalCid) ?? this._resolvers.get(cidString);
+				if (resolver) {
+					try {
+						// A read can install its resolver while eager validation is in
+						// progress. Let that resolver enforce its own (possibly custom)
+						// hasher contract and learn the provider only if it succeeds.
+						await resolver(bytes, providerHash);
+					} catch {
+						// Match an invalid active response: drop it and leave the read open.
+					}
+					return;
+				}
+				if (!cache.add(canonicalCid, bytes)) {
+					this._eagerAdmission.rejectedSize += 1;
+					return;
+				}
+				this._eagerAdmission.admitted += 1;
+				if (providerHash) {
+					// An unsolicited response is only a provider signal after both its
+					// CID and payload have passed the integrity gate.
+					this.rememberProvider(canonicalCid, providerHash);
+				}
+			} finally {
+				releaseReservation();
+			}
+		};
+		try {
+			void queue.add(validateAndAdmit).catch(() => {
+				releaseReservation();
+				if (!generationSignal.aborted) {
+					this._eagerAdmission.rejectedLifecycle += 1;
+				}
+			});
+		} catch {
+			releaseReservation();
+			this._eagerAdmission.rejectedLifecycle += 1;
+		}
+	}
+
+	private validateEagerBlock(
+		cid: CID,
+		bytes: Uint8Array,
+		codec: (typeof codecCodes)[keyof typeof codecCodes],
+	) {
+		return verifyBlockBytes(cid, bytes, { codec });
+	}
+
 	private normalizeProviderHints(
 		providers: string[] | undefined,
 		limit = this.maxProviderHintsPerCid || 8,
@@ -663,7 +915,9 @@ export class RemoteBlocks implements IBlocks {
 				const cidObject = cidifyString(cid);
 				value = await this._readFromPeers(cid, cidObject, remoteOptions);
 				if (remoteOptions?.replicate && value) {
-					await this.put(value);
+					// _readFromPeers verifies the response bytes against cid before it
+					// resolves, so avoid hashing the full block a second time here.
+					await this.putKnown(cid, value);
 				}
 			}
 		}
@@ -792,6 +1046,7 @@ export class RemoteBlocks implements IBlocks {
 							signal: controller.signal,
 							timeout: proxyTimeoutMs,
 							from: providers,
+							priority: context?.transport?.requestPriority,
 						});
 					}
 				} finally {
@@ -834,26 +1089,38 @@ export class RemoteBlocks implements IBlocks {
 
 		const codec = codecCodes[cidObject.code as keyof typeof codecCodes];
 
-		const tryDecode = async (bytes: Uint8Array) => {
-			const value = await checkDecodeBlock(cidObject, bytes, {
+		const tryVerify = async (bytes: Uint8Array) => {
+			const verifiedCid = await verifyBlockBytes(cidObject, bytes, {
 				codec,
 				hasher: options?.hasher,
 			});
-
-			return value;
+			// This block-shaped value is internal bookkeeping only. RemoteBlocks moves
+			// opaque bytes and must not invoke the logical codec at this boundary.
+			return {
+				bytes,
+				cid: verifiedCid,
+				value: bytes,
+			} as Block<Uint8Array, any, any, 1>;
 		};
-		const cachedValue = this.options.eagerBlocks
-			? this._blockCache?.get(cidString)
-			: undefined;
-		if (cachedValue) {
-			this._blockCache!.del(cidString);
-			try {
-				const result = await tryDecode(cachedValue);
-				return result.bytes;
-			} catch (error) {
-				// ignore
+		const eagerCacheKey = stringifyCid(cidObject);
+		const consumeCachedValue = (): Uint8Array | undefined => {
+			if (options.hasher && options.hasher !== defaultHasher) {
+				// Eager admission proves the built-in SHA-256 contract only. Keep this
+				// lookup synchronous and leave custom hashers on the requested-response
+				// path; asynchronously revalidating cached entries would reopen a race
+				// before the read resolver is installed.
+				return undefined;
 			}
-		}
+			const cachedValue = this._blockCache?.get(eagerCacheKey);
+			if (cachedValue === undefined) return undefined;
+			this._blockCache!.del(eagerCacheKey);
+			this._eagerAdmission.hits += 1;
+			// Eager entries are inserted only after verifyBlockBytes succeeds. The
+			// one-shot cache hit therefore does not hash the full block a second time.
+			return cachedValue;
+		};
+		let cachedResult = consumeCachedValue();
+		if (cachedResult) return cachedResult;
 
 		const explicitFrom = this.normalizeProviderHints(options.from);
 		let providers =
@@ -865,6 +1132,11 @@ export class RemoteBlocks implements IBlocks {
 		// A resolver may observe abort and still complete normally. Do not create a
 		// timeout-backed read from the candidates it returns after shutdown.
 		throwIfReadWasAborted();
+		// Provider resolution is asynchronous. An eager validation can complete and
+		// cache the response during that await, so consume it before either returning
+		// for lack of providers or installing a resolver that would otherwise wait.
+		cachedResult = consumeCachedValue();
+		if (cachedResult) return cachedResult;
 		const canResolveLater = typeof this.options.resolveProviders === "function";
 		if (providers.length === 0 && !canResolveLater) {
 			// Without an explicit provider set (or a resolver), we intentionally do not
@@ -878,11 +1150,14 @@ export class RemoteBlocks implements IBlocks {
 
 		let inFlight = this._readFromPeersPromises.get(cidString);
 		if (!inFlight) {
+			let requestPriority = options.priority ?? BACKGROUND_MESSAGE_PRIORITY;
 			let publishAdditionalProviders: (providers: string[]) => void = () => {};
 			const promise = new Promise<Block<any, any, any, 1> | undefined>(
 				(resolve, reject) => {
 					let timeoutCallback: ReturnType<typeof setTimeout> | undefined;
-					let resolver: ((bytes: Uint8Array) => Promise<void>) | undefined;
+					let resolver:
+						| ((bytes: Uint8Array, providerHash?: string) => Promise<void>)
+						| undefined;
 					let settled = false;
 					const abortHandler = () => {
 						cleanup();
@@ -921,9 +1196,14 @@ export class RemoteBlocks implements IBlocks {
 						options.timeout || 30 * 1000,
 					);
 
-					resolver = async (bytes: Uint8Array) => {
-						const value = await tryDecode(bytes);
+					resolver = async (bytes: Uint8Array, providerHash?: string) => {
+						const value = await tryVerify(bytes);
 						if (settled) return;
+						if (providerHash) {
+							// A response is only evidence that its sender can provide this CID
+							// after the payload has passed the requested CID's integrity check.
+							this.rememberProvider(cidString, providerHash);
+						}
 						settled = true;
 						cleanup();
 						resolve(value);
@@ -976,8 +1256,8 @@ export class RemoteBlocks implements IBlocks {
 							: this.pickRequestBatch(providers, requeryCount);
 					if (requestProviders.length === 0) return;
 					await this.options.publish(new BlockRequest(cidString), {
-						priority: options.priority,
-						responsePriority: options.priority,
+						priority: requestPriority,
+						responsePriority: requestPriority,
 						expiresAt,
 						mode: new SilentDelivery({
 							to: requestProviders,
@@ -1017,6 +1297,20 @@ export class RemoteBlocks implements IBlocks {
 				promise,
 				addProviders: (nextProviders) =>
 					publishAdditionalProviders(nextProviders),
+				promotePriority: (nextPriority) => {
+					if (!this._resolvers.has(cidString)) return;
+					// A background replication read may win CID coalescing before a
+					// foreground waiter arrives. Reissue only on a strict priority upgrade.
+					const promotedPriority = nextPriority ?? BACKGROUND_MESSAGE_PRIORITY;
+					if (
+						!Number.isFinite(promotedPriority) ||
+						promotedPriority <= requestPriority
+					) {
+						return;
+					}
+					requestPriority = promotedPriority;
+					tryPublishRequest({ force: true }).catch(dontThrowIfDeliveryError);
+				},
 			};
 			this._readFromPeersPromises.set(cidString, inFlight);
 
@@ -1101,6 +1395,7 @@ export class RemoteBlocks implements IBlocks {
 				}
 			}
 		} else {
+			inFlight.promotePriority(options.priority);
 			if (providers.length > 0) {
 				inFlight.addProviders(providers);
 			}
@@ -1174,8 +1469,12 @@ export class RemoteBlocks implements IBlocks {
 			this._deferredStoredNotificationTimer = undefined;
 		}
 		await capture(() => this.flushDeferredStoredNotifications());
-		await capture(() => this._loadFetchQueue.clear());
+		// Queued wrappers observe the aborted generation and drain without starting
+		// new work. Avoid PQueue.clear(): it would strand promises already returned
+		// by the nested background-admission queue.
+		await capture(() => this._backgroundLoadFetchQueue.onIdle());
 		await capture(() => this._loadFetchQueue.onIdle());
+		await capture(() => this._eagerValidationQueue?.onIdle());
 		await capture(() => this.localStore?.stop());
 		this._readFromPeersPromises.clear();
 		this._resolvers.clear();