@alxia/rate-limit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @alxia/rate-limit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rate limiting for [alxia](https://www.npmjs.com/package/@alxia/core), typed:
+the 429 is part of every route behind the limit, so
+[`@alxia/client`](https://www.npmjs.com/package/@alxia/client) reads it. No
+dependency.
+
+```sh
+bun add @alxia/rate-limit @alxia/core
+bun add -d typescript
+```
+
+## Usage
+
+```ts
+import { rateLimit } from '@alxia/rate-limit';
+
+const app = alxia()
+	.get('/health', ...)                                  // not limited
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }))
+	.get('/search', ({ rateLimit, reply }) => ...);      // limited; rateLimit.remaining
+
+const result = await api.get('/search');
+if (result.status === 429) result.data.retryAfter;      // seconds
+```
+
+Past the limit, a 429 with `Retry-After` and
+`{ error: 'rate_limited', retryAfter }`. Every counted response carries the
+IETF draft's `RateLimit-Limit`, `-Remaining`, `-Reset` and `-Policy`.
+
+## Options
+
+| option | default | |
+| --- | --- | --- |
+| `limit` | required | requests per window: a whole number, 1 or more |
+| `windowMs` | required | the window, in milliseconds: a whole number, 1 or more |
+| `key` | the client's address | what is counted: `(ctx) => string \| undefined`; `undefined` is not counted. `rateLimit<{ user: User }>(…)` lets it read a `user` an earlier plugin adds |
+| `store` | `MemoryStore` | where: `redisStore` from `@alxia/redis`, or your own `RateLimitStore` |
+| `skip` | none | requests not counted |
+| `headers` | `'draft'` | `'legacy'` for `X-RateLimit-*`, or `false` |
+
+Behind a proxy, give the app an `ip` option that reads the header it sets:
+`alxia({ ip: (request) => request.headers.get('x-real-ip') ?? undefined })`.
+
+## Across processes
+
+`MemoryStore` counts in one process. Behind a load balancer, give every
+process the same store: [`@alxia/redis`](https://www.npmjs.com/package/@alxia/redis)'s
+`redisStore` counts in Redis, with GCRA timed by the Redis server's clock.
+
+```ts
+import { redisStore } from '@alxia/redis';
+
+app.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(redis, { name: 'api' }) }));
+```
+
+A store of your own implements `RateLimitStore`: `consume(key, { limit,
+windowMs })` decides — `allowed`, `remaining`, `resetAfter` and
+`retryAfter`, delays in milliseconds — and a refused request counts
+nothing.
+
+## API
+
+| export | |
+| --- | --- |
+| `rateLimit(options)` | the plugin: an app that derives `rateLimit` |
+| `MemoryStore` | a fixed window in one process's memory |
+| `RateLimitStore`, `Decision`, `Policy` | a store's contract |
+| `RateLimitedBody`, `RateLimitInfo`, `RateLimitOptions` | its types |
+
+## Documentation
+
+- [Guide](https://github.com/softistx/alxia/tree/develop/packages/rate-limit/docs): the options and their defaults, which requests are counted, the headers, the 429 on the client, stores, and testing.
+- [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/rate-limit/docs/troubleshooting.md): an error message, and what to do about it.
+- [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/rate-limit/docs/roadmap.md): what is coming, and what is not planned.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type RateLimitedBody, type RateLimitInfo, type RateLimitOptions, rateLimit, } from './rate-limit';
+export { type Decision, MemoryStore, type Policy, type RateLimitStore, } from './store';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,SAAS,GACT,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,KAAK,QAAQ,EACb,WAAW,EACX,KAAK,MAAM,EACX,KAAK,cAAc,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,110 @@
+// src/rate-limit.ts
+import { definePlugin } from "@alxia/core";
+
+// src/store.ts
+class MemoryStore {
+  #hits = new Map;
+  #sweeper;
+  consume(key, policy) {
+    const now = Date.now();
+    let entry = this.#hits.get(key);
+    if (entry === undefined || entry.resetAt <= now) {
+      entry = { count: 0, resetAt: now + policy.windowMs };
+      this.#hits.set(key, entry);
+    }
+    this.#sweep(policy.windowMs);
+    const resetAfter = entry.resetAt - now;
+    if (entry.count >= policy.limit) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetAfter,
+        retryAfter: resetAfter
+      };
+    }
+    entry.count++;
+    return {
+      allowed: true,
+      remaining: policy.limit - entry.count,
+      resetAfter,
+      retryAfter: 0
+    };
+  }
+  reset(key) {
+    this.#hits.delete(key);
+  }
+  get size() {
+    return this.#hits.size;
+  }
+  #sweep(windowMs) {
+    if (this.#sweeper !== undefined)
+      return;
+    this.#sweeper = setInterval(() => {
+      const now = Date.now();
+      for (const [key, entry] of this.#hits) {
+        if (entry.resetAt <= now)
+          this.#hits.delete(key);
+      }
+      if (this.#hits.size === 0) {
+        clearInterval(this.#sweeper);
+        this.#sweeper = undefined;
+      }
+    }, windowMs);
+    this.#sweeper.unref?.();
+  }
+}
+
+// src/rate-limit.ts
+function rateLimit(options) {
+  for (const name of ["limit", "windowMs"]) {
+    const value = options[name];
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new TypeError(`rateLimit: ${name} must be a whole number of 1 or more, not ${String(value)}`);
+    }
+  }
+  const store = options.store ?? new MemoryStore;
+  const key = options.key ?? ((ctx) => ctx.ip);
+  const style = options.headers ?? "draft";
+  return definePlugin()((app) => app.derive(async (ctx) => {
+    const counted = options.skip?.(ctx) ? undefined : await key(ctx);
+    if (counted === undefined) {
+      const rateLimit = undefined;
+      return { rateLimit };
+    }
+    const decision = await store.consume(counted, {
+      limit: options.limit,
+      windowMs: options.windowMs
+    });
+    const reset = Math.ceil(decision.resetAfter / 1000);
+    if (style === "draft") {
+      ctx.set.headers.set("ratelimit-limit", String(options.limit));
+      ctx.set.headers.set("ratelimit-remaining", String(decision.remaining));
+      ctx.set.headers.set("ratelimit-reset", String(reset));
+      ctx.set.headers.set("ratelimit-policy", `${options.limit};w=${Math.ceil(options.windowMs / 1000)}`);
+    } else if (style === "legacy") {
+      ctx.set.headers.set("x-ratelimit-limit", String(options.limit));
+      ctx.set.headers.set("x-ratelimit-remaining", String(decision.remaining));
+      ctx.set.headers.set("x-ratelimit-reset", String(Math.ceil((Date.now() + decision.resetAfter) / 1000)));
+    }
+    if (!decision.allowed) {
+      const retryAfter = Math.max(1, Math.ceil(decision.retryAfter / 1000));
+      const body = { error: "rate_limited", retryAfter };
+      return ctx.reply(429, body, {
+        headers: { "retry-after": String(retryAfter) }
+      });
+    }
+    const rateLimit = {
+      limit: options.limit,
+      remaining: decision.remaining,
+      resetAfter: decision.resetAfter
+    };
+    return { rateLimit };
+  }));
+}
+export {
+  MemoryStore,
+  rateLimit
+};
+
+//# debugId=1917CEB5F68549FD64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/rate-limit.ts", "../src/store.ts"],
+  "sourcesContent": [
+    "import { type BaseContext, definePlugin, type Empty } from '@alxia/core';\nimport { MemoryStore, type RateLimitStore } from './store';\n\n/**\n * `Requires` is what `key` and `skip` read from the context beyond\n * `BaseContext` — a `user` an earlier plugin adds — and what the app that\n * uses the limit must then give.\n */\nexport interface RateLimitOptions<Requires extends object = Empty> {\n\t/** How many requests a key may make in a window: a whole number, 1 or more. */\n\treadonly limit: number;\n\t/** The window, in milliseconds: a whole number, 1 or more. */\n\treadonly windowMs: number;\n\t/** What is counted: the client's address by default. `undefined` is not counted. */\n\treadonly key?: (\n\t\tctx: BaseContext & Requires,\n\t) => string | undefined | Promise<string | undefined>;\n\t/** Where it is counted: one process's memory by default. */\n\treadonly store?: RateLimitStore;\n\t/** Requests not counted at all. */\n\treadonly skip?: (ctx: BaseContext & Requires) => boolean;\n\t/**\n\t * The `RateLimit` headers of the IETF draft on every counted response,\n\t * `X-RateLimit-*` with `legacy`, or none. `draft` by default.\n\t */\n\treadonly headers?: 'draft' | 'legacy' | false;\n}\n\n/** The body of the 429. */\nexport interface RateLimitedBody {\n\treadonly error: 'rate_limited';\n\t/** Seconds until the window ends. */\n\treadonly retryAfter: number;\n}\n\n/** What the routes behind the limit read: where the key stands. */\nexport interface RateLimitInfo {\n\treadonly limit: number;\n\treadonly remaining: number;\n\t/** Milliseconds until the allowance is whole again. */\n\treadonly resetAfter: number;\n}\n\n/**\n * A rate limit, as a plugin: every route declared after it counts its\n * requests, and answers a 429 past the limit. The 429 is part of each such\n * route's type, so the client reads it.\n *\n * ```ts\n * app.use(rateLimit({ limit: 100, windowMs: 60_000 })).get(...);\n * ```\n *\n * A `key` that reads what an earlier plugin added names it, and the app\n * must then give it: `rateLimit<{ user: User }>({ key: ({ user }) => user.id, … })`.\n */\nexport function rateLimit<Requires extends object = Empty>(\n\toptions: RateLimitOptions<Requires>,\n) {\n\tfor (const name of ['limit', 'windowMs'] as const) {\n\t\tconst value = options[name];\n\t\tif (!Number.isSafeInteger(value) || value < 1) {\n\t\t\t// 0 refuses every request; a window of 0 or less never ends one.\n\t\t\tthrow new TypeError(\n\t\t\t\t`rateLimit: ${name} must be a whole number of 1 or more, not ${String(value)}`,\n\t\t\t);\n\t\t}\n\t}\n\tconst store = options.store ?? new MemoryStore();\n\tconst key = options.key ?? ((ctx: BaseContext & Requires) => ctx.ip);\n\tconst style = options.headers ?? 'draft';\n\treturn definePlugin<Requires>()((app) =>\n\t\tapp.derive(async (ctx) => {\n\t\t\tconst counted = options.skip?.(ctx) ? undefined : await key(ctx);\n\t\t\tif (counted === undefined) {\n\t\t\t\tconst rateLimit: RateLimitInfo | undefined = undefined;\n\t\t\t\treturn { rateLimit };\n\t\t\t}\n\t\t\tconst decision = await store.consume(counted, {\n\t\t\t\tlimit: options.limit,\n\t\t\t\twindowMs: options.windowMs,\n\t\t\t});\n\t\t\tconst reset = Math.ceil(decision.resetAfter / 1000);\n\t\t\tif (style === 'draft') {\n\t\t\t\tctx.set.headers.set('ratelimit-limit', String(options.limit));\n\t\t\t\tctx.set.headers.set('ratelimit-remaining', String(decision.remaining));\n\t\t\t\tctx.set.headers.set('ratelimit-reset', String(reset));\n\t\t\t\tctx.set.headers.set(\n\t\t\t\t\t'ratelimit-policy',\n\t\t\t\t\t`${options.limit};w=${Math.ceil(options.windowMs / 1000)}`,\n\t\t\t\t);\n\t\t\t} else if (style === 'legacy') {\n\t\t\t\tctx.set.headers.set('x-ratelimit-limit', String(options.limit));\n\t\t\t\tctx.set.headers.set(\n\t\t\t\t\t'x-ratelimit-remaining',\n\t\t\t\t\tString(decision.remaining),\n\t\t\t\t);\n\t\t\t\tctx.set.headers.set(\n\t\t\t\t\t'x-ratelimit-reset',\n\t\t\t\t\tString(Math.ceil((Date.now() + decision.resetAfter) / 1000)),\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (!decision.allowed) {\n\t\t\t\tconst retryAfter = Math.max(1, Math.ceil(decision.retryAfter / 1000));\n\t\t\t\tconst body: RateLimitedBody = { error: 'rate_limited', retryAfter };\n\t\t\t\treturn ctx.reply(429, body, {\n\t\t\t\t\theaders: { 'retry-after': String(retryAfter) },\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst rateLimit: RateLimitInfo | undefined = {\n\t\t\t\tlimit: options.limit,\n\t\t\t\tremaining: decision.remaining,\n\t\t\t\tresetAfter: decision.resetAfter,\n\t\t\t};\n\t\t\treturn { rateLimit };\n\t\t}),\n\t);\n}\n",
+    "/** What a store decides for one request. Every duration is a delay, in milliseconds. */\nexport interface Decision {\n\treadonly allowed: boolean;\n\t/** Requests the key may still make now, after this one. */\n\treadonly remaining: number;\n\t/** Until the key's allowance is whole again. */\n\treadonly resetAfter: number;\n\t/** Until a refused request would be allowed; 0 when this one is. */\n\treadonly retryAfter: number;\n}\n\n/** The policy a store applies: `limit` requests per `windowMs`. */\nexport interface Policy {\n\treadonly limit: number;\n\treadonly windowMs: number;\n}\n\n/**\n * Where requests are counted, and what decides. The memory store counts in\n * one process with a fixed window; `@alxia/redis`'s counts across every\n * process sharing a Redis, with GCRA.\n */\nexport interface RateLimitStore {\n\t/** Counts one request for `key` under `policy`; a refused one counts nothing. */\n\tconsume(key: string, policy: Policy): Decision | Promise<Decision>;\n\t/** Forgets `key`: a user who just logged in. */\n\treset(key: string): void | Promise<void>;\n}\n\n/** A fixed-window counter in memory, swept as windows end. */\nexport class MemoryStore implements RateLimitStore {\n\treadonly #hits = new Map<string, { count: number; resetAt: number }>();\n\t#sweeper: ReturnType<typeof setInterval> | undefined;\n\n\tconsume(key: string, policy: Policy): Decision {\n\t\tconst now = Date.now();\n\t\tlet entry = this.#hits.get(key);\n\t\tif (entry === undefined || entry.resetAt <= now) {\n\t\t\tentry = { count: 0, resetAt: now + policy.windowMs };\n\t\t\tthis.#hits.set(key, entry);\n\t\t}\n\t\tthis.#sweep(policy.windowMs);\n\t\tconst resetAfter = entry.resetAt - now;\n\t\tif (entry.count >= policy.limit) {\n\t\t\treturn {\n\t\t\t\tallowed: false,\n\t\t\t\tremaining: 0,\n\t\t\t\tresetAfter,\n\t\t\t\tretryAfter: resetAfter,\n\t\t\t};\n\t\t}\n\t\tentry.count++;\n\t\treturn {\n\t\t\tallowed: true,\n\t\t\tremaining: policy.limit - entry.count,\n\t\t\tresetAfter,\n\t\t\tretryAfter: 0,\n\t\t};\n\t}\n\n\treset(key: string): void {\n\t\tthis.#hits.delete(key);\n\t}\n\n\t/** How many keys are counted. */\n\tget size(): number {\n\t\treturn this.#hits.size;\n\t}\n\n\t#sweep(windowMs: number): void {\n\t\tif (this.#sweeper !== undefined) return;\n\t\tthis.#sweeper = setInterval(() => {\n\t\t\tconst now = Date.now();\n\t\t\tfor (const [key, entry] of this.#hits) {\n\t\t\t\tif (entry.resetAt <= now) this.#hits.delete(key);\n\t\t\t}\n\t\t\tif (this.#hits.size === 0) {\n\t\t\t\tclearInterval(this.#sweeper);\n\t\t\t\tthis.#sweeper = undefined;\n\t\t\t}\n\t\t}, windowMs);\n\t\tthis.#sweeper.unref?.();\n\t}\n}\n"
+  ],
+  "mappings": ";AAAA;;;AC8BO,MAAM,YAAsC;AAAA,EACzC,QAAQ,IAAI;AAAA,EACrB;AAAA,EAEA,OAAO,CAAC,KAAa,QAA0B;AAAA,IAC9C,MAAM,MAAM,KAAK,IAAI;AAAA,IACrB,IAAI,QAAQ,KAAK,MAAM,IAAI,GAAG;AAAA,IAC9B,IAAI,UAAU,aAAa,MAAM,WAAW,KAAK;AAAA,MAChD,QAAQ,EAAE,OAAO,GAAG,SAAS,MAAM,OAAO,SAAS;AAAA,MACnD,KAAK,MAAM,IAAI,KAAK,KAAK;AAAA,IAC1B;AAAA,IACA,KAAK,OAAO,OAAO,QAAQ;AAAA,IAC3B,MAAM,aAAa,MAAM,UAAU;AAAA,IACnC,IAAI,MAAM,SAAS,OAAO,OAAO;AAAA,MAChC,OAAO;AAAA,QACN,SAAS;AAAA,QACT,WAAW;AAAA,QACX;AAAA,QACA,YAAY;AAAA,MACb;AAAA,IACD;AAAA,IACA,MAAM;AAAA,IACN,OAAO;AAAA,MACN,SAAS;AAAA,MACT,WAAW,OAAO,QAAQ,MAAM;AAAA,MAChC;AAAA,MACA,YAAY;AAAA,IACb;AAAA;AAAA,EAGD,KAAK,CAAC,KAAmB;AAAA,IACxB,KAAK,MAAM,OAAO,GAAG;AAAA;AAAA,MAIlB,IAAI,GAAW;AAAA,IAClB,OAAO,KAAK,MAAM;AAAA;AAAA,EAGnB,MAAM,CAAC,UAAwB;AAAA,IAC9B,IAAI,KAAK,aAAa;AAAA,MAAW;AAAA,IACjC,KAAK,WAAW,YAAY,MAAM;AAAA,MACjC,MAAM,MAAM,KAAK,IAAI;AAAA,MACrB,YAAY,KAAK,UAAU,KAAK,OAAO;AAAA,QACtC,IAAI,MAAM,WAAW;AAAA,UAAK,KAAK,MAAM,OAAO,GAAG;AAAA,MAChD;AAAA,MACA,IAAI,KAAK,MAAM,SAAS,GAAG;AAAA,QAC1B,cAAc,KAAK,QAAQ;AAAA,QAC3B,KAAK,WAAW;AAAA,MACjB;AAAA,OACE,QAAQ;AAAA,IACX,KAAK,SAAS,QAAQ;AAAA;AAExB;;;AD5BO,SAAS,SAA0C,CACzD,SACC;AAAA,EACD,WAAW,QAAQ,CAAC,SAAS,UAAU,GAAY;AAAA,IAClD,MAAM,QAAQ,QAAQ;AAAA,IACtB,IAAI,CAAC,OAAO,cAAc,KAAK,KAAK,QAAQ,GAAG;AAAA,MAE9C,MAAM,IAAI,UACT,cAAc,iDAAiD,OAAO,KAAK,GAC5E;AAAA,IACD;AAAA,EACD;AAAA,EACA,MAAM,QAAQ,QAAQ,SAAS,IAAI;AAAA,EACnC,MAAM,MAAM,QAAQ,QAAQ,CAAC,QAAgC,IAAI;AAAA,EACjE,MAAM,QAAQ,QAAQ,WAAW;AAAA,EACjC,OAAO,aAAuB,EAAE,CAAC,QAChC,IAAI,OAAO,OAAO,QAAQ;AAAA,IACzB,MAAM,UAAU,QAAQ,OAAO,GAAG,IAAI,YAAY,MAAM,IAAI,GAAG;AAAA,IAC/D,IAAI,YAAY,WAAW;AAAA,MAC1B,MAAM,YAAuC;AAAA,MAC7C,OAAO,EAAE,UAAU;AAAA,IACpB;AAAA,IACA,MAAM,WAAW,MAAM,MAAM,QAAQ,SAAS;AAAA,MAC7C,OAAO,QAAQ;AAAA,MACf,UAAU,QAAQ;AAAA,IACnB,CAAC;AAAA,IACD,MAAM,QAAQ,KAAK,KAAK,SAAS,aAAa,IAAI;AAAA,IAClD,IAAI,UAAU,SAAS;AAAA,MACtB,IAAI,IAAI,QAAQ,IAAI,mBAAmB,OAAO,QAAQ,KAAK,CAAC;AAAA,MAC5D,IAAI,IAAI,QAAQ,IAAI,uBAAuB,OAAO,SAAS,SAAS,CAAC;AAAA,MACrE,IAAI,IAAI,QAAQ,IAAI,mBAAmB,OAAO,KAAK,CAAC;AAAA,MACpD,IAAI,IAAI,QAAQ,IACf,oBACA,GAAG,QAAQ,WAAW,KAAK,KAAK,QAAQ,WAAW,IAAI,GACxD;AAAA,IACD,EAAO,SAAI,UAAU,UAAU;AAAA,MAC9B,IAAI,IAAI,QAAQ,IAAI,qBAAqB,OAAO,QAAQ,KAAK,CAAC;AAAA,MAC9D,IAAI,IAAI,QAAQ,IACf,yBACA,OAAO,SAAS,SAAS,CAC1B;AAAA,MACA,IAAI,IAAI,QAAQ,IACf,qBACA,OAAO,KAAK,MAAM,KAAK,IAAI,IAAI,SAAS,cAAc,IAAI,CAAC,CAC5D;AAAA,IACD;AAAA,IACA,IAAI,CAAC,SAAS,SAAS;AAAA,MACtB,MAAM,aAAa,KAAK,IAAI,GAAG,KAAK,KAAK,SAAS,aAAa,IAAI,CAAC;AAAA,MACpE,MAAM,OAAwB,EAAE,OAAO,gBAAgB,WAAW;AAAA,MAClE,OAAO,IAAI,MAAM,KAAK,MAAM;AAAA,QAC3B,SAAS,EAAE,eAAe,OAAO,UAAU,EAAE;AAAA,MAC9C,CAAC;AAAA,IACF;AAAA,IACA,MAAM,YAAuC;AAAA,MAC5C,OAAO,QAAQ;AAAA,MACf,WAAW,SAAS;AAAA,MACpB,YAAY,SAAS;AAAA,IACtB;AAAA,IACA,OAAO,EAAE,UAAU;AAAA,GACnB,CACF;AAAA;",
+  "debugId": "1917CEB5F68549FD64756E2164756E21",
+  "names": []
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,55 @@
+import { type BaseContext, type Empty } from '@alxia/core';
+import { type RateLimitStore } from './store';
+/**
+ * `Requires` is what `key` and `skip` read from the context beyond
+ * `BaseContext` — a `user` an earlier plugin adds — and what the app that
+ * uses the limit must then give.
+ */
+export interface RateLimitOptions<Requires extends object = Empty> {
+    /** How many requests a key may make in a window: a whole number, 1 or more. */
+    readonly limit: number;
+    /** The window, in milliseconds: a whole number, 1 or more. */
+    readonly windowMs: number;
+    /** What is counted: the client's address by default. `undefined` is not counted. */
+    readonly key?: (ctx: BaseContext & Requires) => string | undefined | Promise<string | undefined>;
+    /** Where it is counted: one process's memory by default. */
+    readonly store?: RateLimitStore;
+    /** Requests not counted at all. */
+    readonly skip?: (ctx: BaseContext & Requires) => boolean;
+    /**
+     * The `RateLimit` headers of the IETF draft on every counted response,
+     * `X-RateLimit-*` with `legacy`, or none. `draft` by default.
+     */
+    readonly headers?: 'draft' | 'legacy' | false;
+}
+/** The body of the 429. */
+export interface RateLimitedBody {
+    readonly error: 'rate_limited';
+    /** Seconds until the window ends. */
+    readonly retryAfter: number;
+}
+/** What the routes behind the limit read: where the key stands. */
+export interface RateLimitInfo {
+    readonly limit: number;
+    readonly remaining: number;
+    /** Milliseconds until the allowance is whole again. */
+    readonly resetAfter: number;
+}
+/**
+ * A rate limit, as a plugin: every route declared after it counts its
+ * requests, and answers a 429 past the limit. The 429 is part of each such
+ * route's type, so the client reads it.
+ *
+ * ```ts
+ * app.use(rateLimit({ limit: 100, windowMs: 60_000 })).get(...);
+ * ```
+ *
+ * A `key` that reads what an earlier plugin added names it, and the app
+ * must then give it: `rateLimit<{ user: User }>({ key: ({ user }) => user.id, … })`.
+ */
+export declare function rateLimit<Requires extends object = Empty>(options: RateLimitOptions<Requires>): import("@alxia/core").Alxia<Requires & ({
+    rateLimit: undefined;
+} | {
+    rateLimit: RateLimitInfo;
+}), Empty, "", import("@alxia/core").Reply<429, RateLimitedBody>> & import("@alxia/core").Requiring<Requires>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,SAAS,MAAM,GAAG,KAAK;IAChE,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,GAAG,CAAC,EAAE,CACd,GAAG,EAAE,WAAW,GAAG,QAAQ,KACvB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,QAAQ,KAAK,OAAO,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;CAC9C;AAED,2BAA2B;AAC3B,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,QAAQ,SAAS,MAAM,GAAG,KAAK,EACxD,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC;;;;8GA4DnC"}

