@ayepi/rate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+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,151 @@
+# @ayepi/rate
+
+Rate-limiting middleware for [`@ayepi/core`](https://www.npmjs.com/package/@ayepi/core).
+Derive a key from the request context, pick an algorithm and a store, and exceeded
+requests **short-circuit with a 429** (which also maps to a ws error frame).
+
+```sh
+pnpm add @ayepi/rate @ayepi/core
+```
+
+`@ayepi/rate` ships as a **def / impl split**. The main entry is frontend-safe and exports
+`rateLimit(opts?)`, a middleware **def factory**. The policy (key, limit, window, store, …)
+is bound on the server via `@ayepi/rate/server`, which augments `rateLimit` with
+`.server(def, opts)`.
+
+```ts
+// shared.ts — frontend-safe: the def + the spec
+import { rateLimit } from '@ayepi/rate'
+
+const limit = rateLimit({ requires: [auth] }) // contributes { ratelimit } to the handler ctx
+
+const api = spec({ endpoints: { ...limit.group({ getThing: { … } }) } })
+```
+
+```ts
+// server.ts — binds the policy
+import { rateLimit } from '@ayepi/rate/server'
+import { implement } from '@ayepi/core'
+
+const app = implement(api)
+  // 100 requests / minute per authenticated user, sliding window
+  .middleware(rateLimit.server(limit, {
+    key: (io) => io.ctx.user.id,
+    limit: 100,
+    window: 60_000,
+    algorithm: 'sliding-window',
+  }))
+  .server()
+```
+
+On allowed requests the handler gets `ctx.ratelimit` (`{ limit, remaining, reset,
+retryAfter }`); on exceeded requests the chain short-circuits with the 429.
+
+## Def vs server
+
+- `rateLimit(opts?)` (def factory, `@ayepi/rate`) — frontend-safe. `opts = { name?,
+  requires? }`. Declares the contract and **contributes `{ ratelimit }`** to the handler
+  context. A spec importing only this entry is safe to bundle for the frontend.
+- `rateLimit.server(def, opts)` (`@ayepi/rate/server`) — binds the policy. These options
+  move here: `key, limit, window, algorithm?, store?, prefix?, countRejected?, status?,
+  message?, headers?, alwaysHeaders?, skip?`. Bind it with `implement(api).middleware(...)`.
+
+## Standalone (without middleware)
+
+The middleware is a thin wrapper over two primitives, **both still on the main `@ayepi/rate`
+entry** (frontend-unrelated; use them anywhere — a handler, a queue/cron worker, a CLI,
+another framework):
+
+```ts
+import { limiter, rateLimitResponse } from '@ayepi/rate'
+
+const lim = limiter({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+
+const { allowed, remaining, retryAfter } = await lim.check(userId)
+if (!allowed) {
+  // do whatever you want with the decision:
+  throw reject(429, 'RATE_LIMITED', `retry in ${retryAfter}ms`) // …or
+  return rateLimitResponse({ limit: 100, remaining, reset: 0, retryAfter }) // a ready-made 429
+}
+
+await lim.reset(userId) // clear a key
+```
+
+- `limiter(opts)` → `{ check(key, now?), reset(key), rule }` — the actual limiting
+  (pluggable store + algorithm), no HTTP involved.
+- `rateLimitResponse(info, opts?)` → a `Response` (status/message/headers), if you
+  want one.
+
+`rateLimit.server()` === `limiter()` + `rateLimitResponse()` + key/skip/requires wiring.
+
+## Rate-limited doer (for `@ayepi/work`)
+
+`rateLimitedDoer` is a [`Doer`](https://www.npmjs.com/package/@ayepi/core) (from
+`@ayepi/core/doer`) that caps the **start rate** of tasks through the same `limiter()`
+primitive — so an `@ayepi/work` engine processes work no faster than a budget allows.
+It also stays on the main `@ayepi/rate` entry. Excess tasks wait, oldest-first, and a
+distributed store 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 })   // ≤ 100 sends/min
+```
+
+## Algorithms
+
+- `fixed-window` (default) — simple counter per window.
+- `sliding-window` — weights the previous window for a smoother limit.
+- `token-bucket` — steady rate with bursts up to `limit`.
+
+## Stores (cross-instance)
+
+The default store is in-memory (single process). To limit across pods, use the
+Redis store (each algorithm runs as one atomic Lua script). The store is a `.server`
+option:
+
+```ts
+import Redis from 'ioredis'
+import { rateLimit } from '@ayepi/rate/server'
+import { redisStore } from '@ayepi/rate/redis'
+
+rateLimit.server(limit, {
+  key: (io) => io.ctx.user.id, limit: 100, window: 60_000, store: redisStore(new Redis(url)),
+})
+```
+
+Implement the `RateLimitStore` interface for any other backend.
+
+## Customizing the response
+
+All of these are `.server` options:
+
+```ts
+rateLimit.server(limit, {
+  key: (io) => clientIp(io.req),
+  limit: 20,
+  window: 1000,
+  status: 429,                                   // default 429
+  message: (info) => ({ error: 'slow down', retryAfter: info.retryAfter }), // string | JSON | fn
+  headers: true,        // draft RateLimit-* (+ Retry-After when blocked); false to omit; or a fn for custom headers
+  alwaysHeaders: true,  // also set RateLimit-* on allowed responses (default false)
+  countRejected: false, // default: an over-limit request doesn't count against the limit
+  skip: (io) => io.req.headers.get('x-admin') === '1',
+})
+```
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-rate-stores-doer.md`](./ayepi-rate-stores-doer.md)
+- [`ayepi-rate.md`](./ayepi-rate.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/rate) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/index.cjs

@@ -0,0 +1,337 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _ayepi_core = require("@ayepi/core");
+let _ayepi_core_doer = require("@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 (0, _ayepi_core.middleware)(opts?.name ?? "rateLimit", {
+		provides: (0, _ayepi_core.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 ?? (0, _ayepi_core_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
+exports.limiter = limiter;
+exports.memoryStore = memoryStore;
+exports.rateLimit = rateLimit;
+exports.rateLimitHeaders = rateLimitHeaders;
+exports.rateLimitResponse = rateLimitResponse;
+exports.rateLimitedDoer = rateLimitedDoer;