@north-light/api 0.3.559 → 0.3.560

package/dist/api/client.js

@@ -908,6 +908,8 @@ export class CrtrClient {
         const opts = this.resolveBudget(callOpts);
         const idempotent = method === 'GET' || method === 'HEAD' || method === 'DELETE';
         const maxRetries = opts.maxRetries ?? this.maxRetries;
+        // A hosted runtime being created or replaced answers reads with a refusal that never reached it; wait for it inside this allowance.
+        const replacementWaitEndsAt = Math.min(opts.deadlineAt ?? Infinity, Date.now() + HOSTED_REPLACEMENT_WAIT_MS);
         for (let attempt = 0;; attempt++) {
             let response;
             try {
@@ -942,6 +944,15 @@ export class CrtrClient {
                     throw toTransportApiError(err, opts.signal);
                 }
             }
+            if (isRead(method) && maxRetries > 0 && response.status === 503 && await isRefusedBeforeForwarding(response, opts.deadlineAt)) {
+                const delayMs = Math.max(250, (retryAfterHeaderS(response) ?? 0) * 1_000) + Math.random() * 250;
+                // Out of allowance: the refusal itself is the answer, so the caller sees its cause.
+                if (Date.now() + delayMs >= replacementWaitEndsAt)
+                    return response;
+                await drainResponseBody(response, opts.deadlineAt);
+                await sleepWithin(delayMs, { signal: opts.signal });
+                continue;
+            }
             if (idempotent && attempt < maxRetries && isRetryableStatus(response.status)) {
                 await drainResponseBody(response, opts.deadlineAt);
                 await sleepWithin(retryDelayMs(attempt + 1), opts, retryAfterHeaderS(response));
@@ -1266,6 +1277,29 @@ async function parse(res, deadlineAt) {
     }
     throw new ApiError(res.status, 'internal', `request failed with status ${res.status}`, undefined, res.headers);
 }
+/** How long a read waits for a hosted runtime that is being created or replaced. */
+const HOSTED_REPLACEMENT_WAIT_MS = 60_000;
+/** Only reads are replayed after a refusal; a write is never retried on this state. */
+function isRead(method) {
+    return method === 'GET' || method === 'HEAD';
+}
+/** True when the response is the hosting router's 503 for a runtime that provisioning is creating or replacing
+ *  (`details.forwarded === false`): the request reached no runtime, so replaying it cannot run anything twice.
+ *  Reads a clone, so the caller still gets the body of the response it is handed. */
+async function isRefusedBeforeForwarding(response, deadlineAt) {
+    try {
+        // A router refusal is a few hundred bytes; anything declared larger, or a body that stalls, is not one.
+        if (Number(response.headers.get('content-length') ?? 0) > 8_192)
+            return false;
+        const text = await readTextWithin(response.clone(), Math.min(deadlineAt ?? Infinity, Date.now() + 5_000));
+        const error = JSON.parse(text).error;
+        return error?.origin === 'router' && error.details?.forwarded === false
+            && (error.details.runtime_state === 'creating' || error.details.runtime_state === 'recovering');
+    }
+    catch {
+        return false;
+    }
+}
 /** `429`/`5xx` are the only statuses the §7 retry policy replays. */
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.559",
+  "version": "0.3.560",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",