@boy-offi9-inc/reqkit 0.3.0 → 0.6.0

package/src/downloadResumable.js

@@ -0,0 +1,193 @@
+const { HTTPError } = require("./HTTPError");
+const { BodyTooLargeError } = require("./withProgress");
+const { normalizeError } = require("./normalizeError");
+const { getWaitMsFromHeaders } = require("./_http");
+const { abortableSleep } = require("./_sleep");
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+function parseContentRange(header) {
+  // "bytes 100-199/1000" (total may be "*")
+  const m = /^bytes\s+(\d+)-(\d+)\/(\d+|\*)$/i.exec(String(header || "").trim());
+  if (!m) return null;
+  return { start: Number(m[1]), end: Number(m[2]), total: m[3] === "*" ? null : Number(m[3]) };
+}
+
+function isRetryable(err) {
+  if (err instanceof BodyTooLargeError) return false;
+  if (err instanceof HTTPError) return RETRYABLE_STATUS.has(err.status);
+  const n = normalizeError(err);
+  if (n.isAborted) return false;
+  return n.isNetworkError || n.isTimeout;
+}
+
+/**
+ * Downloads a URL into memory and, if the connection drops mid-body, resumes
+ * from where it stopped with an HTTP `Range` request instead of starting
+ * over. Uses `If-Range` with the first response's strong ETag (or
+ * Last-Modified) so a file that changed on the server is restarted rather
+ * than stitched together wrongly. If the server ignores Range, it simply
+ * restarts from zero.
+ *
+ * `retries` counts consecutive attempts *without progress* — a flaky link
+ * that keeps making headway keeps going. Honors Retry-After on 429/503.
+ *
+ * ```js
+ * const bytes = await downloadResumable(url, {
+ *   onProgress: ({ percent }) => console.log(percent),
+ *   maxBytes: 200 * 1024 * 1024,
+ * });
+ * ```
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetch=globalThis.fetch] - e.g. `createFetch(...)` or a mock
+ * @param {HeadersInit} [opts.headers]
+ * @param {number} [opts.retries=5]
+ * @param {number} [opts.baseDelayMs=500]
+ * @param {number} [opts.maxDelayMs=10000]
+ * @param {(p: {loaded: number, total: number | null, percent: number | null}) => void} [opts.onProgress]
+ * @param {number} [opts.maxBytes] - throws BodyTooLargeError past this
+ * @param {AbortSignal} [opts.signal]
+ * @param {(err: any, attempt: number, delayMs: number, info: {resumeFrom: number}) => void} [opts.onRetry]
+ * @returns {Promise<Uint8Array>}
+ */
+async function downloadResumable(url, opts = {}) {
+  const {
+    fetch: fetchFn = globalThis.fetch,
+    headers,
+    retries = 5,
+    baseDelayMs = 500,
+    maxDelayMs = 10000,
+    onProgress,
+    maxBytes,
+    signal,
+    onRetry,
+  } = opts;
+
+  const chunks = [];
+  let loaded = 0;
+  let total = null;
+  let validator = null;
+  let attempt = 0; // consecutive attempts without progress
+
+  const report = () => {
+    if (onProgress) {
+      onProgress({ loaded, total, percent: total ? Math.min(100, Math.round((loaded / total) * 100)) : null });
+    }
+  };
+
+  for (;;) {
+    signal?.throwIfAborted?.();
+    const loadedBefore = loaded;
+
+    try {
+      const reqHeaders = new Headers(headers || undefined);
+      // Range offsets count encoded bytes, so ask for an uncompressed body.
+      if (!reqHeaders.has("accept-encoding")) reqHeaders.set("accept-encoding", "identity");
+      if (loaded > 0) {
+        reqHeaders.set("range", `bytes=${loaded}-`);
+        if (validator) reqHeaders.set("if-range", validator);
+      }
+
+      const res = await fetchFn(url, { headers: reqHeaders, signal });
+
+      if (res.status === 416 && loaded > 0) {
+        // Our offset no longer fits the file — start over, without burning a retry.
+        await res.body?.cancel?.().catch(() => {});
+        chunks.length = 0;
+        loaded = 0;
+        continue;
+      }
+      if (!res.ok) {
+        await res.body?.cancel?.().catch(() => {});
+        throw new HTTPError(res, { method: "GET", url });
+      }
+
+      const encoding = res.headers.get("content-encoding");
+      const encoded = Boolean(encoding) && encoding.trim().toLowerCase() !== "identity";
+
+      if (loaded > 0) {
+        const range = res.status === 206 ? parseContentRange(res.headers.get("content-range")) : null;
+        if (!range || range.start !== loaded || encoded) {
+          // Server ignored Range, the file changed (If-Range failed), or the
+          // bytes don't line up: discard and restart from the beginning.
+          chunks.length = 0;
+          loaded = 0;
+        }
+      }
+
+      if (loaded === 0) {
+        const range = res.status === 206 ? parseContentRange(res.headers.get("content-range")) : null;
+        const length = Number(res.headers.get("content-length"));
+        total = encoded ? null : range ? range.total : Number.isFinite(length) && res.headers.has("content-length") ? length : null;
+        const etag = res.headers.get("etag");
+        validator = etag && !etag.startsWith("W/") ? etag : res.headers.get("last-modified");
+      }
+
+      if (maxBytes !== undefined && total !== null && total > maxBytes) {
+        await res.body?.cancel?.().catch(() => {});
+        throw new BodyTooLargeError(maxBytes);
+      }
+
+      if (!res.body || typeof res.body.getReader !== "function") {
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (maxBytes !== undefined && buf.byteLength > maxBytes) throw new BodyTooLargeError(maxBytes);
+        chunks.push(buf);
+        loaded += buf.byteLength;
+        total = total ?? loaded;
+        report();
+      } else {
+        const reader = res.body.getReader();
+        const onAbort = () => reader.cancel(signal.reason).catch(() => {});
+        signal?.addEventListener("abort", onAbort, { once: true });
+        let finished = false;
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            signal?.throwIfAborted?.();
+            if (done) break;
+            chunks.push(value);
+            loaded += value.byteLength;
+            if (maxBytes !== undefined && loaded > maxBytes) throw new BodyTooLargeError(maxBytes);
+            report();
+          }
+          finished = true;
+        } finally {
+          signal?.removeEventListener("abort", onAbort);
+          if (!finished) reader.cancel().catch(() => {});
+        }
+      }
+
+      if (total !== null && loaded < total) {
+        // Stream ended early without an error (some servers just close the socket).
+        throw Object.assign(new Error(`Incomplete download: got ${loaded} of ${total} bytes`), { code: "ECONNRESET" });
+      }
+
+      const out = new Uint8Array(loaded);
+      let offset = 0;
+      for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      return out;
+    } catch (err) {
+      if (signal?.aborted) throw signal.reason ?? err;
+      if (!isRetryable(err)) throw err;
+
+      if (loaded > loadedBefore) attempt = 0; // it made progress — doesn't count against the budget
+      if (attempt >= retries) throw err;
+
+      let delayMs = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+      if (err instanceof HTTPError) {
+        const headerMs = getWaitMsFromHeaders(err.response && err.response.headers);
+        if (headerMs !== null) delayMs = Math.min(headerMs, 60000);
+      }
+      attempt++;
+      if (onRetry) onRetry(err, attempt, delayMs, { resumeFrom: loaded });
+      await abortableSleep(delayMs, signal);
+    }
+  }
+}
+
+module.exports = { downloadResumable };

