@cedvict/http-guardian-plugin-rate-limit 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-rate-limit
+
+Rate limit plugin (concurrency + token bucket) for http-guardian.
+
+## Usage
+
+```ts
+import { rateLimitPlugin } from "@cedvict/http-guardian-plugin-rate-limit";
+```

package/dist/index.cjs

@@ -0,0 +1,127 @@
+'use strict';
+
+// src/index.ts
+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;
+}
+var Semaphore = class {
+  max;
+  cur = 0;
+  q = [];
+  constructor(max) {
+    this.max = Math.max(1, max);
+  }
+  async acquire() {
+    if (this.cur < this.max) {
+      this.cur++;
+      return () => this.release();
+    }
+    await new Promise((r) => this.q.push(r));
+    this.cur++;
+    return () => this.release();
+  }
+  release() {
+    this.cur--;
+    const next = this.q.shift();
+    if (next) next();
+  }
+};
+var TokenBucket = class {
+  tokens;
+  cap;
+  refill;
+  intervalMs;
+  lastRefill = Date.now();
+  cooldownUntil = 0;
+  constructor(tokensPerInterval, intervalMs) {
+    this.cap = Math.max(1, tokensPerInterval);
+    this.tokens = this.cap;
+    this.refill = this.cap;
+    this.intervalMs = Math.max(1, intervalMs);
+  }
+  setCooldown(untilMs) {
+    this.cooldownUntil = Math.max(this.cooldownUntil, untilMs);
+  }
+  refillIfNeeded(now) {
+    if (now - this.lastRefill >= this.intervalMs) {
+      const steps = Math.floor((now - this.lastRefill) / this.intervalMs);
+      this.tokens = Math.min(this.cap, this.tokens + steps * this.refill);
+      this.lastRefill += steps * this.intervalMs;
+    }
+  }
+  async take() {
+    while (true) {
+      const now = Date.now();
+      this.refillIfNeeded(now);
+      if (now < this.cooldownUntil) {
+        await new Promise((r) => setTimeout(r, this.cooldownUntil - now));
+        continue;
+      }
+      if (this.tokens > 0) {
+        this.tokens--;
+        return;
+      }
+      const waitMs = Math.max(1, this.intervalMs - (now - this.lastRefill));
+      await new Promise((r) => setTimeout(r, waitMs));
+    }
+  }
+};
+function rateLimitPlugin(opts = {}) {
+  const maxConcurrent = opts.maxConcurrent ?? 8;
+  const tokensPerInterval = opts.tokensPerInterval;
+  const intervalMs = opts.intervalMs ?? 1e3;
+  const honorRetryAfter = opts.honorRetryAfter ?? true;
+  const keyFn = opts.key ?? ((ctx) => new URL(ctx.url).host);
+  const semaphores = /* @__PURE__ */ new Map();
+  const buckets = /* @__PURE__ */ new Map();
+  const getSemaphore = (k) => {
+    let s = semaphores.get(k);
+    if (!s) {
+      s = new Semaphore(maxConcurrent);
+      semaphores.set(k, s);
+    }
+    return s;
+  };
+  const getBucket = (k) => {
+    if (!tokensPerInterval) return void 0;
+    let b = buckets.get(k);
+    if (!b) {
+      b = new TokenBucket(tokensPerInterval, intervalMs);
+      buckets.set(k, b);
+    }
+    return b;
+  };
+  const guard = async (ctx, next) => {
+    const k = keyFn(ctx);
+    const sem = getSemaphore(k);
+    const bucket = getBucket(k);
+    if (bucket) await bucket.take();
+    const release = await sem.acquire();
+    try {
+      const res = await next(ctx);
+      if (honorRetryAfter && bucket && res.status === 429) {
+        const ra = parseRetryAfterMs(res.headers, Date.now());
+        if (typeof ra === "number") bucket.setCooldown(Date.now() + ra);
+      }
+      return res;
+    } finally {
+      release();
+    }
+  };
+  return {
+    name: "rate-limit",
+    apply: (draft) => {
+      draft.guards = [...draft.guards ?? [], guard];
+    }
+  };
+}
+
+exports.rateLimitPlugin = rateLimitPlugin;
+//# 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\ntype KeyFn = (ctx: RequestContext) => string;\n\nexport type RateLimitPluginOptions = {\n  maxConcurrent?: number;\n  tokensPerInterval?: number;\n  intervalMs?: number;\n  honorRetryAfter?: boolean;\n  key?: KeyFn;\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\nclass Semaphore {\n  private max: number;\n  private cur = 0;\n  private q: Array<() => void> = [];\n  constructor(max: number) { this.max = Math.max(1, max); }\n  async acquire(): Promise<() => void> {\n    if (this.cur < this.max) {\n      this.cur++;\n      return () => this.release();\n    }\n    await new Promise<void>((r) => this.q.push(r));\n    this.cur++;\n    return () => this.release();\n  }\n  private release() {\n    this.cur--;\n    const next = this.q.shift();\n    if (next) next();\n  }\n}\n\nclass TokenBucket {\n  private tokens: number;\n  private readonly cap: number;\n  private readonly refill: number;\n  private readonly intervalMs: number;\n  private lastRefill: number = Date.now();\n  private cooldownUntil = 0;\n\n  constructor(tokensPerInterval: number, intervalMs: number) {\n    this.cap = Math.max(1, tokensPerInterval);\n    this.tokens = this.cap;\n    this.refill = this.cap;\n    this.intervalMs = Math.max(1, intervalMs);\n  }\n\n  setCooldown(untilMs: number) { this.cooldownUntil = Math.max(this.cooldownUntil, untilMs); }\n\n  private refillIfNeeded(now: number) {\n    if (now - this.lastRefill >= this.intervalMs) {\n      const steps = Math.floor((now - this.lastRefill) / this.intervalMs);\n      this.tokens = Math.min(this.cap, this.tokens + steps * this.refill);\n      this.lastRefill += steps * this.intervalMs;\n    }\n  }\n\n  async take(): Promise<void> {\n    while (true) {\n      const now = Date.now();\n      this.refillIfNeeded(now);\n      if (now < this.cooldownUntil) {\n        await new Promise((r) => setTimeout(r, this.cooldownUntil - now));\n        continue;\n      }\n      if (this.tokens > 0) {\n        this.tokens--;\n        return;\n      }\n      const waitMs = Math.max(1, this.intervalMs - (now - this.lastRefill));\n      await new Promise((r) => setTimeout(r, waitMs));\n    }\n  }\n}\n\nexport function rateLimitPlugin(opts: RateLimitPluginOptions = {}): HttpPlugin {\n  const maxConcurrent = opts.maxConcurrent ?? 8;\n  const tokensPerInterval = opts.tokensPerInterval;\n  const intervalMs = opts.intervalMs ?? 1000;\n  const honorRetryAfter = opts.honorRetryAfter ?? true;\n  const keyFn: KeyFn = opts.key ?? ((ctx) => new URL(ctx.url).host);\n\n  const semaphores = new Map<string, Semaphore>();\n  const buckets = new Map<string, TokenBucket>();\n\n  const getSemaphore = (k: string) => {\n    let s = semaphores.get(k);\n    if (!s) { s = new Semaphore(maxConcurrent); semaphores.set(k, s); }\n    return s;\n  };\n  const getBucket = (k: string) => {\n    if (!tokensPerInterval) return undefined;\n    let b = buckets.get(k);\n    if (!b) { b = new TokenBucket(tokensPerInterval, intervalMs); buckets.set(k, b); }\n    return b;\n  };\n\n  const guard: Guard = async (ctx, next) => {\n    const k = keyFn(ctx);\n    const sem = getSemaphore(k);\n    const bucket = getBucket(k);\n\n    if (bucket) await bucket.take();\n    const release = await sem.acquire();\n    try {\n      const res = await next(ctx);\n      if (honorRetryAfter && bucket && res.status === 429) {\n        const ra = parseRetryAfterMs(res.headers, Date.now());\n        if (typeof ra === \"number\") bucket.setCooldown(Date.now() + ra);\n      }\n      return res;\n    } finally {\n      release();\n    }\n  };\n\n  return {\n    name: \"rate-limit\",\n    apply: (draft) => {\n      draft.guards = [...(draft.guards ?? []), guard];\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,13 @@
+import { RequestContext, HttpPlugin } from '@cedvict/http-guardian';
+
+type KeyFn = (ctx: RequestContext) => string;
+type RateLimitPluginOptions = {
+    maxConcurrent?: number;
+    tokensPerInterval?: number;
+    intervalMs?: number;
+    honorRetryAfter?: boolean;
+    key?: KeyFn;
+};
+declare function rateLimitPlugin(opts?: RateLimitPluginOptions): HttpPlugin;
+
+export { type RateLimitPluginOptions, rateLimitPlugin };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { RequestContext, HttpPlugin } from '@cedvict/http-guardian';
+
+type KeyFn = (ctx: RequestContext) => string;
+type RateLimitPluginOptions = {
+    maxConcurrent?: number;
+    tokensPerInterval?: number;
+    intervalMs?: number;
+    honorRetryAfter?: boolean;
+    key?: KeyFn;
+};
+declare function rateLimitPlugin(opts?: RateLimitPluginOptions): HttpPlugin;
+
+export { type RateLimitPluginOptions, rateLimitPlugin };

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/index.ts
+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;
+}
+var Semaphore = class {
+  max;
+  cur = 0;
+  q = [];
+  constructor(max) {
+    this.max = Math.max(1, max);
+  }
+  async acquire() {
+    if (this.cur < this.max) {
+      this.cur++;
+      return () => this.release();
+    }
+    await new Promise((r) => this.q.push(r));
+    this.cur++;
+    return () => this.release();
+  }
+  release() {
+    this.cur--;
+    const next = this.q.shift();
+    if (next) next();
+  }
+};
+var TokenBucket = class {
+  tokens;
+  cap;
+  refill;
+  intervalMs;
+  lastRefill = Date.now();
+  cooldownUntil = 0;
+  constructor(tokensPerInterval, intervalMs) {
+    this.cap = Math.max(1, tokensPerInterval);
+    this.tokens = this.cap;
+    this.refill = this.cap;
+    this.intervalMs = Math.max(1, intervalMs);
+  }
+  setCooldown(untilMs) {
+    this.cooldownUntil = Math.max(this.cooldownUntil, untilMs);
+  }
+  refillIfNeeded(now) {
+    if (now - this.lastRefill >= this.intervalMs) {
+      const steps = Math.floor((now - this.lastRefill) / this.intervalMs);
+      this.tokens = Math.min(this.cap, this.tokens + steps * this.refill);
+      this.lastRefill += steps * this.intervalMs;
+    }
+  }
+  async take() {
+    while (true) {
+      const now = Date.now();
+      this.refillIfNeeded(now);
+      if (now < this.cooldownUntil) {
+        await new Promise((r) => setTimeout(r, this.cooldownUntil - now));
+        continue;
+      }
+      if (this.tokens > 0) {
+        this.tokens--;
+        return;
+      }
+      const waitMs = Math.max(1, this.intervalMs - (now - this.lastRefill));
+      await new Promise((r) => setTimeout(r, waitMs));
+    }
+  }
+};
+function rateLimitPlugin(opts = {}) {
+  const maxConcurrent = opts.maxConcurrent ?? 8;
+  const tokensPerInterval = opts.tokensPerInterval;
+  const intervalMs = opts.intervalMs ?? 1e3;
+  const honorRetryAfter = opts.honorRetryAfter ?? true;
+  const keyFn = opts.key ?? ((ctx) => new URL(ctx.url).host);
+  const semaphores = /* @__PURE__ */ new Map();
+  const buckets = /* @__PURE__ */ new Map();
+  const getSemaphore = (k) => {
+    let s = semaphores.get(k);
+    if (!s) {
+      s = new Semaphore(maxConcurrent);
+      semaphores.set(k, s);
+    }
+    return s;
+  };
+  const getBucket = (k) => {
+    if (!tokensPerInterval) return void 0;
+    let b = buckets.get(k);
+    if (!b) {
+      b = new TokenBucket(tokensPerInterval, intervalMs);
+      buckets.set(k, b);
+    }
+    return b;
+  };
+  const guard = async (ctx, next) => {
+    const k = keyFn(ctx);
+    const sem = getSemaphore(k);
+    const bucket = getBucket(k);
+    if (bucket) await bucket.take();
+    const release = await sem.acquire();
+    try {
+      const res = await next(ctx);
+      if (honorRetryAfter && bucket && res.status === 429) {
+        const ra = parseRetryAfterMs(res.headers, Date.now());
+        if (typeof ra === "number") bucket.setCooldown(Date.now() + ra);
+      }
+      return res;
+    } finally {
+      release();
+    }
+  };
+  return {
+    name: "rate-limit",
+    apply: (draft) => {
+      draft.guards = [...draft.guards ?? [], guard];
+    }
+  };
+}
+
+export { rateLimitPlugin };
+//# 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\ntype KeyFn = (ctx: RequestContext) => string;\n\nexport type RateLimitPluginOptions = {\n  maxConcurrent?: number;\n  tokensPerInterval?: number;\n  intervalMs?: number;\n  honorRetryAfter?: boolean;\n  key?: KeyFn;\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\nclass Semaphore {\n  private max: number;\n  private cur = 0;\n  private q: Array<() => void> = [];\n  constructor(max: number) { this.max = Math.max(1, max); }\n  async acquire(): Promise<() => void> {\n    if (this.cur < this.max) {\n      this.cur++;\n      return () => this.release();\n    }\n    await new Promise<void>((r) => this.q.push(r));\n    this.cur++;\n    return () => this.release();\n  }\n  private release() {\n    this.cur--;\n    const next = this.q.shift();\n    if (next) next();\n  }\n}\n\nclass TokenBucket {\n  private tokens: number;\n  private readonly cap: number;\n  private readonly refill: number;\n  private readonly intervalMs: number;\n  private lastRefill: number = Date.now();\n  private cooldownUntil = 0;\n\n  constructor(tokensPerInterval: number, intervalMs: number) {\n    this.cap = Math.max(1, tokensPerInterval);\n    this.tokens = this.cap;\n    this.refill = this.cap;\n    this.intervalMs = Math.max(1, intervalMs);\n  }\n\n  setCooldown(untilMs: number) { this.cooldownUntil = Math.max(this.cooldownUntil, untilMs); }\n\n  private refillIfNeeded(now: number) {\n    if (now - this.lastRefill >= this.intervalMs) {\n      const steps = Math.floor((now - this.lastRefill) / this.intervalMs);\n      this.tokens = Math.min(this.cap, this.tokens + steps * this.refill);\n      this.lastRefill += steps * this.intervalMs;\n    }\n  }\n\n  async take(): Promise<void> {\n    while (true) {\n      const now = Date.now();\n      this.refillIfNeeded(now);\n      if (now < this.cooldownUntil) {\n        await new Promise((r) => setTimeout(r, this.cooldownUntil - now));\n        continue;\n      }\n      if (this.tokens > 0) {\n        this.tokens--;\n        return;\n      }\n      const waitMs = Math.max(1, this.intervalMs - (now - this.lastRefill));\n      await new Promise((r) => setTimeout(r, waitMs));\n    }\n  }\n}\n\nexport function rateLimitPlugin(opts: RateLimitPluginOptions = {}): HttpPlugin {\n  const maxConcurrent = opts.maxConcurrent ?? 8;\n  const tokensPerInterval = opts.tokensPerInterval;\n  const intervalMs = opts.intervalMs ?? 1000;\n  const honorRetryAfter = opts.honorRetryAfter ?? true;\n  const keyFn: KeyFn = opts.key ?? ((ctx) => new URL(ctx.url).host);\n\n  const semaphores = new Map<string, Semaphore>();\n  const buckets = new Map<string, TokenBucket>();\n\n  const getSemaphore = (k: string) => {\n    let s = semaphores.get(k);\n    if (!s) { s = new Semaphore(maxConcurrent); semaphores.set(k, s); }\n    return s;\n  };\n  const getBucket = (k: string) => {\n    if (!tokensPerInterval) return undefined;\n    let b = buckets.get(k);\n    if (!b) { b = new TokenBucket(tokensPerInterval, intervalMs); buckets.set(k, b); }\n    return b;\n  };\n\n  const guard: Guard = async (ctx, next) => {\n    const k = keyFn(ctx);\n    const sem = getSemaphore(k);\n    const bucket = getBucket(k);\n\n    if (bucket) await bucket.take();\n    const release = await sem.acquire();\n    try {\n      const res = await next(ctx);\n      if (honorRetryAfter && bucket && res.status === 429) {\n        const ra = parseRetryAfterMs(res.headers, Date.now());\n        if (typeof ra === \"number\") bucket.setCooldown(Date.now() + ra);\n      }\n      return res;\n    } finally {\n      release();\n    }\n  };\n\n  return {\n    name: \"rate-limit\",\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-rate-limit",
+  "version": "0.0.1-next.10",
+  "description": "Rate limit plugin (concurrency + token bucket) 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"
+  }
+}