@voltro/plugin-ratelimit 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+import { Schema } from 'effect';
+
+/**
+ * Raised on the RPC error channel when a call exceeds its limit. The
+ * interceptor fails with this; the framework's rpc encoder carries it.
+ *
+ * The plugin registers this schema through `errorSchemas` (see
+ * `index.ts`), so it is merged into EVERY procedure's wire error union —
+ * the client decodes it as a typed `RateLimited` instance (catchable via
+ * `Effect.catchTag('RateLimited', …)` or `instanceof RateLimited`) on any
+ * limited call, with no per-route `error:` opt-in required.
+ *
+ * Import it from the browser-safe `@voltro/plugin-ratelimit/errors`
+ * subpath when a descriptor names it in its own `error:` schema — this
+ * file imports only `effect` (no server modules), so it's safe in a
+ * client bundle.
+ */
+export declare class RateLimited extends RateLimited_base {
+}
+
+declare const RateLimited_base: Schema.TaggedErrorClass<RateLimited, "RateLimited", {
+    readonly _tag: Schema.tag<"RateLimited">;
+} & {
+    /** The rpc tag that was limited, e.g. `'todos.create'`. */
+    tag: typeof Schema.String;
+    /** The effective limit that was hit. */
+    limit: typeof Schema.Number;
+    /** The window the limit applies over, in ms. */
+    windowMs: typeof Schema.Number;
+    /** Suggested wait before retrying, in ms. */
+    retryAfterMs: typeof Schema.Number;
+    /** Epoch-ms when the bucket is expected to be replenished. */
+    resetAtMs: typeof Schema.Number;
+}>;
+
+export { }

package/dist/errors.js

@@ -0,0 +1,11 @@
+import { Schema as e } from "effect";
+//#region src/errors.ts
+var t = class extends e.TaggedError()("RateLimited", {
+	tag: e.String,
+	limit: e.Number,
+	windowMs: e.Number,
+	retryAfterMs: e.Number,
+	resetAtMs: e.Number
+}) {};
+//#endregion
+export { t as RateLimited };

package/dist/index.d.ts

