@voltro/plugin-ratelimit 0.1.0

package/dist/postgresStore.js

@@ -0,0 +1,50 @@
+import { t as e } from "./window-lyQ6LXhj.js";
+import { Effect as t } from "effect";
+import { SqlClient as n } from "@effect/sql";
+//#region src/postgresStore.ts
+var r = (r = {}) => {
+	let i = r.table ?? "_voltro_ratelimit", a = r.staleAfterMs ?? 36e5, o = null, s = (e) => t.runPromise(t.provideService(e, n.SqlClient, o)), c = (e, t) => ({
+		allowed: !0,
+		remaining: e.limit,
+		resetAtMs: t + e.windowMs,
+		retryAfterMs: 0
+	});
+	return {
+		consume: (r, a, l) => {
+			if (!o) return t.succeed(c(a, l));
+			let u = t.gen(function* () {
+				let o = yield* n.SqlClient;
+				return yield* o.withTransaction(t.gen(function* () {
+					yield* o`SELECT pg_advisory_xact_lock(hashtextextended(${r}, 0))`;
+					let t = (yield* o`
+              SELECT state FROM ${o(i)} WHERE key = ${r} FOR UPDATE`)[0]?.state, { state: n, decision: s } = e(t, a, l), c = JSON.stringify(n);
+					return yield* o`
+              INSERT INTO ${o(i)} (key, state, touched)
+              VALUES (${r}, ${c}::jsonb, ${l})
+              ON CONFLICT (key) DO UPDATE SET state = ${c}::jsonb, touched = ${l}`, s;
+				}));
+			});
+			return t.tryPromise(() => s(u)).pipe(t.catchAll(() => t.succeed(c(a, l))));
+		},
+		sweep: (e) => {
+			o && s(t.gen(function* () {
+				let t = yield* n.SqlClient;
+				yield* t`DELETE FROM ${t(i)} WHERE touched < ${e - a}`;
+			})).catch(() => {});
+		},
+		size: () => -1,
+		bindSql: async (e) => {
+			await t.runPromise(t.provideService(t.gen(function* () {
+				let e = yield* n.SqlClient;
+				yield* e`
+              CREATE TABLE IF NOT EXISTS ${e(i)} (
+                key     TEXT   PRIMARY KEY,
+                state   JSONB  NOT NULL,
+                touched BIGINT NOT NULL
+              )`;
+			}), n.SqlClient, e)), o = e;
+		}
+	};
+};
+//#endregion
+export { r as postgresStore };

package/dist/redisStore.d.ts

