@ayepi/rate 0.1.0

package/dist/index.js

@@ -0,0 +1,331 @@
+import { ctx, middleware } from "@ayepi/core";
+import { unlimitedDoer } from "@ayepi/core/doer";
+//#region src/index.ts
+/**
+* # @ayepi/rate
+*
+* Rate-limiting middleware for ayepi. {@link rateLimit} builds a middleware that
+* derives a **key from the request context** (e.g. the authenticated user, an IP,
+* an API token), checks it against a **store + algorithm**, and — when the limit
+* is exceeded — **short-circuits with a 429 `Response`** (which also maps to a ws
+* error frame). Successful requests expose `ratelimit` info in the handler
+* context.
+*
+* ```ts
+* // shared.ts (frontend-safe): the def declares what it contributes
+* import { rateLimit } from '@ayepi/rate'
+* const limit = rateLimit({ requires: [auth] })          // provides { ratelimit }
+* spec({ endpoints: { ...limit.group({ … }) } })
+*
+* // server.ts: bind the policy (key, limit, window, store)
+* import { rateLimit } from '@ayepi/rate/server'
+* implement(api).middleware(rateLimit.server(limit, {
+*   key: (io) => io.ctx.user.id,                          // io.ctx.user typed via `requires: [auth]`
+*   limit: 100,
+*   window: 60_000,
+*   algorithm: 'sliding-window',
+* }))
+* ```
+*
+* - **Pluggable store** — in-memory by default ({@link memoryStore}); pass a
+*   distributed store (see `@ayepi/rate/redis`) to limit across instances.
+* - **Algorithms** — `fixed-window`, `sliding-window`, `token-bucket`.
+* - **Customizable response** — status, message (text or JSON), and headers
+*   (draft `RateLimit-*` + `Retry-After` by default, or your own).
+*
+* @module
+*/
+/** Default over-limit HTTP status. */
+const DEFAULT_STATUS = 429;
+/** Default key namespace. */
+const DEFAULT_PREFIX = "rl:";
+/** Default algorithm. */
+const DEFAULT_ALGORITHM = "fixed-window";
+/** Tokens consumed per request (token-bucket). */
+const TOKEN_COST = 1;
+/** Milliseconds per second — `Retry-After` / `RateLimit-Reset` are expressed in seconds. */
+const MS_PER_SECOND = 1e3;
+/** Amortized cleanup: sweep expired in-memory entries once every this many `consume` calls. */
+const SWEEP_EVERY = 1e3;
+/** Drop an idle in-memory token bucket after this long with no activity (it refills to full anyway). */
+const BUCKET_IDLE_MS = 600 * 1e3;
+/**
+* Create a standalone {@link Limiter} — the rate-limit primitive the
+* {@link rateLimit} middleware is built on. Use it anywhere you have a key: a
+* plain handler, a queue/cron worker, a CLI, a different framework.
+*
+* ```ts
+* const lim = limiter({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+* const { allowed, retryAfter } = await lim.check(userId)
+* if (!allowed) throw reject(429, 'RATE_LIMITED', `retry in ${retryAfter}ms`)
+* ```
+*/
+function limiter(opts) {
+	const store = opts.store ?? memoryStore();
+	const rule = {
+		limit: opts.limit,
+		window: opts.window,
+		algorithm: opts.algorithm ?? DEFAULT_ALGORITHM,
+		countRejected: opts.countRejected ?? false
+	};
+	const prefix = opts.prefix ?? DEFAULT_PREFIX;
+	return {
+		rule,
+		check: (key, now) => store.consume(prefix + key, rule, now ?? Date.now()),
+		reset: (key) => Promise.resolve(store.reset?.(prefix + key))
+	};
+}
+/**
+* Compute the rate-limit response headers for `info`. `true` (default) emits the
+* draft `RateLimit-Limit`/`-Remaining`/`-Reset` headers — plus `Retry-After` **only
+* when the request was rejected** (`retryAfter > 0`); `false` emits none; a function
+* returns your own map (which **replaces** the defaults).
+*
+* Shared by {@link rateLimitResponse} (the 429) and the middleware's `alwaysHeaders`
+* option (informational headers on allowed responses).
+*/
+function rateLimitHeaders(info, headers = true) {
+	if (headers === false) return {};
+	if (typeof headers === "function") return { ...headers(info) };
+	const out = {
+		"ratelimit-limit": String(info.limit),
+		"ratelimit-remaining": String(info.remaining),
+		"ratelimit-reset": String(Math.ceil(info.reset / MS_PER_SECOND))
+	};
+	if (info.retryAfter > 0) out["retry-after"] = String(Math.ceil(info.retryAfter / MS_PER_SECOND));
+	return out;
+}
+/**
+* Build a rate-limit (429) `Response` from limiter info — usable on its own,
+* outside any middleware (e.g. from a handler that called {@link limiter} directly).
+*/
+function rateLimitResponse(info, opts = {}) {
+	const status = opts.status ?? DEFAULT_STATUS;
+	const headers = rateLimitHeaders(info, opts.headers);
+	const body = typeof opts.message === "function" ? opts.message(info) : opts.message ?? "Too many requests";
+	if (typeof body === "string") {
+		if (!("content-type" in headers)) headers["content-type"] = "text/plain; charset=utf-8";
+		return new Response(body, {
+			status,
+			headers
+		});
+	}
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: {
+			"content-type": "application/json",
+			...headers
+		}
+	});
+}
+/**
+* Create a rate-limiting middleware **def**. The def declares what the middleware
+* contributes (`{ ratelimit: RateLimitInfo }`) and its dependencies — but **no**
+* policy. Bind the key/limit/window/store with
+* [`rateLimit.server(def, { key, limit, window })`](./server).
+*
+* @typeParam R - inferred from `requires`; their context types flow into the
+*   server-side `key`/`skip`/`message`.
+*/
+function rateLimit(opts) {
+	return middleware(opts?.name ?? "rateLimit", {
+		provides: ctx(),
+		requires: opts?.requires ?? []
+	});
+}
+/** Minimum re-check delay when a deferred task has no explicit retry hint (ms). */
+const DOER_RETRY_FLOOR = 50;
+/**
+* A {@link Doer} (see `@ayepi/core/doer`) that caps the **start rate** of tasks using a
+* standalone {@link limiter} — the same primitive (and pluggable {@link RateLimitStore}/
+* algorithm) the {@link rateLimit} middleware uses. When the limiter admits a task it is
+* handed to an **inner doer** (default {@link unlimitedDoer}), so you can compose a rate
+* cap with a concurrency/ordering policy (e.g. `rateLimitedDoer({ …, doer: priorityDoer({ max: 4 }) })`).
+* Excess tasks wait, oldest-first; a distributed store rate-limits **across a fleet**.
+*
+* ```ts
+* import { rateLimitedDoer } from '@ayepi/rate'
+* import { createWork } from '@ayepi/work'
+*
+* const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+* const w = createWork({ work: [sendEmail] as const, doer })
+* ```
+*/
+function rateLimitedDoer(opts) {
+	const lim = limiter(opts);
+	const inner = opts.doer ?? unlimitedDoer();
+	const now = opts.now ?? Date.now;
+	const floor = opts.retryFloor ?? DOER_RETRY_FLOOR;
+	const keyOf = (o) => typeof opts.key === "function" ? opts.key(o ?? {}) : opts.key ?? "doer";
+	const pending = [];
+	const idle = [];
+	let seq = 0;
+	let draining = false;
+	let timer = null;
+	const arm = (ms) => {
+		if (timer) return;
+		timer = setTimeout(() => {
+			timer = null;
+			drain();
+		}, Math.max(floor, ms));
+		timer.unref?.();
+	};
+	const drain = async () => {
+		if (draining) return;
+		draining = true;
+		try {
+			while (pending.length > 0) {
+				if (inner.available() <= 0) {
+					arm(floor);
+					break;
+				}
+				let best = 0;
+				for (let i = 1; i < pending.length; i++) {
+					const a = pending[i];
+					const b = pending[best];
+					if (a.createdAt < b.createdAt || a.createdAt === b.createdAt && a.seq < b.seq) best = i;
+				}
+				const task = pending[best];
+				let res;
+				try {
+					res = await lim.check(keyOf(task.opts), now());
+				} catch (err) {
+					try {
+						opts.onError?.(err);
+					} catch {}
+					arm(floor);
+					break;
+				}
+				if (!res.allowed) {
+					arm(res.retryAfter);
+					break;
+				}
+				pending.splice(best, 1);
+				inner.do(task.run, task.opts);
+			}
+			if (pending.length === 0) for (const r of idle.splice(0)) r();
+		} finally {
+			draining = false;
+		}
+	};
+	return {
+		available: () => Math.min(Math.max(0, lim.rule.limit - pending.length), inner.available()),
+		do(task, o) {
+			pending.push({
+				run: task,
+				opts: o,
+				createdAt: o?.createdAt ?? now(),
+				seq: seq++
+			});
+			drain();
+		},
+		done: () => pending.length === 0 ? inner.done() : new Promise((r) => idle.push(() => void inner.done().then(r)))
+	};
+}
+function fixedWindow(counters, key, rule, now) {
+	let e = counters.get(key);
+	if (!e || e.reset <= now) {
+		e = {
+			count: 0,
+			reset: now + rule.window
+		};
+		counters.set(key, e);
+	}
+	const allowed = e.count < rule.limit;
+	if (allowed || rule.countRejected) e.count++;
+	const reset = e.reset - now;
+	return {
+		allowed,
+		limit: rule.limit,
+		remaining: Math.max(0, rule.limit - e.count),
+		reset,
+		retryAfter: allowed ? 0 : reset
+	};
+}
+function slidingWindow(counters, key, rule, now) {
+	const windowStart = Math.floor(now / rule.window) * rule.window;
+	const curKey = `${key}|${windowStart}`;
+	const prevKey = `${key}|${windowStart - rule.window}`;
+	let cur = counters.get(curKey);
+	if (!cur || cur.reset <= now) {
+		cur = {
+			count: 0,
+			reset: windowStart + rule.window
+		};
+		counters.set(curKey, cur);
+	}
+	const prevCount = counters.get(prevKey)?.count ?? 0;
+	const weight = (rule.window - (now - windowStart)) / rule.window;
+	const allowed = prevCount * weight + cur.count + 1 <= rule.limit;
+	if (allowed || rule.countRejected) cur.count++;
+	const weighted = prevCount * weight + cur.count;
+	const reset = windowStart + rule.window - now;
+	return {
+		allowed,
+		limit: rule.limit,
+		remaining: Math.max(0, Math.floor(rule.limit - weighted)),
+		reset,
+		retryAfter: allowed ? 0 : reset
+	};
+}
+function tokenBucket(buckets, key, rule, now) {
+	const cap = rule.limit;
+	const refillPerMs = rule.limit / rule.window;
+	let b = buckets.get(key);
+	if (!b) b = {
+		tokens: cap,
+		ts: now
+	};
+	b.tokens = Math.min(cap, b.tokens + (now - b.ts) * refillPerMs);
+	b.ts = now;
+	const cost = TOKEN_COST;
+	let allowed = false;
+	if (b.tokens >= cost) {
+		b.tokens -= cost;
+		allowed = true;
+	}
+	buckets.set(key, b);
+	const remaining = Math.floor(b.tokens);
+	const retryAfter = allowed ? 0 : Math.ceil((cost - b.tokens) / refillPerMs);
+	const reset = Math.ceil((cap - b.tokens) / refillPerMs);
+	return {
+		allowed,
+		limit: cap,
+		remaining,
+		reset,
+		retryAfter
+	};
+}
+/**
+* An in-process {@link RateLimitStore} implementing all three algorithms. The
+* default store — fine for a single instance; use a distributed store (e.g.
+* `@ayepi/rate/redis`) to share limits across pods. Expired entries are swept
+* lazily.
+*/
+function memoryStore() {
+	const counters = /* @__PURE__ */ new Map();
+	const buckets = /* @__PURE__ */ new Map();
+	let ops = 0;
+	const sweep = (now) => {
+		if (++ops % SWEEP_EVERY !== 0) return;
+		for (const [k, e] of counters) if (e.reset <= now) counters.delete(k);
+		for (const [k, b] of buckets) if (now - b.ts > BUCKET_IDLE_MS) buckets.delete(k);
+	};
+	return {
+		consume(key, rule, now) {
+			sweep(now);
+			switch (rule.algorithm) {
+				case "sliding-window": return slidingWindow(counters, key, rule, now);
+				case "token-bucket": return tokenBucket(buckets, key, rule, now);
+				default: return fixedWindow(counters, key, rule, now);
+			}
+		},
+		reset(key) {
+			counters.delete(key);
+			for (const k of counters.keys()) if (k.startsWith(`${key}|`)) counters.delete(k);
+			buckets.delete(key);
+		}
+	};
+}
+//#endregion
+export { limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/redis.cjs

@@ -0,0 +1,103 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/redis.ts
+/** Tokens consumed per request (token-bucket). */
+const TOKEN_COST = 1;
+/** Keep bucketed keys for this many windows so the previous bucket is still readable. */
+const WINDOW_TTL_FACTOR = 2;
+/** The Lua scripts return 1 for an allowed request. */
+const LUA_ALLOWED = 1;
+const FIXED = `
+local c = redis.call('INCR', KEYS[1])
+if c == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+if c > tonumber(ARGV[2]) and ARGV[3] ~= '1' then redis.call('DECR', KEYS[1]) end
+return {c, redis.call('PTTL', KEYS[1])}`;
+const SLIDING = `
+local cur = redis.call('INCR', KEYS[1])
+if cur == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local prev = redis.call('GET', KEYS[2])
+prev = prev and tonumber(prev) or 0
+if prev * tonumber(ARGV[2]) + cur > tonumber(ARGV[3]) and ARGV[4] ~= '1' then redis.call('DECR', KEYS[1]) end
+return {cur, prev}`;
+const TOKEN = `
+local d = redis.call('HMGET', KEYS[1], 't', 's')
+local tokens = tonumber(d[1])
+local ts = tonumber(d[2])
+local cap = tonumber(ARGV[1])
+local rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local ttl = tonumber(ARGV[4])
+local cost = tonumber(ARGV[5])
+if tokens == nil then tokens = cap; ts = now end
+tokens = math.min(cap, tokens + (now - ts) * rate)
+local allowed = 0
+if tokens >= cost then tokens = tokens - cost; allowed = 1 end
+redis.call('HSET', KEYS[1], 't', tokens, 's', now)
+redis.call('PEXPIRE', KEYS[1], ttl)
+return {allowed, tostring(tokens)}`;
+const num = (v) => typeof v === "number" ? v : Number(v);
+/**
+* Create a Redis-backed {@link RateLimitStore}.
+*
+* @param client - an ioredis connection (used to run the limiter Lua scripts).
+*/
+function redisStore(client, opts = {}) {
+	const ns = opts.prefix ?? "";
+	return {
+		async consume(key, rule, now) {
+			const k = ns + key;
+			if (rule.algorithm === "token-bucket") {
+				const cap = rule.limit;
+				const rate = rule.limit / rule.window;
+				const ttl = Math.ceil(rule.window * WINDOW_TTL_FACTOR);
+				const res = await client.eval(TOKEN, 1, k, cap, rate, now, ttl, TOKEN_COST);
+				const allowed = num(res[0]) === LUA_ALLOWED;
+				const tokens = num(res[1]);
+				const retryAfter = allowed ? 0 : Math.ceil((TOKEN_COST - tokens) / rate);
+				const reset = Math.ceil((cap - tokens) / rate);
+				return {
+					allowed,
+					limit: cap,
+					remaining: Math.floor(tokens),
+					reset,
+					retryAfter
+				};
+			}
+			const countRejected = rule.countRejected ? "1" : "0";
+			if (rule.algorithm === "sliding-window") {
+				const windowStart = Math.floor(now / rule.window) * rule.window;
+				const curKey = `${k}|${windowStart}`;
+				const prevKey = `${k}|${windowStart - rule.window}`;
+				const weight = (rule.window - (now - windowStart)) / rule.window;
+				const res = await client.eval(SLIDING, 2, curKey, prevKey, rule.window * WINDOW_TTL_FACTOR, weight, rule.limit, countRejected);
+				const cur = num(res[0]);
+				const weighted = num(res[1]) * weight + cur;
+				const allowed = weighted <= rule.limit;
+				const reset = windowStart + rule.window - now;
+				return {
+					allowed,
+					limit: rule.limit,
+					remaining: Math.max(0, Math.floor(rule.limit - weighted)),
+					reset,
+					retryAfter: allowed ? 0 : reset
+				};
+			}
+			const res = await client.eval(FIXED, 1, k, rule.window, rule.limit, countRejected);
+			const count = num(res[0]);
+			const ttl = num(res[1]);
+			const allowed = count <= rule.limit;
+			const reset = ttl >= 0 ? ttl : rule.window;
+			return {
+				allowed,
+				limit: rule.limit,
+				remaining: Math.max(0, rule.limit - count),
+				reset,
+				retryAfter: allowed ? 0 : reset
+			};
+		},
+		async reset(key) {
+			await client.eval(`return redis.call('DEL', KEYS[1])`, 1, ns + key);
+		}
+	};
+}
+//#endregion
+exports.redisStore = redisStore;

package/dist/redis.d.cts

@@ -0,0 +1,21 @@
+import { RateLimitStore } from "./index.cjs";
+
+//#region src/redis.d.ts
+
+/** The minimal ioredis surface this store uses (ioredis's `Redis` satisfies it). */
+interface RedisEvalLike {
+  eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+/** Options for {@link redisStore}. */
+interface RedisStoreOptions {
+  /** Extra key namespace prepended to every key (default `''`). */
+  readonly prefix?: string;
+}
+/**
+ * Create a Redis-backed {@link RateLimitStore}.
+ *
+ * @param client - an ioredis connection (used to run the limiter Lua scripts).
+ */
+declare function redisStore(client: RedisEvalLike, opts?: RedisStoreOptions): RateLimitStore;
+//#endregion
+export { RedisEvalLike, RedisStoreOptions, redisStore };

package/dist/redis.d.ts

@@ -0,0 +1,21 @@
+import { RateLimitStore } from "./index.js";
+
+//#region src/redis.d.ts
+
+/** The minimal ioredis surface this store uses (ioredis's `Redis` satisfies it). */
+interface RedisEvalLike {
+  eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+/** Options for {@link redisStore}. */
+interface RedisStoreOptions {
+  /** Extra key namespace prepended to every key (default `''`). */
+  readonly prefix?: string;
+}
+/**
+ * Create a Redis-backed {@link RateLimitStore}.
+ *
+ * @param client - an ioredis connection (used to run the limiter Lua scripts).
+ */
+declare function redisStore(client: RedisEvalLike, opts?: RedisStoreOptions): RateLimitStore;
+//#endregion
+export { RedisEvalLike, RedisStoreOptions, redisStore };

package/dist/redis.js

@@ -0,0 +1,102 @@
+//#region src/redis.ts
+/** Tokens consumed per request (token-bucket). */
+const TOKEN_COST = 1;
+/** Keep bucketed keys for this many windows so the previous bucket is still readable. */
+const WINDOW_TTL_FACTOR = 2;
+/** The Lua scripts return 1 for an allowed request. */
+const LUA_ALLOWED = 1;
+const FIXED = `
+local c = redis.call('INCR', KEYS[1])
+if c == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+if c > tonumber(ARGV[2]) and ARGV[3] ~= '1' then redis.call('DECR', KEYS[1]) end
+return {c, redis.call('PTTL', KEYS[1])}`;
+const SLIDING = `
+local cur = redis.call('INCR', KEYS[1])
+if cur == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local prev = redis.call('GET', KEYS[2])
+prev = prev and tonumber(prev) or 0
+if prev * tonumber(ARGV[2]) + cur > tonumber(ARGV[3]) and ARGV[4] ~= '1' then redis.call('DECR', KEYS[1]) end
+return {cur, prev}`;
+const TOKEN = `
+local d = redis.call('HMGET', KEYS[1], 't', 's')
+local tokens = tonumber(d[1])
+local ts = tonumber(d[2])
+local cap = tonumber(ARGV[1])
+local rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local ttl = tonumber(ARGV[4])
+local cost = tonumber(ARGV[5])
+if tokens == nil then tokens = cap; ts = now end
+tokens = math.min(cap, tokens + (now - ts) * rate)
+local allowed = 0
+if tokens >= cost then tokens = tokens - cost; allowed = 1 end
+redis.call('HSET', KEYS[1], 't', tokens, 's', now)
+redis.call('PEXPIRE', KEYS[1], ttl)
+return {allowed, tostring(tokens)}`;
+const num = (v) => typeof v === "number" ? v : Number(v);
+/**
+* Create a Redis-backed {@link RateLimitStore}.
+*
+* @param client - an ioredis connection (used to run the limiter Lua scripts).
+*/
+function redisStore(client, opts = {}) {
+	const ns = opts.prefix ?? "";
+	return {
+		async consume(key, rule, now) {
+			const k = ns + key;
+			if (rule.algorithm === "token-bucket") {
+				const cap = rule.limit;
+				const rate = rule.limit / rule.window;
+				const ttl = Math.ceil(rule.window * WINDOW_TTL_FACTOR);
+				const res = await client.eval(TOKEN, 1, k, cap, rate, now, ttl, TOKEN_COST);
+				const allowed = num(res[0]) === LUA_ALLOWED;
+				const tokens = num(res[1]);
+				const retryAfter = allowed ? 0 : Math.ceil((TOKEN_COST - tokens) / rate);
+				const reset = Math.ceil((cap - tokens) / rate);
+				return {
+					allowed,
+					limit: cap,
+					remaining: Math.floor(tokens),
+					reset,
+					retryAfter
+				};
+			}
+			const countRejected = rule.countRejected ? "1" : "0";
+			if (rule.algorithm === "sliding-window") {
+				const windowStart = Math.floor(now / rule.window) * rule.window;
+				const curKey = `${k}|${windowStart}`;
+				const prevKey = `${k}|${windowStart - rule.window}`;
+				const weight = (rule.window - (now - windowStart)) / rule.window;
+				const res = await client.eval(SLIDING, 2, curKey, prevKey, rule.window * WINDOW_TTL_FACTOR, weight, rule.limit, countRejected);
+				const cur = num(res[0]);
+				const weighted = num(res[1]) * weight + cur;
+				const allowed = weighted <= rule.limit;
+				const reset = windowStart + rule.window - now;
+				return {
+					allowed,
+					limit: rule.limit,
+					remaining: Math.max(0, Math.floor(rule.limit - weighted)),
+					reset,
+					retryAfter: allowed ? 0 : reset
+				};
+			}
+			const res = await client.eval(FIXED, 1, k, rule.window, rule.limit, countRejected);
+			const count = num(res[0]);
+			const ttl = num(res[1]);
+			const allowed = count <= rule.limit;
+			const reset = ttl >= 0 ? ttl : rule.window;
+			return {
+				allowed,
+				limit: rule.limit,
+				remaining: Math.max(0, rule.limit - count),
+				reset,
+				retryAfter: allowed ? 0 : reset
+			};
+		},
+		async reset(key) {
+			await client.eval(`return redis.call('DEL', KEYS[1])`, 1, ns + key);
+		}
+	};
+}
+//#endregion
+export { redisStore };

package/dist/server.cjs

@@ -0,0 +1,66 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_index = require("./index.cjs");
+//#region src/server.ts
+/** Bind a {@link rateLimit} def to its runtime policy. */
+function rateLimitServer(def, opts) {
+	const lim = require_index.limiter(opts);
+	const message = opts.message;
+	const run = async (io) => {
+		const kio = {
+			req: io.req,
+			ctx: io.ctx
+		};
+		const advertise = (info) => {
+			if (!opts.alwaysHeaders) return;
+			for (const [name, value] of Object.entries(require_index.rateLimitHeaders(info, opts.headers))) io.setHeader(name, value);
+		};
+		const fullBudget = () => ({
+			limit: lim.rule.limit,
+			remaining: lim.rule.limit,
+			reset: 0,
+			retryAfter: 0
+		});
+		if (opts.skip?.(kio)) {
+			const skipped = fullBudget();
+			advertise(skipped);
+			return io.next({ ratelimit: skipped });
+		}
+		let result;
+		try {
+			result = await lim.check(opts.key(kio));
+		} catch (err) {
+			try {
+				opts.onError?.(err);
+			} catch {}
+			if (!opts.failOpen) throw err;
+			const allowed = fullBudget();
+			advertise(allowed);
+			return io.next({ ratelimit: allowed });
+		}
+		const info = {
+			limit: result.limit,
+			remaining: result.remaining,
+			reset: result.reset,
+			retryAfter: result.retryAfter
+		};
+		if (!result.allowed) return require_index.rateLimitResponse(info, {
+			status: opts.status,
+			headers: opts.headers,
+			message: typeof message === "function" ? (i) => message(i, kio) : message
+		});
+		advertise(info);
+		return io.next({ ratelimit: info });
+	};
+	return {
+		def,
+		impl: run
+	};
+}
+/**
+* The {@link rateLimit} def factory, augmented with a `.server(def, opts)` binder.
+* Import from `@ayepi/rate/server` in your server entry to bind a def created in a
+* frontend-safe spec.
+*/
+const rateLimit = Object.assign(require_index.rateLimit, { server: rateLimitServer });
+//#endregion
+exports.rateLimit = rateLimit;