@loro-dev/streams-crdt 0.13.0 → 0.14.1

package/dist/{stream-id-CvJLq-0s.js → stream-id-CEp4zEQJ.js}

@@ -547,6 +547,28 @@ var AuthProviderError = class extends Error {
 		if (options?.cause !== void 0) this.cause = options.cause;
 	}
 };
+/**
+* Rejection value used for `waitUntilSynced()` when the local append pipeline
+* fails. Carries the structured {@link TransportError} so downstream callers
+* (e.g. CLIs surfacing "N updates not yet uploaded") can branch on
+* `transportError.code` instead of parsing the message.
+*/
+var LocalAppendFailedError = class extends Error {
+	transportError;
+	constructor(transportError) {
+		super(`local append failed: ${transportError.code}`);
+		this.name = "LocalAppendFailedError";
+		this.transportError = transportError;
+	}
+};
+/**
+* True for HTTP 413 responses. The server (or an intermediary proxy) rejected
+* the request body as too large — a deterministic failure for a given payload:
+* retrying the identical bytes cannot succeed while the limit is unchanged.
+*/
+function isPayloadTooLargeError(error) {
+	return error instanceof HttpError && error.status === 413;
+}
 function isObject(value) {
 	return typeof value === "object" && value != null;
 }
@@ -676,6 +698,18 @@ function classifyFetchError(err) {
 		retriable: false,
 		atMs: Date.now()
 	};
