@jskit-ai/http-runtime 0.1.37 → 0.1.38

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   "packageVersion": 1,
   "packageId": "@jskit-ai/http-runtime",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "kind": "runtime",
   "dependsOn": [],
   "capabilities": {
@@ -67,7 +67,7 @@ export default Object.freeze({
   "mutations": {
     "dependencies": {
       "runtime": {
-        "@jskit-ai/kernel": "0.1.38",
+        "@jskit-ai/kernel": "0.1.39",
         "@fastify/type-provider-typebox": "^6.1.0",
         "typebox": "^1.0.81"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/http-runtime",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -17,7 +17,7 @@
     "./shared/validators/operationValidation": "./src/shared/validators/operationValidation.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.38",
+    "@jskit-ai/kernel": "0.1.39",
     "@fastify/type-provider-typebox": "^6.1.0",
     "typebox": "^1.0.81"
   }

package/src/client/index.js

@@ -1,4 +1,5 @@
 export { createHttpClient } from "../shared/clientRuntime/client.js";
+export { createTransientRetryHttpClient } from "./transientRetryHttpClient.js";
 export {
   normalizeFieldErrors,
   resolveFieldErrors,

package/src/client/transientRetryHttpClient.js

@@ -0,0 +1,64 @@
+import { createHttpClient } from "../shared/clientRuntime/client.js";
+import {
+  isTransientQueryError,
+  transientQueryRetryDelay
+} from "@jskit-ai/kernel/shared/support";
+
+const SAFE_RETRY_METHODS = Object.freeze(new Set(["GET", "HEAD"]));
+const MAX_TRANSIENT_HTTP_RETRIES = 2;
+
+function sleep(delayMs) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+}
+
+function shouldRetryTransientHttpFailure(error, method, attemptIndex) {
+  if (!SAFE_RETRY_METHODS.has(String(method || "GET").toUpperCase())) {
+    return false;
+  }
+  if (!isTransientQueryError(error)) {
+    return false;
+  }
+  return Number(attemptIndex) < MAX_TRANSIENT_HTTP_RETRIES;
+}
+
+async function requestWithTransientRetry(executor, method) {
+  let attemptIndex = 0;
+
+  while (true) {
+    try {
+      return await executor();
+    } catch (error) {
+      if (!shouldRetryTransientHttpFailure(error, method, attemptIndex)) {
+        throw error;
+      }
+      attemptIndex += 1;
+      await sleep(transientQueryRetryDelay(attemptIndex));
+    }
+  }
+}
+
+function createTransientRetryHttpClient(options = {}) {
+  const baseHttpClient = createHttpClient(options);
+
+  return Object.freeze({
+    ...baseHttpClient,
+    request(url, requestOptions = {}, state = null) {
+      const method = String(requestOptions?.method || "GET").toUpperCase();
+      return requestWithTransientRetry(
+        () => baseHttpClient.request(url, requestOptions, state),
+        method
+      );
+    },
+    requestStream(url, requestOptions = {}, handlers = {}, state = null) {
+      const method = String(requestOptions?.method || "GET").toUpperCase();
+      return requestWithTransientRetry(
+        () => baseHttpClient.requestStream(url, requestOptions, handlers, state),
+        method
+      );
+    }
+  });
+}
+
+export { createTransientRetryHttpClient };

package/test/entrypoints.boundary.test.js

@@ -14,8 +14,9 @@ test("package exports include explicit shared entrypoint and no server barrel",
   assert.equal(exportsMap["./shared"], "./src/shared/index.js");
 });
 
-test("client entrypoint exports client runtime and client providers only", () => {
+test("client entrypoint exports client runtime helpers and client providers only", () => {
   assert.equal(typeof clientApi.createHttpClient, "function");
+  assert.equal(typeof clientApi.createTransientRetryHttpClient, "function");
   assert.equal(typeof clientApi.HttpValidatorsClientProvider, "function");
   assert.equal(typeof clientApi.HttpClientRuntimeClientProvider, "function");
   assert.equal(typeof clientApi.withStandardErrorResponses, "undefined");

package/test/transientRetryHttpClient.test.js

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createTransientRetryHttpClient } from "../src/client/index.js";
+
+function mockResponse({ status = 200, data = {}, contentType = "application/json; charset=utf-8", text = "" } = {}) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: {
+      get(name) {
+        return String(name || "").toLowerCase() === "content-type" ? contentType : "";
+      }
+    },
+    async json() {
+      return data;
+    },
+    async text() {
+      return text;
+    }
+  };
+}
+
+async function withImmediateTimers(executor) {
+  const originalSetTimeout = globalThis.setTimeout;
+  globalThis.setTimeout = (handler, _delay, ...args) => {
+    if (typeof handler === "function") {
+      handler(...args);
+    }
+    return 0;
+  };
+
+  try {
+    return await executor();
+  } finally {
+    globalThis.setTimeout = originalSetTimeout;
+  }
+}
+
+test("createTransientRetryHttpClient retries transient GET request failures", async () => {
+  await withImmediateTimers(async () => {
+    let callCount = 0;
+    const client = createTransientRetryHttpClient({
+      fetchImpl: async () => {
+        callCount += 1;
+        if (callCount < 3) {
+          return mockResponse({
+            status: 503,
+            data: {
+              error: "temporarily unavailable"
+            }
+          });
+        }
+
+        return mockResponse({
+          data: {
+            ok: true
+          }
+        });
+      }
+    });
+
+    const payload = await client.request("/api/demo", {
+      method: "GET"
+    });
+
+    assert.deepEqual(payload, { ok: true });
+    assert.equal(callCount, 3);
+  });
+});
+
+test("createTransientRetryHttpClient does not retry unsafe transient failures", async () => {
+  await withImmediateTimers(async () => {
+    let callCount = 0;
+    const client = createTransientRetryHttpClient({
+      fetchImpl: async (url) => {
+        callCount += 1;
+        if (url === "/api/session") {
+          return mockResponse({
+            data: {
+              csrfToken: "csrf-1"
+            }
+          });
+        }
+
+        return mockResponse({
+          status: 503,
+          data: {
+            error: "temporarily unavailable"
+          }
+        });
+      }
+    });
+
+    await assert.rejects(
+      client.request("/api/demo", {
+        method: "POST",
+        body: {
+          ok: true
+        }
+      }),
+      (error) => {
+        assert.equal(error?.status, 503);
+        return true;
+      }
+    );
+
+    assert.equal(callCount, 2);
+  });
+});
+
+test("createTransientRetryHttpClient retries transient GET stream failures", async () => {
+  await withImmediateTimers(async () => {
+    let callCount = 0;
+    const client = createTransientRetryHttpClient({
+      fetchImpl: async () => {
+        callCount += 1;
+        if (callCount === 1) {
+          return mockResponse({
+            status: 503,
+            data: {
+              error: "temporarily unavailable"
+            }
+          });
+        }
+
+        return mockResponse({
+          contentType: "text/plain; charset=utf-8",
+          text: ""
+        });
+      }
+    });
+
+    await client.requestStream("/api/demo-stream", {
+      method: "GET"
+    });
+
+    assert.equal(callCount, 2);
+  });
+});