@@ -0,0 +1,76 @@
+import { Effect } from 'effect';
+import { RespClient } from '@voltro/kv/connection';
+import { SqlClient } from '@effect/sql';
+
+declare type Algorithm = 'fixed-window' | 'sliding-window' | 'token-bucket';
+
+declare interface RateLimitDecision {
+    readonly allowed: boolean;
+    /** Remaining allowance in the current window (best-effort estimate). */
+    readonly remaining: number;
+    /** Epoch-ms when the bucket is expected to be fully replenished. */
+    readonly resetAtMs: number;
+    /** How long the caller should wait before retrying. 0 when allowed. */
+    readonly retryAfterMs: number;
+}
+
+declare interface RateLimitStore {
+    /** Atomically consume one unit for `key` against `limit` at `nowMs`. */
+    readonly consume: (key: string, limit: ResolvedLimit, nowMs: number) => Effect.Effect<RateLimitDecision>;
+    /** Drop entries untouched long enough to be irrelevant. Called on a timer. */
+    readonly sweep: (nowMs: number) => void;
+    /** Current number of tracked keys (diagnostics / tests). `-1` when the
+     *  store can't answer synchronously (e.g. postgres). */
+    readonly size: () => number;
+    /** Optional one-shot setup at plugin activate (open pools, create
+     *  tables). Receives the process env. */
+    readonly activate?: (env: NodeJS.ProcessEnv) => Promise<void>;
+    /** Optional teardown at plugin deactivate (close pools). */
+    readonly deactivate?: () => Promise<void>;
+    /** Optional bind of the framework's already-open `SqlClient` (from the
+     *  plugin's `bindDataStore(store, ctx)` → `ctx.sql`). A SQL-backed store
+     *  runs through THIS client instead of standing up its own pool; creates
+     *  its bookkeeping table here. Not present on memory / redis stores. */
+    readonly bindSql?: (sql: SqlClient.SqlClient) => Promise<void>;
+}
+
+export declare const redisStore: (options?: RedisStoreOptions) => RateLimitStore;
+
+export declare interface RedisStoreOptions {
+    /** Connection url. `resp` driver: `redis://…` / `rediss://…`. `http`
+     *  driver: the Upstash REST url. Falls back to `CACHE_REDIS_URL` /
+     *  `REDIS_URL` env at activate time. */
+    readonly url?: string;
+    /**
+     * How to talk to the server — mirrors the cache plugin's axis:
+     *   - `'resp'` (default) — ioredis over TCP. Works for Redis, Valkey,
+     *     KeyDB, Dragonfly, and Upstash's TCP endpoint.
+     *   - `'http'` — `@upstash/redis` over REST, for serverless/edge where
+     *     TCP isn't available.
+     * Resolved from `CACHE_REDIS_DRIVER` env when omitted. `'redis'` as a
+     * store value is the umbrella for the whole RESP family — the server
+     * brand is just the url; only the DRIVER is a real choice.
+     */
+    readonly driver?: 'resp' | 'http';
+    /** Auth token — `http` (Upstash REST) driver only. Falls back to
+     *  `CACHE_REDIS_TOKEN` / `UPSTASH_REDIS_REST_TOKEN` env. */
+    readonly token?: string;
+    /** Bring your own already-connected RESP client (from
+     *  `@voltro/kv/connection`'s `connect`, or the shared registry). Takes
+     *  precedence over `url` / `driver`. */
+    readonly client?: RespClient;
+    /** Key namespace. Default `'voltro:rl:'`. */
+    readonly keyPrefix?: string;
+}
+
+/** The fully-resolved limit the store consumes against. All dynamic /
+ *  per-tenant resolution has already collapsed into these scalars. */
+declare interface ResolvedLimit {
+    readonly limit: number;
+    readonly windowMs: number;
+    readonly algorithm: Algorithm;
+    /** Token-bucket capacity. Equals `limit` unless an explicit burst was set. */
+    readonly burst: number;
+}
+
+export { }

package/dist/redisStore.js

