@peerbit/shared-log 13.2.35 → 14.0.0

package/src/index.ts

@@ -144,6 +144,7 @@ import {
 	debouncedAccumulatorMap,
 } from "./debounce.js";
 import {
+	CompatibilityModeRetiredError,
 	NativeDurableCommitError,
 	NoPeersError,
 	isNotStartedError,
@@ -428,6 +429,7 @@ export {
 	EntryReplicatedU32,
 	EntryReplicatedU64,
 	type CoverRange,
+	CompatibilityModeRetiredError,
 	NativeDurableCommitError,
 	NoPeersError,
 };
@@ -1248,7 +1250,6 @@ export type SharedLogOptions<
 	waitForPruneDelay?: number;
 	distributionDebounceTime?: number;
 	strictFullReplicaFallback?: boolean;
-	compatibility?: number;
 	domain?: ReplicationDomainConstructor<D>;
 	eagerBlocks?: EagerBlocksSetting;
 	fanout?: SharedLogFanoutOptions;
@@ -1346,6 +1347,13 @@ export const WAIT_FOR_REPLICATOR_TIMEOUT = 20000;
 export const WAIT_FOR_ROLE_MATURITY = 5000;
 export const WAIT_FOR_REPLICATOR_REQUEST_INTERVAL = 1000;
 export const WAIT_FOR_REPLICATOR_REQUEST_MIN_ATTEMPTS = 3;
+// The V2 recovery scheduler is deliberately persistent (a subscribed peer is
+// re-solicited for as long as its topic session stays open), but consecutive
+// fruitless park/unpark cycles double the wait before the next unpark so a
+// silent-but-subscribed peer converges to one bounded request cycle per cap
+// window instead of one per base interval. Any applied V2 progress resets it.
+export const REPLICATION_INFO_V2_RECOVERY_MAX_UNPARK_DELAY = 300_000;
+const REPLICATION_INFO_V2_RECOVERY_MAX_UNPARK_EXPONENT = 20;
 // TODO(prune): Investigate if/when a non-zero prune delay is required for correctness
 // (e.g. responsibility/replication-info message reordering in multi-peer scenarios).
 // Prefer making pruning robust without timing-based heuristics.
@@ -2087,12 +2095,22 @@ export class SharedLog<
 	private _replicationInfoRequestByPeer!: Map<
 		string,
 		{
+			// Legacy scheduler: sends issued (bounded by maxAttempts). V2 recovery
+			// scheduler: consecutive fruitless unparks — the escalation exponent
+			// for the next unpark delay, reset on any applied V2 progress.
 			attempts: number;
 			timer?: ReturnType<typeof setTimeout>;
 			peerSession?: PeerSession;
+			// V2 recovery scheduler only: when the current park was first observed.
+			parkedSinceMs?: number;
 		}
 	>;
 	private _replicationInfoApplyQueueByPeer!: Map<string, Promise<void>>;
+	// One in-flight targeted subscriber-snapshot request per session-less peer.
+	// A capability burst from a peer whose Subscribe has not been observed must
+	// coalesce into a single pubsub.requestSubscribers call (mirrors the
+	// waitForReplicator in-flight coalescing); a later burst may request again.
+	private _subscriberSnapshotRequestsByPeer!: Map<string, Promise<void>>;
 	// Range ids are global primary keys while receive lanes are per peer. Keep
 	// reads and writes that decide one mutation in a single global lane.
 	private _replicationRangeMutationTail: Promise<void> = Promise.resolve();
@@ -3633,6 +3651,7 @@ export class SharedLog<
 		this._pendingIHaveCallbacks = new Set();
 		this.latestReplicationInfoMessage = new Map();
 		this._replicationInfoRequestByPeer = new Map();
+		this._subscriberSnapshotRequestsByPeer = new Map();
 		this._replicationInfoApplyQueueByPeer = new Map();
 		// The registry constructor runs resetForOpen(), which creates the
 		// replication-info blocked set (fence B5) alongside the session maps —
@@ -3742,7 +3761,10 @@ export class SharedLog<
 	}
 
 	get compatibility(): number | undefined {
-		return this._logProperties?.compatibility;
+		// B12: the open option was removed and any defined value rejects at
+		// open(); this is permanently undefined and dies with the residual
+		// gates in a later cleanup stage.
+		return (this._logProperties as any)?.compatibility;
 	}
 
 	/**
@@ -4282,6 +4304,9 @@ export class SharedLog<
 		);
 		if (generationAdvanced) {
 			this._v2Send.advancePeerCapability(peerHash);
+			// A fresh signed capability generation is V2 progress from the peer:
+			// recovery re-solicitation may restart from the base interval.
+			this.resetReplicationInfoV2RecoveryEscalation(peerHash);
 		}
 		return true;
 	}
@@ -4312,6 +4337,36 @@ export class SharedLog<
 		});
 	}
 
+	/**
+	 * Coalesced targeted subscriber-snapshot request for the
+	 * capability-before-Subscribe recovery path. The observed-capability gate
+	 * is sender-paced (any advancing timestamp passes), so a burst of frames
+	 * from one session-less peer must not fan out into one GetSubscribers
+	 * unicast per frame. One request per peer is in flight at a time; once it
+	 * settles, a genuinely new session-less capability may request again.
+	 */
+	private requestSubscriberSnapshotForCapability(target: PublicSignKey): void {
+		const peerHash = target.hashcode();
+		if (this._subscriberSnapshotRequestsByPeer.has(peerHash)) {
+			return;
+		}
+		const request = Promise.resolve()
+			.then(() =>
+				this.node.services.pubsub.requestSubscribers(this.topic, target),
+			)
+			.catch((error) => {
+				if (!isNotStartedError(error as Error)) {
+					logger.error(error?.toString?.() ?? String(error));
+				}
+			})
+			.finally(() => {
+				if (this._subscriberSnapshotRequestsByPeer.get(peerHash) === request) {
+					this._subscriberSnapshotRequestsByPeer.delete(peerHash);
+				}
+			});
+		this._subscriberSnapshotRequestsByPeer.set(peerHash, request);
+	}
+
 	/**
 	 * Live append gossip may use the raw exchange-heads path only when we
 	 * opted into raw sync and every remote recipient advertised raw capability
@@ -14115,6 +14170,17 @@ export class SharedLog<
 	}
 
 	async open(options?: Args<T, D, R>): Promise<void> {
+		// B12: replication-info network compatibility modes are retired. Read the
+		// RAW argument value (the option no longer exists on the type) so untyped
+		// JS callers cannot smuggle a value past the removed field, and reject
+		// ANY defined value — including 10, which previously behaved like the
+		// default — BEFORE any open-time side effect (rpc.open, index/native
+		// setup, domain resolution, synchronizer creation, subscription setup).
+		// An explicitly-present `undefined` stays accepted.
+		const rawCompatibility = (options as any)?.compatibility;
+		if (rawCompatibility !== undefined) {
+			throw new CompatibilityModeRetiredError(rawCompatibility);
+		}
 		this.ensureNativeDurabilityRuntimeState();
 		this._nativeStrictDurableTransactionsClosing = false;
 		this._replicationRangeMutationsClosing = false;
@@ -14176,7 +14242,8 @@ export class SharedLog<
 		this.domain = options?.domain
 			? (options.domain(this) as unknown as D)
 			: (createReplicationDomainHash(
-					options?.compatibility !== undefined && options.compatibility < 10
+					(options as any)?.compatibility !== undefined &&
+						(options as any).compatibility < 10
 						? "u32"
 						: "u64",
 				)(this) as unknown as D);
@@ -14191,6 +14258,7 @@ export class SharedLog<
 		this._pendingIHaveCallbacks = new Set();
 		this.latestReplicationInfoMessage = new Map();
 		this._replicationInfoRequestByPeer = new Map();
+		this._subscriberSnapshotRequestsByPeer = new Map();
 		// Terminal close/drop drains the previous lifecycle before another open can
 		// install fresh lanes and opaque per-subscription ownership tokens.
 		this._replicationInfoApplyQueueByPeer = new Map();
@@ -14785,7 +14853,7 @@ export class SharedLog<
 				sendOptions?: { priority?: number; signal?: AbortSignal },
 			) => this.trySendFusedRawExchangeHeads(hashes, to, sendOptions),
 			warn,
-			compatibility: this._logProperties?.compatibility,
+			compatibility: (this._logProperties as any)?.compatibility,
 			resolution: this.domain.resolution,
 			sync: options?.sync,
 			syncronizer: options?.syncronizer,
@@ -19384,18 +19452,7 @@ export class SharedLog<
 								// subscriber snapshot; the resulting Subscribe creates the real
 								// PeerSession and completes the symmetric capability handshake.
 								// Never synthesize membership from capability traffic alone.
-								void Promise.resolve()
-									.then(() =>
-										this.node.services.pubsub.requestSubscribers(
-											this.topic,
-											context.from,
-										),
-									)
-									.catch((error) => {
-										if (!isNotStartedError(error as Error)) {
-											logger.error(error?.toString?.() ?? String(error));
-										}
-									});
+								this.requestSubscriberSnapshotForCapability(context.from);
 							}
 						}
 					}
@@ -19963,6 +20020,9 @@ export class SharedLog<
 					return;
 				}
 				this._liveness.markReplicatorActivity(fromHash);
+				// A committed V2 announcement is applied progress: the peer answers,
+				// so recovery re-solicitation may restart from the base interval.
+				this.resetReplicationInfoV2RecoveryEscalation(fromHash);
 				if (
 					msg instanceof FullReplicationInfoV2Message &&
 					this.legacyReplicationInfoEnabled
@@ -23432,6 +23492,22 @@ export class SharedLog<
 		this._replicationInfoRequestByPeer.delete(peerHash);
 	}
 
+	/**
+	 * Applied V2 progress from a peer (a committed Full/Added/Stopped, or a
+	 * rotated capability generation) proves the peer answers. Reset the
+	 * recovery scheduler's unpark escalation so a later stall restarts from
+	 * the base interval. Peer-session rotation resets implicitly: the recovery
+	 * scheduler creates a fresh per-session state.
+	 */
+	private resetReplicationInfoV2RecoveryEscalation(peerHash: string) {
+		const state = this._replicationInfoRequestByPeer.get(peerHash);
+		if (!state || state.peerSession === undefined) {
+			return;
+		}
+		state.attempts = 0;
+		state.parkedSinceMs = undefined;
+	}
+
 	private scheduleReplicationInfoV2Recovery(
 		peer: PublicSignKey,
 		replicationLifecycleController = this._instanceLifecycle
@@ -23463,6 +23539,7 @@ export class SharedLog<
 			attempts: number;
 			timer?: ReturnType<typeof setTimeout>;
 			peerSession: PeerSession;
+			parkedSinceMs?: number;
 		} = {
 			attempts: 0,
 			peerSession,
@@ -23478,6 +23555,24 @@ export class SharedLog<
 			requestStates.delete(peerHash);
 		};
 		const intervalMs = Math.max(50, this.waitForReplicatorRequestIntervalMs);