@@ -0,0 +1,319 @@
+import { Effect } from 'effect';
+import { RespClient } from '@voltro/kv/connection';
+import { RpcKind } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { SqlClient } from '@effect/sql';
+import { Subject } from '@voltro/protocol';
+import { VoltroPlugin } from '@voltro/protocol';
+
+export declare type Algorithm = 'fixed-window' | 'sliding-window' | 'token-bucket';
+
+declare interface BucketResult {
+    readonly state: BucketState;
+    readonly decision: RateLimitDecision;
+}
+
+/** Opaque per-key state. The store persists it verbatim; only this
+ *  module reads its shape. */
+export declare type BucketState = {
+    readonly kind: 'fixed';
+    readonly windowStart: number;
+    readonly count: number;
+} | {
+    readonly kind: 'sliding';
+    readonly currStart: number;
+    readonly currCount: number;
+    readonly prevCount: number;
+} | {
+    readonly kind: 'token';
+    readonly tokens: number;
+    readonly lastRefill: number;
+};
+
+export declare const consumeBucket: (prev: BucketState | undefined, limit: ResolvedLimit, now: number) => BucketResult;
+
+/** The fallback rule applied when no `rules` entry matches. Same shape
+ *  minus `match` (it matches whatever's left). Omit to leave unmatched
+ *  calls unlimited. */
+export declare type DefaultRule = Omit<RateLimitRule, 'match'>;
+
+/** A value that can be a constant or computed per-call. Dynamic form
+ *  receives the resolution context (subject, tenant, tag). */
+export declare type Dynamic<T> = T | ((ctx: RateLimitContext) => T);
+
+/** Coarse pre-auth IP shield on the HTTP pipeline. */
+export declare interface HttpShieldOptions {
+    readonly limit: number;
+    readonly window: WindowSpec;
+    /** Default `'fixed-window'` — cheapest for a front-door guard. */
+    readonly algorithm?: Algorithm;
+}
+
+/** What to key the bucket on. Composite arrays join into one key, so
+ *  `['tenant', 'subject']` = one bucket per (tenant, user). */
+export declare type KeyBy = 'subject' | 'tenant' | 'apiKey' | 'global' | ((ctx: RateLimitContext) => string);
+
+/** Diagnostics passed to the optional `onLimited` callback. */
+export declare interface LimitedInfo {
+    readonly tag: string;
+    readonly kind: RpcKind;
+    readonly key: string;
+    readonly tenantId: string | null;
+    readonly limit: number;
+    readonly windowMs: number;
+    readonly retryAfterMs: number;
+}
+
+export declare const memoryStore: (options?: MemoryStoreOptions) => RateLimitStore;
+
+export declare interface MemoryStoreOptions {
+    /** Hard cap on tracked keys. Oldest-touched entries are evicted past
+     *  this. Default 100k — a runaway-key backstop, not a tuning knob. */
+    readonly maxKeys?: number;
+    /** Entries untouched for longer than this (ms) are dropped on sweep.
+     *  Default 1h. */
+    readonly staleAfterMs?: number;
+}
+
+/** Parse a `WindowSpec` to milliseconds. Throws on malformed input — a
+ *  bad window is a config error that should surface loudly at boot. */
+export declare const parseWindow: (spec: WindowSpec) => number;
+
+export declare interface PostgresStoreOptions {
+    /** Table name. Default `_voltro_ratelimit`. */
+    readonly table?: string;
+    /** Drop rows untouched for longer than this (ms) on sweep. Default 1h. */
+    readonly staleAfterMs?: number;
+}
+
+/** The context handed to every dynamic option + the `resolve` hook.
+ *  Derived from the framework's RpcInterceptorContext. */
+export declare interface RateLimitContext {
+    readonly tag: string;
+    readonly kind: RpcKind;
+    readonly subject: Subject;
+    /** Convenience: the subject's tenant (`null` only for unscoped anonymous). */
+    readonly tenantId: string | null;
+    readonly traceId: string;
+}
+
+export 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;
+}
+
+/**
+ * Raised on the RPC error channel when a call exceeds its limit. The
+ * interceptor fails with this; the framework's rpc encoder carries it.
+ *
+ * The plugin registers this schema through `errorSchemas` (see
+ * `index.ts`), so it is merged into EVERY procedure's wire error union —
+ * the client decodes it as a typed `RateLimited` instance (catchable via
+ * `Effect.catchTag('RateLimited', …)` or `instanceof RateLimited`) on any
+ * limited call, with no per-route `error:` opt-in required.
+ *
+ * Import it from the browser-safe `@voltro/plugin-ratelimit/errors`
+ * subpath when a descriptor names it in its own `error:` schema — this
+ * file imports only `effect` (no server modules), so it's safe in a
+ * client bundle.
+ */
+export declare class RateLimited extends RateLimited_base {
+}
+
+declare const RateLimited_base: Schema.TaggedErrorClass<RateLimited, "RateLimited", {
+    readonly _tag: Schema.tag<"RateLimited">;
+} & {
+    /** The rpc tag that was limited, e.g. `'todos.create'`. */
+    tag: typeof Schema.String;
+    /** The effective limit that was hit. */
+    limit: typeof Schema.Number;
+    /** The window the limit applies over, in ms. */
+    windowMs: typeof Schema.Number;
+    /** Suggested wait before retrying, in ms. */
+    retryAfterMs: typeof Schema.Number;
+    /** Epoch-ms when the bucket is expected to be replenished. */
+    resetAtMs: typeof Schema.Number;
+}>;
+
+export declare const rateLimitPlugin: (options?: RateLimitPluginOptions) => VoltroPlugin;
+
+export declare interface RateLimitPluginOptions {
+    /** Ordered, per-endpoint rules. First match wins. */
+    readonly rules?: ReadonlyArray<RateLimitRule>;
+    /**
+     * Coarse PRE-AUTH IP shield, keyed by remote IP. Fires on EVERY HTTP
+     * request — inspect, webhooks, AND the rpc websocket upgrade — before
+     * any subject is resolved. A cheap DoS front-door in addition to the
+     * per-subject rpc `rules`. Shares the same `store`. Omit to disable.
+     * Requires the `http:intercept` permission, which the plugin declares
+     * automatically when this is set.
+     */
+    readonly http?: HttpShieldOptions;
+    /** Fallback for calls no rule matched. Omit → unmatched calls pass. */
+    readonly default?: DefaultRule;
+    /**
+     * Counter backend:
+     *   - `'memory'` (default) — single-node, zero-config.
+     *   - `'postgres'` — multi-node correct; opens its own pool from the
+     *     same `DB_*`/`PG_*` env the framework reads, creates
+     *     `_voltro_ratelimit`, mutates state under a row lock. Fails OPEN
+     *     on db errors (degrades to no-limit, never to 500s).
+     *   - `'redis'` — multi-node, fastest; connects ioredis from
+     *     `CACHE_REDIS_URL`/`REDIS_URL`, runs the whole decision in one
+     *     atomic Lua script. For a custom client/url use the
+     *     `redisStore({...})` factory from `@voltro/plugin-ratelimit/redis`.
+     *   - a custom `RateLimitStore`.
+     */
+    readonly store?: 'memory' | 'postgres' | 'redis' | RateLimitStore;
+    /**
+     * Master gate. `false` disables all limiting; a function lets you gate
+     * per-call (e.g. exempt a tenant, or a maintenance bypass). Returning
+     * `false` means "no limit for this call". Default: enabled.
+     */
+    readonly enabled?: boolean | ((ctx: RateLimitContext) => boolean);
+    /**
+     * Fully-programmatic per-tenant resolution. Runs AFTER a rule + its
+     * static tenant override are resolved; whatever it returns wins. Use
+     * for limits sourced from a tenant's plan/tier (e.g. read
+     * `subject.metadata.plan`, or look the tenant up — return an Effect).
+     *
+     *   - return a `ResolvedRuleOverride` → override this call's limit
+     *   - return `'exempt'`               → skip limiting this call
+     *   - return `undefined`              → keep the rule-derived limit
+     *
+     * Sync, Promise, or Effect — all three are normalised.
+     */
+    readonly resolve?: (ctx: RateLimitContext, base: ResolvedRuleOverride | undefined) => ResolvedRuleOverride | 'exempt' | undefined | Promise<ResolvedRuleOverride | 'exempt' | undefined> | Effect.Effect<ResolvedRuleOverride | 'exempt' | undefined>;
+    /** Fired (best-effort, swallowed on throw) whenever a call is rejected. */
+    readonly onLimited?: (info: LimitedInfo) => void;
+    /** Disambiguates multiple instances of this plugin in one app. */
+    readonly name?: string;
+}
+
+/** One rate-limit rule. Rules are evaluated top-to-bottom; the first
+ *  whose `match` + `kind` accept the call wins. */
+export declare interface RateLimitRule {
+    /**
+     * Which endpoints this rule covers:
+     *   - omitted     → every tag (subject to `kind`)
+     *   - string      → exact rpc tag, e.g. `'todos.create'`
+     *   - string[]    → any of these exact tags
+     *   - RegExp      → tags matching the pattern, e.g. `/^admin\./`
+     */
+    readonly match?: string | ReadonlyArray<string> | RegExp;
+    /** Restrict to certain rpc kinds (limit writes but not reads, etc.).
+     *  Omitted → all kinds. */
+    readonly kind?: RpcKind | ReadonlyArray<RpcKind>;
+    /** Allowance per window. Static, or `(ctx) => n` for per-tenant/plan logic. */
+    readonly limit: Dynamic<number>;
+    /** Window length. Static or dynamic. */
+    readonly window: Dynamic<WindowSpec>;
+    /** Algorithm. Default `'sliding-window'`. */
+    readonly algorithm?: Algorithm;
+    /** Token-bucket burst capacity. Defaults to `limit`. Ignored by the
+     *  window algorithms. */
+    readonly burst?: Dynamic<number>;
+    /** Keying dimension(s). Default `'subject'`. */
+    readonly by?: KeyBy | ReadonlyArray<KeyBy>;
+    /**
+     * Bucket granularity across the tags this rule matches:
+     *   - `'tag'`  (default) — a separate bucket per matched endpoint, so
+     *     `todos.create` and `todos.update` count independently.
+     *   - `'rule'` — one shared bucket across ALL tags the rule matches
+     *     (e.g. "200 writes/min total across every mutation").
+     */
+    readonly scope?: 'tag' | 'rule';
+    /** Static per-tenant overrides, keyed by tenantId. */
+    readonly tenants?: Readonly<Record<string, TenantOverride>>;
+}
+
+export 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. */
+export 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;
+}
+
+/** The limit shape the `resolve` hook returns / receives — scalars only,
+ *  no dynamic wrappers (resolution already happened). */
+export declare interface ResolvedRuleOverride {
+    readonly limit: number;
+    readonly window: WindowSpec;
+    readonly algorithm?: Algorithm;
+    readonly burst?: number;
+}
+
+/** Per-tenant override applied on top of a rule. Any field omitted
+ *  inherits the rule's value. `disabled` exempts the tenant entirely. */
+export declare interface TenantOverride {
+    readonly limit?: Dynamic<number>;
+    readonly window?: Dynamic<WindowSpec>;
+    readonly algorithm?: Algorithm;
+    readonly burst?: Dynamic<number>;
+    readonly disabled?: boolean;
+}
+
+export { VoltroPlugin }
+
+/** A window length. Either milliseconds as a number, or a unit string
+ *  like `'1m'`, `'10s'`, `'500ms'`, `'2h'`, `'1d'`. */
+export declare type WindowSpec = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}` | number;
+
+export { }

package/dist/index.js

@@ -0,0 +1,243 @@
+import { RateLimited as e } from "./errors.js";
+import { n as t, t as n } from "./window-lyQ6LXhj.js";
+import { redisStore as r } from "./redisStore.js";
+import { Effect as i } from "effect";
+import { definePlugin as a } from "@voltro/protocol";
+//#region src/store.ts
+var o = (e = {}) => {
+	let t = e.maxKeys ?? 1e5, r = e.staleAfterMs ?? 36e5, a = /* @__PURE__ */ new Map(), o = (e) => {
+		if (a.size <= t) return;
+		let n = a.size - t, r = 0;
+		for (let t of a.keys()) {
+			if (r >= n) break;
+			t !== e && (a.delete(t), r += 1);
+		}
+	};
+	return {
+		consume: (e, t, r) => i.sync(() => {
+			let { state: i, decision: s } = n(a.get(e)?.state, t, r);
+			return a.set(e, {
+				state: i,
+				touched: r
+			}), o(e), s;
+		}),
+		sweep: (e) => {
+			let t = e - r;
+			for (let [e, n] of a) n.touched < t && a.delete(e);
+		},
+		size: () => a.size
+	};
+}, s = (e, t) => ({
+	allowed: !0,
+	remaining: e.limit,
+	resetAtMs: t + e.windowMs,
+	retryAfterMs: 0
+}), c = (e = {}) => {
+	let t = null;
+	return {
+		consume: (e, n, r) => t ? t.consume(e, n, r) : i.succeed(s(n, r)),
+		sweep: (e) => t?.sweep(e),
+		size: () => t ? t.size() : -1,
+		bindSql: async (n) => {
+			let { postgresStore: r } = await import("./postgresStore.js"), i = r(e);
+			await i.bindSql(n), t = i;
+		}
+	};
+}, l = (e, t) => typeof e == "function" ? e(t) : e, u = (e, t) => e === void 0 ? !0 : typeof e == "string" ? e === t : Array.isArray(e) ? e.includes(t) : e.test(t), d = (e, t) => e === void 0 ? !0 : Array.isArray(e) ? e.includes(t) : e === t, f = (e, t) => {
+	let n = t === null ? void 0 : e.tenants?.[t];
+	return {
+		limit: n?.limit ?? e.limit,
+		window: n?.window ?? e.window,
+		algorithm: n?.algorithm ?? e.algorithm,
+		burst: n?.burst ?? e.burst,
+		by: e.by ?? "subject",
+		scope: e.scope ?? "tag",
+		disabled: n?.disabled ?? !1
+	};
+}, p = (e, t, n) => {
+	for (let t = 0; t < e.length; t++) {
+		let r = e[t];
+		if (u(r.match, n.tag) && d(r.kind, n.kind)) return {
+			effective: f(r, n.tenantId),
+			ruleId: `r${t}`
+		};
+	}
+	if (t && d(t.kind, n.kind)) return {
+		effective: f(t, n.tenantId),
+		ruleId: "default"
+	};
+}, m = (e, n) => {
+	let r = l(e.limit, n);
+	return {
+		limit: r,
+		windowMs: t(l(e.window, n)),
+		algorithm: e.algorithm ?? "sliding-window",
+		burst: e.burst === void 0 ? r : l(e.burst, n)
+	};
+}, h = (e) => {
+	let n = e.limit;
+	return {
+		limit: n,
+		windowMs: t(e.window),
+		algorithm: e.algorithm ?? "sliding-window",
+		burst: e.burst ?? n
+	};
+}, g = (e) => ({
+	limit: e.limit,
+	window: e.windowMs,
+	algorithm: e.algorithm,
+	burst: e.burst
+}), _ = (e, t) => {
+	if (typeof e == "function") return e(t);
+	switch (e) {
+		case "subject": return `s:${t.tenantId ?? "∅"}:${t.subject.id ?? "anon"}`;
+		case "tenant": return `t:${t.tenantId ?? "∅"}`;
+		case "apiKey": return t.subject.type === "apiKey" ? `k:${t.subject.id}` : `s:${t.tenantId ?? "∅"}:${t.subject.id ?? "anon"}`;
+		case "global": return "g";
+	}
+}, v = (e, t) => {
+	let { effective: n, ruleId: r } = e, i = n.scope === "rule" ? `rule#${r}` : `tag:${t.tag}`, a = n.by;
+	return `${i}|${Array.isArray(a) ? a.map((e) => _(e, t)).join("|") : _(a, t)}`;
+}, y = (e) => ({
+	tag: e.tag,
+	kind: e.kind,
+	subject: e.subject,
+	tenantId: e.subject.tenantId ?? null,
+	traceId: e.traceId
+}), b = (n = {}) => {
+	let s = n.rules ?? [], l = n.store === void 0 || n.store === "memory" ? o() : n.store === "postgres" ? c() : n.store === "redis" ? r() : n.store, u = (e) => {
+		let t = n.enabled;
+		return t === void 0 ? !0 : typeof t == "function" ? t(e) : t;
+	}, d = (e, t, r, i) => {
+		if (!n.onLimited) return;
+		let a = {
+			tag: e.tag,
+			kind: e.kind,
+			key: t,
+			tenantId: e.tenantId,
+			limit: r.limit,
+			windowMs: r.windowMs,
+			retryAfterMs: i.retryAfterMs
+		};
+		try {
+			n.onLimited(a);
+		} catch {}
+	}, f = (e, t) => {
+		let r = n.resolve;
+		return r ? i.suspend(() => {
+			let n = r(e, t);
+			return (i.isEffect(n) ? n : n instanceof Promise ? i.promise(() => n) : i.succeed(n)).pipe(i.map((e) => e === "exempt" ? "exempt" : h(e === void 0 ? t : e)));
+		}) : i.succeed(h(t));
+	}, _ = (t, r) => i.suspend(() => {
+		let a = y(r);
+		if (!u(a)) return t;
+		let o = p(s, n.default, a);
+		if (!o || o.effective.disabled) return t;
+		let c = g(m(o.effective, a));
+		return f(a, c).pipe(i.flatMap((n) => {
+			if (n === "exempt") return t;
+			let r = v(o, a);
+			return l.consume(r, n, Date.now()).pipe(i.catchAllDefect((e) => i.as(i.logWarning(`[ratelimit] store error — failing open for ${a.tag}: ${String(e)}`), {
+				allowed: !0,
+				remaining: n.limit,
+				resetAtMs: Date.now(),
+				retryAfterMs: 0
+			})), i.flatMap((o) => o.allowed ? t : i.zipRight(i.sync(() => d(a, r, n, o)), i.fail(new e({
+				tag: a.tag,
+				limit: n.limit,
+				windowMs: n.windowMs,
+				retryAfterMs: o.retryAfterMs,
+				resetAtMs: o.resetAtMs
+			})))));
+		}));
+	}), b = n.http ? async (e, r) => {
+		let a = n.http, o = {
+			limit: a.limit,
+			windowMs: t(a.window),
+			algorithm: a.algorithm ?? "fixed-window",
+			burst: a.limit
+		}, s = r.remoteAddr ?? "unknown", c = Date.now(), u = await i.runPromise(l.consume(`http:ip:${s}`, o, c)), d = String(Math.max(0, Math.ceil((u.resetAtMs - c) / 1e3)));
+		return u.allowed ? e() : {
+			status: 429,
+			body: "Too Many Requests",
+			headers: {
+				"content-type": "text/plain; charset=utf-8",
+				"retry-after": String(Math.max(1, Math.ceil(u.retryAfterMs / 1e3))),
+				"ratelimit-limit": String(o.limit),
+				"ratelimit-remaining": String(Math.max(0, u.remaining)),
+				"ratelimit-reset": d
+			}
+		};
+	} : void 0, x = [
+		"rpc:intercept:mutation",
+		"rpc:intercept:query",
+		"rpc:intercept:action",
+		...n.http ? ["http:intercept"] : []
+	], S, C;
+	return a({
+		name: n.name ? `@voltro/plugin-ratelimit#${n.name}` : "@voltro/plugin-ratelimit",
+		description: "Per-endpoint / per-subject / per-tenant rate limiting via the rpc interceptors. Configurable rules, three algorithms, static + dynamic per-tenant overrides.",
+		permissions: x,
+		declaredEnv: [
+			{
+				name: "CACHE_REDIS_URL",
+				required: !1,
+				secret: !0,
+				description: "Redis connection URL for the redis store (credential-carrying). Falls back to REDIS_URL."
+			},
+			{
+				name: "REDIS_URL",
+				required: !1,
+				secret: !0,
+				description: "Fallback Redis connection URL for the redis store (credential-carrying)."
+			},
+			{
+				name: "CACHE_REDIS_DRIVER",
+				required: !1,
+				secret: !1,
+				description: "Redis driver selector: \"http\" for the Upstash REST client, otherwise RESP."
+			},
+			{
+				name: "CACHE_REDIS_TOKEN",
+				required: !1,
+				secret: !0,
+				description: "Upstash REST token for the http redis driver. Falls back to UPSTASH_REDIS_REST_TOKEN."
+			},
+			{
+				name: "UPSTASH_REDIS_REST_TOKEN",
+				required: !1,
+				secret: !0,
+				description: "Fallback Upstash REST token for the http redis driver."
+			}
+		],
+		...b ? { onHttpRequest: b } : {},
+		errorSchemas: [{
+			schema: e,
+			import: {
+				module: "@voltro/plugin-ratelimit/errors",
+				name: "RateLimited"
+			}
+		}],
+		interceptMutation: _,
+		interceptQuery: _,
+		interceptAction: _,
+		bindDataStore: (e, t) => {
+			let n = t?.sql;
+			n && l.bindSql && l.bindSql(n).catch((e) => {
+				C = e;
+			});
+		},
+		onActivate: (e) => i.gen(function* () {
+			l.activate && (yield* i.promise(() => l.activate(e.env))), S = setInterval(() => l.sweep(Date.now()), 6e4), S.unref?.(), C !== void 0 && e.logger.warn("rate-limit: SQL store bind failed — limiter runs fail-open", { error: C instanceof Error ? C.message : String(C) }), e.logger.info("rate-limit active", {
+				rules: s.length,
+				hasDefault: n.default !== void 0,
+				store: typeof n.store == "string" ? n.store : n.store === void 0 ? "memory" : "custom"
+			});
+		}),
+		onDeactivate: () => i.gen(function* () {
+			S && clearInterval(S), l.deactivate && (yield* i.promise(() => l.deactivate()));
+		})
+	});
+};
+//#endregion
+export { e as RateLimited, n as consumeBucket, o as memoryStore, t as parseWindow, b as rateLimitPlugin, r as redisStore };

package/dist/postgresStore.d.ts

@@ -0,0 +1,55 @@
+import { Effect } from 'effect';
+import { SqlClient } from '@effect/sql';
+
+declare type Algorithm = 'fixed-window' | 'sliding-window' | 'token-bucket';
+
+export declare const postgresStore: (options?: PostgresStoreOptions) => RateLimitStore;
+
+export declare interface PostgresStoreOptions {
+    /** Table name. Default `_voltro_ratelimit`. */
+    readonly table?: string;
+    /** Drop rows untouched for longer than this (ms) on sweep. Default 1h. */
+    readonly staleAfterMs?: number;
+}
+
+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>;
+}
+
+/** 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 { }