@@ -0,0 +1,39 @@
+import { Effect as e } from "effect";
+import { connect as t } from "@voltro/kv/connection";
+//#region src/redisStore.ts
+var n = "\nlocal key = KEYS[1]\nlocal algo = ARGV[1]\nlocal limit = tonumber(ARGV[2])\nlocal windowMs = tonumber(ARGV[3])\nlocal burst = tonumber(ARGV[4])\nlocal now = tonumber(ARGV[5])\n\nlocal raw = redis.call('GET', key)\nlocal s = nil\nif raw then s = cjson.decode(raw) end\n\nlocal allowed, remaining, resetAt, retryAfter\nlocal newstate\n\nif algo == 'fixed-window' then\n  local windowStart = (s and s.windowStart) or now\n  local count = (s and s.count) or 0\n  if now - windowStart >= windowMs then windowStart = now; count = 0 end\n  resetAt = windowStart + windowMs\n  if count >= limit then\n    allowed = false; remaining = 0; retryAfter = resetAt - now\n  else\n    count = count + 1; allowed = true; remaining = limit - count; retryAfter = 0\n  end\n  newstate = { kind = 'fixed', windowStart = windowStart, count = count }\n\nelseif algo == 'token-bucket' then\n  local capacity = burst\n  local refillPerMs = limit / windowMs\n  local tokens = (s and s.tokens) or capacity\n  local lastRefill = (s and s.lastRefill) or now\n  tokens = math.min(capacity, tokens + (now - lastRefill) * refillPerMs)\n  if tokens >= 1 then\n    tokens = tokens - 1\n    resetAt = now + math.ceil((capacity - tokens) / refillPerMs)\n    allowed = true; remaining = math.floor(tokens); retryAfter = 0\n  else\n    retryAfter = math.ceil((1 - tokens) / refillPerMs)\n    resetAt = now + retryAfter; allowed = false; remaining = 0\n  end\n  newstate = { kind = 'token', tokens = tokens, lastRefill = now }\n\nelse\n  -- sliding-window (weighted counter)\n  local w = windowMs\n  local currStart = (s and s.currStart) or now\n  local currCount = (s and s.currCount) or 0\n  local prevCount = (s and s.prevCount) or 0\n  local elapsed = math.floor((now - currStart) / w)\n  if elapsed >= 2 then\n    prevCount = 0; currCount = 0; currStart = now\n  elseif elapsed == 1 then\n    prevCount = currCount; currCount = 0; currStart = currStart + w\n  end\n  local intoCurr = now - currStart\n  local weight = (w - intoCurr) / w\n  local estimate = prevCount * weight + currCount\n  resetAt = currStart + w\n  if estimate >= limit then\n    allowed = false; remaining = 0; retryAfter = resetAt - now\n  else\n    currCount = currCount + 1\n    allowed = true\n    remaining = math.max(0, math.floor(limit - estimate - 1))\n    retryAfter = 0\n  end\n  newstate = { kind = 'sliding', currStart = currStart, currCount = currCount, prevCount = prevCount }\nend\n\nlocal ttl = math.max(windowMs * 2, 60000) + 1000\nredis.call('SET', key, cjson.encode(newstate), 'PX', ttl)\nreturn cjson.encode({ allowed = allowed, remaining = remaining, resetAtMs = resetAt, retryAfterMs = retryAfter })\n", r = (r = {}) => {
+	let i = r.keyPrefix ?? "voltro:rl:", a = r.client ?? null, o = !1, s = (e, t) => ({
+		allowed: !0,
+		remaining: e.limit,
+		resetAtMs: t + e.windowMs,
+		retryAfterMs: 0
+	});
+	return {
+		consume: (t, r, o) => {
+			let c = a;
+			return c ? e.tryPromise(async () => {
+				let e = await c.eval(n, 1, `${i}${t}`, r.algorithm, r.limit, r.windowMs, r.burst, o);
+				return JSON.parse(String(e));
+			}).pipe(e.catchAll(() => e.succeed(s(r, o)))) : e.succeed(s(r, o));
+		},
+		sweep: () => {},
+		size: () => -1,
+		activate: async (n) => {
+			if (a) return;
+			let i = r.url ?? n.RATELIMIT_REDIS_URL ?? n.CACHE_REDIS_URL ?? n.REDIS_URL;
+			if (!i) throw Error("@voltro/plugin-ratelimit redisStore: no client and no url (set RATELIMIT_REDIS_URL / REDIS_URL or pass { url }).");
+			let s = r.driver ?? ((n.RATELIMIT_REDIS_DRIVER ?? n.CACHE_REDIS_DRIVER) === "http" ? "http" : "resp"), c = r.token ?? n.RATELIMIT_REDIS_TOKEN ?? n.CACHE_REDIS_TOKEN ?? n.UPSTASH_REDIS_REST_TOKEN, l = {
+				url: i,
+				driver: s,
+				...c === void 0 ? {} : { token: c }
+			};
+			a = await e.runPromise(t(l)), o = !0;
+		},
+		deactivate: async () => {
+			let e = a;
+			a = null, e && o && await e.close();
+		}
+	};
+};
+//#endregion
+export { r as redisStore };

package/dist/window-lyQ6LXhj.js