+		const maxUnparkDelayMs = Math.max(
+			intervalMs,
+			REPLICATION_INFO_V2_RECOVERY_MAX_UNPARK_DELAY,
+		);
+		const unparkDelayMs = () =>
+			Math.min(
+				maxUnparkDelayMs,
+				intervalMs *
+					2 **
+						Math.min(
+							state.attempts,
+							REPLICATION_INFO_V2_RECOVERY_MAX_UNPARK_EXPONENT,
+						),
+			);
+		const arm = (delayMs: number) => {
+			state.timer = setTimeout(tick, delayMs);
+			state.timer.unref?.();
+		};
 		const tick = () => {
 			if (
 				!this.isReplicationLifecycleActive(replicationLifecycleController) ||
@@ -23487,14 +23582,38 @@ export class SharedLog<
 				cancel();
 				return;
 			}
-			this._v2Receive.resumeParkedRequest({
-				peerHash,
-				peerSession,
-				receiveEpoch: this._peerSessions.receiveEpoch(peerHash),
-			});
-			state.attempts++;
-			state.timer = setTimeout(tick, intervalMs);
-			state.timer.unref?.();
+			const receiveEpoch = this._peerSessions.receiveEpoch(peerHash);
+			if (
+				!this._v2Receive.isRequestParked({ peerHash, peerSession, receiveEpoch })
+			) {
+				// Active, or a bounded request cycle is still running its own
+				// exponential retries. Keep polling for the next park.
+				state.parkedSinceMs = undefined;
+				arm(intervalMs);
+				return;
+			}
+			const now = Date.now();
+			if (state.parkedSinceMs === undefined) {
+				state.parkedSinceMs = now;
+			}
+			const resumeAtMs = state.parkedSinceMs + unparkDelayMs();
+			if (now < resumeAtMs) {
+				arm(Math.max(50, resumeAtMs - now));
+				return;
+			}
+			if (
+				this._v2Receive.resumeParkedRequest({
+					peerHash,
+					peerSession,
+					receiveEpoch,
+				})
+			) {
+				// Fruitless until proven otherwise: escalate the next unpark wait.
+				// Applied progress resets via resetReplicationInfoV2RecoveryEscalation.
+				state.attempts++;
+				state.parkedSinceMs = undefined;
+			}
+			arm(intervalMs);
 		};
 		tick();
 	}

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

