@alxia/redis 0.1.0

package/docs/README.md

@@ -0,0 +1,18 @@
+# @alxia/redis documentation
+
+The [package README](../README.md) is the short version. This folder is
+the long one: a guide page per area, with the options, defaults, errors and
+a realistic example for each.
+
+## Guide
+
+| 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 |
+| [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 |
+| [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 |

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

@@ -0,0 +1,204 @@
+# Caches and locks
+
+This page covers `redis`: a plugin that puts the client, typed caches and a
+lock in the context of every route declared after it.
+
+```ts
+import { alxia } from '@alxia/core';
+import { redis } from '@alxia/redis';
+import { connectRedis, defineCache } from '@nxgt/redis';
+import { z } from 'zod';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const User = z.object({ id: z.string(), name: z.string() });
+const users = defineCache({ name: 'user', key: (id: string) => id, ttl: 300, schema: User });
+
+const loadUser = async (id: string) => ({ id, name: 'Ada' });   // your database
+
+const app = alxia()
+	.use(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);
+	});
+```
+
+## The signature
+
+```ts
+function redis<Caches>(client: RedisClient, options?: RedisContextOptions<Caches>);  // a plugin
+
+interface RedisContextOptions<Caches> {
+	/** `@nxgt/redis` cache definitions, by the name routes read them under. */
+	readonly caches?: Caches;
+}
+
+/** What routes after `redis()` read. */
+interface RedisContext<Caches> {
+	readonly redis: RedisClient;
+	readonly caches: BoundCaches<Caches>;
+	lock<T>(key: string, work: () => Promise<T> | T, options?: LockOptions): Promise<T>;
+}
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `caches` | `Record<string, CacheDefinition>` | none | each definition, bound to the client once, under `ctx.caches.<name>` |
+
+| In the context | What it is |
+| --- | --- |
+| `redis` | Bun's `RedisClient`, untouched: every command Bun has |
+| `caches.<name>` | the `@nxgt/redis` `BoundCache` of that definition, typed by its schema |
+| `lock(key, work, options?)` | `@nxgt/redis`'s `withLock`: `work` under a lock every process respects |
+
+The caches are bound when `redis(…)` is called, not per request.
+
+## Caches
+
+A cache is described with `defineCache` from `@nxgt/redis` — a `name`, a
+`key` function, a `ttl` in **seconds**, and a zod `schema` — and read under
+the name you give it in `caches`:
+
+| `caches.<name>` | |
+| --- | --- |
+| `get(params)` | the value, or `undefined`: a miss, an expiry, or a stored value the schema no longer accepts |
+| `set(params, value, { ttl }?)` | checks `value` against the schema, then stores it |
+| `remember(params, load, { ttl }?)` | the value if it is there; otherwise what `load` gives, stored |
+| `delete(params)` | `true` when something was there |
+| `keyFor(params)` | the Redis key it uses: `<name>:<key(params)>` |
+
+A realistic case, a profile read through the cache and forgotten on write:
+
+```ts
+import { alxia } from '@alxia/core';
+import { redis } from '@alxia/redis';
+import { connectRedis, defineCache } from '@nxgt/redis';
+import { z } from 'zod';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const Profile = z.object({ id: z.string(), name: z.string(), plan: z.enum(['free', 'pro']).default('free') });
+const profiles = defineCache({ name: 'profile', key: (id: string) => id, ttl: 600, schema: Profile });
+const table = new Map<string, z.input<typeof Profile>>([['1', { id: '1', name: 'Ada' }]]);
+
+const app = alxia()
+	.use(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 }) => {
+		table.set(params.id, { id: params.id, ...body });
+		await caches.profiles.delete(params.id);          // the next read loads it again
+		return reply(204, undefined);
+	});
+```
+
+`remember` holds no lock: two requests missing at once both call `load`.
+Wrap it in `lock` where loading is expensive or must happen once. The
+caches' errors, their schemas and their traps are `@nxgt/redis`'s: see its
+documentation.
+
+## Locks
+
+`lock(key, work, options?)` takes `lock:<key>` in Redis, runs `work`, and
+releases the lock — only if it still holds it.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `ttl` | `number` | `30_000` | **milliseconds** the lock is held before Redis drops it |
+| `wait` | `number` | `0` | milliseconds to keep trying to take a held lock |
+| `retryDelay` | `number` | `50` | milliseconds between tries |
+
+A lock that is held, or that expires before `work` returns, throws a
+`RedisError`. Uncaught, the route answers `500 {"error":"internal"}`; catch
+it to answer something better:
+
+```ts
+import { alxia } from '@alxia/core';
+import { redis } from '@alxia/redis';
+import { connectRedis, RedisError } from '@nxgt/redis';
+
+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))
+	.post('/invoices/run', async ({ lock, reply }) => {
+		try {
+			const sent = await lock('invoices', sendInvoices, { ttl: 60_000 });
+			return reply(200, { sent });
+		} catch (error) {
+			if (error instanceof RedisError && error.code === 'LOCK_HELD') {
+				return reply(409, { error: 'already_running' as const });
+			}
+			throw error;
+		}
+	});
+```
+
+| `error.code` | When | Message |
+| --- | --- | --- |
+| `LOCK_HELD` | someone else holds it, and `wait` ran out | ``The lock "invoices" is held by somebody else, and this call did not wait for it — pass `wait` to keep trying`` |
+| `LOCK_LOST` | `work` returned after `ttl` had passed | `The lock "invoices" expired before its work finished: it ran longer than the 60000ms ttl, so it may have run beside another holder` |
+
+`LOCK_HELD` means nothing ran. `LOCK_LOST` means `work` did run, possibly
+beside another holder: size `ttl` above the slowest run you accept.
+
+## The client
+
+`redis` is Bun's `RedisClient`, for every command the plugin does not wrap:
+
+```ts
+import { alxia } from '@alxia/core';
+import { redis } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const app = alxia()
+	.use(redis(connection.client))
+	.post('/articles/:id/views', async ({ redis, params, reply }) => {
+		const views = await redis.incr(`views:${params.id}`);
+		return reply(200, { views });
+	});
+```
+
+## With `@alxia/cache`
+
+`@alxia/cache`'s `cache()` adds `cache` to the context — the response
+cache's `{ tag, skip }`. `redis()` adds `caches`, so the two sit side by side
+on one route, declared in either order:
+
+```ts
+import { cache } from '@alxia/cache';
+import { alxia } from '@alxia/core';
+import { redis } from '@alxia/redis';
+import { connectRedis, defineCache } from '@nxgt/redis';
+import { z } from 'zod';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+const users = defineCache({ name: 'user', key: (id: string) => id, ttl: 300, schema: z.object({ id: z.string(), name: z.string() }) });
+const loadUser = async (id: string) => ({ id, name: 'Ada' });
+
+const app = alxia()
+	.use(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
+		return reply.ok(await caches.users.remember(params.id, () => loadUser(params.id)));   // the Redis cache
+	});
+```
+
+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.
+
+## Next
+
+- [Connecting](connecting.md) — the client, and closing it.
+- [Testing](testing.md) — a route with a cache, in a spec.
+- [`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis) — caches,
+  locks and pub/sub in full.

