@spectrum-ts/core 5.2.0 → 6.1.0

package/dist/authoring.d.ts

@@ -69,6 +69,18 @@ interface ResumableOrderedStreamOptions<TLive, TMissed, TOutput> {
   maxRetryDelayMs?: number;
   processLive: (event: TLive) => Promise<ResumableStreamItem<TOutput>>;
   processMissed: (event: TMissed) => Promise<ResumableStreamItem<TOutput>>;
+  /**
+   * Invoked when reconnects have failed persistently (the consecutive-failure
+   * count has reached a multiple of `PERSISTENT_FAILURE_ERROR_THRESHOLD`) to
+   * rebuild state a plain reconnect cannot refresh — e.g. re-mint an auth token
+   * the server rejects after a restart. Runs between the failure and the next
+   * retry, throttled to once per threshold window, and resets once the stream
+   * recovers. Errors thrown are logged and swallowed; the reconnect loop
+   * continues either way, so a recover that itself fails is harmless.
+   */
+  recover?: (error: unknown, failureCount: number) => Promise<void> | void;
+  /** Cap on how long a `recover` hook may run before it is abandoned; injectable for tests. */
+  recoverTimeoutMs?: number;
   subscribeLive: (cursor?: string) => CloseableAsyncIterable<TLive>;
 }
 /**

package/dist/authoring.js

@@ -147,6 +147,18 @@ const closeIterable = async (iterable) => {
 	await iterable.close?.();
 };
 const ignoreCleanupError = () => void 0;
+const RECOVER_TIMEOUT_MS = 3e4;
+const runWithTimeout = async (work, timeoutMs, onTimeout) => {
+	work.catch(ignoreCleanupError);
+	let timer;
+	try {
+		await Promise.race([work, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(onTimeout()), timeoutMs);
+		})]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+};
 const jitterDelay = (delayMs) => delayMs * (.5 + Math.random() * .5);
 async function* throwOnCursorRejection(source, isCursorRejected) {
 	try {
@@ -178,10 +190,12 @@ const resumableOrderedStream = (options) => stream((emit, end) => {
 	const initialRetryDelayMs = options.initialRetryDelayMs ?? 500;
 	const maxRetryDelayMs = options.maxRetryDelayMs ?? 3e4;
 	const jitter = options.jitter ?? jitterDelay;
+	const recoverTimeoutMs = options.recoverTimeoutMs ?? RECOVER_TIMEOUT_MS;
 	const label = options.label;
 	let activeLive;
 	let closed = false;
 	let failedAttempts = 0;
+	let lastRecoverAttempt = 0;
 	let lastCursor;
 	let retryDelayMs = initialRetryDelayMs;
 	let sleepTimer;
@@ -197,6 +211,7 @@ const resumableOrderedStream = (options) => stream((emit, end) => {
 	});
 	const noteRecovery = () => {
 		retryDelayMs = initialRetryDelayMs;
+		lastRecoverAttempt = 0;
 		if (failedAttempts === 0) return;
 		log.info("stream recovered", {
 			"spectrum.stream.id": streamId,
@@ -267,6 +282,25 @@ const resumableOrderedStream = (options) => stream((emit, end) => {
 		log.warn("stream interrupted; reconnecting", attrs, error);
 		return delayMs;
 	};
+	const maybeRecover = async (error) => {
+		if (!options.recover || failedAttempts < 5 || failedAttempts - lastRecoverAttempt < 5) return;
+		lastRecoverAttempt = failedAttempts;
+		try {
+			await runWithTimeout(Promise.resolve(options.recover(error, failedAttempts)), recoverTimeoutMs, () => /* @__PURE__ */ new Error(`recover hook did not settle within ${recoverTimeoutMs}ms`));
+			log.info("stream recover hook ran", {
+				"spectrum.stream.id": streamId,
+				"spectrum.stream.label": label,
+				"spectrum.stream.attempt": failedAttempts
+			});
+		} catch (recoverError) {
+			log.warn("stream recover hook failed", {
+				"spectrum.stream.id": streamId,
+				"spectrum.stream.label": label,
+				"spectrum.stream.attempt": failedAttempts,
+				...errorAttrs(recoverError)
+			}, recoverError);
+		}
+	};
 	const consumeLive = async () => {
 		const live = options.subscribeLive(lastCursor);
 		activeLive = live;
@@ -366,7 +400,9 @@ const resumableOrderedStream = (options) => stream((emit, end) => {
 				await closeIterable(activeLive).catch(ignoreCleanupError);
 				activeLive = void 0;
 				if (closed) break;
-				await sleep(handleFailure(error, phase));
+				const delayMs = handleFailure(error, phase);
+				await maybeRecover(error);
+				await sleep(delayMs);
 			}
 		}
 		end();

package/dist/index.js

@@ -2994,7 +2994,7 @@ function definePlatform(name, rawDef) {
 }
 //#endregion
 //#region src/build-env.ts
-const SPECTRUM_SDK_VERSION = "5.2.0";
+const SPECTRUM_SDK_VERSION = "6.1.0";
 //#endregion
 //#region src/utils/provider-packages.ts
 const OFFICIAL_PROVIDER_PACKAGES = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-ts/core",
-  "version": "5.2.0",
+  "version": "6.1.0",
   "description": "The spectrum-ts runtime — Spectrum, content builders, fusor, and the provider authoring API.",
   "repository": {
     "type": "git",