@peerbit/shared-log 13.2.31 → 13.2.33

package/src/replication-info-v2-send.ts

@@ -0,0 +1,540 @@
+import { type PublicSignKey, randomBytes } from "@peerbit/crypto";
+import { logger as loggerFn } from "@peerbit/logger";
+import type { RPC } from "@peerbit/rpc";
+import {
+	AcknowledgeDelivery,
+	CONVERGENCE_MESSAGE_PRIORITY,
+} from "@peerbit/stream-interface";
+import type { TransportMessage } from "./message.js";
+import type { ReplicationRangeIndexable } from "./ranges.js";
+import { deriveReplicationInfoV2ReceiverBinding } from "./replication-info-v2-binding.js";
+import {
+	AddedReplicationInfoV2Message,
+	AddedReplicationSegmentMessage,
+	AllReplicatingSegmentsMessage,
+	FullReplicationInfoV2Message,
+	RequestReplicationInfoV2Message,
+	StoppedReplicating,
+	StoppedReplicationInfoV2Message,
+} from "./replication.js";
+
+const logger = loggerFn("peerbit:shared-log:replication-info-v2-send");
+
+const MAX_U64 = (1n << 64n) - 1n;
+
+export { deriveReplicationInfoV2ReceiverBinding } from "./replication-info-v2-binding.js";
+
+export type LegacyReplicationInfoMessage =
+	| AllReplicatingSegmentsMessage
+	| AddedReplicationSegmentMessage
+	| StoppedReplicating;
+
+type SendRequest =
+	| { kind: "snapshot" }
+	| { kind: "message"; message: LegacyReplicationInfoMessage };
+
+export type ReplicationInfoV2SendState = {
+	peerHash: string;
+	target: PublicSignKey;
+	peerSession: object;
+	receiverTransportSession: bigint;
+	senderTransportSession: bigint;
+	capabilityTimestamp: bigint;
+	lastRequestTimestamp: bigint;
+	receiverRequestChallenge: Uint8Array;
+	receiverChallenge: Uint8Array;
+	senderEpoch: Uint8Array;
+	ownershipLifecycleController: AbortController;
+	nextSequence: bigint;
+	established: boolean;
+	suspended: boolean;
+	inFlightSequence?: bigint;
+	controller: AbortController;
+	pending?: SendRequest;
+	worker?: Promise<void>;
+};
+
+export type ReplicationInfoV2SendDeps<R extends "u32" | "u64"> = {
+	getRpc: () => RPC<TransportMessage, TransportMessage>;
+	getSelfKey: () => PublicSignKey;
+	getSenderTransportSession: () => bigint;
+	getMyReplicationSegments: () => Promise<ReplicationRangeIndexable<R>[]>;
+	validatePersistedReplicationRangeSnapshot: (
+		ranges: readonly { mode: unknown }[],
+	) => void;
+	isClosed: () => boolean;
+	isPeerSessionOpen: (peerHash: string, peerSession: object) => boolean;
+	captureReplicationOwnershipLifecycle: () => AbortController;
+	isReplicationOwnershipLifecycleActive: (
+		controller: AbortController,
+	) => boolean;
+};
+
+const bytesEqual = (left: Uint8Array, right: Uint8Array): boolean => {
+	if (left.byteLength !== right.byteLength) {
+		return false;
+	}
+	for (let index = 0; index < left.byteLength; index++) {
+		if (left[index] !== right[index]) {
+			return false;
+		}
+	}
+	return true;
+};
+
+/**
+ * Per-destination V2 sender streams. Each stream retains at most one in-flight
+ * operation and one pending operation. A second pending mutation coalesces to
+ * a freshly collected authoritative snapshot, bounding memory at O(peers).
+ */
+export class ReplicationInfoV2SendCoordinator<R extends "u32" | "u64"> {
+	_senderEpoch!: Uint8Array;
+	_sendStates!: Map<string, ReplicationInfoV2SendState>;
+	_spentPeerSessions!: WeakSet<object>;
+	_retiringWorkersByPeer!: Map<string, Promise<void>>;
+
+	constructor(private readonly deps: ReplicationInfoV2SendDeps<R>) {
+		this._senderEpoch = randomBytes(32);
+		this._sendStates = new Map();
+		this._spentPeerSessions = new WeakSet();
+		this._retiringWorkersByPeer = new Map();
+	}
+
+	resetForOpen(): void {
+		this.clearForClose();
+		this._senderEpoch = randomBytes(32);
+		this._sendStates = new Map();
+		this._spentPeerSessions = new WeakSet();
+	}
+
+	clearForClose(): void {
+		for (const state of [...(this._sendStates?.values() ?? [])]) {
+			this.clearState(state);
+		}
+		this._sendStates?.clear();
+	}
+
+	clearPeer(peerHash: string, expectedSession?: object): void {
+		const state = this._sendStates.get(peerHash);
+		if (!state || (expectedSession && state.peerSession !== expectedSession)) {
+			return;
+		}
+		this.clearState(state);
+	}
+
+	advancePeerCapability(peerHash: string): void {
+		const state = this._sendStates.get(peerHash);
+		if (state) {
+			this.clearState(state);
+		}
+	}
+
+	private clearState(state: ReplicationInfoV2SendState): void {
+		this.trackRetiringWorker(state);
+		state.controller.abort();
+		if (this._sendStates.get(state.peerHash) === state) {
+			this._sendStates.delete(state.peerHash);
+		}
+	}
+
+	private trackRetiringWorker(state: ReplicationInfoV2SendState): void {
+		const worker = state.worker;
+		if (!worker) {
+			return;
+		}
+		const previous = this._retiringWorkersByPeer.get(state.peerHash);
+		if (previous === worker) {
+			return;
+		}
+		const retirement = previous
+			? Promise.allSettled([previous, worker]).then(() => undefined)
+			: worker;
+		this._retiringWorkersByPeer.set(state.peerHash, retirement);
+		const forget = () => {
+			if (this._retiringWorkersByPeer.get(state.peerHash) === retirement) {
+				this._retiringWorkersByPeer.delete(state.peerHash);
+			}
+		};
+		void retirement.then(forget, forget);
+	}
+
+	private isDestinationCurrent(state: ReplicationInfoV2SendState): boolean {
+		return (
+			!this.deps.isClosed() &&
+			!state.controller.signal.aborted &&
+			this._sendStates.get(state.peerHash) === state &&
+			this.deps.isPeerSessionOpen(state.peerHash, state.peerSession) &&
+			this.deps.getSenderTransportSession() === state.senderTransportSession
+		);
+	}
+
+	private isCurrent(state: ReplicationInfoV2SendState): boolean {
+		return (
+			this.isDestinationCurrent(state) &&
+			this.deps.isReplicationOwnershipLifecycleActive(
+				state.ownershipLifecycleController,
+			)
+		);
+	}
+
+	/**
+	 * Accept a signed receiver request. An exact newer retry asks for another
+	 * full snapshot without resetting the epoch/sequence. A different challenge
+	 * can replace the binding only after a strictly newer signed capability;
+	 * retiring work is drained before the replacement can start.
+	 */
+	acceptRequest(
+		request: RequestReplicationInfoV2Message,
+		properties: {
+			from: PublicSignKey;
+			peerSession: object;
+			receiverTransportSession: bigint;
+			capabilityTimestamp: bigint;
+			requestTimestamp: bigint;
+		},
+	): boolean {
+		const self = this.deps.getSelfKey();
+		const senderTransportSession = this.deps.getSenderTransportSession();
+		if (
+			properties.from.equals(self) ||
+			!request.intendedSender.equals(self) ||
+			request.senderSession !== senderTransportSession
+		) {
+			return false;
+		}
+
+		const peerHash = properties.from.hashcode();
+		if (
+			this._retiringWorkersByPeer.has(peerHash) ||
+			this._spentPeerSessions.has(properties.peerSession) ||
+			!this.deps.isPeerSessionOpen(peerHash, properties.peerSession)
+		) {
+			return false;
+		}
+
+		let previous = this._sendStates.get(peerHash);
+		if (
+			previous &&
+			(previous.peerSession !== properties.peerSession ||
+				previous.senderTransportSession !== senderTransportSession)
+		) {
+			this.clearState(previous);
+			previous = undefined;
+			if (this._retiringWorkersByPeer.has(peerHash)) {
+				return false;
+			}
+		}
+		if (previous) {
+			const sameBinding =
+				previous.peerSession === properties.peerSession &&
+				previous.receiverTransportSession ===
+					properties.receiverTransportSession &&
+				bytesEqual(
+					previous.receiverRequestChallenge,
+					request.receiverChallenge,
+				);
+			if (sameBinding) {
+				if (properties.requestTimestamp <= previous.lastRequestTimestamp) {
+					return false;
+				}
+				previous.lastRequestTimestamp = properties.requestTimestamp;
+				previous.capabilityTimestamp = properties.capabilityTimestamp;
+				previous.suspended = false;
+				this.enqueueState(previous, { kind: "snapshot" });
+				return true;
+			}
+
+			if (properties.capabilityTimestamp <= previous.capabilityTimestamp) {
+				return false;
+			}
+			this.clearState(previous);
+			previous = undefined;
+			if (this._retiringWorkersByPeer.has(peerHash)) {
+				return false;
+			}
+		}
+
+		const ownershipLifecycleController =
+			this.deps.captureReplicationOwnershipLifecycle();
+		const state: ReplicationInfoV2SendState = {
+			peerHash,
+			target: properties.from,
+			peerSession: properties.peerSession,
+			receiverTransportSession: properties.receiverTransportSession,
+			senderTransportSession,
+			capabilityTimestamp: properties.capabilityTimestamp,
+			lastRequestTimestamp: properties.requestTimestamp,
+			receiverRequestChallenge: request.receiverChallenge.slice(),
+			receiverChallenge: deriveReplicationInfoV2ReceiverBinding({
+				receiverChallenge: request.receiverChallenge,
+				receiver: properties.from,
+				receiverTransportSession: properties.receiverTransportSession,
+				sender: self,
+				senderTransportSession,
+			}),
+			senderEpoch: this._senderEpoch.slice(),
+			nextSequence: 1n,
+			established: false,
+			suspended: false,
+			controller: new AbortController(),
+			ownershipLifecycleController,
+		};
+		this._sendStates.set(peerHash, state);
+		this.enqueueState(state, { kind: "snapshot" });
+		return true;
+	}
+
+	enqueue(message: LegacyReplicationInfoMessage): void {
+		for (const state of [...this._sendStates.values()]) {
+			this.enqueueState(state, { kind: "message", message });
+		}
+	}
+
+	enqueueSnapshotForPeer(peerHash: string): void {
+		const state = this._sendStates.get(peerHash);
+		if (state) {
+			this.enqueueState(state, { kind: "snapshot" });
+		}
+	}
+
+	private enqueueState(
+		state: ReplicationInfoV2SendState,
+		request: SendRequest,
+	): void {
+		if (!this.isCurrent(state)) {
+			state.pending = undefined;
+			if (
+				!this.isDestinationCurrent(state) ||
+				this.deps.isReplicationOwnershipLifecycleActive(
+					state.ownershipLifecycleController,
+				)
+			) {
+				this.clearState(state);
+			}
+			return;
+		}
+		if (state.suspended) {
+			state.pending = undefined;
+			return;
+		}
+
+		if (!state.worker) {
+			state.pending = request;
+			let worker: Promise<void>;
+			worker = Promise.resolve()
+				.then(() => this.runWorker(state))
+				.catch((error) => {
+					const ownershipActive =
+						this.deps.isReplicationOwnershipLifecycleActive(
+							state.ownershipLifecycleController,
+						);
+					if (
+						ownershipActive &&
+						!state.controller.signal.aborted &&
+						!this.deps.isClosed()
+					) {
+						logger.trace(
+							"Replication-info V2 destination stream failed for %s: %s",
+							state.peerHash,
+							(error as Error)?.message ?? String(error),
+						);
+					}
+					state.pending = undefined;
+					const ordinaryFailure =
+						ownershipActive && this.isDestinationCurrent(state);
+					if (ordinaryFailure) {
+						if (state.inFlightSequence !== undefined) {
+							state.inFlightSequence = undefined;
+							if (state.nextSequence > MAX_U64) {
+								this._spentPeerSessions.add(state.peerSession);
+								this.clearState(state);
+								return;
+							}
+						}
+						// A delivery error is ambiguous: the receiver may already have
+						// applied this sequence. Retain the exact grant, stop ordinary
+						// deltas, and require a newer same-challenge request to resume
+						// with an authoritative Full at the next safe sequence.
+						state.suspended = true;
+						return;
+					}
+					if (!this.isDestinationCurrent(state)) {
+						this.clearState(state);
+					}
+				})
+				.finally(() => {
+					if (state.worker === worker) {
+						state.worker = undefined;
+						// An enqueue can land after runWorker observes an empty slot but
+						// before this promise reaction clears `worker`. Re-arm that item
+						// here so the one-slot bound cannot become a stranded queue.
+						const pending = state.pending;
+						if (pending && this.isCurrent(state)) {
+							state.pending = undefined;
+							this.enqueueState(state, pending);
+						}
+					}
+				});
+			state.worker = worker;
+			return;
+		}
+
+		if (!state.pending) {
+			state.pending = request;
+			return;
+		}
+
+		// One pending item is the hard bound. Once another mutation arrives,
+		// replace the pending delta with a current authoritative snapshot.
+		state.pending = { kind: "snapshot" };
+	}
+
+	private async createMessage(
+		state: ReplicationInfoV2SendState,
+		request: SendRequest,
+	): Promise<
+		| FullReplicationInfoV2Message
+		| AddedReplicationInfoV2Message
+		| StoppedReplicationInfoV2Message
+	> {
+		const common = {
+			receiverChallenge: state.receiverChallenge.slice(),
+			senderEpoch: state.senderEpoch.slice(),
+			sequence: state.nextSequence,
+		};
+		if (request.kind === "snapshot") {
+			const segments = (await this.deps.getMyReplicationSegments()).map(
+				(range) => range.toReplicationRange(),
+			);
+			this.deps.validatePersistedReplicationRangeSnapshot(segments);
+			return new FullReplicationInfoV2Message({ ...common, segments });
+		}
+		if (request.message instanceof AllReplicatingSegmentsMessage) {
+			const segments = request.message.segments;
+			this.deps.validatePersistedReplicationRangeSnapshot(segments);
+			return new FullReplicationInfoV2Message({ ...common, segments });
+		}
+		if (request.message instanceof AddedReplicationSegmentMessage) {
+			return new AddedReplicationInfoV2Message({
+				...common,
+				segments: request.message.segments,
+			});
+		}
+		return new StoppedReplicationInfoV2Message({
+			...common,
+			segmentIds: request.message.segmentIds,
+		});
+	}
+
+	private async runWorker(state: ReplicationInfoV2SendState): Promise<void> {
+		while (this.isCurrent(state)) {
+			const request = state.pending;
+			if (!request) {
+				return;
+			}
+			state.pending = undefined;
+			if (state.nextSequence > MAX_U64) {
+				this.clearState(state);
+				return;
+			}
+
+			const message = await this.createMessage(state, request);
+			if (!this.isCurrent(state)) {
+				return;
+			}
+			// Consume the sequence before the transport attempt. From this point on
+			// delivery is ambiguous even if ownership aborts before the await
+			// continuation runs, so `nextSequence` always remains the next value that
+			// has never been attempted with different content.
+			state.inFlightSequence = state.nextSequence;
+			state.nextSequence += 1n;
+			await this.deps.getRpc().send(message, {
+				mode: new AcknowledgeDelivery({
+					to: [state.target],
+					redundancy: 1,
+				}),
+				priority: CONVERGENCE_MESSAGE_PRIORITY,
+				signal: AbortSignal.any([
+					state.controller.signal,
+					state.ownershipLifecycleController.signal,
+				]),
+			});
+			state.inFlightSequence = undefined;
+			if (!this.isCurrent(state)) {
+				return;
+			}
+			state.established = true;
+			if (state.nextSequence > MAX_U64) {
+				this._spentPeerSessions.add(state.peerSession);
+				this.clearState(state);
+				return;
+			}
+		}
+	}
+
+	/**
+	 * Terminal close/drop runs after the normal ownership generation is aborted.
+	 * Send an authoritative empty Full directly from the retained destination
+	 * bindings. `nextSequence` is consumed before every transport attempt, so it
+	 * is always safe for different terminal content even if a just-aborted frame
+	 * was delivered. Receivers admit Full gaps as authoritative resynchronization.
+	 */
+	async sendTerminalReset(signal: AbortSignal): Promise<void> {
+		const sends: Promise<unknown>[] = [];
+		for (const state of [...this._sendStates.values()]) {
+			if (
+				signal.aborted ||
+				!this.isDestinationCurrent(state) ||
+				state.nextSequence > MAX_U64
+			) {
+				continue;
+			}
+			state.pending = undefined;
+			const message = new FullReplicationInfoV2Message({
+				receiverChallenge: state.receiverChallenge.slice(),
+				senderEpoch: state.senderEpoch.slice(),
+				sequence: state.nextSequence,
+				segments: [],
+			});
+			sends.push(
+				this.deps.getRpc().send(message, {
+					mode: new AcknowledgeDelivery({
+						to: [state.target],
+						redundancy: 1,
+					}),
+					priority: CONVERGENCE_MESSAGE_PRIORITY,
+					signal,
+				}),
+			);
+		}
+		await Promise.allSettled(sends);
+	}
+
+	async drain(signal?: AbortSignal): Promise<void> {
+		while (!signal?.aborted) {
+			const workers = [
+				...[...this._sendStates.values()]
+					.map((state) => state.worker)
+					.filter((worker): worker is Promise<void> => worker != null),
+				...this._retiringWorkersByPeer.values(),
+			];
+			const uniqueWorkers = [...new Set(workers)];
+			if (uniqueWorkers.length === 0) {
+				return;
+			}
+			const settled = Promise.allSettled(uniqueWorkers).then(() => undefined);
+			if (!signal) {
+				await settled;
+			} else {
+				await new Promise<void>((resolve) => {
+					const onAbort = () => resolve();
+					signal.addEventListener("abort", onAbort, { once: true });
+					void settled.then(() => {
+						signal.removeEventListener("abort", onAbort);
+						resolve();
+					});
+				});
+			}
+		}
+	}
+}

