@boy-offi9-inc/reqkit 0.3.0 → 0.5.0

package/src/createFetch.js

@@ -4,24 +4,17 @@ const { withDedupe } = require("./withDedupe");
 const { buildQuery } = require("./buildQuery");
 const { parseJsonSafe } = require("./parseJsonSafe");
 const { normalizeError } = require("./normalizeError");
+const { HTTPError } = require("./HTTPError");
+const { createRateLimiter } = require("./createRateLimiter");
+const { createCircuitBreaker } = require("./createCircuitBreaker");
+const { createMemoryCache } = require("./createMemoryCache");
+const { cacheKey, snapshotResponse, entryToResponse } = require("./_cache");
+const { discardBody } = require("./_http");
 
 const DEFAULT_RETRY_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504];
 // Safe to repeat without side effects. POST/PATCH are deliberately absent.
 const DEFAULT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"];
 
-class HTTPError extends Error {
-  constructor(response, request) {
-    const statusText = response.statusText ? ` ${response.statusText}` : "";
-    super(`Request failed with status ${response.status}${statusText}: ${request.method} ${request.url}`);
-    this.name = "HTTPError";
-    this.status = response.status;
-    this.statusText = response.statusText || "";
-    this.response = response;
-    this.url = request.url;
-    this.method = request.method;
-  }
-}
-
 function isAbsoluteUrl(url) {
   return /^[a-z][a-z0-9+.-]*:/i.test(url);
 }
