@theholocron/http-client 1.57.1-alpha.1 → 1.57.1-alpha.2

package/README.md

@@ -28,21 +28,34 @@ const data = await client.request<{ id: string }>("/widgets/42");
 
 **Config options:**
 
-| Option         | Type                     | Default            | Description                                       |
-| -------------- | ------------------------ | ------------------ | ------------------------------------------------- |
-| `baseUrl`      | `string`                 | —                  | Base URL, trailing slashes trimmed automatically  |
-| `token`        | `string`                 | —                  | Auth token                                        |
-| `tokenScheme`  | `"bearer" \| "apikey"`   | `"bearer"`         | How the token is sent                             |
-| `apiKeyHeader` | `string`                 | `"x-api-key"`      | Header name when `tokenScheme` is `"apikey"`      |
-| `extraHeaders` | `Record<string, string>` | —                  | Static headers merged into every request          |
-| `defaultQuery` | `Record<string, string>` | —                  | Query params appended to every request URL        |
-| `vendor`       | `string`                 | —                  | Vendor label for error messages                   |
-| `fetch`        | `typeof fetch`           | `globalThis.fetch` | Override fetch for testing                        |
-| `logger`       | `Logger`                 | no-op              | Structured request/response diagnostics (`debug`) |
-| `errors`       | `ErrorSink`              | no-op              | Reports transport failures + unexpected 5xx       |
+| Option          | Type                     | Default            | Description                                                  |
+| --------------- | ------------------------ | ------------------ | ------------------------------------------------------------ |
+| `baseUrl`       | `string`                 | —                  | Base URL, trailing slashes trimmed automatically             |
+| `token`         | `string`                 | —                  | Auth token                                                   |
+| `tokenScheme`   | `"bearer" \| "apikey"`   | `"bearer"`         | How the token is sent                                        |
+| `apiKeyHeader`  | `string`                 | `"x-api-key"`      | Header name when `tokenScheme` is `"apikey"`                 |
+| `extraHeaders`  | `Record<string, string>` | —                  | Static headers merged into every request                     |
+| `defaultQuery`  | `Record<string, string>` | —                  | Query params appended to every request URL                   |
+| `vendor`        | `string`                 | —                  | Vendor label for error messages                              |
+| `fetch`         | `typeof fetch`           | `globalThis.fetch` | Override fetch for testing                                   |
+| `logger`        | `Logger`                 | no-op              | Structured request/response diagnostics (`debug`)            |
+| `errors`        | `ErrorSink`              | no-op              | Reports transport failures + unexpected 5xx                  |
+| `retries`       | `number`                 | `2`                | Times a request is sent again (see Retries); `0` is off      |
+| `retryDelayMs`  | `number`                 | `300`              | Wait before the first retry; each later one waits 3× as long |
+| `retryStatuses` | `readonly number[]`      | none               | HTTP statuses a **read** is sent again on (see Retries)      |
+
+**Retries.** A request is sent again, up to `retries` times, after a transport failure that cannot have applied it twice (the connection never opened, or a read was dropped). By default an HTTP error status is never retried. List statuses in `retryStatuses` (for example `[500, 502, 503, 504]`) to ask for a read again when the server answers one of them. Only `GET` and `HEAD` are repeated on a status: a write may already have been applied, so it fails at once. A status that is not listed (a 4xx, a 429) fails at once too; `Retry-After` is not honoured.
+
+When a request still fails after being sent again, the `ProviderApiError` keeps the last `status` and `details` and its message says how many sends it took, with the vendor's request id when the response carried one (`cf-ray`, else `x-request-id`):
+
+```text
+Cloudflare GET /zones/abc/dns_records → 500 (after 3 attempts; cf-ray: 8a1b2c3d4e5f-LHR)
+```
+
+Every retry is reported to [`onRetry`](#onretrylistener); for a status the event's `code` is `HTTP 500`.
 
 **Observability seam.** `logger` and `errors` accept the `Logger` / `ErrorSink`
-interfaces from [`@theholocron/observability/core`](https://github.com/theholocron/observability)
+interfaces from [`@theholocron/observability/core`](https://github.com/theholocron/holocron/tree/alpha/observability)
 — a seam, not a runtime: the library never calls `Sentry.init` or reads
 credentials itself, and both default to a silent no-op when omitted.
 

package/dist/index.d.mts

@@ -91,12 +91,18 @@ interface RestClientConfig {
   errors?: ErrorSink;
   /**
    * How many times to send a request again after a transport failure that is safe to repeat (see `worthRetrying`):
-   * the connection never opened, or a read was dropped. HTTP error statuses are never retried. Defaults to 2; 0
-   * turns it off.
+   * the connection never opened, or a read was dropped. An HTTP error status is retried only when it is listed in
+   * `retryStatuses`. Defaults to 2; 0 turns it off.
    */
   retries?: number;
   /** Milliseconds before the first retry; each later one waits three times as long. Defaults to 300. */
   retryDelayMs?: number;
+  /**
+   * HTTP statuses (for example `[500, 502, 503, 504]`) that are worth asking for again, using the same `retries`
+   * and `retryDelayMs`. Only a read (GET or HEAD) is repeated; a write is never sent again on a status, because the
+   * server may have applied it. Defaults to none, so a client that does not ask behaves as before.
+   */
+  retryStatuses?: readonly number[];
 }
 interface RequestOptions {
   method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
@@ -111,13 +117,16 @@ interface RestClient {
   request<T>(path: string, opts?: RequestOptions): Promise<T>;
 }
 export declare function createRestClient(config: RestClientConfig): RestClient;
-/** A request about to be sent again after a transport failure. */
+/** A request about to be sent again after a transport failure, or an HTTP status the client was told to retry. */
 interface RetryEvent {
   /** The client's `vendor` label, e.g. `GitHub`. */
   vendor?: string;
   method: string;
   path: string;
-  /** What went wrong (`ECONNRESET`, `UND_ERR_CONNECT_TIMEOUT`); a failure with no known cause is never retried. */
+  /**
+   * What went wrong (`ECONNRESET`, `UND_ERR_CONNECT_TIMEOUT`, or `HTTP 503` for a retried status); a failure with no
+   * known cause is never retried.
+   */
   code: string;
   /** The number of the send that is about to happen: 2 for the first retry. */
   attempt: number;

package/dist/index.mjs

@@ -95,6 +95,10 @@ const DROPPED = /* @__PURE__ */ new Set([
 	"UND_ERR_SOCKET",
 	"ETIMEDOUT"
 ]);
+/** Whether a request only reads, so sending it again changes nothing. */
+function isRead(method) {
+	return method === "GET" || method === "HEAD";
+}
 /**
 * Whether a failed request is worth sending again: always when it never left, and for a read when the connection
 * dropped (a repeat read changes nothing). A write that may have arrived is never repeated.
@@ -102,9 +106,23 @@ const DROPPED = /* @__PURE__ */ new Set([
 function worthRetrying(code, method) {
 	if (!code) return false;
 	if (NEVER_SENT.has(code)) return true;
-	return DROPPED.has(code) && (method === "GET" || method === "HEAD");
+	return DROPPED.has(code) && isRead(method);
 }
 // src/rest-client.ts
+/** The text of a response, or nothing when it cannot be read: an error body is a courtesy, not a reason to fail. */
+const readBody = (res) => res.text().catch(() => "");
+/** Response headers that name the request on the vendor's side, the first one present is quoted in an error. */
+const REQUEST_ID_HEADERS = ["cf-ray", "x-request-id"];
+/**
+* What to add to the message of an error that came after the request was sent again: how many sends it took, and the
+* vendor's id for the last one, so a failure that kept happening can be told apart from a misconfiguration and be
+* reported to the vendor. Nothing for a request that was only sent once.
+*/
+function retriedNote(res, attempt) {
+	if (attempt === 0) return "";
+	const header = REQUEST_ID_HEADERS.find((name) => res.headers.has(name));
+	return ` (after ${attempt + 1} attempts${header ? `; ${header}: ${res.headers.get(header)}` : ""})`;
+}
 function createRestClient(config) {
 	const fetchImpl = config.fetch ?? globalThis.fetch;
 	const vendor = config.vendor ?? "";
@@ -112,6 +130,7 @@ function createRestClient(config) {
 	const errors = config.errors ?? new NoopErrorSink();
 	const maxRetries = config.retries ?? 2;
 	const retryDelay = config.retryDelayMs ?? 300;
+	const retryStatuses = new Set(config.retryStatuses ?? []);
 	let baseUrl = config.baseUrl;
 	while (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
 	const staticHeaders = { accept: "application/json" };
@@ -140,40 +159,51 @@ function createRestClient(config) {
 				method: init.method,
 				path
 			}, "request");
+			const pause = async (attempt, code) => {
+				logger.debug({
+					vendor,
+					method: init.method,
+					path,
+					code,
+					attempt: attempt + 1
+				}, "retrying");
+				const delayMs = retryDelay * 3 ** attempt;
+				notifyRetry({
+					...vendor ? { vendor } : {},
+					method: init.method,
+					path,
+					code,
+					attempt: attempt + 2,
+					of: maxRetries + 1,
+					delayMs
+				});
+				await new Promise((resolve) => setTimeout(resolve, delayMs));
+			};
 			let res;
-			for (let attempt = 0;; attempt++) try {
-				res = await fetchImpl(url.toString(), init);
-				break;
-			} catch (err) {
-				const code = transportCode(err);
-				if (attempt < maxRetries && worthRetrying(code, init.method)) {
-					logger.debug({
-						vendor,
-						method: init.method,
-						path,
-						code,
-						attempt: attempt + 1
-					}, "retrying");
-					const delayMs = retryDelay * 3 ** attempt;
-					notifyRetry({
-						...vendor ? { vendor } : {},
-						method: init.method,
-						path,
-						code,
-						attempt: attempt + 2,
-						of: maxRetries + 1,
-						delayMs
-					});
-					await new Promise((resolve) => setTimeout(resolve, delayMs));
+			let attempt = 0;
+			for (;; attempt++) {
+				try {
+					res = await fetchImpl(url.toString(), init);
+				} catch (err) {
+					const code = transportCode(err);
+					if (attempt < maxRetries && worthRetrying(code, init.method)) {
+						await pause(attempt, code);
+						continue;
+					}
+					const apiErr = new ProviderApiError(`${tag} failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}${code ? ` (${code})` : ""}`, 0, void 0);
+					errors.captureException(apiErr);
+					throw apiErr;
+				}
+				if (!res.ok && attempt < maxRetries && retryStatuses.has(res.status) && isRead(init.method)) {
+					await readBody(res);
+					await pause(attempt, `HTTP ${res.status}`);
 					continue;
 				}
-				const apiErr = new ProviderApiError(`${tag} failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}${code ? ` (${code})` : ""}`, 0, void 0);
-				errors.captureException(apiErr);
-				throw apiErr;
+				break;
 			}
 			if (!res.ok) {
-				const body = await res.text().catch(() => "");
-				const apiErr = new ProviderApiError(`${tag} → ${res.status}`, res.status, body);
+				const body = await readBody(res);
+				const apiErr = new ProviderApiError(`${tag} → ${res.status}${retriedNote(res, attempt)}`, res.status, body);
 				if (res.status >= 500) errors.captureException(apiErr);
 				throw apiErr;
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/http-client",
-  "version": "1.57.1-alpha.1",
+  "version": "1.57.1-alpha.2",
   "description": "Shared HTTP primitives for theholocron — REST client factory, auth resolver, and error types",
   "keywords": [
     "typescript",
@@ -36,14 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/env-utils": "^1.16.0",
-    "@theholocron/observability": "^0.6.0"
+    "@theholocron/observability": "^0.6.1-alpha.1",
+    "@theholocron/env-utils": "^1.16.1-alpha.1"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.8.2",
-    "@theholocron/tsconfig": "^8.8.2",
-    "@theholocron/tsdown-config": "^8.8.2",
-    "@theholocron/vitest-config": "^8.8.2",
     "@types/node": "^26",
     "@vitest/coverage-v8": "^5.0.5",
     "@vitest/eslint-plugin": "^1.6.27",
@@ -52,7 +48,11 @@
     "globals": "^17.11.0",
     "tsdown": "^0.23.3",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "@theholocron/eslint-config": "^8.9.0-alpha.3",
+    "@theholocron/tsconfig": "^8.9.0-alpha.3",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
+    "@theholocron/vitest-config": "^8.9.0-alpha.3"
   },
   "peerDependencies": {
     "vitest": ">=4.0.0"