@peerbit/shared-log 16.0.26 → 16.0.28

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

@@ -122,11 +122,46 @@ type ReplicationInfoV2RemoteFullRearm = {
 	receiveEpoch: object | null;
 	receiverTransportSession: bigint;
 	nextAttemptAt: number;
+	attemptsStarted: number;
 	outstandingAttempts: number;
 	inFlight?: Promise<void>;
 	controller?: AbortController;
 };
 
+export type ReplicationInfoV2ReceiveDiagnostic = Readonly<{
+	state: "absent" | "current" | "stale";
+	/** Current-state classification; no historical packet/drop log is retained. */
+	reason:
+		| "state-absent"
+		| "peer-session-mismatch"
+		| "receive-epoch-mismatch"
+		| "transport-session-mismatch"
+		| "state-not-current"
+		| "admission-pending"
+		| "active"
+		| "request-parked"
+		| "request-in-flight"
+		| "request-scheduled"
+		| "awaiting-full"
+		| "resync";
+	phase?: ReplicationInfoV2ReceivePhase;
+	requestState?:
+		| "idle"
+		| "scheduled"
+		| "in-flight"
+		| "parked"
+		| "admission-pending";
+	lastAppliedSequence?: string;
+	requestAttempts?: number;
+	capabilityAdvertisementAttempts: number;
+	capabilityAdvertisement: "absent" | "advertising" | "ready" | "stale";
+	remoteFullRearm: "idle" | "in-flight" | "cooldown" | "limited";
+	remoteFullRearmAttempts: number;
+	remoteFullRearmOutstanding: number;
+	remoteFullRearmGlobalOutstanding: number;
+	remoteFullRearmCooldownRemainingMs?: number;
+}>;
+
 export type ReplicationInfoV2LocalCapabilityRefresh = {
 	receiverTransportSession: bigint;
 	requestNotBeforeMs: number;
@@ -796,6 +831,7 @@ export class ReplicationInfoV2ReceiveCoordinator {
 				receiveEpoch: properties.receiveEpoch,
 				receiverTransportSession,
 				nextAttemptAt: now + this.remoteFullRearmCooldownMs,
+				attemptsStarted: 0,
 				outstandingAttempts: 0,
 			};
 			this._remoteFullRearmBySession.set(properties.peerSession, rearm);
@@ -804,6 +840,10 @@ export class ReplicationInfoV2ReceiveCoordinator {
 		}
 		const attemptState = rearm;
 		const outstandingReservation = {};
+		attemptState.attemptsStarted = Math.min(
+			MAX_REMOTE_FULL_REARM_OUTSTANDING_GLOBAL,
+			attemptState.attemptsStarted + 1,
+		);
 		attemptState.outstandingAttempts++;
 		this._remoteFullRearmOutstanding.add(outstandingReservation);
 
@@ -916,6 +956,175 @@ export class ReplicationInfoV2ReceiveCoordinator {
 		return true;
 	}
 
+	/**
+	 * Bounded, read-only state for persisted-readiness troubleshooting. This
+	 * intentionally omits transport sessions, challenges, payloads, and maps.
+	 */
+	diagnosePeer(properties: {
+		peerHash: string;
+		peerSession?: object;
+		receiveEpoch?: object | null;
+		senderTransportSession?: bigint;
+	}): ReplicationInfoV2ReceiveDiagnostic {
+		const state = this._receiveStates.get(properties.peerHash);
+		const advertisement = this._localCapabilityAdvertisementsByPeer.get(
+			properties.peerHash,
+		);
+		const session =
+			properties.peerSession ??
+			state?.peerSession ??
+			advertisement?.peerSession;
+		const ready = session
+			? this._localCapabilityReadyBySession.get(session)
+			: undefined;
+		let capabilityAdvertisement: ReplicationInfoV2ReceiveDiagnostic["capabilityAdvertisement"] =
+			"absent";
+		if (ready && ready.peerHash === properties.peerHash) {
+			capabilityAdvertisement =
+				session !== undefined &&
+				this.deps.isPeerSessionCurrent(properties.peerHash, session) &&
+				this.deps.isReceiveEpochCurrent(
+					properties.peerHash,
+					ready.receiveEpoch,
+				) &&
+				ready.receiverTransportSession ===
+					this.deps.getReceiverTransportSession() &&
+				(properties.receiveEpoch === undefined ||
+					ready.receiveEpoch === properties.receiveEpoch)
+					? "ready"
+					: "stale";
+		} else if (advertisement) {
+			capabilityAdvertisement =
+				advertisement.peerHash === properties.peerHash &&
+				advertisement.peerSession === session &&
+				(properties.receiveEpoch === undefined ||
+					advertisement.receiveEpoch === properties.receiveEpoch) &&
+				this.isLocalCapabilityAdvertisementGenerationCurrent(advertisement)
+					? "advertising"
+					: "stale";
+		}
+
+		const rearm = session
+			? this._remoteFullRearmBySession.get(session)
+			: undefined;
+		const now = this.now();
+		const rearmLimited =
+			(rearm?.outstandingAttempts ?? 0) >=
+				MAX_REMOTE_FULL_REARM_OUTSTANDING_PER_SESSION ||
+			this._remoteFullRearmOutstanding.size >=
+				this.maxRemoteFullRearmOutstandingGlobal;
+		const rearmStatus: ReplicationInfoV2ReceiveDiagnostic["remoteFullRearm"] =
+			rearm?.inFlight
+				? "in-flight"
+				: rearmLimited
+					? "limited"
+					: rearm && now < rearm.nextAttemptAt
+						? "cooldown"
+						: "idle";
+		const common = {
+			capabilityAdvertisementAttempts: Math.min(
+				MAX_BACKOFF_EXPONENT + 1,
+				Math.max(0, advertisement?.attempts ?? 0),
+			),
+			capabilityAdvertisement,
+			remoteFullRearm: rearmStatus,
+			remoteFullRearmAttempts: Math.min(
+				MAX_REMOTE_FULL_REARM_OUTSTANDING_GLOBAL,
+				Math.max(0, rearm?.attemptsStarted ?? 0),
+			),
+			remoteFullRearmOutstanding: Math.min(
+				MAX_REMOTE_FULL_REARM_OUTSTANDING_PER_SESSION,
+				Math.max(0, rearm?.outstandingAttempts ?? 0),
+			),
+			remoteFullRearmGlobalOutstanding: Math.min(
+				this.maxRemoteFullRearmOutstandingGlobal,
+				this._remoteFullRearmOutstanding.size,
+			),
+			...(rearm && now < rearm.nextAttemptAt
+				? {
+						remoteFullRearmCooldownRemainingMs: Math.min(
+							MAX_TIMER_MS,
+							Math.max(0, rearm.nextAttemptAt - now),
+						),
+					}
+				: {}),
+		};
+		if (!state) {
+			return Object.freeze({
+				state: "absent" as const,
+				reason: "state-absent" as const,
+				...common,
+			});
+		}
+
+		let status: "current" | "stale" = "current";
+		let reason: ReplicationInfoV2ReceiveDiagnostic["reason"];
+		if (
+			properties.peerSession !== undefined &&
+			state.peerSession !== properties.peerSession
+		) {
+			status = "stale";
+			reason = "peer-session-mismatch";
+		} else if (
+			properties.receiveEpoch !== undefined &&
+			state.receiveEpoch !== properties.receiveEpoch
+		) {
+			status = "stale";
+			reason = "receive-epoch-mismatch";
+		} else if (
+			properties.senderTransportSession !== undefined &&
+			state.senderTransportSession !== properties.senderTransportSession
+		) {
+			status = "stale";
+			reason = "transport-session-mismatch";
+		} else if (!this.isStateCurrent(state)) {
+			status = "stale";
+			reason = "state-not-current";
+		} else if (
+			state.reservedAdmission !== undefined ||
+			this._reservedAdmissionsByPeer.has(properties.peerHash)
+		) {
+			reason = "admission-pending";
+		} else if (state.phase === "active") {
+			reason = "active";
+		} else if (state.requestParked) {
+			reason = "request-parked";
+		} else if (state.requestInFlight !== undefined) {
+			reason = "request-in-flight";
+		} else if (state.requestTimer !== undefined) {
+			reason = "request-scheduled";
+		} else {
+			reason = state.phase;
+		}
+		const requestState: NonNullable<
+			ReplicationInfoV2ReceiveDiagnostic["requestState"]
+		> =
+			state.reservedAdmission !== undefined ||
+			this._reservedAdmissionsByPeer.has(properties.peerHash)
+				? "admission-pending"
+				: state.requestParked
+					? "parked"
+					: state.requestInFlight !== undefined
+						? "in-flight"
+						: state.requestTimer !== undefined
+							? "scheduled"
+							: "idle";
+		return Object.freeze({
+			state: status,
+			reason,
+			phase: state.phase,
+			requestState,
+			...(state.lastSequence === undefined
+				? {}
+				: { lastAppliedSequence: state.lastSequence.toString() }),
+			requestAttempts: Math.min(
+				this.requestMaxAttempts,
+				Math.max(0, state.requestAttempts),
+			),
+			...common,
+		});
+	}
+
 	private promoteLocalCapabilityAdvertisement(
 		state: ReplicationInfoV2LocalCapabilityAdvertisement,
 	): boolean {

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

@@ -55,6 +55,7 @@ type ApplicationConfirmationTarget = {
 type ApplicationConfirmationWaiter = {
 	revision: bigint;
 	minPeers: number;
+	startedAt: number;
 	target?: ApplicationConfirmationTarget;
 	resolve: () => void;
 	reject: (error: unknown) => void;
@@ -63,6 +64,37 @@ type ApplicationConfirmationWaiter = {
 	onAbort?: () => void;
 };
 
+export type ReplicationInfoV2SendDiagnostic = Readonly<{
+	state: "absent" | "current" | "stale";
+	/** Current-state classification; no historical packet/drop log is retained. */
+	reason:
+		| "state-absent"
+		| "state-retiring"
+		| "peer-session-mismatch"
+		| "transport-session-mismatch"
+		| "destination-not-current"
+		| "destination-not-open"
+		| "ownership-inactive"
+		| "retry-backoff"
+		| "send-in-flight"
+		| "send-pending"
+		| "confirmation-in-flight"
+		| "latest-applied"
+		| "latest-unconfirmed";
+	established?: boolean;
+	suspended?: boolean;
+	currentRevision: string;
+	pendingRevision?: string;
+	inFlightRevision?: string;
+	inFlightSequence?: string;
+	appliedRevision?: string;
+	confirmationRevision?: string;
+	confirmationSequence?: string;
+	retryAttempts?: number;
+	confirmationWaiters: number;
+	oldestConfirmationAgeMs?: number;
+}>;
+
 export type ReplicationInfoV2ConfirmationOptions = {
 	/** Distinct current peers that must report durable application. Defaults to 1. */
 	minPeers?: number;
@@ -460,6 +492,7 @@ export class ReplicationInfoV2SendCoordinator<R extends "u32" | "u64"> {
 			const waiter: ApplicationConfirmationWaiter = {
 				revision: this._revision,
 				minPeers: properties.minPeers,
+				startedAt: Date.now(),
 				target: properties.target ? { ...properties.target } : undefined,
 				resolve,
 				reject,
@@ -488,6 +521,137 @@ export class ReplicationInfoV2SendCoordinator<R extends "u32" | "u64"> {
 		});
 	}
 
+	/**
+	 * Bounded, read-only state for persisted-readiness troubleshooting. Opaque
+	 * session/challenge values and peer maps are intentionally excluded.
+	 */
+	diagnosePeer(target: {
+		peerHash: string;
+		peerSession?: object;
+		receiverTransportSession?: bigint;
+	}): ReplicationInfoV2SendDiagnostic {
+		const state = this._sendStates.get(target.peerHash);
+		let matchingConfirmationCount = 0;
+		let oldestStartedAt: number | undefined;
+		for (const waiter of this._confirmations) {
+			if (
+				waiter.target?.peerHash !== target.peerHash ||
+				(target.peerSession !== undefined &&
+					waiter.target.peerSession !== target.peerSession) ||
+				(target.receiverTransportSession !== undefined &&
+					waiter.target.receiverTransportSession !==
+						target.receiverTransportSession)
+			) {
+				continue;
+			}
+			matchingConfirmationCount++;
+			oldestStartedAt =
+				oldestStartedAt === undefined
+					? waiter.startedAt
+					: Math.min(oldestStartedAt, waiter.startedAt);
+		}
+		const common = {
+			currentRevision: this._revision.toString(),
+			confirmationWaiters: Math.min(
+				this.maxConfirmationWaiters,
+				matchingConfirmationCount,
+			),
+			...(oldestStartedAt === undefined
+				? {}
+				: {
+						oldestConfirmationAgeMs: Math.min(
+							MAX_TIMER_MS,
+							Math.max(0, Date.now() - oldestStartedAt),
+						),
+					}),
+		};
+		if (!state) {
+			return Object.freeze({
+				state: this._retiringWorkersByPeer.has(target.peerHash)
+					? ("stale" as const)
+					: ("absent" as const),
+				reason: this._retiringWorkersByPeer.has(target.peerHash)
+					? ("state-retiring" as const)
+					: ("state-absent" as const),
+				...common,
+			});
+		}
+
+		let status: "current" | "stale" = "current";
+		let reason: ReplicationInfoV2SendDiagnostic["reason"];
+		if (
+			target.peerSession !== undefined &&
+			state.peerSession !== target.peerSession
+		) {
+			status = "stale";
+			reason = "peer-session-mismatch";
+		} else if (
+			target.receiverTransportSession !== undefined &&
+			state.receiverTransportSession !== target.receiverTransportSession
+		) {
+			status = "stale";
+			reason = "transport-session-mismatch";
+		} else if (!this.isDestinationCurrent(state)) {
+			status = "stale";
+			reason = "destination-not-current";
+		} else if (!this.isDestinationReady(state)) {
+			reason = "destination-not-open";
+		} else if (
+			!this.deps.isReplicationOwnershipLifecycleActive(
+				state.ownershipLifecycleController,
+			)
+		) {
+			reason = "ownership-inactive";
+		} else if (state.suspended || state.retryTimer !== undefined) {
+			reason = "retry-backoff";
+		} else if (state.applicationConfirmationRequest !== undefined) {
+			reason = "confirmation-in-flight";
+		} else if (state.inFlightRevision !== undefined) {
+			reason = "send-in-flight";
+		} else if (state.pending !== undefined) {
+			reason = "send-pending";
+		} else if (
+			state.appliedRevision !== undefined &&
+			state.appliedRevision >= this._revision
+		) {
+			reason = "latest-applied";
+		} else {
+			reason = "latest-unconfirmed";
+		}
+
+		return Object.freeze({
+			state: status,
+			reason,
+			established: state.established,
+			suspended: state.suspended,
+			...common,
+			...(state.pending === undefined
+				? {}
+				: { pendingRevision: state.pending.revision.toString() }),
+			...(state.inFlightRevision === undefined
+				? {}
+				: { inFlightRevision: state.inFlightRevision.toString() }),
+			...(state.inFlightSequence === undefined
+				? {}
+				: { inFlightSequence: state.inFlightSequence.toString() }),
+			...(state.appliedRevision === undefined
+				? {}
+				: { appliedRevision: state.appliedRevision.toString() }),
+			...(state.applicationConfirmationRequest === undefined
+				? {}
+				: {
+						confirmationRevision:
+							state.applicationConfirmationRequest.revision.toString(),
+						confirmationSequence:
+							state.applicationConfirmationRequest.sequence.toString(),
+					}),
+			retryAttempts: Math.min(
+				MAX_BACKOFF_EXPONENT + 1,
+				Math.max(0, state.retryAttempts),
+			),
+		});
+	}
+
 	/**
 	 * Wait until the latest committed local replication revision is reported as
 	 * durably applied by the configured number of current peers. Revisions newer