@cedvict/http-guardian-plugin-retry 0.0.1-next.10

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1-next.7
+
+- Initial prerelease.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cedvict
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @cedvict/http-guardian-plugin-retry
+
+Retry plugin (exponential backoff) for http-guardian.
+
+## Usage
+
+```ts
+import { retryPlugin } from "@cedvict/http-guardian-plugin-retry";
+```

package/dist/index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+// src/index.ts
+var META_KEY = /* @__PURE__ */ Symbol.for("http-guardian.retry");
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function parseRetryAfterMs(h, nowMs) {
+  const v = h.get("retry-after");
+  if (!v) return void 0;
+  const asInt = Number(v);
+  if (Number.isFinite(asInt)) return Math.max(0, asInt * 1e3);
+  const asDate = Date.parse(v);
+  if (!Number.isNaN(asDate)) return Math.max(0, asDate - nowMs);
+  return void 0;
+}
+function isIdempotent(method) {
+  return method === "GET" || method === "HEAD" || method === "OPTIONS";
+}
+function backoffDelayMs(attempt, base, max, jitter) {
+  const exp = Math.min(max, base * Math.pow(2, attempt - 1));
+  if (jitter === "full") return Math.floor(Math.random() * exp);
+  return exp;
+}
+function retryPlugin(options = {}) {
+  const retries = options.retries ?? 3;
+  const baseDelayMs = options.baseDelayMs ?? 200;
+  const maxDelayMs = options.maxDelayMs ?? 5e3;
+  const jitter = options.jitter ?? "full";
+  const retryOnStatuses = options.retryOnStatuses ?? [408, 429, 500, 502, 503, 504];
+  const retryOnNetworkError = options.retryOnNetworkError ?? true;
+  const isRetryableRequest = options.isRetryableRequest ?? ((ctx) => isIdempotent(ctx.method));
+  const wait = options.wait ?? ((ms) => sleep(ms));
+  const guard = async (ctx, next) => {
+    if (!isRetryableRequest(ctx)) return next(ctx);
+    const meta = ctx[META_KEY] ??= { attempt: 0 };
+    while (true) {
+      let res;
+      let networkError;
+      try {
+        res = await next(ctx);
+      } catch (e) {
+        networkError = e;
+      }
+      const shouldRetryNetwork = !!networkError && retryOnNetworkError;
+      const shouldRetryStatus = !!res && retryOnStatuses.includes(res.status);
+      if (!shouldRetryNetwork && !shouldRetryStatus) {
+        if (networkError) throw networkError;
+        return res;
+      }
+      if (meta.attempt >= retries) {
+        if (networkError) throw networkError;
+        return res;
+      }
+      meta.attempt += 1;
+      const now = Date.now();
+      let delay = backoffDelayMs(meta.attempt, baseDelayMs, maxDelayMs, jitter);
+      if (res) {
+        const ra = parseRetryAfterMs(res.headers, now);
+        if (typeof ra === "number") delay = Math.min(maxDelayMs, Math.max(delay, ra));
+      }
+      await wait(delay, ctx);
+      ctx = Object.assign({}, ctx, { attempt: ctx.attempt + 1 });
+      ctx[META_KEY] = meta;
+    }
+  };
+  return {
+    name: "retry",
+    apply: (draft) => {
+      draft.guards = [...draft.guards ?? [], guard];
+    }
+  };
+}
+
+exports.retryPlugin = retryPlugin;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { HttpPlugin } from \"@cedvict/http-guardian\";\nimport type { Guard } from \"@cedvict/http-guardian\";\nimport type { RequestContext } from \"@cedvict/http-guardian\";\n\nexport type RetryJitter = \"none\" | \"full\";\n\nexport type RetryPluginOptions = {\n  retries?: number;\n  baseDelayMs?: number;\n  maxDelayMs?: number;\n  jitter?: RetryJitter;\n  retryOnStatuses?: number[];\n  retryOnNetworkError?: boolean;\n  /**\n   * By default, retries only idempotent methods.\n   */\n  isRetryableRequest?: (ctx: RequestContext) => boolean;\n  /**\n   * Override wait logic (useful for tests).\n   */\n  wait?: (ms: number, ctx: RequestContext) => Promise<void>;\n};\n\nconst META_KEY = Symbol.for(\"http-guardian.retry\");\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((r) => setTimeout(r, ms));\n}\n\nfunction parseRetryAfterMs(h: Headers, nowMs: number): number | undefined {\n  const v = h.get(\"retry-after\");\n  if (!v) return undefined;\n  const asInt = Number(v);\n  if (Number.isFinite(asInt)) return Math.max(0, asInt * 1000);\n  const asDate = Date.parse(v);\n  if (!Number.isNaN(asDate)) return Math.max(0, asDate - nowMs);\n  return undefined;\n}\n\nfunction isIdempotent(method: string): boolean {\n  return method === \"GET\" || method === \"HEAD\" || method === \"OPTIONS\";\n}\n\nfunction backoffDelayMs(attempt: number, base: number, max: number, jitter: RetryJitter): number {\n  // attempt starts at 1 for first retry\n  const exp = Math.min(max, base * Math.pow(2, attempt - 1));\n  if (jitter === \"full\") return Math.floor(Math.random() * exp);\n  return exp;\n}\n\n/**\n * Production-grade retry plugin:\n * - exponential backoff (+ jitter)\n * - honors Retry-After for 429/503 etc\n * - idempotent only by default\n * - uses ctx.attempt to keep compatibility with other guards\n */\nexport function retryPlugin(options: RetryPluginOptions = {}): HttpPlugin {\n  const retries = options.retries ?? 3;\n  const baseDelayMs = options.baseDelayMs ?? 200;\n  const maxDelayMs = options.maxDelayMs ?? 5_000;\n  const jitter = options.jitter ?? \"full\";\n  const retryOnStatuses = options.retryOnStatuses ?? [408, 429, 500, 502, 503, 504];\n  const retryOnNetworkError = options.retryOnNetworkError ?? true;\n  const isRetryableRequest = options.isRetryableRequest ?? ((ctx) => isIdempotent(ctx.method));\n  const wait = options.wait ?? ((ms) => sleep(ms));\n\n  const guard: Guard = async (ctx, next) => {\n    if (!isRetryableRequest(ctx)) return next(ctx);\n\n    const meta = ((ctx as any)[META_KEY] ??= { attempt: 0 }) as { attempt: number };\n    // If another guard already replayed, do not loop forever:\n    // retries count are independent from refresh, but we cap them.\n    while (true) {\n      let res: Response | undefined;\n      let networkError: unknown | undefined;\n\n      try {\n        res = await next(ctx);\n      } catch (e) {\n        networkError = e;\n      }\n\n      const shouldRetryNetwork = !!networkError && retryOnNetworkError;\n      const shouldRetryStatus = !!res && retryOnStatuses.includes(res.status);\n\n      if (!shouldRetryNetwork && !shouldRetryStatus) {\n        if (networkError) throw networkError;\n        return res as Response;\n      }\n\n      if (meta.attempt >= retries) {\n        if (networkError) throw networkError;\n        return res as Response;\n      }\n\n      meta.attempt += 1;\n\n      const now = Date.now();\n      let delay = backoffDelayMs(meta.attempt, baseDelayMs, maxDelayMs, jitter);\n\n      if (res) {\n        const ra = parseRetryAfterMs(res.headers, now);\n        if (typeof ra === \"number\") delay = Math.min(maxDelayMs, Math.max(delay, ra));\n      }\n\n      await wait(delay, ctx);\n\n      // clone ctx with incremented attempt to keep anti-loop invariants aligned with core\n      ctx = Object.assign({}, ctx, { attempt: ctx.attempt + 1 }) as RequestContext;\n      (ctx as any)[META_KEY] = meta;\n    }\n  };\n\n  return {\n    name: \"retry\",\n    apply: (draft) => {\n      draft.guards = [...(draft.guards ?? []), guard];\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+import { RequestContext, HttpPlugin } from '@cedvict/http-guardian';
+
+type RetryJitter = "none" | "full";
+type RetryPluginOptions = {
+    retries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: RetryJitter;
+    retryOnStatuses?: number[];
+    retryOnNetworkError?: boolean;
+    /**
+     * By default, retries only idempotent methods.
+     */
+    isRetryableRequest?: (ctx: RequestContext) => boolean;
+    /**
+     * Override wait logic (useful for tests).
+     */
+    wait?: (ms: number, ctx: RequestContext) => Promise<void>;
+};
+/**
+ * Production-grade retry plugin:
+ * - exponential backoff (+ jitter)
+ * - honors Retry-After for 429/503 etc
+ * - idempotent only by default
+ * - uses ctx.attempt to keep compatibility with other guards
+ */
+declare function retryPlugin(options?: RetryPluginOptions): HttpPlugin;
+
+export { type RetryJitter, type RetryPluginOptions, retryPlugin };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { RequestContext, HttpPlugin } from '@cedvict/http-guardian';
+
+type RetryJitter = "none" | "full";
+type RetryPluginOptions = {
+    retries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: RetryJitter;
+    retryOnStatuses?: number[];
+    retryOnNetworkError?: boolean;
+    /**
+     * By default, retries only idempotent methods.
+     */
+    isRetryableRequest?: (ctx: RequestContext) => boolean;
+    /**
+     * Override wait logic (useful for tests).
+     */
+    wait?: (ms: number, ctx: RequestContext) => Promise<void>;
+};
+/**
+ * Production-grade retry plugin:
+ * - exponential backoff (+ jitter)
+ * - honors Retry-After for 429/503 etc
+ * - idempotent only by default
+ * - uses ctx.attempt to keep compatibility with other guards
+ */
+declare function retryPlugin(options?: RetryPluginOptions): HttpPlugin;
+
+export { type RetryJitter, type RetryPluginOptions, retryPlugin };