@@ -0,0 +1,117 @@
+//#region src/window.ts
+var e = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+}, t = (t) => {
+	if (typeof t == "number") {
+		if (!Number.isFinite(t) || t <= 0) throw Error(`@voltro/plugin-ratelimit: window must be a positive number, got ${t}`);
+		return t;
+	}
+	let n = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(t.trim());
+	if (!n) throw Error(`@voltro/plugin-ratelimit: invalid window "${t}" — use e.g. "1m", "10s", "500ms", "2h", "1d"`);
+	return Number(n[1]) * e[n[2]];
+}, n = (e, t, n) => {
+	switch (t.algorithm) {
+		case "fixed-window": return r(e, t, n);
+		case "sliding-window": return i(e, t, n);
+		case "token-bucket": return a(e, t, n);
+	}
+}, r = (e, t, n) => {
+	let r = e?.kind === "fixed" ? e.windowStart : n, i = e?.kind === "fixed" ? e.count : 0;
+	n - r >= t.windowMs && (r = n, i = 0);
+	let a = r + t.windowMs;
+	return i >= t.limit ? {
+		state: {
+			kind: "fixed",
+			windowStart: r,
+			count: i
+		},
+		decision: {
+			allowed: !1,
+			remaining: 0,
+			resetAtMs: a,
+			retryAfterMs: a - n
+		}
+	} : (i += 1, {
+		state: {
+			kind: "fixed",
+			windowStart: r,
+			count: i
+		},
+		decision: {
+			allowed: !0,
+			remaining: t.limit - i,
+			resetAtMs: a,
+			retryAfterMs: 0
+		}
+	});
+}, i = (e, t, n) => {
+	let r = t.windowMs, i = e?.kind === "sliding" ? e.currStart : n, a = e?.kind === "sliding" ? e.currCount : 0, o = e?.kind === "sliding" ? e.prevCount : 0, s = Math.floor((n - i) / r);
+	s >= 2 ? (o = 0, a = 0, i = n) : s === 1 && (o = a, a = 0, i += r);
+	let c = (r - (n - i)) / r, l = o * c + a, u = i + r;
+	return l >= t.limit ? {
+		state: {
+			kind: "sliding",
+			currStart: i,
+			currCount: a,
+			prevCount: o
+		},
+		decision: {
+			allowed: !1,
+			remaining: 0,
+			resetAtMs: u,
+			retryAfterMs: u - n
+		}
+	} : (a += 1, {
+		state: {
+			kind: "sliding",
+			currStart: i,
+			currCount: a,
+			prevCount: o
+		},
+		decision: {
+			allowed: !0,
+			remaining: Math.max(0, Math.floor(t.limit - l - 1)),
+			resetAtMs: u,
+			retryAfterMs: 0
+		}
+	});
+}, a = (e, t, n) => {
+	let r = t.burst, i = t.limit / t.windowMs, a = e?.kind === "token" ? e.tokens : r, o = e?.kind === "token" ? e.lastRefill : n;
+	if (a = Math.min(r, a + (n - o) * i), a >= 1) {
+		--a;
+		let e = n + Math.ceil((r - a) / i);
+		return {
+			state: {
+				kind: "token",
+				tokens: a,
+				lastRefill: n
+			},
+			decision: {
+				allowed: !0,
+				remaining: Math.floor(a),
+				resetAtMs: e,
+				retryAfterMs: 0
+			}
+		};
+	}
+	let s = Math.ceil((1 - a) / i);
+	return {
+		state: {
+			kind: "token",
+			tokens: a,
+			lastRefill: n
+		},
+		decision: {
+			allowed: !1,
+			remaining: 0,
+			resetAtMs: n + s,
+			retryAfterMs: s
+		}
+	};
+};
+//#endregion
+export { t as n, n as t };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@voltro/plugin-ratelimit",
+  "version": "0.1.0",
+  "description": "Rate-limiting plugin — per-endpoint, per-subject and per-tenant request limits via the RPC interceptors. Highly configurable rules (fixed-window / sliding-window / token-bucket), composite keying, static per-tenant overrides and a dynamic resolve() hook. Stores: memory (default, single-node), postgres + redis (multi-node, atomic).",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgresStore.d.ts",
+      "import": "./dist/postgresStore.js",
+      "default": "./dist/postgresStore.js"
+    },
+    "./redis": {
+      "types": "./dist/redisStore.d.ts",
+      "import": "./dist/redisStore.js",
+      "default": "./dist/redisStore.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/kv": "0.1.0",
+    "@voltro/protocol": "0.1.0"
+  },
+  "optionalDependencies": {
+    "@effect/sql": "^0.51.1"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}