@limitry/sdk 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/retry.js

@@ -13,11 +13,31 @@
  * handed back to the caller rather than slept through. A request whose
  * own signal aborted (a caller's timeout) is never retried: the caller
  * decided.
+ *
+ * A `503 moving` (a subject handed over between Limitry's servers, a few
+ * seconds) or `503 busy` (too many checks inside one of them at once) is
+ * retried for up to MOVING_MS whatever `maxRetries` says: nothing was
+ * charged, and the same key gets the answer once it lands. Each wait is
+ * the Retry-After (at least a second) plus full jitter on a capped
+ * exponential backoff (`retryWaitMs`), so clients turned away together
+ * don't come back together. A caller that keeps its own time budget (the
+ * guard and reserve helpers) sends `MOVING_HEADER: return` and gets
+ * either answer back at once.
  */
 const WRITES = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
 export const DEFAULT_MAX_RETRIES = 2;
 export const MAX_WAIT_MS = 20_000;
+/**
+ * How long a `moving` or `busy` answer is retried, all told: a handover's
+ * freeze lasts at most 30 s.
+ */
+export const MOVING_MS = 30_000;
+/** Sent by a caller that retries `moving` and `busy` itself (never reaches the API). */
+export const MOVING_HEADER = "x-limitry-moving";
+/** The backoff added to a `moving` or `busy` wait: full jitter under base × 2^n, capped. */
+export const JITTER_BASE_MS = 250;
+export const JITTER_CAP_MS = 4_000;
 /** The longest key a caller may pass where a client derives keys from it. */
 export const MAX_BASE_KEY = 200;
 const wait = (ms) => new Promise((done) => setTimeout(done, ms));
@@ -35,6 +55,34 @@ function retryAfter(response) {
     const date = Date.parse(value);
     return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
 }
+/**
+ * The wait before retrying a `moving` or `busy` answer, the `attempt`th
+ * in a row (0 first): the server's Retry-After, at least a second (a 0,
+ * or a date past, must not spin), plus full jitter — anywhere from 0 to
+ * min(JITTER_CAP_MS, JITTER_BASE_MS × 2^attempt).
+ */
+export function retryWaitMs(retryAfterMs, attempt, random = Math.random) {
+    const floor = Math.max(1_000, retryAfterMs ?? 1_000);
+    const ceiling = Math.min(JITTER_CAP_MS, JITTER_BASE_MS * 2 ** attempt);
+    return floor + random() * ceiling;
+}
+/** A `503` that says retry later with the same key: `moving` or `busy` (else null). */
+export async function retryLater(response) {
+    if (response.status !== 503)
+        return null;
+    try {
+        const body = (await response.clone().json());
+        const code = body.error?.code;
+        return code === "moving" || code === "busy" ? code : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A `503` whose error code is `moving`. */
+export async function isMoving(response) {
+    return (await retryLater(response)) === "moving";
+}
 async function retryable(response) {
     if (RETRY_STATUSES.has(response.status))
         return true;
@@ -48,11 +96,31 @@ async function retryable(response) {
         return false;
     }
 }
+/**
+ * `fetch` that only drops MOVING_HEADER (a client with retries off): the
+ * header is between the SDK's own parts, never sent to the API.
+ */
+export function withoutMovingHeader(fetch) {
+    return (request) => {
+        if (!request.headers.has(MOVING_HEADER))
+            return fetch(request);
+        const headers = new Headers(request.headers);
+        headers.delete(MOVING_HEADER);
+        return fetch(new Request(request, { headers }));
+    };
+}
 /** `fetch` with the rule above. Each request is one logical call. */
 export function withRetries(fetch, options = {}) {
     const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     const sleep = options.sleep ?? wait;
+    const random = options.random ?? Math.random;
     return async (request) => {
+        const returnMoving = request.headers.get(MOVING_HEADER) === "return";
+        if (request.headers.has(MOVING_HEADER)) {
+            const headers = new Headers(request.headers);
+            headers.delete(MOVING_HEADER);
+            request = new Request(request, { headers });
+        }
         if (WRITES.has(request.method) && !request.headers.has("idempotency-key")) {
             const url = new URL(request.url);
             const key = options.key
@@ -62,10 +130,12 @@ export function withRetries(fetch, options = {}) {
             headers.set("idempotency-key", key);
             request = new Request(request, { headers });
         }
+        let movingWaited = 0;
+        let movingTries = 0;
         for (let attempt = 0;; attempt++) {
             const last = attempt >= maxRetries;
             // Send a copy while a retry may follow: a body is read once.
-            const sending = last ? request : request.clone();
+            const sending = request.clone();
             let response;
             try {
                 response = await fetch(sending);
@@ -76,6 +146,20 @@ export function withRetries(fetch, options = {}) {
                 await sleep(backoff(attempt));
                 continue;
             }
+            const later = await retryLater(response);
+            if (later && returnMoving)
+                return response;
+            if (later) {
+                // Retried apart from maxRetries, for up to MOVING_MS.
+                const delay = retryWaitMs(retryAfter(response), movingTries++, random);
+                if (movingWaited + delay > MOVING_MS)
+                    return response;
+                movingWaited += delay;
+                await response.body?.cancel();
+                await sleep(delay);
+                attempt--;
+                continue;
+            }
             if (last || !(await retryable(response)))
                 return response;
             const delay = retryAfter(response) ?? backoff(attempt);