package/src/replication.ts

@@ -7,7 +7,7 @@ import {
 	variant,
 	vec,
 } from "@dao-xyz/borsh";
-import { randomBytes } from "@peerbit/crypto";
+import { PublicSignKey, randomBytes } from "@peerbit/crypto";
 import { type Index } from "@peerbit/indexer-interface";
 import { TransportMessage } from "./message.js";
 import {
@@ -126,10 +126,11 @@ export class ReplicationPingMessage extends TransportMessage {
 }
 
 /**
- * Decode-first replication-info V2 messages. This rollout only registers and
- * advertises the final wire schemas; it never sends or applies these messages.
- * A later negotiated phase must bind the signed transport session and an
- * outstanding receiver challenge before any V2 payload is used.
+ * Challenge-bound replication-info V2 messages. Their `receiverChallenge`
+ * field carries a derived receiver binding, not the request's raw nonce. The
+ * binding covers both authenticated identities and signed transport sessions.
+ * Sender-ready nodes may emit them only after a signed, session-bound receiver
+ * request. Receive/apply activation remains separately capability-gated.
  */
 @variant([1, 6])
 export class FullReplicationInfoV2Message extends TransportMessage {
@@ -215,6 +216,39 @@ export class StoppedReplicationInfoV2Message extends TransportMessage {
 	}
 }
 
+/**
+ * Signed, receiver-led permission for one sender to start a V2 stream.
+ *
+ * The transport delivery target is deliberately unsigned because relays may
+ * rewrite it. Carry the intended sender in the signed payload so a valid
+ * request cannot be retargeted to another peer. `senderSession` is copied from
+ * the sender's signed capability envelope and binds the request to that exact
+ * transport incarnation.
+ */
+@variant([1, 9])
+export class RequestReplicationInfoV2Message extends TransportMessage {
+	/** Random receiver nonce used as input to the V2 receiver-binding hash. */
+	@field({ type: fixedArray("u8", 32) })
+	receiverChallenge: Uint8Array;
+
+	@field({ type: PublicSignKey })
+	intendedSender: PublicSignKey;
+
+	@field({ type: "u64" })
+	senderSession: bigint;
+
+	constructor(properties: {
+		receiverChallenge: Uint8Array;
+		intendedSender: PublicSignKey;
+		senderSession: bigint;
+	}) {
+		super();
+		this.receiverChallenge = properties.receiverChallenge;
+		this.intendedSender = properties.intendedSender;
+		this.senderSession = properties.senderSession;
+	}
+}
+
 export type ReplicationInfoV2Message =
 	| FullReplicationInfoV2Message
 	| AddedReplicationInfoV2Message