@alxia/redis 0.1.3 → 0.3.0

package/docs/README.md

@@ -8,11 +8,19 @@ a realistic example for each.
 
 | Page | Read it when |
 | --- | --- |
-| [Connecting](guide/connecting.md) | opening the client every export takes, deciding when to build the plugins, failing fast when Redis is down, closing it, or naming keys so features never share them |
+| [Connecting](guide/connecting.md) | opening the client every export takes, deciding when to build what takes it, failing fast when Redis is down, closing it, naming keys so features never share them, or giving every export one `@nxgt/redis` handle: a prefix on every key, a health check, closing on stop |
 | [Rate limits](guide/rate-limits.md) | sharing an `@alxia/rate-limit` count across processes, understanding why GCRA lets a burst through, choosing `name`, or resetting a key |
 | [Response cache](guide/response-cache.md) | sharing `@alxia/cache` responses across processes, invalidating them everywhere, or knowing what is stored in Redis |
 | [Idempotency](guide/idempotency.md) | making a `POST` run once per `Idempotency-Key`, reading the `409`, `422` and `400`, scoping keys by user, or ordering it with a rate limit or an auth check |
 | [Caches and locks](guide/caches-and-locks.md) | reading typed caches and a lock from the context, catching `LOCK_HELD`, or using `redis()` beside `@alxia/cache` |
-| [Testing](guide/testing.md) | writing specs against a real Redis, giving `app.request()` a client address, or pinning the refusals in the types |
+| [Testing](guide/testing.md) | writing specs against a real Redis, giving `app.request()` a client address, or checking which routes the refusals reach |
 | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message, or a limit, a cache or a replay does not behave as you expected |
 | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |
+
+## Recipes
+
+A task that crosses packages, in [the repository's recipes](https://github.com/softistx/alxia/blob/develop/docs/recipes/README.md), each with a complete example:
+
+- [Caching and rate limiting with Redis](https://github.com/softistx/alxia/blob/develop/docs/recipes/caching-and-rate-limiting.md): a limit and a response cache shared by every process
+- [Test an alxia app](https://github.com/softistx/alxia/blob/develop/docs/recipes/testing.md): `app.request`, a middleware alone, the typed client, sockets, Redis
+- [Health checks and graceful shutdown](https://github.com/softistx/alxia/blob/develop/docs/recipes/health-and-shutdown.md): probes, the drain, Docker and Kubernetes

package/docs/guide/caches-and-locks.md

@@ -17,7 +17,7 @@ const users = defineCache({ name: 'user', key: (id: string) => id, ttl: 300, sch
 const loadUser = async (id: string) => ({ id, name: 'Ada' });   // your database
 
 const app = alxia()
-	.use(redis(connection.client, { caches: { users } }))
+	.plugin(redis(connection.client, { caches: { users } }))
 	.get('/users/:id', async ({ caches, params, reply }) => {
 		const user = await caches.users.remember(params.id, () => loadUser(params.id));   // typed by User
 		return reply.ok(user);
@@ -66,7 +66,7 @@ import type { RedisClient } from 'bun';
 
 export function withCaches<const Caches extends Record<string, AnyCache>>(client: RedisClient, caches: Caches) {
 	return alxia()
-		.use(redis(client, { caches }))
+		.plugin(redis(client, { caches }))
 		.get('/caches', ({ caches: bound, reply }) => reply(200, Object.keys(bound)));
 }
 ```
@@ -88,7 +88,7 @@ the name you give it in `caches`:
 A realistic case, a profile read through the cache and forgotten on write:
 
 ```ts
-import { alxia } from '@alxia/core';
+import { alxia, validate } from '@alxia/core';
 import { redis } from '@alxia/redis';
 import { connectRedis, defineCache } from '@nxgt/redis';
 import { z } from 'zod';
@@ -100,12 +100,12 @@ const profiles = defineCache({ name: 'profile', key: (id: string) => id, ttl: 60
 const table = new Map<string, z.input<typeof Profile>>([['1', { id: '1', name: 'Ada' }]]);
 
 const app = alxia()
-	.use(redis(connection.client, { caches: { profiles } }))
+	.plugin(redis(connection.client, { caches: { profiles } }))
 	.get('/profiles/:id', async ({ caches, params, reply }) => {
 		const profile = await caches.profiles.remember(params.id, async () => table.get(params.id) ?? { id: params.id, name: '?' });
 		return reply.ok(profile);                         // plan is filled in: 'free'
 	})
-	.put('/profiles/:id', { body: Profile.omit({ id: true }) }, async ({ caches, params, body, reply }) => {
+	.put('/profiles/:id', validate({ body: Profile.omit({ id: true }) }), async ({ caches, params, body, reply }) => {
 		table.set(params.id, { id: params.id, ...body });
 		await caches.profiles.delete(params.id);          // the next read loads it again
 		return reply(204, undefined);
@@ -142,7 +142,7 @@ const connection = await connectRedis(Bun.env['REDIS_URL']!);
 const sendInvoices = async () => 12;   // the work that must not run twice at once
 
 const app = alxia()
-	.use(redis(connection.client))
+	.plugin(redis(connection.client))
 	.post('/invoices/run', async ({ lock, reply }) => {
 		try {
 			const sent = await lock('invoices', sendInvoices, { ttl: 60_000 });
@@ -176,7 +176,7 @@ import { connectRedis } from '@nxgt/redis';
 const connection = await connectRedis(Bun.env['REDIS_URL']!);
 
 const app = alxia()
-	.use(redis(connection.client))
+	.plugin(redis(connection.client))
 	.post('/articles/:id/views', async ({ redis, params, reply }) => {
 		const views = await redis.incr(`views:${params.id}`);
 		return reply(200, { views });
@@ -201,7 +201,7 @@ const users = defineCache({ name: 'user', key: (id: string) => id, ttl: 300, sch
 const loadUser = async (id: string) => ({ id, name: 'Ada' });
 
 const app = alxia()
-	.use(redis(connection.client, { caches: { users } }))
+	.plugin(redis(connection.client, { caches: { users } }))
 	.use(cache({ ttl: 60 }))
 	.get('/users/:id', async ({ caches, cache, params, reply }) => {
 		cache.tag(`user:${params.id}`);                                    // the response cache
@@ -213,6 +213,20 @@ Code written for the earlier name — `ctx.cache.users` — no longer compiles;
 [Troubleshooting](../troubleshooting.md#property-cache-does-not-exist-on-type---rediscontext-) has the
 message and the rename.
 
+## From an `@nxgt/redis` handle
+
+`redis(handle)` takes the handle `openRedis(defineRedis({ …, caches }))` gives
+instead of a client and a `caches` option: the context's `caches` are the
+handle's `cache` scope, the `lock` is under its `prefix`, and the handle is
+closed when the app stops. See [Connecting](connecting.md#with-an-nxgtredis-handle).
+
+```ts
+const handle = await openRedis(defineRedis({ uri: Bun.env['REDIS_URL']!, prefix: 'shop', caches: { users } }));
+alxia()
+	.plugin(redis(handle))
+	.get('/users/:id', ({ caches, params, reply }) => reply.ok(caches.users.get(params.id))); // shop:user:<id>
+```
+
 ## Next
 
 - [Connecting](connecting.md) — the client, and closing it.

package/docs/guide/connecting.md

@@ -1,7 +1,7 @@
 # Connecting
 
 This page covers the one thing every export of `@alxia/redis` takes first:
-a Bun `RedisClient`, how to open it, when to make the plugins with it, and
+a Bun `RedisClient`, how to open it, when to build what takes it, and
 how to close it.
 
 ```ts
@@ -12,7 +12,7 @@ import { connectRedis } from '@nxgt/redis';
 const connection = await connectRedis(Bun.env['REDIS_URL'] ?? 'redis://127.0.0.1:6379');
 
 const app = alxia()
-	.use(redis(connection.client))
+	.plugin(redis(connection.client))
 	.get('/ping', async ({ redis, reply }) => reply(200, await redis.ping()));
 
 app.listen({ port: 3000 });
@@ -25,8 +25,8 @@ Every export takes Bun's own `RedisClient` as its first argument:
 ```ts
 redisStore(client: RedisClient, options: RedisStoreOptions): RateLimitStore
 redisCacheStore(client: RedisClient, options: RedisCacheStoreOptions): CacheStore
-idempotency(client: RedisClient, options: IdempotencyOptions)    // a plugin
-redis(client: RedisClient, options?: RedisContextOptions)        // a plugin
+idempotency(client: RedisClient, options: IdempotencyOptions)    // a middleware
+redis(client: RedisClient, options?: RedisContextOptions)        // a plugin, given to app.plugin
 ```
 
 Any `RedisClient` will do. `connectRedis` from
@@ -48,7 +48,7 @@ One client is enough for the whole app: the rate-limit store, the cache
 store, idempotency and `redis()` all send ordinary commands over it. None
 of them subscribes, so none needs a connection of its own.
 
-## Make the plugins after you connect
+## Build them after you connect
 
 Each export binds the client it is given when it is called. Open the
 connection first, then build the app:
@@ -143,6 +143,135 @@ process.on('SIGTERM', async () => {
 `closeRedis()` from `@nxgt/redis` closes every client the process opened
 through `connectRedis` — the end of a test file, say.
 
+## With an `@nxgt/redis` handle
+
+`openRedis(defineRedis({ … }))` opens the client and wires the caches, a
+`prefix` and a lock in one object, the handle. Every export that takes a
+client takes the handle too, and the deployment's `prefix` is then in front of
+every key it writes:
+
+```ts
+import { cache } from '@alxia/cache';
+import { alxia, health } from '@alxia/core';
+import { idempotency, redis, redisCacheStore, redisCheck } from '@alxia/redis';
+import { defineCache, defineRedis, openRedis } from '@nxgt/redis';
+import { z } from 'zod';
+
+const users = defineCache({ name: 'user', key: (id: string) => id, ttl: 300, schema: z.object({ id: z.string(), name: z.string() }) });
+const handle = await openRedis(
+	defineRedis({ uri: Bun.env['REDIS_URL']!, prefix: 'shop', caches: { users } }),
+);
+
+const app = alxia()
+	.plugin(health({ checks: { redis: redisCheck(handle) } }))
+	.plugin(redis(handle))
+	.use(idempotency(handle, { name: 'orders' }))
+	.use(cache({ ttl: 60, store: redisCacheStore(handle, { name: 'pages' }) }))
+	.get('/users/:id', ({ caches, params, reply }) => reply.ok(caches.users.get(params.id)));
+```
+
+| Export | Keys under `prefix: 'shop'` |
+| --- | --- |
+| `redisStore(handle, { name: 'api' })` | `shop:api:<limit>/<windowMs>:<key>`, `shop:api:policies` |
+| `redisCacheStore(handle, { name: 'pages' })` | `shop:pages:response:<key>`, `shop:pages:tag:<tag>` |
+| `idempotency(handle, { name: 'orders' })` | `shop:orders:<route>:<scope>:<Idempotency-Key>` |
+| `redis(handle)` | `shop:<cache name>:<key>`, `lock:shop:<key>` |
+
+The lock is `@nxgt/redis`'s, which writes `lock:` first and the prefix inside
+it. `redis(handle)` puts `redis` (the client), `caches`, `lock` and `prefix` in
+the context; `caches` is the handle's own `cache` scope, typed by each schema.
+
+**Closing.** `redis(handle)` closes the handle in core's `onStop`, once, after
+the requests in flight drained, so `listen`'s graceful shutdown ends with the
+connection closed. Opt out with `redis(handle, { close: false })` when
+something else owns the handle. The stores and `idempotency` never close it;
+an app that does not mount `redis(handle)` closes the handle itself. A
+`client` that `defineRedis` was given is never closed by `@nxgt/redis`.
+
+**Health.** `redisCheck(handle)` is a check for `health({ checks })`: it
+passes while every instance answers a `PING` and is down when one does not;
+given a handle, `{ timeout }` bounds each instance's ping, in milliseconds
+(2 s by default). It takes a bare client too, whose `PING` has no bound of
+its own: `health({ timeout })` bounds the check.
+
+**One instance.** The handle must wire exactly one Redis instance; a handle of
+several is refused with a `TypeError` naming them. Give a bare client,
+`handle.clients.<name>`, to the factory that lives on one of them, with the
+prefix in its `name`.
+
+**Defined once.** With `@nxgt/redis` 0.6 the rate limit and the idempotent
+operation can be wired by `defineRedis` too, and `redisStore` and `idempotency`
+take what it wired: [Defined once, in `defineRedis`](#defined-once-in-defineredis).
+
+**Switching from a bare client** changes the keys: a rate-limit count, a kept
+response or a replayable response written without the prefix is not found
+under it, and the new keys start empty.
+
+## Defined once, in `defineRedis`
+
+`defineRedis` takes `limits` and `idempotency` next to `caches`, and the handle
+exposes each as `handle.limits.<name>` and `handle.idempotency.<name>`, typed
+from the definitions and writing `<prefix>:<name>:<key>`, the layout every
+`@nxgt/redis` consumer of the deployment shares. Hand the wired entry to the
+store and to the middleware instead of a name:
+
+```ts
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { idempotency, idempotencyResult, redisStore } from '@alxia/redis';
+import { defineIdempotency, defineRateLimit, defineRedis, openRedis } from '@nxgt/redis';
+
+const api = defineRateLimit({ name: 'api', key: (ip: string) => ip, limit: 100, per: 60_000 });
+const orders = defineIdempotency({ name: 'orders', key: (id: string) => id, ttl: 86_400, schema: idempotencyResult });
+
+const handle = await openRedis(
+	defineRedis({ uri: Bun.env['REDIS_URL']!, prefix: 'shop', limits: { api }, idempotency: { orders } }),
+);
+
+const app = alxia()
+	.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(handle.limits.api) })) // shop:api:<address>
+	.use(idempotency(handle.idempotency.orders)) // shop:orders:<route>:<scope>:<key>
+	.post('/orders', ({ reply }) => reply(201, { id: crypto.randomUUID() }));
+```
+
+| Wired | Keys under `prefix: 'shop'` | Also written by |
+| --- | --- | --- |
+| `redisStore(handle.limits.api)` | `shop:api:<key>` | `handle.limits.api.consume(key)` anywhere |
+| `idempotency(handle.idempotency.orders)` | `shop:orders:<route>:<scope>:<Idempotency-Key>` | `idempotency(handle, { name: 'orders' })`: the same keys |
+
+What to know:
+
+- **The definition is the one place.** The name, `limit`, `per` and `burst` of
+  a rate limit, the name, `ttl` and `lease` of an idempotency, are the
+  definition's. `idempotency(handle.idempotency.orders)` takes the middleware's
+  options (`required`, `scope`, `wait`, `methods`, `header`) but not `name`,
+  `ttl` or `lease`: the types refuse them, and a script that passes them gets a
+  `TypeError`.
+- **The rate is the definition's, and `rateLimit` repeats it for its
+  headers.** The store counts by the wired limit's own rate, so `limit` and
+  `windowMs` on `rateLimit` only write `RateLimit-*`: give them the definition's
+  numbers.
+- **The limit counts by a string.** `rateLimit` counts by the string its `key`
+  returns, so the wired limit's key must take one, as `key: (ip: string) => ip`.
+  `redisStore(handle.limits.byIp)` for a limit keyed by `{ ip }` does not
+  compile.
+- **The idempotency keeps a response.** Its `schema` must be
+  `idempotencyResult`, the shape `@alxia/redis` stores (status, headers, body),
+  and its key must take a string; the middleware builds
+  `<route>:<scope>:<Idempotency-Key>` itself. Another schema does not compile.
+- **A guard bound by hand works too**: `redisStore(bindRateLimit(client, api))`,
+  with no prefix.
+- **Same name, one kind.** One name shared by a cache and a limit or an
+  idempotency on one instance is refused when the handle is wired:
+  [troubleshooting](../troubleshooting.md#typeerror-defineredis-instance-default-wires-the-cache-users-and-the-rate-limit-login-under-one-name-user-they-would-share-every-key-in-redis-give-one-of-them-a-name-of-its-own).
+- **Moving from the by-name form.** An idempotency keeps its keys. A rate limit
+  does not: the by-name store counts under `shop:api:<limit>/<windowMs>:<key>`,
+  the wired one under `shop:api:<key>`, so counts restart:
+  [troubleshooting](../troubleshooting.md#counts-restart-after-moving-a-rate-limit-to-the-wired-form).
+- **Both forms stay**, and need `@nxgt/redis` 0.6 only for `handle.limits` and
+  `handle.idempotency`: a limit or an idempotency bound by hand with 0.5 is
+  accepted the same.
+
 ## Naming keys
 
 Every export that writes takes a `name`, prepended to its keys, so several
@@ -155,7 +284,8 @@ apps and several features can share one Redis:
 | `idempotency(client, { name })` | `<name>:<route>:<scope>:<Idempotency-Key>` |
 | `redis(client, { caches })` | each cache's own `<name>:<key>`, and `lock:<key>` |
 
-Two features given the same `name` share their keys; give each its own.
+Two features given the same `name` share their keys; give each its own. Given a
+[handle](#with-an-nxgtredis-handle), each key also starts with its `prefix`.
 
 ## Next
 

package/docs/guide/idempotency.md

@@ -1,13 +1,13 @@
 # Idempotency
 
-This page covers `idempotency`: a plugin that runs a `POST` or `PATCH`
+This page covers `idempotency`: a middleware, given to `app.use`, that runs a `POST` or `PATCH`
 once per `Idempotency-Key`, replays its response to every repeat, and
 refuses the repeats it cannot answer — across every process sharing a
 Redis.
 
 ```ts
-import { alxia } from '@alxia/core';
-import { idempotency } from '@alxia/redis';
+import { alxia, validate } from '@alxia/core';
+import { idempotency, type IdempotencyErrorBody } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
 import { z } from 'zod';
 
@@ -16,7 +16,7 @@ const Payment = z.object({ amount: z.number().int().positive() });
 
 const app = alxia()
 	.use(idempotency(connection.client, { name: 'payments' }))
-	.post('/payments', { body: Payment }, ({ body, reply }) =>
+	.post('/payments', validate({ body: Payment }), ({ body, reply }) =>
 		reply(201, { id: crypto.randomUUID(), amount: body.amount }),
 	);
 ```
@@ -28,12 +28,15 @@ curl -X POST localhost:3000/payments -H 'idempotency-key: 4f1c' -H 'content-type
 # 201 {"id":"9a…","amount":10}     Idempotent-Replayed: true — the route did not run
 ```
 
-Only the routes declared **after** `use(idempotency(…))` are guarded.
+Only the routes declared **after** `use(idempotency(…))` are guarded. A request
+no route matches is not: there is no route to scope its key by, so it passes
+to the 404.
 
 ## The signature
 
 ```ts
-function idempotency(client: RedisClient, options: IdempotencyOptions);  // a plugin
+function idempotency(target: RedisClient | Redis<any>, options: IdempotencyOptions);  // a middleware
+function idempotency(wired: WiredIdempotency, options?: WiredIdempotencyOptions);   // wired by defineRedis
 
 interface IdempotencyOptions {
 	readonly name: string;
@@ -56,7 +59,7 @@ interface IdempotencyOptions {
 | `methods` | `readonly string[]` | `['POST', 'PATCH']` | the methods it guards; the others pass through |
 | `header` | `string` | `'idempotency-key'` | the request header the key is read from (any case) |
 | `required` | `boolean` | `false` | refuse a guarded request with no key, with a `400` |
-| `scope` | `(ctx: BaseContext) => string \| undefined` | `ctx.ip` | whose key it is; `undefined` scopes it to everyone |
+| `scope` | `(ctx: BaseContext) => string \| undefined` | `ctx.ip` | whose key it is; `undefined` leaves the request unguarded, with a warning |
 
 `name`, `ttl` and `lease` are checked when `idempotency(…)` is called, so a
 wrong one throws at startup:
@@ -71,6 +74,12 @@ TypeError: defineIdempotency: an idempotent operation needs a name, for its keys
 guarded request a `500`, logging
 `TypeError: run on "payments": wait is a whole number of milliseconds, 0 or more`.
 
+`idempotency(handle.idempotency.orders)` takes an idempotency wired by
+`defineRedis` instead: its definition holds the `name`, `ttl` and `lease`, and
+its `schema` is `idempotencyResult`. The options are the others of the table
+(`WiredIdempotencyOptions`). See
+[Defined once, in `defineRedis`](connecting.md#defined-once-in-defineredis).
+
 ## What each request gets
 
 | Request | Answer |
@@ -84,8 +93,9 @@ guarded request a `500`, logging
 | no key, without `required` | the route runs, unguarded |
 | a method not in `methods` | the route runs, unguarded |
 
-Every refusal is typed as `IdempotencyErrorBody` and is part of each
-guarded route's type, so `@alxia/client` reads it:
+Every refusal's body is an `IdempotencyErrorBody`; declare the statuses in
+your OpenAPI document, and the client you generate from it (with
+`@nxgt/openapi-codegen`, say) reads them typed:
 
 ```ts
 interface IdempotencyErrorBody {
@@ -100,9 +110,8 @@ interface IdempotencyErrorBody {
 ```
 
 ```ts
-import { client } from '@alxia/client';
-import { alxia } from '@alxia/core';
-import { idempotency } from '@alxia/redis';
+import { alxia, validate } from '@alxia/core';
+import { idempotency, type IdempotencyErrorBody } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
 import { z } from 'zod';
 
@@ -110,18 +119,19 @@ const connection = await connectRedis(Bun.env['REDIS_URL']!);
 
 const app = alxia()
 	.use(idempotency(connection.client, { name: 'payments', required: true }))
-	.post('/payments', { body: z.object({ amount: z.number() }) }, ({ body, reply }) =>
+	.post('/payments', validate({ body: z.object({ amount: z.number() }) }), ({ body, reply }) =>
 		reply(201, { id: crypto.randomUUID(), amount: body.amount }),
 	);
 
-const api = client(app);
-const result = await api.post('/payments', {
-	body: { amount: 10 },
-	init: { headers: { 'idempotency-key': crypto.randomUUID() } },
+const result = await app.request('/payments', {
+	method: 'POST',
+	headers: { 'content-type': 'application/json', 'idempotency-key': crypto.randomUUID() },
+	body: JSON.stringify({ amount: 10 }),
 });
-// result.status: 201 | 400 | 409 | 422 | 500
+// result.status: 201, or 400, 409, 422 from the guard, or 500
 if (result.status === 409) {
-	await Bun.sleep(result.data.retryAfter! * 1000);   // then send the same request again
+	const { retryAfter } = (await result.json()) as IdempotencyErrorBody;
+	await Bun.sleep(retryAfter! * 1000);   // then send the same request again
 }
 ```
 
@@ -150,7 +160,7 @@ gets the replay rather than the `409`:
 
 ```ts
 import { alxia } from '@alxia/core';
-import { idempotency } from '@alxia/redis';
+import { idempotency, type IdempotencyErrorBody } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
 
 const connection = await connectRedis(Bun.env['REDIS_URL']!);
@@ -165,15 +175,22 @@ const app = alxia()
 Clients choose their keys, so two clients can choose the same one. The
 stored key is `<name>:<route>:<scope>:<key>`, where `scope(ctx)` is the
 client's address by default. When it is `undefined` — no address, as with
-`app.request()` in a test or a server that cannot see one — the scope is
-`anyone`, and every client shares the key space.
+`app.request()` in a test or a server that cannot see one, and no `scope`
+option, or one that returns `undefined` — the request runs unguarded:
+nothing is stored, nothing replayed, and each repeat runs the route again.
+Sharing one key space between every client would replay one client's
+response to another. The middleware warns once:
+
+```
+idempotency "payments": no client scope could be derived (ctx.ip is undefined and no scope option returned one), so these requests run unguarded, nothing stored or replayed. Pass a scope option, (ctx) => a user id, or an ip option to alxia().
+```
 
 Behind a proxy, the address is the proxy's unless the app's `ip` option
 reads the forwarded header. Where requests carry a user, scope by the user:
 
 ```ts
 import { alxia } from '@alxia/core';
-import { idempotency } from '@alxia/redis';
+import { idempotency, type IdempotencyErrorBody } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
 
 const connection = await connectRedis(Bun.env['REDIS_URL']!);
@@ -197,9 +214,11 @@ is two keys.
 
 ## Order: what runs inside the guard
 
-The plugin wraps the routes declared after it, and every route hook
+The middleware wraps the routes declared after it, and every middleware
 declared after it too. Whatever those answer is kept like the route's
-answer. A rate limit or an authentication check declared **after**
+answer: so is what a try/catch middleware, an `HttpError` or a validation
+refusal answers, because `idempotency` settles the rest of the request before
+it keeps it. A rate limit or an authentication check declared **after**
 `idempotency` has its `429` or `401` kept and replayed — even once the
 client is allowed through. Declare them **before**:
 
@@ -222,6 +241,10 @@ Measured: with the rate limit after `idempotency`, a key refused with a
 had passed; with it before, the same repeat ran the route and answered
 `201`.
 
+Declared on the app, a rate limit or a guard also runs on a request no route
+matches, and answers it before `idempotency` is reached; that is not a
+concern here, since `idempotency` skips that request anyway.
+
 A route that refuses a request it might accept later — a `401` before the
 client signs in again, a `409` on a state that changes — should answer it
 before the guard, or the client should send a new key when it retries.
@@ -251,5 +274,5 @@ Yield (`await Bun.sleep(0)`) inside long synchronous work, or move it to a
 
 - [Rate limits](rate-limits.md) — `redisStore`.
 - [Testing](testing.md) — specs for a guarded route.
-- [`@nxgt/redis-guard`](https://www.npmjs.com/package/@nxgt/redis-guard) —
+- [`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis) —
   the primitive underneath, for idempotency outside HTTP.

package/docs/guide/rate-limits.md

@@ -28,7 +28,8 @@ bun add @alxia/rate-limit
 ## The signature
 
 ```ts
-function redisStore(client: RedisClient, options: RedisStoreOptions): RateLimitStore;
+function redisStore(target: RedisClient | Redis<any>, options: RedisStoreOptions): RateLimitStore;
+function redisStore(limit: BoundRateLimit<string>): RateLimitStore; // wired by defineRedis
 
 interface RedisStoreOptions {
 	/** Prepended to every key it counts: one name per limit, so two never share a count. */
@@ -46,6 +47,11 @@ interface RedisStoreOptions {
 `429 { error: 'rate_limited', retryAfter }` with `Retry-After`, the same as
 with the memory store.
 
+A limit wired by `defineRedis`, `redisStore(handle.limits.api)`, takes no
+`name`: its definition holds the name and the rate, and the keys are
+`<prefix>:<name>:<key>`, shared with every other `@nxgt/redis` consumer. See
+[Defined once, in `defineRedis`](connecting.md#defined-once-in-defineredis).
+
 ## What changes with Redis
 
 - **Every process counts together.** Behind a load balancer, a client gets
@@ -124,7 +130,7 @@ are the same count.
 `rateLimit` refuses a `limit` or a `windowMs` that is not a whole number of
 1 or more when it is created, with
 [`TypeError: rateLimit: … must be a whole number of 1 or more, not …`](https://github.com/softistx/alxia/blob/develop/packages/rate-limit/docs/troubleshooting.md#typeerror-ratelimit--must-be-a-whole-number-of-1-or-more-not-).
-`redisStore` checks two more bounds, `@nxgt/redis-guard`'s, only when it
+`redisStore` checks two more bounds, `@nxgt/redis`'s, only when it
 first counts under a policy, not when the app starts. A policy past either
 makes the first request it counts, and every one after it, a
 `500 {"error":"internal"}`, with the reason in the log — a refused policy
@@ -145,7 +151,7 @@ and [ten years](../troubleshooting.md#typeerror-defineratelimit--would-take-long
 `store.reset(key)` forgets a key — after a successful login, say:
 
 ```ts
-import { alxia } from '@alxia/core';
+import { alxia, validate } from '@alxia/core';
 import { rateLimit } from '@alxia/rate-limit';
 import { redisStore } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
@@ -158,7 +164,7 @@ const passwords = new Map([['ada', 'lovelace']]);
 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 }) => {
+		.post('/login', 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 });
 			}

package/docs/guide/response-cache.md

@@ -49,7 +49,7 @@ Everything else — `ttl`, `staleWhileRevalidate`, `key`, `vary`, `statuses`,
 
 - **A response** is one Redis string at `<name>:response:<key>`: an
   `@nxgt/redis` cache record holding the status, the headers, the body as
-  base64, and the plugin's `storedAt`, `ttl` and `stale`. Redis expires it
+  base64, and the cache's `storedAt`, `ttl` and `stale`. Redis expires it
   when `ttl + staleWhileRevalidate` has passed, rounded up to the second.
 - **A tag** is a Redis set at `<name>:tag:<tag>`, of the response keys it
   names. Besides your tags, every response carries `alxia:path:<path>` —
@@ -77,7 +77,7 @@ process sharing it misses on its next request:
 
 ```ts
 import { cache } from '@alxia/cache';
-import { alxia } from '@alxia/core';
+import { alxia, validate } from '@alxia/core';
 import { redisCacheStore } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
 import { z } from 'zod';
@@ -90,7 +90,7 @@ const store = redisCacheStore(connection.client, { name: 'shop' });
 const products = cache({ ttl: 60, staleWhileRevalidate: 300, store, tags: () => ['products'] });
 
 const app = alxia()
-	.post('/products', { body: Product }, async ({ body, reply }) => {
+	.post('/products', validate({ body: Product }), async ({ body, reply }) => {
 		catalogue.set(body.id, body);
 		await products.invalidateTag('products');      // forgotten in every process
 		return reply(201, body);

package/docs/guide/testing.md

@@ -61,8 +61,9 @@ it, as below.
 ## Give each test a client address
 
 `app.request()` has no socket, so `ctx.ip` is `undefined`. A rate limit
-then counts nothing, and idempotency scopes every key to `anyone`. Pass the
-app an `ip` that answers, as above, or one per test to stand for two
+then counts nothing, and idempotency guards nothing: each request runs, and
+it warns once that no client scope could be derived. Pass the app an `ip`
+that answers, as above, or one per test to stand for two
 clients:
 
 ```ts
@@ -87,14 +88,13 @@ test('two processes share one count', async () => {
 });
 ```
 
-## Typed refusals
+## Refusals behind the middleware only
 
-The `409`, `422` and `400` of `idempotency` are part of each guarded route's
-type. `@alxia/client` and `expectTypeOf` pin them, with no Redis call:
+The `409`, `422` and `400` of `idempotency` are answered by the routes
+declared after it alone, never by a request no route matches. Send a key it refuses to both:
 
 ```ts
-import { expect, expectTypeOf, test } from 'bun:test';
-import { client } from '@alxia/client';
+import { expect, test } from 'bun:test';
 import { alxia } from '@alxia/core';
 import { idempotency } from '@alxia/redis';
 import { connectRedis } from '@nxgt/redis';
@@ -106,13 +106,10 @@ const app = alxia()
 	.use(idempotency(connection.client, { name: 'payments' }))
 	.post('/payments', ({ reply }) => reply(201, 'ok'));
 
-test('only the routes after the plugin carry its refusals', () => {
-	const types = async () => {
-		const api = client(app);
-		expectTypeOf((await api.post('/payments')).status).toEqualTypeOf<201 | 400 | 409 | 422 | 500>();
-		expectTypeOf((await api.post('/open')).status).toEqualTypeOf<201 | 500>();
-	};
-	expect(types).toBeFunction();
+test('only the routes after the middleware refuse a bad key', async () => {
+	const init = { method: 'POST', headers: { 'idempotency-key': 'not a key' } };
+	expect((await app.request('/payments', init)).status).toBe(400);
+	expect((await app.request('/open', init)).status).toBe(201);
 });
 ```