package/src/index.js

@@ -8,6 +8,13 @@ const { withProgress, BodyTooLargeError } = require("./withProgress");
 const { withDedupe } = require("./withDedupe");
 const { createLimiter } = require("./createLimiter");
 const { createFetch, HTTPError } = require("./createFetch");
+const { createRateLimiter } = require("./createRateLimiter");
+const { createCircuitBreaker, CircuitOpenError } = require("./createCircuitBreaker");
+const { createMemoryCache } = require("./createMemoryCache");
+const { createMockFetch } = require("./createMockFetch");
+const { downloadResumable } = require("./downloadResumable");
+const { readLines, readNDJSON, readSSE } = require("./streams");
+const { streamSSE } = require("./streamSSE");
 
 module.exports = {
   withRetry,
@@ -27,4 +34,14 @@ module.exports = {
   createLimiter,
   createFetch,
   HTTPError,
+  createRateLimiter,
+  createCircuitBreaker,
+  CircuitOpenError,
+  createMemoryCache,
+  createMockFetch,
+  downloadResumable,
+  readLines,
+  readNDJSON,
+  readSSE,
+  streamSSE,
 };

package/src/index.mjs

@@ -18,6 +18,16 @@ export const {
   createLimiter,
   createFetch,
   HTTPError,
+  createRateLimiter,
+  createCircuitBreaker,
+  CircuitOpenError,
+  createMemoryCache,
+  createMockFetch,
+  downloadResumable,
+  readLines,
+  readNDJSON,
+  readSSE,
+  streamSSE,
 } = reqkit;
 
 export default reqkit;

package/src/normalizeError.js

@@ -54,7 +54,7 @@ function isNetworkCode(code) {
 
 // Browsers and Node throw a bare TypeError for network-level fetch failures.
 const FETCH_NETWORK_MESSAGE =
-  /fetch failed|failed to fetch|network ?request failed|load failed|networkerror when attempting to fetch/i;
+  /fetch failed|failed to fetch|network ?request failed|load failed|networkerror when attempting to fetch|^terminated$|^network error$/i;
 
 function isFetchNetworkTypeError(err) {
   return err.name === "TypeError" && FETCH_NETWORK_MESSAGE.test(err.message || "");

package/src/streamSSE.js

@@ -0,0 +1,197 @@
+const { readSSE } = require("./streams");
+const { HTTPError } = require("./HTTPError");
+const { normalizeError } = require("./normalizeError");
+const { getWaitMsFromHeaders, discardBody } = require("./_http");
+const { abortableSleep } = require("./_sleep");
+
+function isRetryableStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function isRetryableError(err) {
+  const n = normalizeError(err);
+  return !n.isAborted && (n.isNetworkError || n.isTimeout);
+}
+
+async function resolveHeaders(source) {
+  const value = typeof source === "function" ? await source() : source;
+  return new Headers(value || undefined);
+}
+
+/**
+ * Connects to a Server-Sent Events endpoint and yields its events — and when
+ * the connection drops (or the server closes it), reconnects by itself,
+ * sending `Last-Event-ID` so the server can resume where you left off. This is
+ * what the browser's `EventSource` does, but with `fetch`: custom headers,
+ * POST bodies, AbortSignal, your own retry/backoff rules.
+ *
+ * ```js
+ * for await (const { data } of streamSSE("https://api.example.com/events", { signal })) {
+ *   console.log(data);
+ * }
+ * ```
+ *
+ * Reconnect behavior:
+ *  - `Last-Event-ID` is sent on every reconnect (the last `id:` seen).
+ *  - A server `retry: <ms>` field sets the base reconnect delay, like EventSource.
+ *  - Waits back off exponentially (capped at `maxDelayMs`) while connecting keeps
+ *    failing; 429/503 `Retry-After` is honored. A connection that delivered at
+ *    least one event resets the failure count (only no-progress attempts count
+ *    toward `retries`).
+ *  - HTTP 204 means "stop reconnecting" (iteration ends). A non-retryable
+ *    status (e.g. 401/404) or a wrong content-type throws immediately.
+ *  - Only GET reconnects by default. For other methods (e.g. a POST that starts
+ *    an LLM stream) re-sending the request could repeat side effects, so
+ *    nothing is retried unless you pass `reconnect: true`.
+ *  - Breaking out of the loop, or aborting `signal`, closes the connection.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetch=globalThis.fetch] - e.g. a createFetch() instance
+ * @param {string} [opts.method="GET"]
+ * @param {HeadersInit | (() => HeadersInit | Promise<HeadersInit>)} [opts.headers] -
+ *   a function is called before every (re)connect — handy for refreshing a token
+ * @param {BodyInit} [opts.body]
+ * @param {AbortSignal} [opts.signal]
+ * @param {string} [opts.lastEventId] - resume from here on the very first connect
+ * @param {boolean} [opts.reconnect] - default: true for GET/HEAD, false otherwise
+ * @param {number} [opts.retries=10] - consecutive failed connections before giving up (Infinity = never)
+ * @param {number} [opts.reconnectDelayMs=1000] - base delay (the server's `retry:` overrides it)
+ * @param {number} [opts.maxDelayMs=30000]
+ * @param {(event: object) => boolean} [opts.stopWhen] - end the stream (no reconnect) after this event, e.g. `e => e.data === "[DONE]"`
+ * @param {(info: {connections: number, lastEventId: string}) => void} [opts.onOpen]
+ * @param {(info: {reason: "error"|"end"|"status", error?: any, status?: number, attempt: number, delayMs: number, lastEventId: string}) => void} [opts.onReconnect]
+ * @returns {AsyncGenerator<{event: string, data: string, id: string, retry: number|undefined}>}
+ */
+async function* streamSSE(url, opts = {}) {
+  const {
+    fetch: fetchFn = globalThis.fetch,
+    method = "GET",
+    headers,
+    body,
+    signal,
+    reconnect = method === "GET" || method === "HEAD",
+    retries = 10,
+    reconnectDelayMs = 1000,
+    maxDelayMs = 30000,
+    stopWhen,
+    onOpen,
+    onReconnect,
+  } = opts;
+
+  let lastId = opts.lastEventId || "";
+  let baseDelay = reconnectDelayMs;
+  let failures = 0; // consecutive connections that delivered nothing
+  let connections = 0;
+
+  for (;;) {
+    signal?.throwIfAborted?.();
+    let failure = null; // { reason, error?, status?, response? }
+    let res = null;
+
+    // ---- connect -----------------------------------------------------------
+    try {
+      const h = await resolveHeaders(headers);
+      if (!h.has("accept")) h.set("accept", "text/event-stream");
+      if (!h.has("cache-control")) h.set("cache-control", "no-cache");
+      if (lastId) h.set("last-event-id", lastId);
+      res = await fetchFn(url, { method, headers: h, body, signal });
+    } catch (err) {
+      if (signal?.aborted) throw signal.reason ?? err;
+      if (err instanceof HTTPError) {
+        if (!isRetryableStatus(err.status)) throw err;
+        failure = { reason: "status", status: err.status, response: err.response, error: err };
+      } else if (isRetryableError(err)) {
+        failure = { reason: "error", error: err };
+      } else {
+        throw err;
+      }
+    }
+
+    // ---- inspect the response ---------------------------------------------
+    if (!failure) {
+      if (res.status === 204) {
+        await discardBody(res);
+        return; // the server's way of saying "don't reconnect"
+      }
+      if (!res.ok) {
+        if (!isRetryableStatus(res.status)) {
+          await discardBody(res);
+          throw new HTTPError(res, { method, url });
+        }
+        failure = { reason: "status", status: res.status, response: res };
+      } else {
+        const type = res.headers.get("content-type") || "";
+        if (!/text\/event-stream/i.test(type)) {
+          await discardBody(res);
+          throw Object.assign(new Error(`streamSSE: expected "text/event-stream" but the server sent "${type || "no content-type"}"`), {
+            code: "SSE_BAD_CONTENT_TYPE",
+          });
+        }
+      }
+    }
+
+    // ---- stream ------------------------------------------------------------
+    let gotEvent = false;
+    if (!failure) {
+      connections++;
+      if (onOpen) onOpen({ connections, lastEventId: lastId });
+      try {
+        for await (const event of readSSE(res, { signal })) {
+          gotEvent = true;
+          lastId = event.id;
+          if (event.retry !== undefined) baseDelay = event.retry;
+          yield event;
+          if (stopWhen && stopWhen(event)) return;
+        }
+        failure = { reason: "end" };
+      } catch (err) {
+        if (signal?.aborted) throw signal.reason ?? err;
+        if (!isRetryableError(err)) throw err;
+        failure = { reason: "error", error: err };
+      }
+    }
+
+    // ---- decide whether and when to reconnect ------------------------------
+    if (!reconnect) {
+      if (failure.reason === "end") return;
+      if (failure.reason === "status") {
+        throw failure.error || new HTTPError(failure.response, { method, url });
+      }
+      throw failure.error;
+    }
+
+    // A connection that delivered events made progress: reconnect promptly and
+    // start the failure count over. Only no-progress attempts count toward `retries`.
+    failures = gotEvent ? 0 : failures + 1;
+    if (failures > retries) {
+      if (failure.reason === "status") throw failure.error || new HTTPError(failure.response, { method, url });
+      if (failure.reason === "error") throw failure.error;
+      throw Object.assign(new Error(`streamSSE: the server keeps closing the stream without sending events — gave up after ${retries} retries`), {
+        code: "SSE_GAVE_UP",
+      });
+    }
+
+    let delayMs = Math.min(baseDelay * 2 ** Math.max(failures - 1, 0), maxDelayMs);
+    if (failure.reason === "status" && failure.response) {
+      const headerMs = getWaitMsFromHeaders(failure.response.headers);
+      if (headerMs !== null) delayMs = Math.min(headerMs, 60000);
+      await discardBody(failure.response);
+    }
+    delayMs += Math.random() * delayMs * 0.1; // a little jitter so clients don't reconnect in lockstep
+
+    if (onReconnect) {
+      onReconnect({
+        reason: failure.reason,
+        error: failure.error,
+        status: failure.status,
+        attempt: Math.max(failures, 1),
+        delayMs,
+        lastEventId: lastId,
+      });
+    }
+    await abortableSleep(delayMs, signal);
+  }
+}
+
+module.exports = { streamSSE };

package/src/streams.js

@@ -0,0 +1,149 @@
+const encoder = new TextEncoder();
+
+// Yields Uint8Array chunks from a fetch Response, a web ReadableStream, or any
+// async iterable (e.g. a Node Readable). Cancels the underlying stream when
+// the consumer stops early or the signal aborts, so the connection is freed.
+async function* chunks(source, signal) {
+  let body = source;
+  if (body && typeof body.getReader !== "function" && "body" in body) body = body.body; // a Response
+  if (body === null || body === undefined) return;
+  signal?.throwIfAborted?.();
+
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    const onAbort = () => reader.cancel(signal.reason).catch(() => {});
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        signal?.throwIfAborted?.(); // cancel() makes read() resolve as done — don't mistake that for the end
+        if (done) return;
+        yield value;
+      }
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+      reader.cancel().catch(() => {});
+    }
+  } else if (typeof body[Symbol.asyncIterator] === "function") {
+    for await (const chunk of body) {
+      signal?.throwIfAborted?.();
+      yield typeof chunk === "string" ? encoder.encode(chunk) : chunk;
+    }
+  } else {
+    throw new TypeError("reqkit streams: expected a Response, a ReadableStream or an async iterable");
+  }
+}
+
+/**
+ * Async-iterates the text lines of a streamed body. Handles \n, \r\n and \r,
+ * multi-byte characters split across chunks, and a leading BOM.
+ *
+ * ```js
+ * for await (const line of readLines(response)) console.log(line);
+ * ```
+ *
+ * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {AsyncGenerator<string>}
+ */
+async function* readLines(source, opts = {}) {
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  let first = true;
+
+  for await (const chunk of chunks(source, opts.signal)) {
+    buffer += decoder.decode(chunk, { stream: true });
+    if (first && buffer.length > 0) {
+      buffer = buffer.replace(/^\uFEFF/, "");
+      first = false;
+    }
+
+    let pos = 0;
+    for (;;) {
+      const rest = buffer.slice(pos);
+      const i = rest.search(/\r\n|\n|\r/);
+      if (i === -1) break;
+      // A trailing "\r" might be the first half of "\r\n" — wait for more data.
+      if (rest[i] === "\r" && i === rest.length - 1) break;
+      yield rest.slice(0, i);
+      pos += i + (rest.startsWith("\r\n", i) ? 2 : 1);
+    }
+    buffer = buffer.slice(pos);
+  }
+
+  buffer += decoder.decode();
+  if (buffer.endsWith("\r")) buffer = buffer.slice(0, -1);
+  if (buffer.length > 0) yield buffer;
+}
+
+/**
+ * Async-iterates parsed JSON values from a newline-delimited JSON stream
+ * (NDJSON / JSON Lines). Blank lines are skipped. A malformed line throws a
+ * SyntaxError naming the line, unless `skipInvalid` is true.
+ *
+ * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
+ * @param {{ signal?: AbortSignal, skipInvalid?: boolean }} [opts]
+ */
+async function* readNDJSON(source, opts = {}) {
+  let lineNo = 0;
+  for await (const line of readLines(source, opts)) {
+    lineNo++;
+    if (line.trim() === "") continue;
+    try {
+      yield JSON.parse(line);
+    } catch (err) {
+      if (opts.skipInvalid) continue;
+      throw new SyntaxError(`readNDJSON: invalid JSON on line ${lineNo}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Async-iterates Server-Sent Events (text/event-stream) as
+ * `{ event, data, id, retry }`, following the spec: multi-line `data:` is
+ * joined with "\n", comments (`:`) are ignored, `event` defaults to
+ * "message", `id` carries over between events, and an event cut off by the end
+ * of the stream is discarded. Great for LLM token streams.
+ *
+ * ```js
+ * for await (const { data } of readSSE(response)) {
+ *   if (data === "[DONE]") break;
+ *   console.log(JSON.parse(data));
+ * }
+ * ```
+ *
+ * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
+ * @param {{ signal?: AbortSignal }} [opts]
+ */
+async function* readSSE(source, opts = {}) {
+  let event = "";
+  let data = [];
+  let retry;
+  let lastId = "";
+
+  for await (const line of readLines(source, opts)) {
+    if (line === "") {
+      if (data.length > 0) yield { event: event || "message", data: data.join("\n"), id: lastId, retry };
+      event = "";
+      data = [];
+      retry = undefined;
+      continue;
+    }
+    if (line.startsWith(":")) continue;
+
+    const idx = line.indexOf(":");
+    const field = idx === -1 ? line : line.slice(0, idx);
+    let value = idx === -1 ? "" : line.slice(idx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+    else if (field === "id") {
+      if (!value.includes("\0")) lastId = value;
+    } else if (field === "retry") {
+      if (/^\d+$/.test(value)) retry = Number(value);
+    }
+  }
+}
+
+module.exports = { readLines, readNDJSON, readSSE };