@zauru-sdk/common 6.9.0 → 6.10.0

package/dist/common.d.ts

@@ -182,9 +182,12 @@ export declare const sortByProperty: (array: any[], property: string) => any[];
 /**
  * Handle web app table actions and return a response with a consistent format.
  * @param action A function that returns a Promise of type T.
+ * @param timeout Seconds for the whole callback. Omit to use the active
+ *   HTTP client policy (25s by default). `false` disables the race so each
+ *   HTTP call uses its own axios timeout.
  * @returns A Promise of AxiosUtilsResponse<T>.
  */
-export declare function handlePossibleAxiosErrors<T>(action: () => Promise<T>, timeout?: number): Promise<AxiosUtilsResponse<T>>;
+export declare function handlePossibleAxiosErrors<T>(action: () => Promise<T>, timeout?: number | false): Promise<AxiosUtilsResponse<T>>;
 /**
  * createPostgresUrl
  * @param host

package/dist/esm/common.js

@@ -25,6 +25,7 @@ const moment_1 = __importDefault(require("moment"));
 require("moment-timezone");
 const types_1 = require("@zauru-sdk/types");
 const rejectionPercentageAdjustment_js_1 = require("./rejectionPercentageAdjustment.js");
+const httpClientPolicy_js_1 = require("./httpClientPolicy.js");
 exports.DESTINOS_MUESTRA_OPTIONS = [
     { label: "Microbiología", value: "microbiologa" },
     { label: "Residuos de plaguicidas", value: "residuos_de_plaguicidas" },
@@ -711,13 +712,36 @@ exports.sortByProperty = sortByProperty;
 /**
  * Handle web app table actions and return a response with a consistent format.
  * @param action A function that returns a Promise of type T.
+ * @param timeout Seconds for the whole callback. Omit to use the active
+ *   HTTP client policy (25s by default). `false` disables the race so each
+ *   HTTP call uses its own axios timeout.
  * @returns A Promise of AxiosUtilsResponse<T>.
  */
