@alxia/rate-limit 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @alxia/rate-limit
 
-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
+Rate limiting for [alxia](https://www.npmjs.com/package/@alxia/core), as a
+middleware: every request it runs on answers a 429 with `Retry-After` once a key has
+spent its allowance, and reads what is left as a typed `ctx.rateLimit`. No
 dependency.
 
 ```sh
@@ -20,8 +20,8 @@ const app = alxia()
 	.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
+const response = await app.request('/search');
+if (response.status === 429) (await response.json()).retryAfter; // seconds
 ```
 
 Past the limit, a 429 with `Retry-After` and
@@ -34,11 +34,18 @@ IETF draft's `RateLimit-Limit`, `-Remaining`, `-Reset` and `-Policy`.
 | --- | --- | --- |
 | `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 |
+| `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 middleware 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` |
 
+## Order
+
+`rateLimit` counts every request it runs on. Given to `app.use`, that is the
+routes declared after it, and also a request no route matches: it is counted,
+and past the limit answers the 429 before the 404. Put it in a `group` to
+count only some routes: a path-scoped `use('/api', …)` cannot give `rateLimit` to the context.
+
 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 })`.
 
@@ -63,13 +70,13 @@ nothing.
 
 | export | |
 | --- | --- |
-| `rateLimit(options)` | the plugin: an app that derives `rateLimit` |
+| `rateLimit(options)` | the middleware: gives `rateLimit` to what runs after it, or answers the 429 |
 | `MemoryStore` | a fixed window in one process's memory |
 | `RateLimitStore`, `Decision`, `Policy` | a store's contract |
-| `RateLimitedBody`, `RateLimitInfo`, `RateLimitOptions` | its types |
+| `RateLimit`, `RateLimitedBody`, `RateLimitInfo`, `RateLimitOptions` | its types: `RateLimit<Requires>` is the middleware `rateLimit()` returns |
 
 ## 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.
+- [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 wire, 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

@@ -1,3 +1,3 @@
-export { type RateLimitedBody, type RateLimitInfo, type RateLimitOptions, rateLimit, } from './rate-limit';
+export { type RateLimit, 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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EACd,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

@@ -1,5 +1,7 @@
 // src/rate-limit.ts
-import { definePlugin } from "@alxia/core";
+import {
+  defineMiddleware
+} from "@alxia/core";
 
 // src/store.ts
 class MemoryStore {
@@ -65,27 +67,17 @@ function rateLimit(options) {
   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) => {
+  return defineMiddleware()(async (ctx, next) => {
     const counted = options.skip?.(ctx) ? undefined : await key(ctx);
     if (counted === undefined) {
       const rateLimit = undefined;
-      return { rateLimit };
+      return next({ 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)));
-    }
+    said(ctx.set.headers, style, options, decision);
     if (!decision.allowed) {
       const retryAfter = Math.max(1, Math.ceil(decision.retryAfter / 1000));
       const body = { error: "rate_limited", retryAfter };
@@ -98,13 +90,25 @@ function rateLimit(options) {
       remaining: decision.remaining,
       resetAfter: decision.resetAfter
     };
-    return { rateLimit };
-  }));
+    return next({ rateLimit });
+  });
+}
+function said(headers, style, options, decision) {
+  if (style === "draft") {
+    headers.set("ratelimit-limit", String(options.limit));
+    headers.set("ratelimit-remaining", String(decision.remaining));
+    headers.set("ratelimit-reset", String(Math.ceil(decision.resetAfter / 1000)));
+    headers.set("ratelimit-policy", `${options.limit};w=${Math.ceil(options.windowMs / 1000)}`);
+  } else if (style === "legacy") {
+    headers.set("x-ratelimit-limit", String(options.limit));
+    headers.set("x-ratelimit-remaining", String(decision.remaining));
+    headers.set("x-ratelimit-reset", String(Math.ceil((Date.now() + decision.resetAfter) / 1000)));
+  }
 }
 export {
   MemoryStore,
   rateLimit
 };
 
-//# debugId=1917CEB5F68549FD64756E2164756E21
+//# debugId=8BE4A8782C7D852264756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,10 +2,10 @@
   "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",
+    "import {\n\ttype BaseContext,\n\tdefineMiddleware,\n\ttype Empty,\n\ttype Middleware,\n\ttype MiddlewareMark,\n\ttype Next,\n\ttype Reply,\n} from '@alxia/core';\nimport { type Decision, 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 middleware 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 * What `rateLimit()` makes: a middleware that requires `Requires` of the\n * app, and gives `rateLimit` or answers the 429.\n */\nexport type RateLimit<Requires extends object = Empty> = Middleware<\n\tRequires,\n\tPromise<\n\t\tReply<429, RateLimitedBody> | Next<{ rateLimit: RateLimitInfo | undefined }>\n\t>\n> &\n\tMiddlewareMark;\n\n/**\n * A rate limit, as a middleware: every request it runs on is counted —\n * the routes declared after it, and, given to `app.use`, a request no\n * route matches too — and answered a 429 past the limit.\n *\n * ```ts\n * app.use(rateLimit({ limit: 100, windowMs: 60_000 })).get(...);\n * ```\n *\n * A `key` that reads what an earlier middleware added names it, and the\n * app must then give it: `rateLimit<{ user: User }>({ key: ({ user }) => user.id, … })`.\n */\nexport function rateLimit<Requires extends object = Empty>(\n\toptions: RateLimitOptions<Requires>,\n): NoInfer<RateLimit<Requires>> {\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 defineMiddleware<Requires>()(async (ctx, next) => {\n\t\tconst counted = options.skip?.(ctx) ? undefined : await key(ctx);\n\t\tif (counted === undefined) {\n\t\t\tconst rateLimit: RateLimitInfo | undefined = undefined;\n\t\t\treturn next({ rateLimit });\n\t\t}\n\t\tconst decision = await store.consume(counted, {\n\t\t\tlimit: options.limit,\n\t\t\twindowMs: options.windowMs,\n\t\t});\n\t\tsaid(ctx.set.headers, style, options, decision);\n\t\tif (!decision.allowed) {\n\t\t\tconst retryAfter = Math.max(1, Math.ceil(decision.retryAfter / 1000));\n\t\t\tconst body: RateLimitedBody = { error: 'rate_limited', retryAfter };\n\t\t\treturn ctx.reply(429, body, {\n\t\t\t\theaders: { 'retry-after': String(retryAfter) },\n\t\t\t});\n\t\t}\n\t\tconst rateLimit: RateLimitInfo | undefined = {\n\t\t\tlimit: options.limit,\n\t\t\tremaining: decision.remaining,\n\t\t\tresetAfter: decision.resetAfter,\n\t\t};\n\t\treturn next({ rateLimit });\n\t});\n}\n\n/** The headers that say where the key stands, in the `style` asked for. */\nfunction said(\n\theaders: Headers,\n\tstyle: 'draft' | 'legacy' | false,\n\toptions: { readonly limit: number; readonly windowMs: number },\n\tdecision: Decision,\n): void {\n\tif (style === 'draft') {\n\t\theaders.set('ratelimit-limit', String(options.limit));\n\t\theaders.set('ratelimit-remaining', String(decision.remaining));\n\t\theaders.set(\n\t\t\t'ratelimit-reset',\n\t\t\tString(Math.ceil(decision.resetAfter / 1000)),\n\t\t);\n\t\theaders.set(\n\t\t\t'ratelimit-policy',\n\t\t\t`${options.limit};w=${Math.ceil(options.windowMs / 1000)}`,\n\t\t);\n\t} else if (style === 'legacy') {\n\t\theaders.set('x-ratelimit-limit', String(options.limit));\n\t\theaders.set('x-ratelimit-remaining', String(decision.remaining));\n\t\theaders.set(\n\t\t\t'x-ratelimit-reset',\n\t\t\tString(Math.ceil((Date.now() + decision.resetAfter) / 1000)),\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": "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",
-  "debugId": "1917CEB5F68549FD64756E2164756E21",
+  "mappings": ";AAAA;AAAA;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;;;ADRO,SAAS,SAA0C,CACzD,SAC+B;AAAA,EAC/B,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,iBAA2B,EAAE,OAAO,KAAK,SAAS;AAAA,IACxD,MAAM,UAAU,QAAQ,OAAO,GAAG,IAAI,YAAY,MAAM,IAAI,GAAG;AAAA,IAC/D,IAAI,YAAY,WAAW;AAAA,MAC1B,MAAM,YAAuC;AAAA,MAC7C,OAAO,KAAK,EAAE,UAAU,CAAC;AAAA,IAC1B;AAAA,IACA,MAAM,WAAW,MAAM,MAAM,QAAQ,SAAS;AAAA,MAC7C,OAAO,QAAQ;AAAA,MACf,UAAU,QAAQ;AAAA,IACnB,CAAC;AAAA,IACD,KAAK,IAAI,IAAI,SAAS,OAAO,SAAS,QAAQ;AAAA,IAC9C,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,KAAK,EAAE,UAAU,CAAC;AAAA,GACzB;AAAA;AAIF,SAAS,IAAI,CACZ,SACA,OACA,SACA,UACO;AAAA,EACP,IAAI,UAAU,SAAS;AAAA,IACtB,QAAQ,IAAI,mBAAmB,OAAO,QAAQ,KAAK,CAAC;AAAA,IACpD,QAAQ,IAAI,uBAAuB,OAAO,SAAS,SAAS,CAAC;AAAA,IAC7D,QAAQ,IACP,mBACA,OAAO,KAAK,KAAK,SAAS,aAAa,IAAI,CAAC,CAC7C;AAAA,IACA,QAAQ,IACP,oBACA,GAAG,QAAQ,WAAW,KAAK,KAAK,QAAQ,WAAW,IAAI,GACxD;AAAA,EACD,EAAO,SAAI,UAAU,UAAU;AAAA,IAC9B,QAAQ,IAAI,qBAAqB,OAAO,QAAQ,KAAK,CAAC;AAAA,IACtD,QAAQ,IAAI,yBAAyB,OAAO,SAAS,SAAS,CAAC;AAAA,IAC/D,QAAQ,IACP,qBACA,OAAO,KAAK,MAAM,KAAK,IAAI,IAAI,SAAS,cAAc,IAAI,CAAC,CAC5D;AAAA,EACD;AAAA;",
+  "debugId": "8BE4A8782C7D852264756E2164756E21",
   "names": []
 }