@@ -991,6 +991,28 @@ export class ReplicationInfoV2ReceiveCoordinator {
 		return true;
 	}
 
+	/**
+	 * Whether the request generation for this exact peer state is parked: the
+	 * bounded retry cycle exhausted its attempts and no timer or send is in
+	 * flight. Read-only probe for the host's recovery scheduler.
+	 */
+	isRequestParked(properties: {
+		peerHash: string;
+		peerSession: object;
+		receiveEpoch: object | null;
+	}): boolean {
+		const state = this._receiveStates.get(properties.peerHash);
+		return (
+			state !== undefined &&
+			state.peerSession === properties.peerSession &&
+			state.receiveEpoch === properties.receiveEpoch &&
+			state.phase !== "active" &&
+			state.requestParked &&
+			state.requestTimer === undefined &&
+			state.requestInFlight === undefined
+		);
+	}
+
 	/**
 	 * Resume only a request generation that exhausted its bounded retries.
 	 * Wait/liveness callers may nudge recovery without invalidating an active,
@@ -1023,7 +1045,24 @@ export class ReplicationInfoV2ReceiveCoordinator {
 		}
 		state.requestAttempts = 0;
 		state.requestsSinceCapabilityRefresh = 0;
-		state.capabilityRefreshRequired = true;
+		if (!state.capabilityRefreshRequired) {
+			// Only rotate the grant when it is genuinely stale: the peer's
+			// capability rotation paths already flagged a refresh, and a missing
+			// or transport-outdated local grant cannot authorize a request. A
+			// still-current grant must keep its challenge so a Full already in
+			// flight for the pre-park request generation still applies.
+			const ready = this._localCapabilityReadyBySession.get(state.peerSession);
+			const grantCurrent =
+				ready !== undefined &&
+				ready.peerHash === state.peerHash &&
+				ready.receiveEpoch === state.receiveEpoch &&
+				ready.receiverTransportSession === state.receiverTransportSession &&
+				ready.receiverTransportSession ===
+					this.deps.getReceiverTransportSession();
+			if (!grantCurrent) {
+				state.capabilityRefreshRequired = true;
+			}
+		}
 		state.requestParked = false;
 		this.armRequest(state, 0);
 		return true;