+	if (status === 413) return {
+		code: "payload_too_large",
+		message,
+		retriable: false,
+		atMs: Date.now()
+	};
+	if (status === 429) return {
+		code: "server",
+		message,
+		retriable: true,
+		atMs: Date.now()
+	};
 	if (typeof status === "number" && status >= 500 && status < 600) return {
 		code: "server",
 		message,
@@ -763,6 +797,13 @@ function toTransportError(error) {
 		message: error.message,
 		...error.body !== void 0 && { body: error.body }
 	};
+	if (isPayloadTooLargeError(error)) return {
+		code: "payload_too_large",
+		retryable: false,
+		status: 413,
+		message: error.message,
+		...error.body !== void 0 && { body: error.body }
+	};
 	if (error instanceof ProtocolError) return {
 		code: "protocol_error",
 		retryable: false,
@@ -790,7 +831,7 @@ function toTransportError(error) {
 		message: error.message,
 		...error.body !== void 0 && { body: error.body }
 	};
-	if (error instanceof HttpError && error.status >= 500 && error.status < 600) return {
+	if (error instanceof HttpError && (error.status === 429 || error.status >= 500 && error.status < 600)) return {
 		code: "server_error",
 		retryable: true,
 		status: error.status,
@@ -1684,6 +1725,9 @@ var EphemeralStreamCrdt = class {
 			get status() {
 				return state.status;
 			},
+			get pendingLocalCount() {
+				return state.pendingLocal.length;
+			},
 			onStatusChange: (listener) => this.onStatusChange(state, listener),
 			waitUntilSynced: async () => {
 				if (state.closed) throw closedSubscriptionError();
@@ -2335,6 +2379,10 @@ function createJoinState(cursor, liveMode = "sse") {
 		flushingLocal: false,
 		retryAttempt: 0,
 		retrySleepController: new AbortController(),
+		readLoopRunning: false,
+		readErrorRetryAttempt: 0,
+		writeErrorRetryAttempt: 0,
+		flushHeadBatchOnly: false,
 		cursor,
 		liveMode,
 		snapshot: createTransportSnapshotState(),
@@ -2346,6 +2394,14 @@ function createJoinState(cursor, liveMode = "sse") {
 async function disposeJoinState(state, options) {
 	state.closed = true;
 	options.snapshotManager.dispose(state);
+	if (state.readRestartTimer != null) {
+		clearTimeout(state.readRestartTimer);
+		state.readRestartTimer = void 0;
+	}
+	if (state.writeRetryTimer != null) {
+		clearTimeout(state.writeRetryTimer);
+		state.writeRetryTimer = void 0;
+	}
 	const requestController = state.requestController;
 	state.requestController = void 0;
 	const unsubscribeLocal = state.unsubscribeLocal;
@@ -2400,6 +2456,8 @@ var StreamsCrdt = class StreamsCrdt {
 	writeOnlyDisabledReason;
 	joinState;
 	opQueue = Promise.resolve();
+	/** Wall-clock ms of the last durably committed local append, if any. */
+	lastLocalAppendAtMs;
 	/**
 	* Internal catch-up result used when callers need to handle 410 by
 	* preserving local state before rebuilding through bootstrap.
@@ -2519,6 +2577,10 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 		if ((state.readSubStatus === "ok" || state.readSubStatus === "connecting") && state.writeSubStatus === "ok") return;
 		state.retryAttempt = 0;
+		state.readErrorRetryAttempt = 0;
+		state.writeErrorRetryAttempt = 0;
+		this.clearReadRestartTimer(state);
+		this.clearWriteRetryTimer(state);
 		state.retrySleepController.abort();
 		state.retrySleepController = new AbortController();
 		const previousController = state.requestController;
@@ -2535,6 +2597,23 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 	}
 	/**
+	* Reports current local upload health for this transport.
+	*
+	* In join mode this reflects the live room's pending queue; in write-only
+	* mode it reflects the write-only queue. Intended for downstream tooling
+	* (e.g. a CLI showing "N updates not yet uploaded" plus the blocking
+	* error) without needing a `TransportSubscription` reference.
+	*/
+	getLocalSyncStats() {
+		const state = this.joinState;
+		return {
+			pendingLocalCount: state != null && !state.closed ? state.pendingLocal.length : this.writeOnlyDisabledReason == null ? this.pendingWriteOnly.length : 0,
+			...this.lastLocalAppendAtMs !== void 0 && { lastLocalAppendAtMs: this.lastLocalAppendAtMs },
+			...state?.lastError !== void 0 && { lastError: state.lastError },
+			...state?.lastWriteError !== void 0 && { lastWriteError: state.lastWriteError }
+		};
+	}
+	/**
 	* Reads the latest remote snapshot offset, if the server exposes one.
 	*/
 	async getSnapshotOffset() {
@@ -2763,6 +2842,7 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 	}
 	createSubscription(state, params) {
+		const self = this;
 		state.refCount += 1;
 		const statusListener = params?.onStatusChange;
 		if (statusListener != null) {
@@ -2790,6 +2870,15 @@ var StreamsCrdt = class StreamsCrdt {
 			get lastError() {
 				return state.lastError;
 			},
+			get pendingLocalCount() {
+				return state.pendingLocal.length;
+			},
+			get lastLocalAppendAtMs() {
+				return self.lastLocalAppendAtMs;
+			},
+			get lastWriteError() {
+				return state.lastWriteError;
+			},
 			onStatusChange: (listener) => {
 				state.statusListeners.add(listener);
 				listener(state.status);
@@ -2809,6 +2898,7 @@ var StreamsCrdt = class StreamsCrdt {
 					throw new Error(te.code ? `initial sync failed: ${te.code}` : "initial sync failed");
 				}
 				if (state.writeSubStatus === "error") {
+					if (state.lastWriteError != null) throw new LocalAppendFailedError(state.lastWriteError);
 					const msg = state.lastError?.code ? `local append failed: ${state.lastError.code}` : "local append failed";
 					throw new Error(msg);
 				}
@@ -3093,7 +3183,7 @@ var StreamsCrdt = class StreamsCrdt {
 			state.lastError = void 0;
 			this.setReadSubStatus(state, "ok");
 			if (state.pendingLocal.length > 0) this.flushPendingLocal(state);
-			return true;
+			return "recovered";
 		} catch (error) {
 			const classified = classifyFetchError(error);
 			this.logError("live incomplete apply recovery failed", error, {
@@ -3101,8 +3191,12 @@ var StreamsCrdt = class StreamsCrdt {
 				code: classified.code
 			});
 			state.lastError = toTransportError(error);
-			this.setReadSubStatus(state, classified.retriable ? "disconnected" : "error");
-			return false;
+			if (classified.retriable && !isAuthOrProtocolError(error)) {
+				this.setReadSubStatus(state, "reconnecting");
+				return "retry";
+			}
+			this.setReadSubStatus(state, "error");
+			return "terminal";
 		}
 	}
 	async appendLocalBatch(cursor, batch, pendingCount, streamCursor) {
@@ -3227,6 +3321,7 @@ var StreamsCrdt = class StreamsCrdt {
 		this.producerEpoch = ack.epoch;
 		this.nextProducerSeq = ack.seq + 1;
 		this.frozenLocalAppend = void 0;
+		this.lastLocalAppendAtMs = Date.now();
 	}
 	abandonFrozenLocalAppend(frozen) {
 		if (this.frozenLocalAppend !== frozen) return;
@@ -3348,6 +3443,98 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 	}
 	async runReadLoop(state) {
+		if (state.readLoopRunning) return;
+		state.readLoopRunning = true;
+		this.clearReadRestartTimer(state);
+		try {
+			await this.runReadLoopIterations(state);
+		} finally {
+			state.readLoopRunning = false;
+		}
+		this.maybeScheduleReadLoopRestart(state);
+	}
+	/**
+	* Schedules a background self-restart of the read loop after it exits with
+	* a terminal-class ("error") failure.
+	*
+	* Non-retryable errors (auth failure, protocol error, stream 404) used to
+	* stop the live read loop permanently — the room's remote cursor silently
+	* froze until a process restart. Instead, the room stays in "error" status
+	* (callers still see the failure via `status`/`lastError`) while a capped
+	* exponential backoff (floor 1s, cap = last reconnect-table delay, with
+	* jitter) keeps retrying in the background. Each retry issues fresh
+	* requests, and every request re-runs the auth callback — on a 401/403 the
+	* HTTP layer additionally forces a token refresh (`reason: "unauthorized"`)
+	* and retries that request once — so refreshed credentials are picked up
+	* without any caller intervention.
+	*
+	* "disconnected" (a finite `maxAttempts` budget exhausted on retryable
+	* errors) intentionally stays terminal-until-`rejoin()`: a finite budget is
+	* an explicit opt-in to giving up.
+	*/
+	maybeScheduleReadLoopRestart(state) {
+		if (state.closed || this.joinState !== state || !this.readLoopNeedsRestart(state) || state.readRestartTimer != null || state.readLoopRunning) return;
+		const delay = reconnectDelayWithFloor(state.readErrorRetryAttempt, this.reconnectConfig);
+		state.readErrorRetryAttempt += 1;
+		state.readRestartTimer = setTimeout(() => {
+			state.readRestartTimer = void 0;
+			if (state.closed || this.joinState !== state || !this.readLoopNeedsRestart(state)) return;
+			this.runReadLoop(state);
+		}, delay);
+	}
+	/**
+	* Whether an exited read loop still needs a background restart.
+	*
+	* Only ever evaluated after the loop has unwound (from
+	* `maybeScheduleReadLoopRestart`, called at `runReadLoop`'s tail). "error" is
+	* the ordinary terminal-class exit. "reconnecting" here is the anomalous case
+	* where `rejoin()` ran re-entrantly from a status listener *during* the loop's
+	* terminal `setReadSubStatus("error")`: it flipped the sub-status to
+	* "reconnecting" and fire-and-forgot `runReadLoop`, but that no-oped because
+	* the loop was still on the stack — so without this, the loop would exit and
+	* nothing would ever restart it (a permanent stall, the very failure mode this
+	* file removes). "disconnected" (a finite `maxAttempts` budget) stays terminal
+	* by design, and "ok"/"connecting" don't reach this path via an exit.
+	*/
+	readLoopNeedsRestart(state) {
+		return state.readSubStatus === "error" || state.readSubStatus === "reconnecting";
+	}
+	clearReadRestartTimer(state) {
+		if (state.readRestartTimer != null) {
+			clearTimeout(state.readRestartTimer);
+			state.readRestartTimer = void 0;
+		}
+	}
+	clearWriteRetryTimer(state) {
+		if (state.writeRetryTimer != null) {
+			clearTimeout(state.writeRetryTimer);
+			state.writeRetryTimer = void 0;
+		}
+	}
+	/**
+	* Applies the budgeted backoff for a retryable read-loop failure.
+	*
+	* Returns `true` when the loop should continue with the next attempt, or
+	* `false` (after surfacing "disconnected") when a finite retry budget is
+	* exhausted.
+	*/
+	async awaitReadRetryBackoff(state, error) {
+		const maxAttempts = this.reconnectConfig.maxAttempts;
+		if (state.retryAttempt >= maxAttempts) {
+			this.logError("live read reconnect exhausted", error, {
+				streamUrl: this.streamUrl,
+				attempts: state.retryAttempt
+			});
+			state.lastError = toTransportError(error);
+			this.setReadSubStatus(state, "disconnected");
+			return false;
+		}
+		const delay = computeRetryDelay(state.retryAttempt, this.reconnectConfig, error instanceof HttpError ? error.retryAfterMs : void 0);
+		state.retryAttempt += 1;
+		await sleep(delay, state.retrySleepController.signal);
+		return true;
+	}
+	async runReadLoopIterations(state) {
 		state.requestController ??= new AbortController();
 		while (!state.closed) {
 			const capturedController = state.requestController;
@@ -3480,7 +3667,10 @@ var StreamsCrdt = class StreamsCrdt {
 				if (state.closed) return;
 				if (error instanceof CrdtApplyIncompleteError) {
 					if (capturedController?.signal.aborted && state.requestController === capturedController) state.requestController = new AbortController();
-					if (await this.recoverLiveIncompleteRemoteApply(state)) continue;
+					const recovery = await this.recoverLiveIncompleteRemoteApply(state);
+					if (recovery === "recovered") continue;
+					if (recovery === "terminal") return;
+					if (await this.awaitReadRetryBackoff(state, error)) continue;
 					return;
 				}
 				if (capturedController?.signal.aborted) {
@@ -3511,7 +3701,10 @@ var StreamsCrdt = class StreamsCrdt {
 					const flushError = abortReason instanceof Error ? abortReason : error;
 					if (flushError instanceof CrdtApplyIncompleteError) {
 						if (state.requestController === capturedController) state.requestController = new AbortController();
-						if (await this.recoverLiveIncompleteRemoteApply(state)) continue;
+						const recovery = await this.recoverLiveIncompleteRemoteApply(state);
+						if (recovery === "recovered") continue;
+						if (recovery === "terminal") return;
+						if (await this.awaitReadRetryBackoff(state, flushError)) continue;
 						return;
 					}
 					if (flushError instanceof Error && !(flushError instanceof DOMException && flushError.name === "AbortError")) {
@@ -3542,19 +3735,7 @@ var StreamsCrdt = class StreamsCrdt {
 				}
 				this.setReadSubStatus(state, "reconnecting");
 				if (sseOpenedAtMs > 0 && Date.now() - sseOpenedAtMs >= 5e3) state.retryAttempt = 0;
-				const maxAttempts = this.reconnectConfig.maxAttempts;
-				if (state.retryAttempt >= maxAttempts) {
-					this.logError("live read reconnect exhausted", error, {
-						streamUrl: this.streamUrl,
-						attempts: state.retryAttempt
-					});
-					state.lastError = toTransportError(error);
-					this.setReadSubStatus(state, "disconnected");
-					return;
-				}
-				const delay = computeRetryDelay(state.retryAttempt, this.reconnectConfig, error instanceof HttpError ? error.retryAfterMs : void 0);
-				state.retryAttempt += 1;
-				await sleep(delay, state.retrySleepController.signal);
+				if (!await this.awaitReadRetryBackoff(state, error)) return;
 			}
 		}
 	}
@@ -3564,16 +3745,19 @@ var StreamsCrdt = class StreamsCrdt {
 	* Drain up to `MAX_BATCH_BYTES` worth of queued batches from the front of
 	* `pendingLocal` and merge them into a single `CrdtUpdateBatch`.
 	*
+	* `maxCount` optionally caps how many queued batches may be merged (used to
+	* isolate the head batch after a 413 rejection).
+	*
 	* Returns `undefined` when the queue is empty.
 	*/
-	async drainQueuedBatch(pendingLocal) {
+	async drainQueuedBatch(pendingLocal, maxCount) {
 		const first = pendingLocal.peekFront();
 		if (first == null) return;
 		const maxBytes = StreamsCrdt.MAX_BATCH_BYTES;
 		let mergedVersion = first.version;
 		const allUpdates = Array.from(first.updates);
 		let count = 1;
-		while (count < pendingLocal.length) {
+		while (count < pendingLocal.length && (maxCount == null || count < maxCount)) {
 			const next = pendingLocal.at(count);
 			const candidateUpdates = [...allUpdates, ...next.updates];
 			if (await this.measureAppendBodyByteLength(candidateUpdates) > maxBytes) break;
@@ -3594,17 +3778,32 @@ var StreamsCrdt = class StreamsCrdt {
 		};
 	}
 	drainPendingBatch(state) {
-		return this.drainQueuedBatch(state.pendingLocal);
+		return this.drainQueuedBatch(state.pendingLocal, state.flushHeadBatchOnly ? 1 : void 0);
 	}
 	drainPendingWriteOnlyBatch() {
 		return this.drainQueuedBatch(this.pendingWriteOnly);
 	}
+	/**
+	* Drains `pendingLocal` to the server in strict FIFO order.
+	*
+	* FIFO invariant: batches are only popped after a durable append, and a
+	* failing head batch is retried in place — never skipped, dropped, or
+	* reordered. See the `JoinState.pendingLocal` doc for why this strictness
+	* (rather than a version-vector diff upload) is what prevents undetectable
+	* per-author holes.
+	*
+	* Failure handling is self-healing: a terminal-class failure surfaces
+	* `"error"` write status (with `lastWriteError` set) and then retries via
+	* this flush's own backoff timer (`maybeScheduleWriteRetry`) — it does not
+	* depend on a future local op to re-trigger the flush.
+	*/
 	async flushPendingLocal(state) {
 		if (state.flushingLocal || state.closed) return;
 		if (!this.cursorManager.isCursorComplete(state.cursor)) return;
+		this.clearWriteRetryTimer(state);
 		state.flushingLocal = true;
 		try {
-			while (!state.closed) {
+			outer: while (!state.closed) {
 				const drained = await this.drainPendingBatch(state);
 				if (drained == null) return;
 				let attempts = 0;
@@ -3615,24 +3814,34 @@ var StreamsCrdt = class StreamsCrdt {
 					const committedCount = this.consumeCommittedPendingCount() ?? drained.count;
 					for (let i = 0; i < committedCount; i += 1) state.pendingLocal.popFront();
 					this.notifySyncWaiters(state, committedCount);
+					state.flushHeadBatchOnly = false;
+					state.lastWriteError = void 0;
 					this.setWriteSubStatus(state, "ok");
 					this.snapshotManager.schedule(state);
 					break;
 				} catch (error) {
+					if (isPayloadTooLargeError(error) && drained.count > 1 && this.abandonPendingFrozenLocalAppend()) {
+						state.flushHeadBatchOnly = true;
+						continue outer;
+					}
 					const classified = classifyFetchError(error);
+					const transportError = toTransportError(error);
 					if (!classified.retriable || isAuthOrProtocolError(error)) {
+						if (isPayloadTooLargeError(error)) state.flushHeadBatchOnly = true;
 						this.logError("local append failed", error, {
 							streamUrl: this.streamUrl,
 							code: classified.code
 						});
-						state.lastError = toTransportError(error);
-						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error(`local append failed: ${classified.code}`));
+						state.lastError = transportError;
+						state.lastWriteError = transportError;
+						this.rejectSyncWaiters(state, new LocalAppendFailedError(transportError));
 						this.setWriteSubStatus(state, "error");
 						return;
 					}
 					const maxAttempts = this.reconnectConfig.maxAttempts;
 					if (attempts >= maxAttempts) {
-						state.lastError = toTransportError(error);
+						state.lastError = transportError;
+						state.lastWriteError = transportError;
 						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error("local append retry budget exhausted"));
 						this.setWriteSubStatus(state, "error");
 						return;
@@ -3645,9 +3854,44 @@ var StreamsCrdt = class StreamsCrdt {
 			}
 		} finally {
 			state.flushingLocal = false;
+			this.maybeScheduleWriteRetry(state);
 		}
 	}
 	/**
+	* Abandons the current frozen "pending" append, fencing its producer
+	* session. Only safe when the server definitively did not append the frozen
+	* body (e.g. a 413 rejection happens before any append). Returns `false`
+	* when there is no matching frozen pending append to abandon.
+	*/
+	abandonPendingFrozenLocalAppend() {
+		const frozen = this.frozenLocalAppend;
+		if (frozen == null || frozen.source !== "pending") return false;
+		this.abandonFrozenLocalAppend(frozen);
+		return true;
+	}
+	/**
+	* Schedules a self-driven retry of the pending-local flush after a
+	* terminal-class failure.
+	*
+	* Historically a non-retryable append error parked the queue until the next
+	* local op happened to trigger a flush — an idle session with stranded
+	* updates would never upload them (data stayed local until process
+	* restart). The write queue now owns its retry timer: capped exponential
+	* backoff (floor 1s, cap = last reconnect-table delay, jittered),
+	* independent of new local ops. `rejoin()` and fresh local ops still retry
+	* immediately.
+	*/
+	maybeScheduleWriteRetry(state) {
+		if (state.closed || this.joinState !== state || state.writeSubStatus !== "error" || state.pendingLocal.length === 0 || state.writeRetryTimer != null || state.flushingLocal) return;
+		const delay = reconnectDelayWithFloor(state.writeErrorRetryAttempt, this.reconnectConfig);
+		state.writeErrorRetryAttempt += 1;
+		state.writeRetryTimer = setTimeout(() => {
+			state.writeRetryTimer = void 0;
+			if (state.closed || this.joinState !== state) return;
+			this.flushPendingLocal(state);
+		}, delay);
+	}
+	/**
 	* Decrements all sync waiters by the number of flushed batches and
 	* resolves any that have reached zero.
 	*/
@@ -3675,11 +3919,13 @@ var StreamsCrdt = class StreamsCrdt {
 		});
 	}
 	setReadSubStatus(state, sub) {
+		if (sub === "ok") state.readErrorRetryAttempt = 0;
 		if (state.readSubStatus === sub) return;
 		state.readSubStatus = sub;
 		this.recomputeJoinStatus(state);
 	}
 	setWriteSubStatus(state, sub) {
+		if (sub === "ok") state.writeErrorRetryAttempt = 0;
 		if (state.writeSubStatus === sub) return;
 		state.writeSubStatus = sub;
 		this.recomputeJoinStatus(state);
@@ -3768,6 +4014,6 @@ function createStreamUrl(input) {
 	return `${baseUrl}/ds/${encodeURIComponent(input.bucketId)}/${encodeURIComponent(streamId)}`;
 }
 //#endregion
-export { InMemoryRemoteCursorStore as a, EphemeralStreamCrdt as c, StreamsCrdt as i, PayloadProtectionError as l, isValidBucketId as n, IndexedDbRemoteCursorStore as o, isValidRillId as r, createInitialRemoteCursor as s, createStreamUrl as t };
+export { InMemoryRemoteCursorStore as a, EphemeralStreamCrdt as c, StreamsCrdt as i, LocalAppendFailedError as l, isValidBucketId as n, IndexedDbRemoteCursorStore as o, isValidRillId as r, createInitialRemoteCursor as s, createStreamUrl as t, PayloadProtectionError as u };
 
-//# sourceMappingURL=stream-id-CvJLq-0s.js.map
+//# sourceMappingURL=stream-id-CEp4zEQJ.js.map