package/dist/rate-limit.d.ts

@@ -1,8 +1,8 @@
-import { type BaseContext, type Empty } from '@alxia/core';
+import { type BaseContext, type Empty, type Middleware, type MiddlewareMark, type Next, type Reply } 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
+ * `BaseContext` — a `user` an earlier middleware adds — and what the app that
  * uses the limit must then give.
  */
 export interface RateLimitOptions<Requires extends object = Empty> {
@@ -36,20 +36,23 @@ export interface RateLimitInfo {
     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.
+ * What `rateLimit()` makes: a middleware that requires `Requires` of the
+ * app, and gives `rateLimit` or answers the 429.
+ */
+export type RateLimit<Requires extends object = Empty> = Middleware<Requires, Promise<Reply<429, RateLimitedBody> | Next<{
+    rateLimit: RateLimitInfo | undefined;
+}>>> & MiddlewareMark;
+/**
+ * A rate limit, as a middleware: every request it runs on is counted —
+ * the routes declared after it, and, given to `app.use`, a request no
+ * route matches too — and answered a 429 past the limit.
  *
  * ```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, … })`.
+ * A `key` that reads what an earlier middleware 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>;
+export declare function rateLimit<Requires extends object = Empty>(options: RateLimitOptions<Requires>): NoInfer<RateLimit<Requires>>;
 //# sourceMappingURL=rate-limit.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAEhB,KAAK,KAAK,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,KAAK,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,EAA8B,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;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;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,QAAQ,SAAS,MAAM,GAAG,KAAK,IAAI,UAAU,CAClE,QAAQ,EACR,OAAO,CACN,KAAK,CAAC,GAAG,EAAE,eAAe,CAAC,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,CAAC,CAC5E,CACD,GACA,cAAc,CAAC;AAEhB;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,QAAQ,SAAS,MAAM,GAAG,KAAK,EACxD,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GACjC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAsC9B"}

package/docs/README.md

@@ -6,6 +6,6 @@ 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 |
+| [Guide](guide.md) | choosing what to count and where, reading the 429 on the wire, 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

@@ -2,7 +2,7 @@
 
 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.
+read, and where the counts are kept. It is a middleware: `app.use(rateLimit(…))`.
 
 ```ts
 import { alxia } from '@alxia/core';
@@ -25,7 +25,7 @@ app.listen({ port: 3000 });
 ```ts
 function rateLimit<Requires extends object = Empty>(
 	options: RateLimitOptions<Requires>,
-): Alxia<…> & Requiring<Requires>; // an app, given to `use`, which checks `Requires`
+): RateLimit<Requires>; // a middleware, given to `app.use`, which checks `Requires`
 
 interface RateLimitOptions<Requires extends object = Empty> {
 	readonly limit: number;
@@ -37,10 +37,19 @@ interface RateLimitOptions<Requires extends object = Empty> {
 }
 ```
 
-`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).
+`rateLimit` returns a middleware that counts the request. Given to `app.use`,
+it adds `rateLimit` to the context of every route declared after it, and each
+of those routes may answer its 429; it also counts a request no route
+matches, and answers its 429 before the 404 (see [Which requests are
+counted](#which-requests-are-counted)). `Requires` is what `key` and `skip`
+read beyond `BaseContext`; see [Reading the app's context](#reading-the-apps-context).
+
+```ts
+type RateLimit<Requires extends object = Empty> = Middleware<
+	Requires,
+	Promise<Reply<429, RateLimitedBody> | Next<{ rateLimit: RateLimitInfo | undefined }>>
+>;
+```
 
 ## Options
 
@@ -89,9 +98,9 @@ app.use(
 );
 ```
 
-`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
+`key` is typed with `BaseContext`, what every middleware reads: the request,
+`url`, `ip`, `server`, `route` (`undefined` on a request no route matches) and `pathParams`, and with `Requires`, empty
+by default. To read what an earlier middleware added, see [Reading the app's
 context](#reading-the-apps-context).
 
 ### `skip`
@@ -111,10 +120,10 @@ app.use(
 
 ### 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.
+To count by what an earlier middleware added, such as a signed-in `user`,
+name it as `rateLimit`'s type argument. `key` and `skip` then read it, and
+the app that uses the limit must give it first: an app that does not give
+`user` before it cannot use it.
 
 ```ts
 const perUser = rateLimit<{ user: { id: string; role: string } }>({
@@ -125,12 +134,12 @@ const perUser = rateLimit<{ user: { id: string; role: string } }>({
 });
 
 const app = alxia()
-	.use(auth) // derives user, or answers 401
+	.plugin(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
+// error: Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: { id: string; role: string; }; }'
 ```
 
 ### `headers`
@@ -163,13 +172,25 @@ counts live in that process and are lost when it stops. See
 
 ## Which requests are counted
 
-The limit is a route hook, so order decides, at runtime and in the types:
+The limit is a middleware, 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 **before** `use(rateLimit(…))` is not counted, and
+  never answers the 429;
 - a route declared **after** it is counted, and may answer the 429;
+- a request **no route matches** (a 404, a 405) is counted too, when the limit
+  is on the app: every top-level `use()` runs on it, wherever declared, and
+  past the limit the 429 comes before the 404. Spamming missing paths spends
+  the allowance;
 - 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.
+  the limit stays inside it: its routes, and an unmatched request under the
+  group's prefix, never a route declared after the group nor a path outside
+  the prefix;
+- a path-scoped `use('/api', rateLimit(…))` does not compile: a middleware
+  given a path may add nothing to the context, and the limit adds
+  `rateLimit`. A group is the scope.
+
+A guard on the app answers an anonymous caller of a missing path with its
+refusal, not the 404: that is the same rule for a rate limit.
 
 ```ts
 const app = alxia()
@@ -183,9 +204,8 @@ const app = alxia()
 	.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.
+The limit runs before the request is validated: a request the route
+refuses with a 400 has already been 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
@@ -226,7 +246,7 @@ app
 
 ## The 429
 
-Past the limit the hook ends the request before the route runs:
+Past the limit the middleware ends the request before the route runs:
 
 ```text
 HTTP/1.1 429 Too Many Requests
@@ -249,30 +269,25 @@ interface RateLimitedBody {
 `retryAfter` and `Retry-After` are the same number. A refused request
 counts nothing: retrying after `retryAfter` seconds succeeds.
 
-## On the client
+## On the wire
 
-[`@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 }`.
+Every route after the limit may answer `429 { error: 'rate_limited',
+retryAfter }`; a route declared before it never does. Declare the 429 in
+your OpenAPI document, and the client you generate from it (with
+`@nxgt/openapi-codegen`, say) reads it typed. A caller waits, then tries
+again:
 
 ```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
+		const response = await fetch('http://localhost:3000/search');
+		if (response.status !== 429) return response;
+		const { retryAfter } = await response.json();
+		await Bun.sleep(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,
@@ -348,7 +363,7 @@ 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 { alxia, validate } from '@alxia/core';
 import { MemoryStore, rateLimit } from '@alxia/rate-limit';
 import { z } from 'zod';
 
@@ -361,7 +376,7 @@ export const app = alxia()
 			.use(rateLimit({ limit: 5, windowMs: 15 * 60_000, store: attempts }))
 			.post(
 				'/login',
-				{ body: z.object({ name: z.string(), password: z.string() }) },
+				validate({ 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 });
@@ -390,7 +405,6 @@ 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';
 
@@ -399,15 +413,13 @@ const app = alxia({ ip: (request) => request.headers.get('x-ip') ?? undefined })
 	.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);
+	const from = (ip: string) => app.request('/limited', { headers: { 'x-ip': ip } });
+	expect(await (await from('1.1.1.1')).json()).toBe(1);
+	await from('1.1.1.1');
+	const third = await from('1.1.1.1');
 	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);
+	expect(third.headers.get('retry-after')).toBe('60');
+	expect((await from('2.2.2.2')).status).toBe(200);
 });
 ```
 
@@ -417,5 +429,5 @@ 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.
+- [`@alxia/core`'s middleware guide](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/middleware.md):
+  how `use`, groups and their order work, and which requests a middleware runs on.

package/docs/roadmap.md

@@ -7,7 +7,10 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing scheduled yet.
+- **A middleware, not a plugin.** `app.use(rateLimit({ limit, windowMs }))` is
+  the form; `app.plugin(rateLimit(…))` keeps working, deprecated. Given to the
+  app, the limit also counts a request no route matches, and `RateLimit<Requires>`
+  names what `rateLimit()` returns.
 
 ## Next
 
@@ -30,15 +33,17 @@ Nothing scheduled yet.
 
 ### 0.1.0
 
-- **A rate limit as a plugin.** `use(rateLimit({ limit, windowMs }))` counts
+- **A rate limit as a plugin.** `plugin(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.
+- **A 429 only behind the limit.** A route declared before the limit is
+  never counted and never answers a 429. (Its place in a typed client left
+  with the client: alxia is OpenAPI spec first, so the 429 is declared in
+  the document a client is generated from.)
 - **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`,

package/docs/troubleshooting.md

@@ -9,7 +9,6 @@ nothing of its own; past the limit it answers a 429.
 - [`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**
 
@@ -25,19 +24,20 @@ nothing of its own; past the limit it answers a 429.
 - [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)
+- [A missing path answers 429](#a-missing-path-answers-429)
 
 ## Types
 
 ### `Property 'user' does not exist on type 'BaseContext & Empty'`
 
-**When:** a `key` (or `skip`) reads something an earlier `derive` or plugin
+**When:** a `key` (or `skip`) reads something an earlier `derive` or middleware
 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
+**Why:** `key` and `skip` are typed with `BaseContext`, what every middleware
 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.
@@ -52,11 +52,11 @@ const perUser = rateLimit<{ user: { id: string } }>({
 	key: ({ user }) => user.id,
 });
 
-alxia().use(auth).use(perUser); // auth derives user
+alxia().plugin(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).
+`Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: { id: string; }; }'`.
 
 ### `Type '() => Promise<boolean>' is not assignable to type '(ctx: BaseContext & Empty) => boolean'`
 
@@ -104,29 +104,6 @@ app
 	.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 …`
@@ -161,13 +138,12 @@ app.use(rateLimit({ limit: Number(Bun.env.RATE_LIMIT ?? 100), windowMs: 60_000 }
 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:
+**Fix:** on the client, wait that long, then try again:
 
 ```ts
-const result = await api.get('/search');
-if (result.status === 429) {
-	await Bun.sleep(result.data.retryAfter * 1000);
+const response = await fetch('http://localhost:3000/search');
+if (response.status === 429) {
+	await Bun.sleep((await response.json()).retryAfter * 1000);
 }
 ```
 
@@ -197,13 +173,14 @@ const app = alxia({
 
 **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`.
+the app through `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.)
+either, and never answers a 429; nor is a request a group's limit does not
+run on.)
 
 **Fix:** in tests, read the address from a header you send:
 
@@ -212,7 +189,7 @@ 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' } } });
+await app.request('/limited', { headers: { 'x-ip': '1.1.1.1' } });
 ```
 
 ### A client makes more than `limit` requests
@@ -245,6 +222,9 @@ app.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(redis, { nam
   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.
+- **Unmatched requests are counted.** On the app, the limit runs on a
+  request no route matches too, so a client probing missing paths spends
+  its allowance: see [A missing path answers 429](#a-missing-path-answers-429).
 
 **Fix:** give each limit its own `MemoryStore` — or none, and `rateLimit`
 creates one — and give all but one limit `headers: false`:
@@ -254,3 +234,25 @@ app
 	.use(rateLimit({ limit: 10, windowMs: 1_000 }))
 	.use(rateLimit({ limit: 1_000, windowMs: 60 * 60_000, headers: false }));
 ```
+
+### A missing path answers 429
+
+**When:** a request to a path no route serves answers `429`, not `404`, once
+the client is past the limit.
+
+**Why:** a limit given to `app.use` runs on every request, a request no
+route matches included, and answers before the 404. Declared after a route,
+it still runs for unmatched requests: only the routes before it are spared.
+A limit inside a `group` does not.
+
+**Fix:** that is the limit working. To count only some routes, scope it:
+
+```ts
+const app = alxia()
+	.get('/health', ({ reply }) => reply(200, 'ok'))
+	.group('/api', (api) =>
+		api
+			.use(rateLimit({ limit: 100, windowMs: 60_000 })) // /api routes only
+			.get('/search', ({ reply }) => reply(200, [])),
+	);
+```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@alxia/rate-limit",
-	"version": "0.1.1",
-	"description": "Rate limiting for alxia, typed: the 429 is part of every route behind it, and the client reads it",
+	"version": "0.2.0",
+	"description": "Rate limiting for alxia: a 429 with Retry-After past the limit, the remaining allowance typed in the context, pluggable stores",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -41,13 +41,12 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/client": "^0.2.0",
-		"@alxia/core": "^0.2.0",
+		"@alxia/core": "^0.4.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.2.0"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.2.0",
+		"@alxia/core": "^0.4.0",
 		"typescript": "^6.0.3 || ^7.0.0"
 	}
 }