package/dist/index.js

@@ -0,0 +1,75 @@
+// src/index.ts
+var META_KEY = /* @__PURE__ */ Symbol.for("http-guardian.retry");
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function parseRetryAfterMs(h, nowMs) {
+  const v = h.get("retry-after");
+  if (!v) return void 0;
+  const asInt = Number(v);
+  if (Number.isFinite(asInt)) return Math.max(0, asInt * 1e3);
+  const asDate = Date.parse(v);
+  if (!Number.isNaN(asDate)) return Math.max(0, asDate - nowMs);
+  return void 0;
+}
+function isIdempotent(method) {
+  return method === "GET" || method === "HEAD" || method === "OPTIONS";
+}
+function backoffDelayMs(attempt, base, max, jitter) {
+  const exp = Math.min(max, base * Math.pow(2, attempt - 1));
+  if (jitter === "full") return Math.floor(Math.random() * exp);
+  return exp;
+}
+function retryPlugin(options = {}) {
+  const retries = options.retries ?? 3;
+  const baseDelayMs = options.baseDelayMs ?? 200;
+  const maxDelayMs = options.maxDelayMs ?? 5e3;
+  const jitter = options.jitter ?? "full";
+  const retryOnStatuses = options.retryOnStatuses ?? [408, 429, 500, 502, 503, 504];
+  const retryOnNetworkError = options.retryOnNetworkError ?? true;
+  const isRetryableRequest = options.isRetryableRequest ?? ((ctx) => isIdempotent(ctx.method));
+  const wait = options.wait ?? ((ms) => sleep(ms));
+  const guard = async (ctx, next) => {
+    if (!isRetryableRequest(ctx)) return next(ctx);
+    const meta = ctx[META_KEY] ??= { attempt: 0 };
+    while (true) {
+      let res;
+      let networkError;
+      try {
+        res = await next(ctx);
+      } catch (e) {
+        networkError = e;
+      }
+      const shouldRetryNetwork = !!networkError && retryOnNetworkError;
+      const shouldRetryStatus = !!res && retryOnStatuses.includes(res.status);
+      if (!shouldRetryNetwork && !shouldRetryStatus) {
+        if (networkError) throw networkError;
+        return res;
+      }
+      if (meta.attempt >= retries) {
+        if (networkError) throw networkError;
+        return res;
+      }
+      meta.attempt += 1;
+      const now = Date.now();
+      let delay = backoffDelayMs(meta.attempt, baseDelayMs, maxDelayMs, jitter);
+      if (res) {
+        const ra = parseRetryAfterMs(res.headers, now);
+        if (typeof ra === "number") delay = Math.min(maxDelayMs, Math.max(delay, ra));
+      }
+      await wait(delay, ctx);
+      ctx = Object.assign({}, ctx, { attempt: ctx.attempt + 1 });
+      ctx[META_KEY] = meta;
+    }
+  };
+  return {
+    name: "retry",
+    apply: (draft) => {
+      draft.guards = [...draft.guards ?? [], guard];
+    }
+  };
+}
+
+export { retryPlugin };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { HttpPlugin } from \"@cedvict/http-guardian\";\nimport type { Guard } from \"@cedvict/http-guardian\";\nimport type { RequestContext } from \"@cedvict/http-guardian\";\n\nexport type RetryJitter = \"none\" | \"full\";\n\nexport type RetryPluginOptions = {\n  retries?: number;\n  baseDelayMs?: number;\n  maxDelayMs?: number;\n  jitter?: RetryJitter;\n  retryOnStatuses?: number[];\n  retryOnNetworkError?: boolean;\n  /**\n   * By default, retries only idempotent methods.\n   */\n  isRetryableRequest?: (ctx: RequestContext) => boolean;\n  /**\n   * Override wait logic (useful for tests).\n   */\n  wait?: (ms: number, ctx: RequestContext) => Promise<void>;\n};\n\nconst META_KEY = Symbol.for(\"http-guardian.retry\");\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((r) => setTimeout(r, ms));\n}\n\nfunction parseRetryAfterMs(h: Headers, nowMs: number): number | undefined {\n  const v = h.get(\"retry-after\");\n  if (!v) return undefined;\n  const asInt = Number(v);\n  if (Number.isFinite(asInt)) return Math.max(0, asInt * 1000);\n  const asDate = Date.parse(v);\n  if (!Number.isNaN(asDate)) return Math.max(0, asDate - nowMs);\n  return undefined;\n}\n\nfunction isIdempotent(method: string): boolean {\n  return method === \"GET\" || method === \"HEAD\" || method === \"OPTIONS\";\n}\n\nfunction backoffDelayMs(attempt: number, base: number, max: number, jitter: RetryJitter): number {\n  // attempt starts at 1 for first retry\n  const exp = Math.min(max, base * Math.pow(2, attempt - 1));\n  if (jitter === \"full\") return Math.floor(Math.random() * exp);\n  return exp;\n}\n\n/**\n * Production-grade retry plugin:\n * - exponential backoff (+ jitter)\n * - honors Retry-After for 429/503 etc\n * - idempotent only by default\n * - uses ctx.attempt to keep compatibility with other guards\n */\nexport function retryPlugin(options: RetryPluginOptions = {}): HttpPlugin {\n  const retries = options.retries ?? 3;\n  const baseDelayMs = options.baseDelayMs ?? 200;\n  const maxDelayMs = options.maxDelayMs ?? 5_000;\n  const jitter = options.jitter ?? \"full\";\n  const retryOnStatuses = options.retryOnStatuses ?? [408, 429, 500, 502, 503, 504];\n  const retryOnNetworkError = options.retryOnNetworkError ?? true;\n  const isRetryableRequest = options.isRetryableRequest ?? ((ctx) => isIdempotent(ctx.method));\n  const wait = options.wait ?? ((ms) => sleep(ms));\n\n  const guard: Guard = async (ctx, next) => {\n    if (!isRetryableRequest(ctx)) return next(ctx);\n\n    const meta = ((ctx as any)[META_KEY] ??= { attempt: 0 }) as { attempt: number };\n    // If another guard already replayed, do not loop forever:\n    // retries count are independent from refresh, but we cap them.\n    while (true) {\n      let res: Response | undefined;\n      let networkError: unknown | undefined;\n\n      try {\n        res = await next(ctx);\n      } catch (e) {\n        networkError = e;\n      }\n\n      const shouldRetryNetwork = !!networkError && retryOnNetworkError;\n      const shouldRetryStatus = !!res && retryOnStatuses.includes(res.status);\n\n      if (!shouldRetryNetwork && !shouldRetryStatus) {\n        if (networkError) throw networkError;\n        return res as Response;\n      }\n\n      if (meta.attempt >= retries) {\n        if (networkError) throw networkError;\n        return res as Response;\n      }\n\n      meta.attempt += 1;\n\n      const now = Date.now();\n      let delay = backoffDelayMs(meta.attempt, baseDelayMs, maxDelayMs, jitter);\n\n      if (res) {\n        const ra = parseRetryAfterMs(res.headers, now);\n        if (typeof ra === \"number\") delay = Math.min(maxDelayMs, Math.max(delay, ra));\n      }\n\n      await wait(delay, ctx);\n\n      // clone ctx with incremented attempt to keep anti-loop invariants aligned with core\n      ctx = Object.assign({}, ctx, { attempt: ctx.attempt + 1 }) as RequestContext;\n      (ctx as any)[META_KEY] = meta;\n    }\n  };\n\n  return {\n    name: \"retry\",\n    apply: (draft) => {\n      draft.guards = [...(draft.guards ?? []), guard];\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cedvict/http-guardian-plugin-retry",
+  "version": "0.0.1-next.10",
+  "description": "Retry plugin (exponential backoff) for http-guardian.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cedvict/http-guardian.git"
+  },
+  "peerDependencies": {
+    "@cedvict/http-guardian": "^0.0.1-next.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "eslint . --max-warnings=0",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "prepublishOnly": "npm -w @cedvict/http-guardian run build && npm run test && npm run lint && npm run typecheck && npm run build",
+    "prebuild": "npm -w @cedvict/http-guardian run build",
+    "pretypecheck": "npm -w @cedvict/http-guardian run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.4.0",
+    "tsup": "^8.0.0",
+    "vitest": "^1.5.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0"
+  },
+  "dependencies": {
+    "@cedvict/http-guardian": "^0.0.1-next.10"
+  }
+}