@@ -53,14 +46,21 @@ function isStreamBody(body) {
   return Boolean(body) && typeof body === "object" && typeof body.getReader === "function";
 }
 
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+
 function mergeDefaults(base, extra) {
-  const headersOf = (d) => d.headers;
   const merged = { ...base, ...extra };
 
   if (base.headers || extra.headers) {
     merged.headers = async () => {
-      const a = await resolveHeaders(headersOf(base));
-      const b = await resolveHeaders(headersOf(extra));
+      const a = await resolveHeaders(base.headers);
+      const b = await resolveHeaders(extra.headers);
       return mergeHeaders(a, b);
     };
   }
@@ -81,6 +81,11 @@ function mergeDefaults(base, extra) {
  *  - per-attempt `timeout` (withTimeout) and external `signal`
  *  - retries (withRetry) on network errors/timeouts and retryable statuses,
  *    honoring Retry-After; only for idempotent methods unless you opt in
+ *  - `rateLimit`: stay under a budget and obey X-RateLimit-* / Retry-After
+ *    *before* the server has to say 429
+ *  - `circuitBreaker`: fail fast against a service that keeps failing
+ *  - `cache`: in-memory GET cache with TTL, stale-while-revalidate and
+ *    ETag / Last-Modified revalidation (304s)
  *  - concurrent GET de-duplication (withDedupe)
  *  - `HTTPError` on non-2xx (turn off with `throwHttpErrors: false`)
  *  - `onRequest` / `onResponse` hooks
@@ -92,6 +97,13 @@ function mergeDefaults(base, extra) {
  * @param {false | object} [defaults.retry] - false disables. Options:
  *   `retries`(2), `statusCodes`, `methods`, `baseDelayMs`, `maxDelayMs`,
  *   `factor`, `jitter`, `maxRetryTime`, `onRetry`, `calculateDelay`
+ * @param {boolean | object} [defaults.rateLimit] - `true` just learns from
+ *   response headers; `{ requests, perMs }` also enforces a budget; or pass a
+ *   createRateLimiter() instance to share one budget
+ * @param {boolean | object | Function} [defaults.circuitBreaker] - options for
+ *   a per-origin breaker, a createCircuitBreaker() instance, or `(url) => breaker`
+ * @param {boolean | object} [defaults.cache] - `{ ttl, staleWhileRevalidate,
+ *   maxEntries, maxBodyBytes, store, onEvent }`; `true` = 60s TTL
  * @param {boolean} [defaults.dedupe=false] - merge identical concurrent GET/HEAD calls
  * @param {boolean} [defaults.throwHttpErrors=true]
  * @param {typeof fetch} [defaults.fetch=globalThis.fetch]
@@ -105,6 +117,9 @@ function createFetch(defaults = {}) {
     headers: defaultHeaders,
     timeout: defaultTimeout = 30000,
     retry: defaultRetry = {},
+    rateLimit,
+    circuitBreaker,
+    cache,
     dedupe = false,
     throwHttpErrors: defaultThrow = true,
     fetch: customFetch,
@@ -114,10 +129,67 @@ function createFetch(defaults = {}) {
 
   const doFetch = (...args) => (customFetch || globalThis.fetch)(...args);
 
+  // --- stateful pieces, built once so `extend()` children share them -------
+  const limiter = !rateLimit
+    ? null
+    : typeof rateLimit.acquire === "function"
+      ? rateLimit
+      : createRateLimiter(rateLimit === true ? {} : rateLimit);
+
+  const breakerRegistry = new Map();
+  const breakerFor = !circuitBreaker
+    ? null
+    : typeof circuitBreaker === "function"
+      ? circuitBreaker
+      : typeof circuitBreaker.run === "function"
+        ? () => circuitBreaker
+        : (url) => {
+            const origin = originOf(url);
+            if (!breakerRegistry.has(origin)) {
+              breakerRegistry.set(origin, createCircuitBreaker(circuitBreaker === true ? {} : circuitBreaker));
+            }
+            return breakerRegistry.get(origin);
+          };
+
+  const cacheCfg = !cache
+    ? null
+    : {
+        ttl: 60000,
+        staleWhileRevalidate: 0,
+        maxEntries: 100,
+        maxBodyBytes: undefined,
+        ...(cache === true ? {} : cache),
+      };
+  if (cacheCfg && !cacheCfg.store) cacheCfg.store = createMemoryCache({ maxEntries: cacheCfg.maxEntries });
+  // In-flight bookkeeping lives on the (shared) cache config so `extend()`
+  // children see the parent's pending writes and revalidations.
+  if (cacheCfg) {
+    cacheCfg.pending = cacheCfg.pending || new Map();
+    cacheCfg.revalidating = cacheCfg.revalidating || new Set();
+  }
+  const pendingStores = cacheCfg ? cacheCfg.pending : null;
+  const revalidating = cacheCfg ? cacheCfg.revalidating : null;
+  const emit = (type, url) => cacheCfg && cacheCfg.onEvent && cacheCfg.onEvent({ type, url });
+
   // Shared in-flight GETs. Every caller gets its own clone of the response so
   // body reads don't fight each other.
   const sharedFetch = withDedupe((key, url, init) => doFetch(url, init), { keyFn: (key) => key });
 
+  function scheduleStore(key, response, url) {
+    const p = snapshotResponse(response, cacheCfg.maxBodyBytes)
+      .then(async (entry) => {
+        if (entry) {
+          await cacheCfg.store.set(key, entry);
+          emit("store", url);
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        if (pendingStores.get(key) === p) pendingStores.delete(key);
+      });
+    pendingStores.set(key, p);
+  }
+
   async function request(input, init = {}) {
     const {
       query,
@@ -127,6 +199,7 @@ function createFetch(defaults = {}) {
       throwHttpErrors = defaultThrow,
       signal,
       headers: initHeaders,
+      cache: cacheMode,
       ...fetchInit
     } = init;
 
@@ -152,30 +225,43 @@ function createFetch(defaults = {}) {
       retryCfg !== false &&
       !isStreamBody(ctx.init.body) && // a consumed stream can't be replayed
       (methods.map((m) => m.toUpperCase()).includes(finalMethod) || hasIdempotencyKey);
-
-    const attemptOnce = () =>
-      withTimeout(
-        (attemptSignal) => {
-          const attemptInit = { ...ctx.init, method: finalMethod, headers: finalHeaders, signal: attemptSignal };
-          const useDedupe = dedupe && !signal && !ctx.init.body && (finalMethod === "GET" || finalMethod === "HEAD");
-          if (!useDedupe) return doFetch(ctx.url, attemptInit);
-          // No per-attempt signal on a shared request: aborting one caller
-          // must never cancel everyone else's.
-          // It still gets its own timeout so a hung server can't leak the request.
-          const sharedInit = { ...attemptInit, signal: timeout === false ? undefined : AbortSignal.timeout(timeout) };
-          const key = `${finalMethod} ${ctx.url} ${JSON.stringify([...finalHeaders.entries()].sort())}`;
-          return sharedFetch(key, ctx.url, sharedInit).then((res) => res.clone());
-        },
-        timeout === false ? Infinity : timeout,
-        { signal }
-      );
-
     const { statusCodes, methods: _methods, retries = 2, shouldRetry: customShouldRetry, ...retryRest } = retryCfg || {};
 
-    let response;
-    try {
-      response = canRetry
-        ? await withRetry(attemptOnce, {
+    // One trip to the network: rate limit → circuit breaker → per-attempt
+    // timeout → fetch, retried per the policy above. `netHeaders` and
+    // `netSignal` are parameters so background revalidation can reuse this.
+    function network(netHeaders, netSignal) {
+      const attemptOnce = () => {
+        const attempt = async () => {
+          if (limiter) await limiter.acquire({ signal: netSignal });
+          const res = await withTimeout(
+            (attemptSignal) => {
+              const attemptInit = { ...ctx.init, method: finalMethod, headers: netHeaders, signal: attemptSignal };
+              const useDedupe =
+                dedupe && !netSignal && !ctx.init.body && (finalMethod === "GET" || finalMethod === "HEAD");
+              if (!useDedupe) return doFetch(ctx.url, attemptInit);
+              // No per-attempt signal on a shared request: aborting one caller
+              // must never cancel everyone else's. It still gets its own
+              // timeout so a hung server can't leak the request.
+              const sharedInit = {
+                ...attemptInit,
+                signal: timeout === false ? undefined : AbortSignal.timeout(timeout),
+              };
+              const key = `${finalMethod} ${ctx.url} ${JSON.stringify([...netHeaders.entries()].sort())}`;
+              return sharedFetch(key, ctx.url, sharedInit).then((res) => res.clone());
+            },
+            timeout === false ? Infinity : timeout,
+            { signal: netSignal }
+          );
+          if (limiter) limiter.update(res);
+          return res;
+        };
+        const breaker = breakerFor && breakerFor(ctx.url);
+        return breaker ? breaker.run(attempt) : attempt();
+      };
+
+      return canRetry
+        ? withRetry(attemptOnce, {
             ...retryRest,
             retries,
             retryStatusCodes: statusCodes || DEFAULT_RETRY_STATUS_CODES,
@@ -185,20 +271,102 @@ function createFetch(defaults = {}) {
                 const n = normalizeError(err);
                 return n.isNetworkError || n.isTimeout;
               }),
-            signal,
+            signal: netSignal,
           })
-        : await attemptOnce();
+        : attemptOnce();
+    }
+
+    function conditionalHeaders(entry) {
+      const h = new Headers(finalHeaders);
+      if (entry) {
+        if (entry.etag && !h.has("if-none-match")) h.set("if-none-match", entry.etag);
+        if (entry.lastModified && !h.has("if-modified-since")) h.set("if-modified-since", entry.lastModified);
+      }
+      return h;
+    }
+
+    // --- cache lookup --------------------------------------------------------
+    const useCache =
+      Boolean(cacheCfg) &&
+      finalMethod === "GET" &&
+      !ctx.init.body &&
+      cacheMode !== false &&
+      cacheMode !== "no-store";
+    const key = useCache ? cacheKey(finalMethod, ctx.url, finalHeaders) : null;
+    let entry = null;
+
+    const finish = async (response) => {
+      if (onResponse) await onResponse({ url: ctx.url, init: ctx.init, response });
+      if (throwHttpErrors && !response.ok) {
+        throw new HTTPError(response, { method: finalMethod, url: ctx.url });
+      }
+      return response;
+    };
+
+    if (useCache && cacheMode !== "reload") {
+      if (pendingStores.has(key)) await pendingStores.get(key);
+      entry = (await cacheCfg.store.get(key)) || null;
+      if (entry) {
+        const age = Date.now() - entry.storedAt;
+        if (age < cacheCfg.ttl) {
+          emit("hit", ctx.url);
+          return finish(entryToResponse(entry));
+        }
+        if (age < cacheCfg.ttl + cacheCfg.staleWhileRevalidate) {
+          emit("stale", ctx.url);
+          if (!revalidating.has(key)) {
+            revalidating.add(key);
+            const staleEntry = entry;
+            (async () => {
+              try {
+                const res = await network(conditionalHeaders(staleEntry), undefined);
+                if (res.status === 304) {
+                  staleEntry.storedAt = Date.now();
+                  await cacheCfg.store.set(key, staleEntry);
+                  emit("revalidated", ctx.url);
+                  await discardBody(res);
+                } else if (res.status === 200) {
+                  scheduleStore(key, res, ctx.url);
+                  await pendingStores.get(key);
+                } else {
+                  await discardBody(res);
+                }
+              } catch {
+                // keep serving the stale copy; try again next time
+              } finally {
+                revalidating.delete(key);
+              }
+            })();
+          }
+          return finish(entryToResponse(entry));
+        }
+      }
+    }
+
+    // --- network -------------------------------------------------------------
+    let response;
+    try {
+      response = await network(useCache ? conditionalHeaders(entry) : finalHeaders, signal);
     } catch (err) {
       // Present a user abort as the plain AbortError they caused, not as retry internals.
       if (err instanceof RetryAbortedError && signal && signal.aborted) throw signal.reason ?? err;
       throw err;
     }
 
-    if (onResponse) await onResponse({ url: ctx.url, init: ctx.init, response });
-    if (throwHttpErrors && !response.ok) {
-      throw new HTTPError(response, { method: finalMethod, url: ctx.url });
+    if (useCache) {
+      if (response.status === 304 && entry) {
+        entry.storedAt = Date.now();
+        await cacheCfg.store.set(key, entry);
+        emit("revalidated", ctx.url);
+        await discardBody(response);
+        response = entryToResponse(entry);
+      } else {
+        emit("miss", ctx.url);
+        if (response.status === 200) scheduleStore(key, response, ctx.url);
+      }
     }
-    return response;
+
+    return finish(response);
   }
 
   /** Like `request`, but resolves to the parsed JSON body (null for an empty body). */
@@ -210,7 +378,19 @@ function createFetch(defaults = {}) {
   };
 
   /** A new fetch with these defaults merged over the current ones (headers and retry are merged, the rest replaced). */
-  request.extend = (overrides = {}) => createFetch(mergeDefaults(defaults, overrides));
+  request.extend = (overrides = {}) =>
+    createFetch(
+      mergeDefaults(
+        {
+          ...defaults,
+          // children share the parent's budget, breakers and cache unless they bring their own
+          rateLimit: limiter || undefined,
+          circuitBreaker: breakerFor || undefined,
+          cache: cacheCfg || undefined,
+        },
+        overrides
+      )
+    );
 
   return request;
 }

package/src/createMemoryCache.js

@@ -0,0 +1,40 @@
+/**
+ * A small in-memory LRU store for createFetch's `cache` option. Anything with
+ * async-or-sync `get(key)`, `set(key, value)` and `delete(key)` can be used
+ * instead (Redis, IndexedDB, a Map...).
+ *
+ * @param {{ maxEntries?: number }} [opts]
+ */
+function createMemoryCache(opts = {}) {
+  const { maxEntries = 100 } = opts;
+  if (!(Number.isInteger(maxEntries) && maxEntries >= 1)) {
+    throw new TypeError("createMemoryCache: `maxEntries` must be an integer >= 1");
+  }
+  const map = new Map();
+
+  return {
+    get(key) {
+      if (!map.has(key)) return undefined;
+      const value = map.get(key);
+      map.delete(key); // re-insert so it counts as most recently used
+      map.set(key, value);
+      return value;
+    },
+    set(key, value) {
+      map.delete(key);
+      map.set(key, value);
+      while (map.size > maxEntries) map.delete(map.keys().next().value);
+    },
+    delete(key) {
+      return map.delete(key);
+    },
+    clear() {
+      map.clear();
+    },
+    get size() {
+      return map.size;
+    },
+  };
+}
+
+module.exports = { createMemoryCache };

package/src/createMockFetch.js

@@ -0,0 +1,184 @@
+const { abortableSleep } = require("./_sleep");
+
+const BODYLESS = new Set([101, 204, 205, 304]);
+
+function toBody(body, headers) {
+  if (body === null || body === undefined) return null;
+  if (typeof body === "string") return body;
+  if (
+    body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(body) ||
+    (typeof Blob !== "undefined" && body instanceof Blob) ||
+    (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) ||
+    body instanceof URLSearchParams
+  ) {
+    return body;
+  }
+  if (!headers.has("content-type")) headers.set("content-type", "application/json");
+  return JSON.stringify(body);
+}
+
+function buildResponse(status, body, extraHeaders) {
+  const headers = new Headers(extraHeaders || undefined);
+  const payload = BODYLESS.has(status) ? null : toBody(body, headers);
+  return new Response(payload, { status, headers });
+}
+
+function matchesUrl(matcher, url) {
+  if (typeof matcher === "function") return Boolean(matcher(url));
+  if (matcher instanceof RegExp) return matcher.test(url);
+  if (matcher === "*" || matcher === undefined) return true;
+  if (url === matcher) return true;
+  try {
+    const u = new URL(url);
+    if (matcher === u.pathname + u.search) return true;
+    if (!String(matcher).includes("?") && matcher === u.pathname) return true;
+  } catch {
+    // relative/odd URL — exact match only
+  }
+  return false;
+}
+
+/**
+ * A scriptable, fetch-compatible test double — for testing code that uses
+ * retries, timeouts, rate limits and so on without a network.
+ *
+ * ```js
+ * const mock = createMockFetch();
+ * mock.on("GET", "/users/1")
+ *   .replyOnce(503, "busy", { headers: { "retry-after": "0" } })
+ *   .reply(200, { id: 1 });
+ * mock.on("POST", /\/orders/).fail(mock.networkError());
+ *
+ * const api = createFetch({ fetch: mock.fetch, baseUrl: "https://api.test" });
+ * await api.json("/users/1");          // → { id: 1 } after one retry
+ * mock.calls.length;                   // 2
+ * ```
+ *
+ * String matchers match the full URL, `pathname + search`, or the bare
+ * `pathname`; you can also pass a RegExp or a `(url) => boolean`. `"*"` as the
+ * method matches any method. Unmatched requests reject with a clear error.
+ */
+function createMockFetch() {
+  let routes = [];
+  const calls = [];
+
+  function on(method, matcher) {
+    const route = { method: String(method).toUpperCase(), matcher, once: [], fallback: null };
+    routes.push(route);
+
+    const chain = {
+      /** Always answer like this (once any `…Once` replies are used up). */
+      reply(status = 200, body, opts) {
+        route.fallback = replyHandler(status, body, opts);
+        return chain;
+      },
+      replyOnce(status = 200, body, opts) {
+        route.once.push(replyHandler(status, body, opts));
+        return chain;
+      },
+      /** `fn(call)` returns a Response, `{ status, body, headers }`, or throws/rejects. */
+      replyWith(fn) {
+        route.fallback = customHandler(fn);
+        return chain;
+      },
+      replyWithOnce(fn) {
+        route.once.push(customHandler(fn));
+        return chain;
+      },
+      /** Reject like fetch does on a network failure. */
+      fail(err = networkError()) {
+        route.fallback = async () => {
+          throw err;
+        };
+        return chain;
+      },
+      failOnce(err = networkError()) {
+        route.once.push(async () => {
+          throw err;
+        });
+        return chain;
+      },
+    };
+    return chain;
+  }
+
+  function replyHandler(status, body, opts = {}) {
+    return async (call) => {
+      if (opts.delayMs) await abortableSleep(opts.delayMs, call.signal);
+      return buildResponse(status, body, opts.headers);
+    };
+  }
+
+  function customHandler(fn) {
+    return async (call) => {
+      const out = await fn(call);
+      if (out instanceof Response) return out;
+      return buildResponse(out.status ?? 200, out.body, out.headers);
+    };
+  }
+
+  function networkError(code = "ECONNREFUSED") {
+    const err = new TypeError("fetch failed");
+    err.cause = Object.assign(new Error(`connect ${code}`), { code });
+    return err;
+  }
+
+  async function mockFetch(input, init = {}) {
+    const url = input instanceof URL ? input.href : typeof input === "string" ? input : input.url;
+    const method = String(init.method || (typeof input === "object" && input.method) || "GET").toUpperCase();
+    const signal = init.signal || (typeof input === "object" ? input.signal : undefined);
+    signal?.throwIfAborted?.();
+
+    const headers = {};
+    new Headers(init.headers || (typeof input === "object" ? input.headers : undefined)).forEach((v, k) => {
+      headers[k] = v;
+    });
+
+    const call = {
+      url,
+      method,
+      headers,
+      body: init.body,
+      signal,
+      get json() {
+        try {
+          return typeof this.body === "string" ? JSON.parse(this.body) : undefined;
+        } catch {
+          return undefined;
+        }
+      },
+    };
+    calls.push(call);
+
+    const route = routes.find(
+      (r) => (r.method === "*" || r.method === method) && matchesUrl(r.matcher, url) && (r.once.length > 0 || r.fallback)
+    );
+    if (!route) {
+      throw new Error(`createMockFetch: no mock registered for ${method} ${url}`);
+    }
+    const handler = route.once.length > 0 ? route.once.shift() : route.fallback;
+    return handler(call);
+  }
+
+  return {
+    fetch: mockFetch,
+    on,
+    get: (m) => on("GET", m),
+    post: (m) => on("POST", m),
+    put: (m) => on("PUT", m),
+    patch: (m) => on("PATCH", m),
+    delete: (m) => on("DELETE", m),
+    /** A TypeError("fetch failed") with `cause.code`, like Node's fetch throws. */
+    networkError,
+    /** Every request made so far, in order. */
+    calls,
+    /** Remove all routes and forget recorded calls. */
+    reset() {
+      routes = [];
+      calls.length = 0;
+    },
+  };
+}
+
+module.exports = { createMockFetch };

package/src/createRateLimiter.js

@@ -0,0 +1,111 @@
+const { abortableSleep } = require("./_sleep");
+const { getRateLimitInfo } = require("./_http");
+
+function abortable(promise, signal) {
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (v) => (signal.removeEventListener("abort", onAbort), resolve(v)),
+      (e) => (signal.removeEventListener("abort", onAbort), reject(e))
+    );
+  });
+}
+
+/**
+ * A *proactive* rate limiter: slows you down before the server has to say
+ * 429. Two things feed it:
+ *  1. your own budget — `requests` per `perMs` (sliding window), and
+ *  2. what the server tells you — `update(response)` reads X-RateLimit-* /
+ *     RateLimit-* / Retry-After and pauses everything once `remaining` hits 0
+ *     (or the server sent Retry-After), until the reset time.
+ *
+ * Callers are served FIFO.
+ *
+ * ```js
+ * const rl = createRateLimiter({ requests: 10, perMs: 1000 });
+ * const res = await rl.run(() => fetch(url)); // acquire → call → learn from headers
+ * ```
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.requests=Infinity] - max requests per window
+ * @param {number} [opts.perMs=1000] - window length
+ */
+function createRateLimiter(opts = {}) {
+  const { requests = Infinity, perMs = 1000 } = opts;
+  if (requests !== Infinity && !(Number.isInteger(requests) && requests >= 1)) {
+    throw new TypeError("createRateLimiter: `requests` must be an integer >= 1 (or Infinity)");
+  }
+  if (!(typeof perMs === "number" && perMs > 0 && Number.isFinite(perMs))) {
+    throw new TypeError("createRateLimiter: `perMs` must be a positive number");
+  }
+
+  const stamps = [];
+  let blockedUntil = 0;
+  let tail = Promise.resolve();
+
+  async function take(signal) {
+    for (;;) {
+      signal?.throwIfAborted?.();
+      const now = Date.now();
+      while (stamps.length > 0 && stamps[0] <= now - perMs) stamps.shift();
+
+      let waitMs = 0;
+      if (blockedUntil > now) waitMs = blockedUntil - now;
+      else if (stamps.length >= requests) waitMs = stamps[0] + perMs - now;
+
+      if (waitMs <= 0) {
+        stamps.push(now);
+        return;
+      }
+      await abortableSleep(waitMs, signal);
+    }
+  }
+
+  /** Resolves when it's your turn. Rejects with the signal's reason if aborted while waiting. */
+  function acquire({ signal } = {}) {
+    const turn = tail.then(() => take(signal));
+    tail = turn.catch(() => {});
+    return abortable(turn, signal);
+  }
+
+  /** Feed a response (anything with `.headers`/`.status`) so the limiter learns the server's limits. */
+  function update(response) {
+    if (!response || !response.headers) return;
+    const { remaining, resetMs, retryAfterMs } = getRateLimitInfo(response.headers);
+    let blockMs = null;
+    if (retryAfterMs !== null && (response.status === 429 || response.status === 503)) blockMs = retryAfterMs;
+    else if (remaining === 0 && resetMs !== null) blockMs = resetMs;
+    if (blockMs !== null) blockedUntil = Math.max(blockedUntil, Date.now() + blockMs);
+  }
+
+  /** acquire → fn() → update(result). Errors thrown by fn propagate (the slot stays spent). */
+  async function run(fn, { signal } = {}) {
+    await acquire({ signal });
+    const result = await fn();
+    update(result);
+    return result;
+  }
+
+  return {
+    acquire,
+    update,
+    run,
+    /** Ms until the server-imposed pause ends (0 if none). */
+    get blockedForMs() {
+      return Math.max(0, blockedUntil - Date.now());
+    },
+    /** Forget all history and server hints. */
+    reset() {
+      stamps.length = 0;
+      blockedUntil = 0;
+    },
+  };
+}
+
+module.exports = { createRateLimiter };