js-bao-wss-client 2.0.6 → 2.0.7

package/dist/JsBaoClient.js

@@ -41,6 +41,24 @@ export { ANALYTICS_UNAUTHENTICATED_USER } from "./internal/analyticsQueue";
 const DEFAULT_RETURN_ACTIVE_MIN_MS = 5 * 60 * 1000;
 const DEFAULT_SYNC_ERROR_MIN_MS = 30 * 1000;
 const logger = createLogger({ scope: "JsBaoClient" });
+// Workflow apply-lifecycle durability (#1694). The server confirm is idempotent
+// (read-then-conditional-write; returns `confirmed: true` if the run already
+// completed), so a lost or hung confirm POST is safe to retry — retrying only
+// re-sends the confirm, never the user's onApply handler. These bounds keep the
+// retry inside the server's 30s apply lease so a stranded run recovers within
+// the same client session instead of waiting for a full restart.
+//
+// A per-request timeout (via AbortController in the HTTP layer) turns a hung
+// apply POST into a retryable network error. Scope note: this timeout is applied
+// only to the apply-lifecycle calls (claim/confirm/release), not to every client
+// request — a blanket request timeout has a much larger blast radius.
+const APPLY_REQUEST_TIMEOUT_MS = 8000;
+const APPLY_CONFIRM_MAX_ATTEMPTS = 6;
+const APPLY_CONFIRM_BASE_DELAY_MS = 250;
+const APPLY_CONFIRM_MAX_DELAY_MS = 4000;
+// Total retry budget, kept under the 30s server apply lease so the claim is
+// still valid when a retry finally lands.
+const APPLY_CONFIRM_RETRY_BUDGET_MS = 25000;
 function debugLog(tag, payload) {
     try {
         if (!logger.shouldLog("debug"))
@@ -2624,7 +2642,9 @@ export class JsBaoClient extends Observable {
         if (options.contextDocId) {
             payload.contextDocId = options.contextDocId;
         }
-        const response = await this.makeRequest("POST", path, payload);
+        const response = await this.makeRequest("POST", path, payload, {
+            timeoutMs: APPLY_REQUEST_TIMEOUT_MS,
+        });
         return response;
     }
     async releaseWorkflowApply(options) {
@@ -2635,7 +2655,9 @@ export class JsBaoClient extends Observable {
         if (options.contextDocId) {
             payload.contextDocId = options.contextDocId;
         }
-        const response = await this.makeRequest("POST", path, payload);
+        const response = await this.makeRequest("POST", path, payload, {
+            timeoutMs: APPLY_REQUEST_TIMEOUT_MS,
+        });
         return response;
     }
     async confirmWorkflowApply(options) {
@@ -2652,9 +2674,63 @@ export class JsBaoClient extends Observable {
         if (options.contextDocId) {
             payload.contextDocId = options.contextDocId;
         }
-        const response = await this.makeRequest("POST", path, payload);
+        const response = await this.makeRequest("POST", path, payload, {
+            timeoutMs: APPLY_REQUEST_TIMEOUT_MS,
+        });
         return response;
     }
+    /**
+     * Whether a thrown confirm-apply error is worth retrying. Network failures
+     * (unreachable server, refused connection, DNS failure, or an aborted
+     * timeout — all surfaced as `JsBaoNetworkError`) and HTTP 5xx are transient,
+     * so retrying the idempotent confirm may still succeed. Any other HTTP status
+     * (4xx) is a definitive rejection and is not retried.
+     */
+    isRetryableConfirmError(err) {
+        if (err instanceof JsBaoNetworkError) {
+            return true;
+        }
+        if (err instanceof JsBaoApiError) {
+            return err.status >= 500 && err.status < 600;
+        }
+        return false;
+    }
+    /**
+     * Retry the confirm POST on transient failures, bounded by both an attempt
+     * count and a time budget that stays within the server's apply lease. Only
+     * the confirm POST is retried here — the caller runs the user's onApply
+     * handler exactly once, before invoking this, so retries never re-run it.
+     * A `confirmed: false` result (a genuine claim loss) is returned normally,
+     * not retried; the caller releases the claim in that case.
+     */
+    async confirmWorkflowApplyWithRetry(options) {
+        const deadline = Date.now() + APPLY_CONFIRM_RETRY_BUDGET_MS;
+        let attempt = 0;
+        let delayMs = APPLY_CONFIRM_BASE_DELAY_MS;
+        for (;;) {
+            attempt++;
+            try {
+                return await this.confirmWorkflowApply(options);
+            }
+            catch (err) {
+                const nextDelay = Math.min(delayMs, APPLY_CONFIRM_MAX_DELAY_MS);
+                const outOfBudget = Date.now() + nextDelay >= deadline;
+                if (!this.isRetryableConfirmError(err) ||
+                    attempt >= APPLY_CONFIRM_MAX_ATTEMPTS ||
+                    outOfBudget) {
+                    throw err;
+                }
+                logger.warn("[workflowApply] confirm failed, retrying", {
+                    workflowKey: options.workflowKey,
+                    runKey: options.runKey,
+                    attempt,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                await new Promise((resolve) => setTimeout(resolve, nextDelay));
+                delayMs = Math.min(delayMs * 2, APPLY_CONFIRM_MAX_DELAY_MS);
+            }
+        }
+    }
     async getWorkflowPendingApplies(options) {
         if (!options?.contextDocId) {
             throw new JsBaoError("INVALID_ARGUMENT", "contextDocId is required for workflows.getPendingApplies");
@@ -2702,11 +2778,15 @@ export class JsBaoClient extends Observable {
                 startedByUserId: event.startedByUserId,
                 meta: statusResult.run?.meta ?? undefined,
             });
-            // Confirm the apply. Surface a server-side rejection (`confirmed: false`)
-            // as an error so we don't silently leave the workflow stuck in
-            // `apply_claimed` (issue #614). The catch block below releases the
-            // claim and emits a diagnostic.
-            const confirmResult = await this.confirmWorkflowApply({
+            // Confirm the apply, retrying the POST on transient failures (#1694).
+            // The handler above has already run exactly once; the retry re-sends only
+            // the idempotent confirm, never the handler. A lost or hung confirm would
+            // otherwise strand the run in `apply_claimed` for the whole client session
+            // with no way to recover short of a restart. Surface a server-side
+            // rejection (`confirmed: false`) as an error so we don't silently leave
+            // the workflow stuck in `apply_claimed` (issue #614). The catch block
+            // below releases the claim and emits a diagnostic.
+            const confirmResult = await this.confirmWorkflowApplyWithRetry({
                 workflowKey: event.workflowKey,
                 runKey: event.runKey,
                 contextDocId: event.contextDocId,
@@ -2716,7 +2796,10 @@ export class JsBaoClient extends Observable {
             }
         }
         catch (err) {
-            logger.warn("[workflowApply] apply handler failed", {
+            // Elevated to `error` (#1694): apply-flow failures strand a run in
+            // `apply_claimed`, and tests (and apps) commonly run at logLevel `error`,
+            // so a `warn`/`debug` diagnostic here is invisible exactly when it matters.
+            logger.error("[workflowApply] apply handler failed", {
                 workflowKey: event.workflowKey,
                 runKey: event.runKey,
                 error: err instanceof Error ? err.message : String(err),
@@ -2730,7 +2813,7 @@ export class JsBaoClient extends Observable {
                 });
             }
             catch (releaseErr) {
-                logger.debug("[workflowApply] failed to release claim", {
+                logger.error("[workflowApply] failed to release claim", {
                     workflowKey: event.workflowKey,
                     runKey: event.runKey,
                     error: releaseErr instanceof Error ? releaseErr.message : String(releaseErr),