package/dist/store.d.ts

@@ -0,0 +1,35 @@
+/** What a store decides for one request. Every duration is a delay, in milliseconds. */
+export interface Decision {
+    readonly allowed: boolean;
+    /** Requests the key may still make now, after this one. */
+    readonly remaining: number;
+    /** Until the key's allowance is whole again. */
+    readonly resetAfter: number;
+    /** Until a refused request would be allowed; 0 when this one is. */
+    readonly retryAfter: number;
+}
+/** The policy a store applies: `limit` requests per `windowMs`. */
+export interface Policy {
+    readonly limit: number;
+    readonly windowMs: number;
+}
+/**
+ * Where requests are counted, and what decides. The memory store counts in
+ * one process with a fixed window; `@alxia/redis`'s counts across every
+ * process sharing a Redis, with GCRA.
+ */
+export interface RateLimitStore {
+    /** Counts one request for `key` under `policy`; a refused one counts nothing. */
+    consume(key: string, policy: Policy): Decision | Promise<Decision>;
+    /** Forgets `key`: a user who just logged in. */
+    reset(key: string): void | Promise<void>;
+}
+/** A fixed-window counter in memory, swept as windows end. */
+export declare class MemoryStore implements RateLimitStore {
+    #private;
+    consume(key: string, policy: Policy): Decision;
+    reset(key: string): void;
+    /** How many keys are counted. */
+    get size(): number;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,mEAAmE;AACnE,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,iFAAiF;IACjF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnE,gDAAgD;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,8DAA8D;AAC9D,qBAAa,WAAY,YAAW,cAAc;;IAIjD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ;IA0B9C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB,iCAAiC;IACjC,IAAI,IAAI,IAAI,MAAM,CAEjB;CAgBD"}

package/docs/README.md

@@ -0,0 +1,11 @@
+# @alxia/rate-limit documentation
+
+The [package README](../README.md) is the short version. This folder is
+the long one: the options, defaults and behaviours with an example each,
+the errors you may meet, and what is coming.
+
+| Page | Read it when |
+| --- | --- |
+| [Guide](guide.md) | choosing what to count and where, reading the 429 on the client, keeping counts across processes, or testing a limit |
+| [Troubleshooting](troubleshooting.md) | something went wrong and you have the message, or a limit does not count as you expected |
+| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide.md

@@ -0,0 +1,421 @@
+# Guide
+
+This page covers everything `rateLimit` does: which requests it counts, what
+it answers past the limit, the headers it sets, what a route and a client
+read, and where the counts are kept.
+
+```ts
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+
+const app = alxia()
+	.get('/health', ({ reply }) => reply(200, 'ok'))      // not limited
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }))
+	.get('/search', ({ rateLimit, reply }) =>             // limited
+		reply(200, { remaining: rateLimit?.remaining }),
+	);
+
+app.listen({ port: 3000 });
+// the 101st GET /search from one address within a minute
+// → 429 {"error":"rate_limited","retryAfter":…}
+```
+
+## The signature
+
+```ts
+function rateLimit<Requires extends object = Empty>(
+	options: RateLimitOptions<Requires>,
+): Alxia<…> & Requiring<Requires>; // an app, given to `use`, which checks `Requires`
+
+interface RateLimitOptions<Requires extends object = Empty> {
+	readonly limit: number;
+	readonly windowMs: number;
+	readonly key?: (ctx: BaseContext & Requires) => string | undefined | Promise<string | undefined>;
+	readonly store?: RateLimitStore;
+	readonly skip?: (ctx: BaseContext & Requires) => boolean;
+	readonly headers?: 'draft' | 'legacy' | false;
+}
+```
+
+`rateLimit` returns an app whose single route hook counts the request. Given
+to `use`, it adds `rateLimit` to the context of every route declared after
+it, and its 429 to each of those routes' types. `Requires` is what `key`
+and `skip` read beyond `BaseContext`; see [Reading the app's context](#reading-the-apps-context).
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `limit` | `number` | required | requests one key may make in a window: a whole number, 1 or more |
+| `windowMs` | `number` | required | the window, in milliseconds: a whole number, 1 or more |
+| `key` | `(ctx: BaseContext & Requires) => string \| undefined \| Promise<…>` | `ctx.ip` | what is counted; `undefined` is not counted |
+| `store` | `RateLimitStore` | a new `MemoryStore` | where the counts are kept |
+| `skip` | `(ctx: BaseContext & Requires) => boolean` | none | requests not counted at all |
+| `headers` | `'draft' \| 'legacy' \| false` | `'draft'` | which rate-limit headers each counted response carries |
+
+A `limit` or a `windowMs` that is not a whole number of 1 or more makes
+`rateLimit()` throw a `TypeError` when it is called, so the app fails at
+startup ([troubleshooting](troubleshooting.md#typeerror-ratelimit--must-be-a-whole-number-of-1-or-more-not-)).
+
+A store may refuse larger values than `rateLimit` does: `redisStore`
+refuses a `limit × windowMs` above 9,007,199,254,740 and a `windowMs`
+above ten 365-day years (315,360,000,000), on the first request it counts rather than at startup
+([`@alxia/redis`: Policies Redis refuses](https://github.com/softistx/alxia/blob/develop/packages/redis/docs/guide/rate-limits.md#policies-redis-refuses)).
+
+### `key`
+
+By default a limit counts per client address, `ctx.ip`, which is what the
+app's [`ip` option](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#the-clients-address-ip)
+reads. Behind a proxy, that is the proxy's address unless you set `ip`:
+
+```ts
+const app = alxia({
+	ip: (request, server) =>
+		request.headers.get('x-real-ip') ?? server?.requestIP(request)?.address,
+}).use(rateLimit({ limit: 100, windowMs: 60_000 }));
+```
+
+Count by something else — an API key, a token — by returning it from `key`.
+It may be async. A request whose key is `undefined` is not counted: it passes,
+gets no rate-limit header, and its route reads `rateLimit` as `undefined`.
+
+```ts
+app.use(
+	rateLimit({
+		limit: 1_000,
+		windowMs: 60 * 60_000,
+		key: ({ request }) => request.headers.get('x-api-key') ?? undefined, // no key: not counted
+	}),
+);
+```
+
+`key` is typed with `BaseContext`, what every route hook reads: the request,
+`url`, `ip`, `server`, `route` and `pathParams`, and with `Requires`, empty
+by default. To read what an earlier plugin added, see [Reading the app's
+context](#reading-the-apps-context).
+
+### `skip`
+
+A request `skip` returns `true` for is not counted, exactly like one whose
+key is `undefined`. It is synchronous.
+
+```ts
+app.use(
+	rateLimit({
+		limit: 100,
+		windowMs: 60_000,
+		skip: ({ ip }) => ip === '127.0.0.1', // the local health checker
+	}),
+);
+```
+
+### Reading the app's context
+
+To count by what an earlier plugin added, such as a signed-in `user`, name
+it as `rateLimit`'s type argument. `key` and `skip` then read it, and the
+limit is a [`definePlugin`](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/writing-a-plugin.md#a-plugin-that-needs-an-earlier-one)
+plugin: an app that does not give `user` before it cannot use it.
+
+```ts
+const perUser = rateLimit<{ user: { id: string; role: string } }>({
+	limit: 100,
+	windowMs: 60_000,
+	key: ({ user }) => user.id,
+	skip: ({ user }) => user.role === 'admin',
+});
+
+const app = alxia()
+	.use(auth) // derives user, or answers 401
+	.use(perUser)
+	.get('/search', handler);
+
+alxia().use(perUser);
+// error: the plugin reads "user", which this app's context does not give: use the plugin that adds it first
+```
+
+### `headers`
+
+Every counted response — the route's own and the 429 alike — carries the
+headers of the style you choose:
+
+| `headers` | Sent | Values |
+| --- | --- | --- |
+| `'draft'` (default) | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy` | the limit; what is left; seconds until the allowance is whole again; `<limit>;w=<window in seconds>` |
+| `'legacy'` | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` | the limit; what is left; the Unix time, in seconds, at which the allowance is whole again |
+| `false` | none | — |
+
+With `limit: 1, windowMs: 60_000`, the first request answers:
+
+```text
+ratelimit-limit: 1
+ratelimit-remaining: 0
+ratelimit-reset: 60
+ratelimit-policy: 1;w=60
+```
+
+The 429 carries `Retry-After` whatever `headers` says.
+
+### `store`
+
+Each `rateLimit` call without a `store` creates its own `MemoryStore`: the
+counts live in that process and are lost when it stops. See
+[Stores](#stores) for sharing them across processes, and for resetting a key.
+
+## Which requests are counted
+
+The limit is a route hook, so order decides, at runtime and in the types:
+
+- a route declared **before** `use(rateLimit(…))` is not counted, and its
+  type has no 429;
+- a route declared **after** it is counted, and may answer the 429;
+- inside a [group](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/groups-and-plugins.md#groups),
+  the limit stays in the group.
+
+```ts
+const app = alxia()
+	.get('/health', ({ reply }) => reply(200, 'ok'))                 // never counted
+	.group('/auth', (auth) =>
+		auth
+			.use(rateLimit({ limit: 5, windowMs: 15 * 60_000 }))         // 5 per 15 minutes
+			.post('/login', ({ reply }) => reply(200, 'ok')),
+	)
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }))               // 100 per minute
+	.get('/search', ({ reply }) => reply(200, []));                  // the group's limit does not reach it
+```
+
+Route hooks run before the request is validated: a request the route
+refuses with a 400 has already been counted. A request that matches no route
+(a 404) never reaches the hook, and is not counted.
+
+Two limits on the same routes both count, and either may answer the 429 —
+a burst limit and an hourly one, say. Each sets its own headers on the
+response, so with two `'draft'` limits the later one's values win; give the
+other `headers: false`. A route reads the `rateLimit` of the later one.
+
+```ts
+app
+	.use(rateLimit({ limit: 10, windowMs: 1_000 }))                      // a burst
+	.use(rateLimit({ limit: 1_000, windowMs: 60 * 60_000, headers: false })) // an hour
+	.get('/search', ({ rateLimit, reply }) => reply(200, rateLimit ?? null)); // the hourly limit's info
+```
+
+## What a route reads
+
+Every route after the limit reads `ctx.rateLimit`:
+
+```ts
+interface RateLimitInfo {
+	readonly limit: number;
+	readonly remaining: number;   // after this request
+	readonly resetAfter: number;  // milliseconds until the allowance is whole again
+}
+```
+
+It is `RateLimitInfo | undefined`: `undefined` when the request was not
+counted, by `skip` or an `undefined` key.
+
+```ts
+app
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }))
+	.get('/quota', ({ rateLimit, reply }) =>
+		rateLimit === undefined
+			? reply(200, { limited: false as const })
+			: reply(200, { limited: true as const, remaining: rateLimit.remaining }),
+	);
+```
+
+## The 429
+
+Past the limit the hook ends the request before the route runs:
+
+```text
+HTTP/1.1 429 Too Many Requests
+retry-after: 60
+ratelimit-limit: 100
+ratelimit-remaining: 0
+ratelimit-reset: 60
+ratelimit-policy: 100;w=60
+
+{"error":"rate_limited","retryAfter":60}
+```
+
+```ts
+interface RateLimitedBody {
+	readonly error: 'rate_limited';
+	readonly retryAfter: number; // seconds until a request would be allowed, at least 1
+}
+```
+
+`retryAfter` and `Retry-After` are the same number. A refused request
+counts nothing: retrying after `retryAfter` seconds succeeds.
+
+## On the client
+
+[`@alxia/client`](https://www.npmjs.com/package/@alxia/client) reads the
+429 from the app's type: a route after the limit resolves to a union with
+`429`, whose `data` is `{ error: 'rate_limited'; retryAfter: number }`.
+
+```ts
+import { client } from '@alxia/client';
+import type { App } from './server';
+
+const api = client<App>('http://localhost:3000');
+
+async function search() {
+	for (;;) {
+		const result = await api.get('/search');
+		if (result.status !== 429) return result;
+		await Bun.sleep(result.data.retryAfter * 1000); // wait, then try again
+	}
+}
+```
+
+A route declared before the limit has no 429 in its type; comparing its
+status to `429` is a compile error.
+
+## Stores
+
+A store counts and decides. `rateLimit` asks it once per counted request,
+and never knows which store it was given.
+
+```ts
+interface RateLimitStore {
+	/** Counts one request for `key` under `policy`; a refused one counts nothing. */
+	consume(key: string, policy: Policy): Decision | Promise<Decision>;
+	/** Forgets `key`. */
+	reset(key: string): void | Promise<void>;
+}
+
+interface Policy {
+	readonly limit: number;
+	readonly windowMs: number;
+}
+
+interface Decision {
+	readonly allowed: boolean;
+	readonly remaining: number;   // requests still allowed now, after this one
+	readonly resetAfter: number;  // ms until the allowance is whole again
+	readonly retryAfter: number;  // ms until a refused request would be allowed; 0 when allowed
+}
+```
+
+### `MemoryStore`
+
+A fixed window per key, in one process's memory. The first request of a key
+opens a window of `windowMs`; the key may make `limit` requests in it; the
+next request after it ends opens a new one. Ended windows are swept on a
+timer that does not keep the process alive.
+
+```ts
+import { MemoryStore } from '@alxia/rate-limit';
+
+const store = new MemoryStore();
+const policy = { limit: 2, windowMs: 60_000 };
+
+store.consume('a', policy); // { allowed: true,  remaining: 1, resetAfter: 60000, retryAfter: 0 }
+store.consume('a', policy); // { allowed: true,  remaining: 0, … }
+store.consume('a', policy); // { allowed: false, remaining: 0, retryAfter: 60000, … }
+store.reset('a');
+store.consume('a', policy); // { allowed: true,  remaining: 1, … }
+store.size;                 // 1: the keys it counts
+```
+
+A `MemoryStore` keys its counts by `key` alone, not by policy: give each
+limit its own store, as `rateLimit` does when you pass none.
+
+### Across processes
+
+Behind a load balancer each process would count on its own, and a client
+would get `limit` requests per process. Give every process the same store:
+[`@alxia/redis`](https://www.npmjs.com/package/@alxia/redis)'s `redisStore`
+counts in Redis, with GCRA timed by the Redis server's clock.
+
+```ts
+import { redisStore } from '@alxia/redis';
+
+app.use(
+	rateLimit({
+		limit: 100,
+		windowMs: 60_000,
+		store: redisStore(redis, { name: 'api' }), // redis: a Bun RedisClient
+	}),
+);
+```
+
+### Resetting a key
+
+Keep a reference to the store to forget a key — the failed logins of an
+address that has just logged in:
+
+```ts
+import { alxia } from '@alxia/core';
+import { MemoryStore, rateLimit } from '@alxia/rate-limit';
+import { z } from 'zod';
+
+const attempts = new MemoryStore();
+const passwords = new Map([['ada', 'lovelace']]);
+
+export const app = alxia()
+	.group('/auth', (auth) =>
+		auth
+			.use(rateLimit({ limit: 5, windowMs: 15 * 60_000, store: attempts }))
+			.post(
+				'/login',
+				{ body: z.object({ name: z.string(), password: z.string() }) },
+				async ({ body, ip, reply }) => {
+					if (passwords.get(body.name) !== body.password) {
+						return reply(401, { error: 'invalid_credentials' as const });
+					}
+					if (ip !== undefined) await attempts.reset(ip); // the key is ctx.ip by default
+					return reply(200, { name: body.name });
+				},
+			),
+	);
+```
+
+The key to reset is the one `key` returned: `ctx.ip` by default.
+
+### A store of your own
+
+Implement `RateLimitStore`. `consume` decides — `allowed`, `remaining`,
+`resetAfter` and `retryAfter`, each delay in milliseconds — and must count
+nothing for a refused request, or a client that retries on time is refused
+again. `rateLimit` rounds the delays up to seconds for the headers and the
+429 body.
+
+## Testing
+
+Without a server, `ctx.ip` is `undefined`, so the default key counts
+nothing. Give the app an `ip` that reads a header, and send it:
+
+```ts
+import { expect, test } from 'bun:test';
+import { client } from '@alxia/client';
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+
+const app = alxia({ ip: (request) => request.headers.get('x-ip') ?? undefined })
+	.use(rateLimit({ limit: 2, windowMs: 60_000 }))
+	.get('/limited', ({ rateLimit, reply }) => reply(200, rateLimit?.remaining ?? -1));
+
+test('answers 429 past the limit, per address', async () => {
+	const api = client(app);
+	const init = { init: { headers: { 'x-ip': '1.1.1.1' } } };
+	expect((await api.get('/limited', init)).data).toBe(1);
+	await api.get('/limited', init);
+	const third = await api.get('/limited', init);
+	expect(third.status).toBe(429);
+	expect(third.response.headers.get('retry-after')).toBe('60');
+	const other = await api.get('/limited', { init: { headers: { 'x-ip': '2.2.2.2' } } });
+	expect(other.status).toBe(200);
+});
+```
+
+The counts live as long as the app: build a new app per test, or use a
+distinct `x-ip` in each, so one test does not spend another's allowance.
+
+## See also
+
+- [Troubleshooting](troubleshooting.md): a message, and what to do about it.
+- [`@alxia/core`'s hooks](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/hooks.md):
+  how route hooks and their order work.

package/docs/roadmap.md

@@ -0,0 +1,53 @@
+# Roadmap
+
+What `@alxia/rate-limit` gives an app, and what is coming. This page is a
+direction, not a commitment: the version something shipped in is the only
+number on it. Every release, with each change it made, is in
+[`CHANGELOG.md`](https://github.com/softistx/alxia/blob/develop/packages/rate-limit/CHANGELOG.md).
+
+## Now
+
+Nothing scheduled yet.
+
+## Next
+
+Nothing scheduled yet.
+
+## Later
+
+Nothing scheduled yet.
+
+## Not planned
+
+- **A runtime dependency.** `@alxia/rate-limit` installs nothing beside
+  itself; `@alxia/core` is its only peer.
+- **A Redis store in this package.** This package defines the store's
+  contract and ships the memory store; counting across processes is
+  `@alxia/redis`'s `redisStore`, which answers the same contract, so an app
+  that never runs more than one process installs no Redis client.
+
+## Shipped
+
+### 0.1.0
+
+- **A rate limit as a plugin.** `use(rateLimit({ limit, windowMs }))` counts
+  the requests of every route declared after it, per client address by
+  default, and answers a 429 with `Retry-After` and
+  `{ error: 'rate_limited', retryAfter }` past the limit.
+- **Options that can work, or a startup error.** A `limit` or `windowMs`
+  that is not a whole number of 1 or more throws when `rateLimit()` is
+  called.
+- **A typed 429.** The 429 is part of each limited route's type, so
+  `@alxia/client` reads it, and a route declared before the limit has none.
+- **What the route reads.** `ctx.rateLimit` gives the limit, what is left,
+  and when the allowance is whole again.
+- **Standard headers.** The IETF draft's `RateLimit-Limit`, `-Remaining`,
+  `-Reset` and `-Policy` on every counted response, `X-RateLimit-*` with
+  `headers: 'legacy'`, or none.
+- **What is counted, your way.** `key` counts by an address, a token or an
+  API key, sync or async; `skip` and an `undefined` key leave a request
+  uncounted. `rateLimit<{ user: User }>(…)` types them with what an earlier
+  plugin adds, and an app that does not give it cannot use the limit.
+- **A store contract.** `RateLimitStore` decides each request; `MemoryStore`
+  counts a fixed window in one process, and `@alxia/redis`'s `redisStore`
+  counts across processes. `reset(key)` forgets a key.

package/docs/troubleshooting.md

@@ -0,0 +1,256 @@
+# Troubleshooting
+
+Each entry is headed by what you see: a TypeScript error, a response, or a
+limit that does not count the way you expected. `@alxia/rate-limit` throws
+nothing of its own; past the limit it answers a 429.
+
+**Types**
+
+- [`Property 'user' does not exist on type 'BaseContext & Empty'`](#property-user-does-not-exist-on-type-basecontext--empty)
+- [`Type '() => Promise<boolean>' is not assignable to type '(ctx: BaseContext & Empty) => boolean'`](#type---promiseboolean-is-not-assignable-to-type-ctx-basecontext--empty--boolean)
+- [`'rateLimit' is possibly 'undefined'`](#ratelimit-is-possibly-undefined)
+- [`This comparison appears to be unintentional because the types '200 | 500' and '429' have no overlap`](#this-comparison-appears-to-be-unintentional-because-the-types-200--500-and-429-have-no-overlap)
+
+**Startup**
+
+- [`TypeError: rateLimit: … must be a whole number of 1 or more, not …`](#typeerror-ratelimit--must-be-a-whole-number-of-1-or-more-not-)
+
+**Responses**
+
+- [`429 {"error":"rate_limited","retryAfter":…}`](#429-errorrate_limitedretryafter)
+
+**Counting**
+
+- [Every client is refused at once](#every-client-is-refused-at-once)
+- [Nothing is limited, and no `RateLimit-*` header is sent](#nothing-is-limited-and-no-ratelimit--header-is-sent)
+- [A client makes more than `limit` requests](#a-client-makes-more-than-limit-requests)
+- [A client is refused before `limit` requests](#a-client-is-refused-before-limit-requests)
+
+## Types
+
+### `Property 'user' does not exist on type 'BaseContext & Empty'`
+
+**When:** a `key` (or `skip`) reads something an earlier `derive` or plugin
+added to the context, and `rateLimit` is not told about it.
+
+```text
+error TS2339: Property 'user' does not exist on type 'BaseContext & Empty'.
+```
+
+**Why:** `key` and `skip` are typed with `BaseContext`, what every route hook
+reads — `request`, `url`, `ip`, `server`, `route`, `pathParams` — plus what
+you name as `rateLimit`'s type argument, and nothing else. `rateLimit` is
+built before it is used, so it cannot see the app it will be used on.
+
+**Fix:** name what `key` reads. The app that uses the limit must then give
+it, before the limit:
+
+```ts
+const perUser = rateLimit<{ user: { id: string } }>({
+	limit: 100,
+	windowMs: 60_000,
+	key: ({ user }) => user.id,
+});
+
+alxia().use(auth).use(perUser); // auth derives user
+```
+
+On an app that does not give `user`, `use(perUser)` is a compile error:
+[`the plugin reads "user", which this app's context does not give`](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#the-plugin-reads--which-this-apps-context-does-not-give-use-the-plugin-that-adds-it-first).
+
+### `Type '() => Promise<boolean>' is not assignable to type '(ctx: BaseContext & Empty) => boolean'`
+
+**When:** `skip` is an `async` function.
+
+```text
+error TS2322: Type '() => Promise<boolean>' is not assignable to type '(ctx: BaseContext & Empty) => boolean'.
+  Type 'Promise<boolean>' is not assignable to type 'boolean'.
+```
+
+**Why:** `skip` is synchronous: a promise is always truthy, so an async
+`skip` would skip every request. `key` may be async; `skip` may not.
+
+**Fix:** decide synchronously, or move the async part into `key` and return
+`undefined` for a request that should not be counted:
+
+```ts
+app.use(
+	rateLimit({
+		limit: 100,
+		windowMs: 60_000,
+		key: async ({ ip }) => ((await isTrusted(ip)) ? undefined : ip), // undefined: not counted
+	}),
+);
+```
+
+### `'rateLimit' is possibly 'undefined'`
+
+**When:** a route reads `ctx.rateLimit.remaining` directly.
+
+```text
+error TS18048: 'rateLimit' is possibly 'undefined'.
+```
+
+**Why:** `ctx.rateLimit` is `RateLimitInfo | undefined`. It is `undefined`
+for a request that was not counted: `skip` returned `true`, or `key`
+returned `undefined` — which the default key does when `ctx.ip` is
+`undefined`.
+
+**Fix:**
+
+```ts
+app
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }))
+	.get('/quota', ({ rateLimit, reply }) => reply(200, { remaining: rateLimit?.remaining ?? null }));
+```
+
+### `This comparison appears to be unintentional because the types '200 | 500' and '429' have no overlap`
+
+**When:** client code checks for a 429 on a route that cannot answer one.
+The left-hand union is that route's statuses.
+
+```text
+error TS2367: This comparison appears to be unintentional because the types '200 | 500' and '429' have no overlap.
+```
+
+**Why:** the limit applies to the routes declared after
+`use(rateLimit(…))`, in the types as at runtime. This route was declared
+before it, or outside the group that holds the limit, so it is never
+limited and its type has no 429.
+
+**Fix:** declare the route after the limit, if it should be limited — or
+drop the check, if it should not:
+
+```ts
+const app = alxia()
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }))
+	.get('/search', ({ reply }) => reply(200, [])); // now 200 | 429 | 500
+```
+
+## Startup
+
+### `TypeError: rateLimit: … must be a whole number of 1 or more, not …`
+
+**When:** `rateLimit()` is called with a `limit` or a `windowMs` of 0, a
+negative or fractional number, or `NaN`, often from an environment variable
+that is unset. It throws at once, so the app fails at startup:
+
+```text
+TypeError: rateLimit: limit must be a whole number of 1 or more, not 0
+TypeError: rateLimit: windowMs must be a whole number of 1 or more, not NaN
+```
+
+**Why:** a `limit` of 0 would refuse every request, and a window of 0 or
+less would never end one.
+
+**Fix:** pass whole numbers. A value read from the environment is a
+string, or `undefined` when the variable is unset: give it a default, and
+let an empty or non-numeric value still fail at startup, as it should:
+
+```ts
+app.use(rateLimit({ limit: Number(Bun.env.RATE_LIMIT ?? 100), windowMs: 60_000 }));
+```
+
+## Responses
+
+### `429 {"error":"rate_limited","retryAfter":…}`
+
+**When:** a key has made `limit` counted requests within the window.
+
+**Why:** that is the limit working. `retryAfter` and the `Retry-After`
+header are the seconds until a request would be allowed, at least 1. The
+refused request counted nothing.
+
+**Fix:** on the client, wait that long; the 429 is in the route's type, so
+`data` is typed:
+
+```ts
+const result = await api.get('/search');
+if (result.status === 429) {
+	await Bun.sleep(result.data.retryAfter * 1000);
+}
+```
+
+If it arrives sooner than you expect, see the entries below.
+
+## Counting
+
+### Every client is refused at once
+
+**When:** in production, behind a reverse proxy or a load balancer: one
+busy client, or a handful of ordinary ones, and everyone gets the 429.
+
+**Why:** the default key is `ctx.ip`, the connection's address — the
+proxy's, the same for every request. All clients share one allowance.
+
+**Fix:** give the app an `ip` option that reads the header your proxy sets,
+and only from a proxy you trust:
+
+```ts
+const app = alxia({
+	ip: (request, server) =>
+		request.headers.get('x-real-ip') ?? server?.requestIP(request)?.address,
+}).use(rateLimit({ limit: 100, windowMs: 60_000 }));
+```
+
+### Nothing is limited, and no `RateLimit-*` header is sent
+
+**When:** requests past `limit` still answer 200, without a rate-limit
+header, and `ctx.rateLimit` is `undefined` — typically in a test calling
+the app through `client(app)`, `app.fetch` or `app.request`.
+
+**Why:** a request whose key is `undefined` is not counted. Without a server
+there is no connection, so the default `ip` is `undefined`, and so is the
+default key. A custom `key` returning `undefined`, or a `skip` returning
+`true`, does the same. (A route declared before the limit is not counted
+either, and has no 429 in its type.)
+
+**Fix:** in tests, read the address from a header you send:
+
+```ts
+const app = alxia({ ip: (request) => request.headers.get('x-ip') ?? undefined })
+	.use(rateLimit({ limit: 2, windowMs: 60_000 }))
+	.get('/limited', ({ reply }) => reply(200, 'ok'));
+
+await client(app).get('/limited', { init: { headers: { 'x-ip': '1.1.1.1' } } });
+```
+
+### A client makes more than `limit` requests
+
+**When:** the app runs as several processes or instances, or restarts.
+
+**Why:** the default store is a `MemoryStore`, which counts in one process's
+memory. Each process grants `limit` on its own, and a restart forgets
+every count.
+
+**Fix:** give every process the same store, such as `@alxia/redis`'s:
+
+```ts
+import { redisStore } from '@alxia/redis';
+
+app.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(redis, { name: 'api' }) }));
+```
+
+### A client is refused before `limit` requests
+
+**When:** a 429 comes earlier than `limit` suggests.
+
+**Why:** one of these:
+
+- **Two limits share one `MemoryStore`.** It keys its counts by key alone,
+  not by policy, so both limits spend the same count, and the smaller
+  `limit` refuses first.
+- **Two limits apply to the route.** A group's limit and an app-wide one
+  both count; either may refuse. With two `'draft'` limits, the headers
+  show the later one's numbers.
+- **Refused requests are counted.** The limit runs before the route
+  validates the request, so a request answered 400 has spent one.
+
+**Fix:** give each limit its own `MemoryStore` — or none, and `rateLimit`
+creates one — and give all but one limit `headers: false`:
+
+```ts
+app
+	.use(rateLimit({ limit: 10, windowMs: 1_000 }))
+	.use(rateLimit({ limit: 1_000, windowMs: 60 * 60_000, headers: false }));
+```

package/package.json

@@ -1,6 +1,53 @@
 {
-  "name": "@alxia/rate-limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@alxia/rate-limit",
+	"version": "0.1.0",
+	"description": "Rate limiting for alxia, typed: the 429 is part of every route behind it, and the client reads it",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/alxia.git",
+		"directory": "packages/rate-limit"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"test": "bun test src",
+		"typecheck": "tsc --noEmit"
+	},
+	"alxia": {
+		"entrypoints": [
+			"src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@alxia/client": "^0.1.0",
+		"@alxia/core": "^0.1.0",
+		"@types/bun": "^1.4.2",
+		"zod": "^4.2.0"
+	},
+	"peerDependencies": {
+		"@alxia/core": "^0.1.0",
+		"typescript": "^6.0.3 || ^7.0.0"
+	}
+}