-async function handlePossibleAxiosErrors(action, timeout = 25) {
-    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout skipped after ${timeout} seconds`)), timeout * 1000));
+async function handlePossibleAxiosErrors(action, timeout) {
+    const policyTimeout = (0, httpClientPolicy_js_1.getHttpClientPolicy)().actionTimeoutSeconds;
+    const resolved = timeout === undefined ? policyTimeout : timeout;
+    const seconds = resolved === false || resolved <= 0
+        ? null
+        : resolved ?? httpClientPolicy_js_1.DEFAULT_ACTION_TIMEOUT_SECONDS;
     try {
-        const result = await Promise.race([action(), timeoutPromise]);
-        return { error: false, data: result };
+        if (seconds == null) {
+            const result = await action();
+            return { error: false, data: result };
+        }
+        let timer;
+        try {
+            const result = await Promise.race([
+                action(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`Timeout skipped after ${seconds} seconds`)), seconds * 1000);
+                }),
+            ]);
+            return { error: false, data: result };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
     }
     catch (error) {
         return {

package/dist/esm/httpClientPolicy.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Timeouts and retries for outbound HTTP (Zauru REST + Hasura GraphQL).
+ *
+ * Defaults keep the 25s action budget of Netlify sync functions. Background
+ * lambdas opt into {@link BACKGROUND_HTTP_CLIENT_POLICY}: per-request max of
+ * 30s (Heroku router H12 and Hasura `HASURA_GRAPHQL_SERVER_TIMEOUT` default)
+ * and one retry. The 25s `handlePossibleAxiosErrors` race is disabled there
+ * so a slow query is not aborted before the platform itself gives up.
+ *
+ * Use {@link runWithHttpClientPolicy} / {@link withHttpClientPolicy} around a
+ * set of calls, or pass `timeout` on a single axios config to override one
+ * request. GraphQL POSTs retry; Zauru writes do not retry on timeout (the
+ * server may have committed).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BACKGROUND_HTTP_CLIENT_POLICY = exports.DEFAULT_HTTP_CLIENT_POLICY = exports.HASURA_SERVER_TIMEOUT_SECONDS = exports.HEROKU_ROUTER_TIMEOUT_SECONDS = exports.DEFAULT_HTTP_TIMEOUT_SECONDS = exports.DEFAULT_ACTION_TIMEOUT_SECONDS = void 0;
+exports.mergeHttpClientPolicies = mergeHttpClientPolicies;
+exports.bindHttpClientPolicyRuntime = bindHttpClientPolicyRuntime;
+exports.getHttpClientPolicy = getHttpClientPolicy;
+exports.runWithHttpClientPolicy = runWithHttpClientPolicy;
+exports.withHttpClientPolicy = withHttpClientPolicy;
+exports.isRetryableHttpError = isRetryableHttpError;
+exports.httpTimeoutMsForClient = httpTimeoutMsForClient;
+exports.DEFAULT_ACTION_TIMEOUT_SECONDS = 25;
+exports.DEFAULT_HTTP_TIMEOUT_SECONDS = 200;
+exports.HEROKU_ROUTER_TIMEOUT_SECONDS = 30;
+exports.HASURA_SERVER_TIMEOUT_SECONDS = 30;
+exports.DEFAULT_HTTP_CLIENT_POLICY = {
+    actionTimeoutSeconds: exports.DEFAULT_ACTION_TIMEOUT_SECONDS,
+    zauruTimeoutSeconds: exports.DEFAULT_HTTP_TIMEOUT_SECONDS,
+    graphqlTimeoutSeconds: exports.DEFAULT_HTTP_TIMEOUT_SECONDS,
+    retries: 0,
+};
+exports.BACKGROUND_HTTP_CLIENT_POLICY = {
+    actionTimeoutSeconds: false,
+    zauruTimeoutSeconds: exports.HEROKU_ROUTER_TIMEOUT_SECONDS,
+    graphqlTimeoutSeconds: exports.HASURA_SERVER_TIMEOUT_SECONDS,
+    retries: 1,
+};
+const RETRYABLE_STATUS = new Set([408, 429, 502, 503, 504]);
+const RETRYABLE_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ECONNABORTED",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ERR_NETWORK",
+    "ERR_CANCELED",
+]);
+function mergeHttpClientPolicies(base, override = {}) {
+    return {
+        ...exports.DEFAULT_HTTP_CLIENT_POLICY,
+        ...base,
+        ...override,
+    };
+}
+let fallbackStore;
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.then === "function");
+}
+function runWithFallbackStore(policy, fn) {
+    const previous = fallbackStore;
+    fallbackStore = policy;
+    try {
+        const result = fn();
+        if (isThenable(result)) {
+            return result.finally(() => {
+                fallbackStore = previous;
+            });
+        }
+        fallbackStore = previous;
+        return result;
+    }
+    catch (error) {
+        fallbackStore = previous;
+        throw error;
+    }
+}
+const fallbackRuntime = {
+    get: () => fallbackStore,
+    run: runWithFallbackStore,
+};
+let runtime = fallbackRuntime;
+/**
+ * Services bind AsyncLocalStorage here so concurrent serverless invocations
+ * do not leak policy. Common stays browser-safe (no `node:async_hooks`).
+ */
+function bindHttpClientPolicyRuntime(next) {
+    runtime = next;
+}
+function getHttpClientPolicy() {
+    return mergeHttpClientPolicies(undefined, runtime.get() ?? {});
+}
+function runWithHttpClientPolicy(policy, fn) {
+    const merged = mergeHttpClientPolicies(runtime.get(), policy);
+    return runtime.run(merged, fn);
+}
+function withHttpClientPolicy(policy, fn) {
+    return (...args) => runWithHttpClientPolicy(policy, () => fn(...args));
+}
+function isTimeoutError(error) {
+    const code = error.code ?? "";
+    if (code === "ECONNABORTED" || code === "ETIMEDOUT") {
+        return true;
+    }
+    return /timeout/i.test(error.message ?? "");
+}
+function isTransientFailure(error) {
+    const status = error.response?.status;
+    if (status != null) {
+        return RETRYABLE_STATUS.has(status);
+    }
+    const code = error.code ?? "";
+    return isTimeoutError(error) || RETRYABLE_NETWORK_CODES.has(code);
+}
+function isRetryableZauruError(error) {
+    const method = (error.config?.method ?? "get").toLowerCase();
+    const idempotent = method === "get" || method === "head" || method === "options";
+    if (idempotent) {
+        return isTransientFailure(error);
+    }
+    if (error.response?.status != null || isTimeoutError(error)) {
+        return false;
+    }
+    return RETRYABLE_NETWORK_CODES.has(error.code ?? "");
+}
+function isRetryableHttpError(error, client) {
+    switch (client) {
+        case "graphql":
+            return isTransientFailure(error);
+        case "zauru":
+            return isRetryableZauruError(error);
+        default: {
+            const _never = client;
+            return _never;
+        }
+    }
+}
+function httpTimeoutMsForClient(client, policy = getHttpClientPolicy()) {
+    switch (client) {
+        case "graphql":
+            return policy.graphqlTimeoutSeconds * 1000;
+        case "zauru":
+            return policy.zauruTimeoutSeconds * 1000;
+        default: {
+            const _never = client;
+            return _never;
+        }
+    }
+}

package/dist/esm/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./common.js"), exports);
 __exportStar(require("./gtZones.js"), exports);
+__exportStar(require("./httpClientPolicy.js"), exports);
 __exportStar(require("./oauthErrors.js"), exports);
 __exportStar(require("./rejectionPercentageAdjustment.js"), exports);

package/dist/httpClientPolicy.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Timeouts and retries for outbound HTTP (Zauru REST + Hasura GraphQL).
+ *
+ * Defaults keep the 25s action budget of Netlify sync functions. Background
+ * lambdas opt into {@link BACKGROUND_HTTP_CLIENT_POLICY}: per-request max of
+ * 30s (Heroku router H12 and Hasura `HASURA_GRAPHQL_SERVER_TIMEOUT` default)
+ * and one retry. The 25s `handlePossibleAxiosErrors` race is disabled there
+ * so a slow query is not aborted before the platform itself gives up.
+ *
+ * Use {@link runWithHttpClientPolicy} / {@link withHttpClientPolicy} around a
+ * set of calls, or pass `timeout` on a single axios config to override one
+ * request. GraphQL POSTs retry; Zauru writes do not retry on timeout (the
+ * server may have committed).
+ */
+export type HttpClientKind = "graphql" | "zauru";
+export type HttpClientPolicy = {
+    /**
+     * Budget for the whole `handlePossibleAxiosErrors` callback.
+     * `false` disables that race so each HTTP call uses its own timeout.
+     */
+    actionTimeoutSeconds?: number | false;
+    zauruTimeoutSeconds?: number;
+    graphqlTimeoutSeconds?: number;
+    /** Extra attempts after the first failure. `1` = retry once. */
+    retries?: number;
+};
+export type ResolvedHttpClientPolicy = {
+    actionTimeoutSeconds: number | false;
+    zauruTimeoutSeconds: number;
+    graphqlTimeoutSeconds: number;
+    retries: number;
+};
+export type HttpErrorLike = {
+    code?: string;
+    message?: string;
+    response?: {
+        status?: number;
+    };
+    config?: {
+        method?: string;
+    };
+};
+export declare const DEFAULT_ACTION_TIMEOUT_SECONDS = 25;
+export declare const DEFAULT_HTTP_TIMEOUT_SECONDS = 200;
+export declare const HEROKU_ROUTER_TIMEOUT_SECONDS = 30;
+export declare const HASURA_SERVER_TIMEOUT_SECONDS = 30;
+export declare const DEFAULT_HTTP_CLIENT_POLICY: ResolvedHttpClientPolicy;
+export declare const BACKGROUND_HTTP_CLIENT_POLICY: HttpClientPolicy;
+export declare function mergeHttpClientPolicies(base: HttpClientPolicy | undefined, override?: HttpClientPolicy): ResolvedHttpClientPolicy;
+type PolicyRuntime = {
+    get: () => HttpClientPolicy | undefined;
+    run: <T>(policy: ResolvedHttpClientPolicy, fn: () => T) => T;
+};
+/**
+ * Services bind AsyncLocalStorage here so concurrent serverless invocations
+ * do not leak policy. Common stays browser-safe (no `node:async_hooks`).
+ */
+export declare function bindHttpClientPolicyRuntime(next: PolicyRuntime): void;
+export declare function getHttpClientPolicy(): ResolvedHttpClientPolicy;
+export declare function runWithHttpClientPolicy<T>(policy: HttpClientPolicy, fn: () => T): T;
+export declare function withHttpClientPolicy<Args extends unknown[], Result>(policy: HttpClientPolicy, fn: (...args: Args) => Result): (...args: Args) => Result;
+export declare function isRetryableHttpError(error: HttpErrorLike, client: HttpClientKind): boolean;
+export declare function httpTimeoutMsForClient(client: HttpClientKind, policy?: ResolvedHttpClientPolicy): number;
+export {};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./common.js";
 export * from "./gtZones.js";
+export * from "./httpClientPolicy.js";
 export * from "./oauthErrors.js";
 export * from "./rejectionPercentageAdjustment.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zauru-sdk/common",
-  "version": "6.9.0",
+  "version": "6.10.0",
   "description": "Funciones de uso común en el desarrollo de webapps en Zauru",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
@@ -12,11 +12,12 @@
   "scripts": {
     "build": "npm run build:esm",
     "build:esm": "tsc -p tsconfig.esm.json",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "tsx --test src/httpClientPolicy.test.ts"
   },
   "author": "Oscar Cuéllar",
   "license": "MIT",
   "devDependencies": {
+    "tsx": "^4.23.15",
     "typescript": "^5.1.6"
   },
   "dependencies": {
@@ -25,5 +26,5 @@
     "moment": "^2.30.1",
     "moment-timezone": "^0.5.45"
   },
-  "gitHead": "a46ebe234551d76d6a0ea9095be6e55540006ab3"
+  "gitHead": "8df8d97cb33e23e09198c617a95cffdff96cd05b"
 }

package/src/common.ts

@@ -21,6 +21,10 @@ import {
   normalizeRejectionPercentageLayers,
   resolveRejectionPercentageOrigin,
 } from "./rejectionPercentageAdjustment.js";
+import {
+  DEFAULT_ACTION_TIMEOUT_SECONDS,
+  getHttpClientPolicy,
+} from "./httpClientPolicy.js";
 
 export const DESTINOS_MUESTRA_OPTIONS: SelectFieldOption[] = [
   { label: "Microbiología", value: "microbiologa" },
@@ -848,22 +852,44 @@ export const sortByProperty = (array: any[], property: string) => {
 /**
  * Handle web app table actions and return a response with a consistent format.
  * @param action A function that returns a Promise of type T.
+ * @param timeout Seconds for the whole callback. Omit to use the active
+ *   HTTP client policy (25s by default). `false` disables the race so each
+ *   HTTP call uses its own axios timeout.
  * @returns A Promise of AxiosUtilsResponse<T>.
  */
 export async function handlePossibleAxiosErrors<T>(
   action: () => Promise<T>,
-  timeout: number = 25
+  timeout?: number | false,
 ): Promise<AxiosUtilsResponse<T>> {
-  const timeoutPromise = new Promise((_, reject) =>
-    setTimeout(
-      () => reject(new Error(`Timeout skipped after ${timeout} seconds`)),
-      timeout * 1000
-    )
-  );
+  const policyTimeout = getHttpClientPolicy().actionTimeoutSeconds;
+  const resolved = timeout === undefined ? policyTimeout : timeout;
+  const seconds =
+    resolved === false || resolved <= 0
+      ? null
+      : resolved ?? DEFAULT_ACTION_TIMEOUT_SECONDS;
 
   try {
-    const result = await Promise.race([action(), timeoutPromise]);
-    return { error: false, data: result } as AxiosUtilsResponse<T>;
+    if (seconds == null) {
+      const result = await action();
+      return { error: false, data: result } as AxiosUtilsResponse<T>;
+    }
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const result = await Promise.race([
+        action(),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () =>
+              reject(new Error(`Timeout skipped after ${seconds} seconds`)),
+            seconds * 1000,
+          );
+        }),
+      ]);
+      return { error: false, data: result } as AxiosUtilsResponse<T>;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
   } catch (error) {
     return {
       error: true,

package/src/httpClientPolicy.test.ts

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { handlePossibleAxiosErrors } from "./common.js";
+import {
+  BACKGROUND_HTTP_CLIENT_POLICY,
+  DEFAULT_HTTP_CLIENT_POLICY,
+  getHttpClientPolicy,
+  isRetryableHttpError,
+  mergeHttpClientPolicies,
+  runWithHttpClientPolicy,
+} from "./httpClientPolicy.js";
+
+describe("mergeHttpClientPolicies", () => {
+  it("When merging an empty override, it should keep the defaults", () => {
+    assert.deepEqual(
+      mergeHttpClientPolicies(undefined, {}),
+      DEFAULT_HTTP_CLIENT_POLICY,
+    );
+  });
+
+  it("When merging a background policy, it should disable the action race and set 30s + 1 retry", () => {
+    const merged = mergeHttpClientPolicies(
+      undefined,
+      BACKGROUND_HTTP_CLIENT_POLICY,
+    );
+    assert.equal(merged.actionTimeoutSeconds, false);
+    assert.equal(merged.zauruTimeoutSeconds, 30);
+    assert.equal(merged.graphqlTimeoutSeconds, 30);
+    assert.equal(merged.retries, 1);
+  });
+
+  it("When nesting policies, it should let the inner override win", () => {
+    const merged = mergeHttpClientPolicies(
+      BACKGROUND_HTTP_CLIENT_POLICY,
+      { graphqlTimeoutSeconds: 15, retries: 2 },
+    );
+    assert.equal(merged.actionTimeoutSeconds, false);
+    assert.equal(merged.graphqlTimeoutSeconds, 15);
+    assert.equal(merged.zauruTimeoutSeconds, 30);
+    assert.equal(merged.retries, 2);
+  });
+});
+
+describe("runWithHttpClientPolicy", () => {
+  it("When running a policy, it should apply inside the callback and restore after", () => {
+    assert.equal(getHttpClientPolicy().retries, 0);
+    const inside = runWithHttpClientPolicy({ retries: 1 }, () =>
+      getHttpClientPolicy().retries,
+    );
+    assert.equal(inside, 1);
+    assert.equal(getHttpClientPolicy().retries, 0);
+  });
+
+  it("When the callback is async, it should restore the policy after it settles", async () => {
+    await runWithHttpClientPolicy(
+      { actionTimeoutSeconds: false },
+      async () => {
+        assert.equal(getHttpClientPolicy().actionTimeoutSeconds, false);
+      },
+    );
+    assert.equal(getHttpClientPolicy().actionTimeoutSeconds, 25);
+  });
+});
+
+describe("isRetryableHttpError", () => {
+  it("When GraphQL times out, it should retry", () => {
+    assert.equal(
+      isRetryableHttpError(
+        { code: "ECONNABORTED", message: "timeout of 30000ms exceeded" },
+        "graphql",
+      ),
+      true,
+    );
+  });
+
+  it("When GraphQL returns 503, it should retry", () => {
+    assert.equal(
+      isRetryableHttpError({ response: { status: 503 } }, "graphql"),
+      true,
+    );
+  });
+
+  it("When Zauru GET times out, it should retry", () => {
+    assert.equal(
+      isRetryableHttpError(
+        { code: "ETIMEDOUT", config: { method: "get" } },
+        "zauru",
+      ),
+      true,
+    );
+  });
+
+  it("When Zauru POST times out, it should not retry", () => {
+    assert.equal(
+      isRetryableHttpError(
+        { code: "ECONNABORTED", config: { method: "post" } },
+        "zauru",
+      ),
+      false,
+    );
+  });
+
+  it("When Zauru POST gets 422, it should not retry", () => {
+    assert.equal(
+      isRetryableHttpError(
+        { response: { status: 422 }, config: { method: "post" } },
+        "zauru",
+      ),
+      false,
+    );
+  });
+});
+
+describe("handlePossibleAxiosErrors", () => {
+  it("When the action timeout is disabled, it should wait for a slow callback", async () => {
+    const result = await runWithHttpClientPolicy(
+      { actionTimeoutSeconds: false },
+      () =>
+        handlePossibleAxiosErrors(async () => {
+          await new Promise((resolve) => setTimeout(resolve, 80));
+          return "ok";
+        }),
+    );
+    assert.equal(result.error, false);
+    assert.equal(result.data, "ok");
+  });
+
+  it("When the action exceeds the timeout, it should return Timeout skipped", async () => {
+    const result = await handlePossibleAxiosErrors(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 80));
+      return "ok";
+    }, 0.05);
+    assert.equal(result.error, true);
+    assert.match(result.userMsg ?? "", /Timeout skipped after 0.05 seconds/);
+  });
+});

package/src/httpClientPolicy.ts

@@ -0,0 +1,216 @@
+/**
+ * Timeouts and retries for outbound HTTP (Zauru REST + Hasura GraphQL).
+ *
+ * Defaults keep the 25s action budget of Netlify sync functions. Background
+ * lambdas opt into {@link BACKGROUND_HTTP_CLIENT_POLICY}: per-request max of
+ * 30s (Heroku router H12 and Hasura `HASURA_GRAPHQL_SERVER_TIMEOUT` default)
+ * and one retry. The 25s `handlePossibleAxiosErrors` race is disabled there
+ * so a slow query is not aborted before the platform itself gives up.
+ *
+ * Use {@link runWithHttpClientPolicy} / {@link withHttpClientPolicy} around a
+ * set of calls, or pass `timeout` on a single axios config to override one
+ * request. GraphQL POSTs retry; Zauru writes do not retry on timeout (the
+ * server may have committed).
+ */
+
+export type HttpClientKind = "graphql" | "zauru";
+
+export type HttpClientPolicy = {
+  /**
+   * Budget for the whole `handlePossibleAxiosErrors` callback.
+   * `false` disables that race so each HTTP call uses its own timeout.
+   */
+  actionTimeoutSeconds?: number | false;
+  zauruTimeoutSeconds?: number;
+  graphqlTimeoutSeconds?: number;
+  /** Extra attempts after the first failure. `1` = retry once. */
+  retries?: number;
+};
+
+export type ResolvedHttpClientPolicy = {
+  actionTimeoutSeconds: number | false;
+  zauruTimeoutSeconds: number;
+  graphqlTimeoutSeconds: number;
+  retries: number;
+};
+
+export type HttpErrorLike = {
+  code?: string;
+  message?: string;
+  response?: { status?: number };
+  config?: { method?: string };
+};
+
+export const DEFAULT_ACTION_TIMEOUT_SECONDS = 25;
+export const DEFAULT_HTTP_TIMEOUT_SECONDS = 200;
+export const HEROKU_ROUTER_TIMEOUT_SECONDS = 30;
+export const HASURA_SERVER_TIMEOUT_SECONDS = 30;
+
+export const DEFAULT_HTTP_CLIENT_POLICY: ResolvedHttpClientPolicy = {
+  actionTimeoutSeconds: DEFAULT_ACTION_TIMEOUT_SECONDS,
+  zauruTimeoutSeconds: DEFAULT_HTTP_TIMEOUT_SECONDS,
+  graphqlTimeoutSeconds: DEFAULT_HTTP_TIMEOUT_SECONDS,
+  retries: 0,
+};
+
+export const BACKGROUND_HTTP_CLIENT_POLICY: HttpClientPolicy = {
+  actionTimeoutSeconds: false,
+  zauruTimeoutSeconds: HEROKU_ROUTER_TIMEOUT_SECONDS,
+  graphqlTimeoutSeconds: HASURA_SERVER_TIMEOUT_SECONDS,
+  retries: 1,
+};
+
+const RETRYABLE_STATUS = new Set([408, 429, 502, 503, 504]);
+const RETRYABLE_NETWORK_CODES = new Set([
+  "ECONNRESET",
+  "ECONNABORTED",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ERR_NETWORK",
+  "ERR_CANCELED",
+]);
+
+export function mergeHttpClientPolicies(
+  base: HttpClientPolicy | undefined,
+  override: HttpClientPolicy = {},
+): ResolvedHttpClientPolicy {
+  return {
+    ...DEFAULT_HTTP_CLIENT_POLICY,
+    ...base,
+    ...override,
+  };
+}
+
+type PolicyRuntime = {
+  get: () => HttpClientPolicy | undefined;
+  run: <T>(policy: ResolvedHttpClientPolicy, fn: () => T) => T;
+};
+
+let fallbackStore: HttpClientPolicy | undefined;
+
+function isThenable(value: unknown): value is Promise<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function runWithFallbackStore<T>(
+  policy: ResolvedHttpClientPolicy,
+  fn: () => T,
+): T {
+  const previous = fallbackStore;
+  fallbackStore = policy;
+  try {
+    const result = fn();
+    if (isThenable(result)) {
+      return result.finally(() => {
+        fallbackStore = previous;
+      }) as T;
+    }
+    fallbackStore = previous;
+    return result;
+  } catch (error) {
+    fallbackStore = previous;
+    throw error;
+  }
+}
+
+const fallbackRuntime: PolicyRuntime = {
+  get: () => fallbackStore,
+  run: runWithFallbackStore,
+};
+
+let runtime: PolicyRuntime = fallbackRuntime;
+
+/**
+ * Services bind AsyncLocalStorage here so concurrent serverless invocations
+ * do not leak policy. Common stays browser-safe (no `node:async_hooks`).
+ */
+export function bindHttpClientPolicyRuntime(next: PolicyRuntime): void {
+  runtime = next;
+}
+
+export function getHttpClientPolicy(): ResolvedHttpClientPolicy {
+  return mergeHttpClientPolicies(undefined, runtime.get() ?? {});
+}
+
+export function runWithHttpClientPolicy<T>(
+  policy: HttpClientPolicy,
+  fn: () => T,
+): T {
+  const merged = mergeHttpClientPolicies(runtime.get(), policy);
+  return runtime.run(merged, fn);
+}
+
+export function withHttpClientPolicy<Args extends unknown[], Result>(
+  policy: HttpClientPolicy,
+  fn: (...args: Args) => Result,
+): (...args: Args) => Result {
+  return (...args: Args) =>
+    runWithHttpClientPolicy(policy, () => fn(...args));
+}
+
+function isTimeoutError(error: HttpErrorLike): boolean {
+  const code = error.code ?? "";
+  if (code === "ECONNABORTED" || code === "ETIMEDOUT") {
+    return true;
+  }
+  return /timeout/i.test(error.message ?? "");
+}
+
+function isTransientFailure(error: HttpErrorLike): boolean {
+  const status = error.response?.status;
+  if (status != null) {
+    return RETRYABLE_STATUS.has(status);
+  }
+  const code = error.code ?? "";
+  return isTimeoutError(error) || RETRYABLE_NETWORK_CODES.has(code);
+}
+
+function isRetryableZauruError(error: HttpErrorLike): boolean {
+  const method = (error.config?.method ?? "get").toLowerCase();
+  const idempotent =
+    method === "get" || method === "head" || method === "options";
+  if (idempotent) {
+    return isTransientFailure(error);
+  }
+  if (error.response?.status != null || isTimeoutError(error)) {
+    return false;
+  }
+  return RETRYABLE_NETWORK_CODES.has(error.code ?? "");
+}
+
+export function isRetryableHttpError(
+  error: HttpErrorLike,
+  client: HttpClientKind,
+): boolean {
+  switch (client) {
+    case "graphql":
+      return isTransientFailure(error);
+    case "zauru":
+      return isRetryableZauruError(error);
+    default: {
+      const _never: never = client;
+      return _never;
+    }
+  }
+}
+
+export function httpTimeoutMsForClient(
+  client: HttpClientKind,
+  policy: ResolvedHttpClientPolicy = getHttpClientPolicy(),
+): number {
+  switch (client) {
+    case "graphql":
+      return policy.graphqlTimeoutSeconds * 1000;
+    case "zauru":
+      return policy.zauruTimeoutSeconds * 1000;
+    default: {
+      const _never: never = client;
+      return _never;
+    }
+  }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./common.js";
 export * from "./gtZones.js";
+export * from "./httpClientPolicy.js";
 export * from "./oauthErrors.js";
 export * from "./rejectionPercentageAdjustment.js";

package/tsconfig.json

@@ -1,5 +1,6 @@
 {
-  "include": ["**/*.ts"],
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"],
   "compilerOptions": {
     "target": "ES2022",
     "module": "NodeNext",