package/docs/guide/connecting.md

@@ -0,0 +1,165 @@
+# 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
+how to close it.
+
+```ts
+import { alxia } from '@alxia/core';
+import { redis } from '@alxia/redis';
+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))
+	.get('/ping', async ({ redis, reply }) => reply(200, await redis.ping()));
+
+app.listen({ port: 3000 });
+```
+
+## The client
+
+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
+```
+
+Any `RedisClient` will do. `connectRedis` from
+[`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis) is the usual
+way: it shares one client per URI across the process, connects it once
+even when two calls race, and gives back a `RedisConnection` with
+`client`, `ping()` and `close()`. A client you open yourself works the
+same:
+
+```ts
+import { redisStore } from '@alxia/redis';
+import { RedisClient } from 'bun';
+
+const client = new RedisClient(Bun.env['REDIS_URL']);
+const store = redisStore(client, { name: 'api' });
+```
+
+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
+
+Each export binds the client it is given when it is called. Open the
+connection first, then build the app:
+
+```ts
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { idempotency, redisStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const app = alxia()
+	.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(connection.client, { name: 'api' }) }))
+	.use(idempotency(connection.client, { name: 'orders' }))
+	.post('/orders', ({ reply }) => reply(201, { id: crypto.randomUUID() }));
+```
+
+In a test, that means building the app in `beforeAll`, once Redis is up —
+see [Testing](testing.md).
+
+## When Redis is down
+
+`@alxia/redis` does not catch Redis's errors. A command that fails while a
+request runs fails that request: the app answers
+`500 {"error":"internal"}` and logs Bun's error, code
+`ERR_REDIS_CONNECTION_CLOSED`: `Max reconnection attempts reached` for the
+first command once Bun's client has given up reconnecting, then
+`Connection has failed` for the ones after it
+([troubleshooting](../troubleshooting.md#rediserror-connection-has-failed)).
+A short outage recovers on its own while the client is still retrying;
+after it has given up, do not count on it coming back — restart the process.
+There is no fail-open mode: a rate limit that cannot count does not let the
+request through, and an idempotent route that cannot take its key does not
+run. The response cache is the exception, as `@alxia/cache` decides it: a
+cached route whose `redisCacheStore` cannot answer runs and answers
+`X-Cache: MISS`, with the outage's first error logged; only its
+invalidations reject.
+
+At startup, Bun's client reconnects by default, so a `connectRedis` to a
+server that is not there keeps trying for about half a minute before it
+rejects. For a check that should fail at once, pass `autoReconnect: false`:
+
+```ts
+import { connectRedis } from '@nxgt/redis';
+
+try {
+	const check = await connectRedis(Bun.env['REDIS_URL']!, { autoReconnect: false });
+	await check.close();
+} catch (error) {
+	console.error('Redis is not reachable', error);
+	process.exit(1);
+}
+```
+
+`connectRedis` shares one client per URI, so every later call for the same
+URI must pass the same options, or it throws
+`TypeError: connectRedis: this URI is already connected with other options. Pass the same options everywhere, or close the first connection.` Close the
+check before the app connects, as above, or pass the same options
+everywhere.
+
+`connection.ping()` never throws, and is a health route in one line:
+
+```ts
+import { alxia } from '@alxia/core';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const app = alxia().get('/health', async ({ reply }) => {
+	const redis = await connection.ping();
+	return redis.ok ? reply(200, { redis: 'up', ms: redis.latencyMs }) : reply(503, { redis: 'down' });
+});
+```
+
+## Closing
+
+Nothing here listens to a signal. Close the connection when the process
+stops:
+
+```ts
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+process.on('SIGTERM', async () => {
+	await connection.close();
+	process.exit(0);
+});
+```
+
+`closeRedis()` from `@nxgt/redis` closes every client the process opened
+through `connectRedis` — the end of a test file, say.
+
+## Naming keys
+
+Every export that writes takes a `name`, prepended to its keys, so several
+apps and several features can share one Redis:
+
+| Export | Keys it writes |
+| --- | --- |
+| `redisStore(client, { name })` | `<name>:<limit>/<windowMs>:<key>`, and `<name>:policies` |
+| `redisCacheStore(client, { name })` | `<name>:response:<key>`, and `<name>:tag:<tag>`, which expires with its longest-kept response |
+| `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.
+
+## Next
+
+- [Rate limits](rate-limits.md) — `redisStore`.
+- [Response cache](response-cache.md) — `redisCacheStore`.
+- [Idempotency](idempotency.md) — `idempotency`.
+- [Caches and locks](caches-and-locks.md) — `redis`.

package/docs/guide/idempotency.md

@@ -0,0 +1,255 @@
+# Idempotency
+
+This page covers `idempotency`: a plugin 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 { connectRedis } from '@nxgt/redis';
+import { z } from 'zod';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+const Payment = z.object({ amount: z.number().int().positive() });
+
+const app = alxia()
+	.use(idempotency(connection.client, { name: 'payments' }))
+	.post('/payments', { body: Payment }, ({ body, reply }) =>
+		reply(201, { id: crypto.randomUUID(), amount: body.amount }),
+	);
+```
+
+```sh
+curl -X POST localhost:3000/payments -H 'idempotency-key: 4f1c' -H 'content-type: application/json' -d '{"amount":10}'
+# 201 {"id":"9a…","amount":10}
+curl -X POST localhost:3000/payments -H 'idempotency-key: 4f1c' -H 'content-type: application/json' -d '{"amount":10}'
+# 201 {"id":"9a…","amount":10}     Idempotent-Replayed: true — the route did not run
+```
+
+Only the routes declared **after** `use(idempotency(…))` are guarded.
+
+## The signature
+
+```ts
+function idempotency(client: RedisClient, options: IdempotencyOptions);  // a plugin
+
+interface IdempotencyOptions {
+	readonly name: string;
+	readonly ttl?: number;
+	readonly lease?: number;
+	readonly wait?: number;
+	readonly methods?: readonly string[];
+	readonly header?: string;
+	readonly required?: boolean;
+	readonly scope?: (ctx: BaseContext) => string | undefined;
+}
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | required | the prefix of every key it stores |
+| `ttl` | `number` | `86_400` (a day) | **seconds** a finished response is replayed. A whole number, at least 1 |
+| `lease` | `number` | `10_000` | **milliseconds** a running request holds its key unless renewed; renewed every third of it while the route runs. A whole number, at least 1 |
+| `wait` | `number` | `0` | **milliseconds** a repeat waits for a running first request before its `409`. A whole number, 0 or more |
+| `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 |
+
+`name`, `ttl` and `lease` are checked when `idempotency(…)` is called, so a
+wrong one throws at startup:
+
+```text
+TypeError: defineIdempotency: "payments" has a ttl of 1.5; it is a whole number of seconds, and must be at least 1
+TypeError: defineIdempotency: "payments" has a lease of 500.5; it is a whole number of milliseconds, and must be at least 1
+TypeError: defineIdempotency: an idempotent operation needs a name, for its keys
+```
+
+`wait` is checked on the first guarded request: a wrong one makes every
+guarded request a `500`, logging
+`TypeError: run on "payments": wait is a whole number of milliseconds, 0 or more`.
+
+## What each request gets
+
+| Request | Answer |
+| --- | --- |
+| a guarded method with a new key | the route runs; its response is kept and sent |
+| the same key, method, path, query and body again, within `ttl` | the first response — status, headers, body — with `Idempotent-Replayed: true`; the route does not run |
+| the same key while the first still runs | `409 { error: 'idempotency_in_progress', retryAfter }`, with `Retry-After` — after up to `wait` ms |
+| the same key with another method, path, query or body | `422 { error: 'idempotency_key_reused' }` |
+| a key that is not 1 to 255 printable ASCII characters (no space) | `400 { error: 'idempotency_key_invalid' }` |
+| no key, with `required: true` | `400 { error: 'idempotency_key_missing' }` |
+| 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:
+
+```ts
+interface IdempotencyErrorBody {
+	readonly error:
+		| 'idempotency_key_missing'
+		| 'idempotency_key_invalid'
+		| 'idempotency_in_progress'
+		| 'idempotency_key_reused';
+	/** Seconds until a running request should be over: with `idempotency_in_progress`. */
+	readonly retryAfter?: number;
+}
+```
+
+```ts
+import { client } from '@alxia/client';
+import { alxia } from '@alxia/core';
+import { idempotency } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+import { z } from 'zod';
+
+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 }) =>
+		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() } },
+});
+// result.status: 201 | 400 | 409 | 422 | 500
+if (result.status === 409) {
+	await Bun.sleep(result.data.retryAfter! * 1000);   // then send the same request again
+}
+```
+
+### What is replayed
+
+The status, every header but `Set-Cookie`, `Date` and `Content-Length`,
+and the body, byte for byte. A cookie belongs to the response that set it:
+a repeat never receives a session.
+
+### What is not kept
+
+- **A `5xx`** — a thrown error included — is answered and not kept: the key
+  is free again, and the next repeat runs the route.
+- **A `text/event-stream` response** is answered and not kept.
+- **Everything else is kept**, `4xx` included: a `400`, a `401`, a `404`
+  or a `429` answered under a key is replayed to every repeat for `ttl`
+  seconds — see [Order](#order-what-runs-inside-the-guard) below.
+
+### `409` and `Retry-After`
+
+`retryAfter` is when the running request's lease lapses **unless it is
+renewed**, rounded up to the second — 10 by default, however short the
+route actually is. A client that waits that long and repeats gets the
+replay. With `wait`, the repeat waits on the server instead, and usually
+gets the replay rather than the `409`:
+
+```ts
+import { alxia } from '@alxia/core';
+import { idempotency } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const app = alxia()
+	.use(idempotency(connection.client, { name: 'orders', wait: 2_000 }))   // keep it under your HTTP timeout
+	.post('/orders', async ({ reply }) => reply(201, { id: crypto.randomUUID() }));
+```
+
+## Scope: whose key it is
+
+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.
+
+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 { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const app = alxia({ ip: (request) => request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() })
+	.use(
+		idempotency(connection.client, {
+			name: 'payments',
+			scope: ({ request }) => request.headers.get('x-user-id') ?? undefined,
+		}),
+	)
+	.post('/payments', ({ reply }) => reply(201, { ok: true }));
+```
+
+`scope` receives `BaseContext` — `request`, `url`, `ip`, `route` and the
+rest — not what an earlier `derive` added; read the user from the request.
+Read the forwarded header only behind a proxy you trust.
+
+A key is also scoped by route: the same key on `/payments` and `/refunds`
+is two keys.
+
+## Order: what runs inside the guard
+
+The plugin wraps the routes declared after it, and every route hook
+declared after it too. Whatever those answer is kept like the route's
+answer. 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**:
+
+```ts
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { idempotency, redisStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const app = alxia()
+	.use(rateLimit({ limit: 10, windowMs: 60_000, store: redisStore(connection.client, { name: 'pay' }) }))  // its 429 is never kept
+	.use(idempotency(connection.client, { name: 'payments' }))
+	.post('/payments', ({ reply }) => reply(201, { ok: true }));
+```
+
+Measured: with the rate limit after `idempotency`, a key refused with a
+`429` answered `429` again, `Idempotent-Replayed: true`, after the window
+had passed; with it before, the same repeat ran the route and answered
+`201`.
+
+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.
+
+## The fingerprint
+
+The first request's method, path, query and raw body are hashed and stored
+with the key. A repeat whose hash differs is the `422`. Headers are not
+part of it: a repeat with another `Authorization` and the same body is a
+replay, within the same scope.
+
+## When the route outlives its lease
+
+The lease is renewed by a timer while the route runs. A route that blocks
+the event loop — a synchronous loop, `Bun.sleepSync` — cannot renew it:
+after a whole `lease`, a repeat can take the key and run the route again,
+and the first request ends in a `500`, logging
+
+```text
+GuardError: run on "payments": the key was taken from this run before it finished (forgotten, or its lease of 10000ms went unrenewed), so a repeat may have run it too; its result was not stored
+```
+
+Yield (`await Bun.sleep(0)`) inside long synchronous work, or move it to a
+`Worker`.
+
+## Next
+
+- [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) —
+  the primitive underneath, for idempotency outside HTTP.