@alxia/redis 0.2.0 → 0.4.0

package/docs/README.md

@@ -8,7 +8,7 @@ a realistic example for each.
 
 | Page | Read it when |
 | --- | --- |
-| [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, 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 |
@@ -16,3 +16,11 @@ a realistic example for each.
 | [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

@@ -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

@@ -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({ store: redisStore(handle.limits.api, api) })) // shop:api:<address>, 100 per 60 s from `api`
+	.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

@@ -35,7 +35,8 @@ to the 404.
 ## The signature
 
 ```ts
-function idempotency(client: RedisClient, options: IdempotencyOptions);  // a middleware
+function idempotency(target: RedisClient | Redis<any>, options: IdempotencyOptions);  // a middleware
+function idempotency(wired: WiredIdempotency, options?: WiredIdempotencyOptions);   // wired by defineRedis
 
 interface IdempotencyOptions {
 	readonly name: string;
@@ -73,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 |
@@ -209,7 +216,7 @@ is two keys.
 
 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: so is what an `onError` hook, an `HttpError` or a validation
+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
@@ -267,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,9 @@ 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
+function redisStore(limit: BoundRateLimit<string>, definition: RateLimitDefinition<string>): PolicyStore; // and its policy
 
 interface RedisStoreOptions {
 	/** Prepended to every key it counts: one name per limit, so two never share a count. */
@@ -46,6 +48,34 @@ 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).
+
+### The rate, written once
+
+`@nxgt/redis` 0.6 does not expose a bound limit's rate, so a store of the
+bound limit alone cannot tell `rateLimit` what it counts by, and `limit` and
+`windowMs` repeat the definition for the headers. Give the definition as the
+second argument and the store declares it as its `policy`:
+
+```ts
+const api = defineRateLimit({ name: 'api', key: (ip: string) => ip, limit: 100, per: 60_000 });
+const handle = await openRedis(defineRedis({ uri, prefix: 'shop', limits: { api } }));
+
+app.use(rateLimit({ store: redisStore(handle.limits.api, api) })); // 100 per 60 s
+```
+
+`rateLimit` reads `limit` (the definition's `limit`) and `windowMs` (its
+`per`) from the policy: the 429 and the `RateLimit-Limit`, `-Remaining`,
+`-Reset` and `-Policy` headers come from the definition, and one place holds
+the numbers. A `limit` or `windowMs` given too must equal them, or
+`rateLimit()` throws at declaration. A definition that is not the one that
+wired the limit — another `name` — is a `TypeError` from `redisStore`.
+The definition's `burst`, when it sets one, still governs how many requests
+pass at once; the policy states `limit` per `per`.
+
 ## What changes with Redis
 
 - **Every process counts together.** Behind a load balancer, a client gets
@@ -124,7 +154,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

package/docs/roadmap.md

@@ -7,10 +7,8 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-- **`idempotency` as a middleware.** `app.use(idempotency(client, { name }))` is
-  the form; `app.plugin(idempotency(…))` keeps working, deprecated. It skips a
-  request no route matches, and keeps what the route answers, an error's
-  answer included. `redis()` stays a plugin.
+Nothing in progress: `idempotency` as a middleware, the last change planned,
+shipped in 0.2.0 and finished in 0.3.0.
 
 ## Next
 
@@ -23,14 +21,64 @@ Nothing scheduled yet.
 ## Not planned
 
 - **A second Redis implementation.** `@alxia/redis` is an adapter over
-  [`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis) and
-  [`@nxgt/redis-guard`](https://www.npmjs.com/package/@nxgt/redis-guard),
-  never a rewrite of them: their scripts, keys and errors are what it runs.
+  [`@nxgt/redis`](https://www.npmjs.com/package/@nxgt/redis),
+  never a rewrite of it: its scripts, keys and errors are what it runs.
   They run on Bun's built-in `RedisClient`, so there is no driver to
   install, and it does not run on Node.
 
 ## Shipped
 
+### 0.4.0: the rate, written once
+
+- **A rate limit that reads its policy from the store.**
+  `redisStore(handle.limits.api, api)`, given the definition beside the wired
+  limit, declares the definition's `limit` and `per` as the store's `policy`;
+  `rateLimit({ store })` takes `limit` and `windowMs` from it (optional in the
+  type, with `@alxia/rate-limit` 0.4) and writes its `RateLimit-*` headers
+  from it, and numbers that differ throw at declaration. `redisStore` returns
+  a `PolicyStore`. The one-argument form stays, with its numbers repeated.
+  (`@nxgt/redis` 0.6 does not expose a bound limit's rate, hence the
+  definition as an argument.)
+
+### 0.3.0, continued: wired guards
+
+- **On `@nxgt/redis` 0.6.** The peer range is `^0.5.0 || ^0.6.0`: the new forms
+  need no more than 0.5's types, and 0.6 only adds `handle.limits` and
+  `handle.idempotency` to wire them.
+- **A rate limit and an idempotency defined once.** `redisStore(handle.limits.api)`
+  and `idempotency(handle.idempotency.orders)` take what `defineRedis`
+  wired, so the definition lives in one place and writes the keys
+  `@nxgt/redis` writes, `<prefix>:<name>:<key>`: every consumer of the handle
+  shares the count. `idempotencyResult` is the schema of the wired idempotency.
+  Both older forms stay.
+
+### 0.3.0
+
+- **On `@nxgt/redis` 0.5 alone.** The rate limits and the idempotency that
+  `@nxgt/redis-guard` held live in `@nxgt/redis` now, and `@nxgt/redis-guard`
+  is no longer a peer.
+- **One form for `idempotency`.** The middleware's type is a plain
+  `(ctx, next)` function, and `app.plugin(idempotency(…))`, deprecated in
+  0.2.0, is gone: give it to `use(…)`.
+- **An `@nxgt/redis` handle everywhere.** `redis(handle)` takes the handle
+  `openRedis(defineRedis({ … }))` gives: typed `caches` from its scopes, a
+  `lock` and every key under its `prefix`, and the handle closed once in
+  `onStop`, after the drain (`{ close: false }` to opt out). `redisStore`,
+  `redisCacheStore` and `idempotency` take it where they take a client and
+  put its prefix in front of their keys, and `redisCheck` is a readiness
+  check for `health()`. The bare `RedisClient` forms are unchanged.
+
+### 0.2.0
+
+- **Middlewares, under the same names.** `app.use(idempotency(client, …))`
+  replaces `app.plugin(idempotency(…))`, which stayed, deprecated, until 0.3.0;
+  `IdempotencyMiddleware` is the type it returns. A request no route matches
+  passes through it, never kept.
+- **A client no one can tell apart is not shared.** A request with no
+  `ctx.ip` and no `scope` runs unguarded, nothing stored or replayed, and
+  the middleware warns once, instead of keying every such client to
+  `anyone`, where one could be replayed another's response.
+
 ### 0.1.0
 
 - **A rate limit every process shares.** `redisStore` is an

package/docs/troubleshooting.md

@@ -2,9 +2,10 @@
 
 Each entry is headed by the text you see: a TypeScript error, an exception
 at startup, an exception in the log beside a `500 {"error":"internal"}`, or
-the response a client got. `@alxia/redis` throws nothing of its own: the
-messages are `@nxgt/redis`'s, `@nxgt/redis-guard`'s and Bun's, and it lets
-each through. It prints one warning of its own, under
+the response a client got. `@alxia/redis` throws almost nothing of its own: the
+messages are `@nxgt/redis`'s and Bun's, and it lets
+each through; its own refusals, a handle of several instances, a wired guard given a
+`name`, `ttl` or `lease`, or a client given without a `name`, say what to pass instead. It prints one warning of its own, under
 [Runtime: a warning in the log](#runtime-a-warning-in-the-log). What prints nothing is under [Traps](#traps), by symptom.
 
 **Install and types**
@@ -20,8 +21,13 @@ each through. It prints one warning of its own, under
 - [`TypeError: defineIdempotency: "…" has a lease of …; it is a whole number of milliseconds, and must be at least 1`](#typeerror-defineidempotency--has-a-lease-of--it-is-a-whole-number-of-milliseconds-and-must-be-at-least-1)
 - [`TypeError: defineIdempotency: an idempotent operation needs a name, for its keys`](#typeerror-defineidempotency-an-idempotent-operation-needs-a-name-for-its-keys)
 - [`RedisError: Connection closed`](#rediserror-connection-closed)
+- [`TypeError: redisStore: the definition "…" is not the one that wired this limit`](#typeerror-redisstore-the-definition--is-not-the-one-that-wired-this-limit)
 - [`TypeError: connectRedis: this URI is already connected with other options. Pass the same options everywhere, or close the first connection.`](#typeerror-connectredis-this-uri-is-already-connected-with-other-options-pass-the-same-options-everywhere-or-close-the-first-connection)
 
+- [`TypeError: @alxia/redis: this @nxgt/redis handle wires N Redis instances (…), and one is needed.`](#typeerror-alxiaredis-this-nxgtredis-handle-wires-n-redis-instances--and-one-is-needed)
+- [`TypeError: defineRedis: instance "default" wires no cache, no channel, no rate limit and no idempotency. Pass the module that exports them, or drop the instance.`](#typeerror-defineredis-instance-default-wires-no-cache-no-channel-no-rate-limit-and-no-idempotency-pass-the-module-that-exports-them-or-drop-the-instance)
+- [`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.`](#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)
+
 **Runtime: a 500, with this in the log**
 
 - [`TypeError: defineRateLimit: "…" has a burst of … and a per of …ms; burst × per must be at most 9007199254740 for the script to count exactly`](#typeerror-defineratelimit--has-a-burst-of--and-a-per-of-ms-burst--per-must-be-at-most-9007199254740-for-the-script-to-count-exactly)
@@ -55,6 +61,9 @@ each through. It prints one warning of its own, under
 - [Two limits count each other's requests](#two-limits-count-each-others-requests)
 - [A `401` or a `429` is replayed, with `Idempotent-Replayed: true`, after the client fixed it](#a-401-or-a-429-is-replayed-with-idempotent-replayed-true-after-the-client-fixed-it)
 - [One client gets another client's response](#one-client-gets-another-clients-response)
+- [Counts and kept responses vanish after moving to a handle with a `prefix`](#counts-and-kept-responses-vanish-after-moving-to-a-handle-with-a-prefix)
+- [Counts restart after moving a rate limit to the wired form](#counts-restart-after-moving-a-rate-limit-to-the-wired-form)
+- [The handle is closed while something still uses it](#the-handle-is-closed-while-something-still-uses-it)
 
 ## Install and types
 
@@ -222,6 +231,80 @@ await check.close();
 const connection = await connectRedis(Bun.env['REDIS_URL']!);
 ```
 
+### `TypeError: @alxia/redis: this @nxgt/redis handle wires N Redis instances (…), and one is needed.`
+
+**When:** a handle wiring several instances is given to `redis()`,
+`redisStore`, `redisCacheStore`, `idempotency` or `redisCheck`, at startup.
+
+**Why:** the keys of one deployment live on one Redis; which of several is
+meant is not guessed.
+
+**Fix:** give the bare client of the one, with the prefix in the `name`:
+
+```ts
+redisStore(handle.clients.cache, { name: 'shop:api' });
+```
+
+or wire one instance per handle.
+
+### `TypeError: defineRedis: instance "default" wires no cache, no channel, no rate limit and no idempotency. Pass the module that exports them, or drop the instance.`
+
+**When:** `defineRedis({ uri, prefix })` is written only to give the stores
+and `idempotency` a prefix. `@nxgt/redis` 0.5 said `wires no cache and no
+channel`; 0.6 counts the rate limits and the idempotency it can now wire too.
+
+**Why:** `@nxgt/redis` refuses a handle that wires nothing.
+
+**Fix:** wire at least one of the four on it: a cache, which `redis(handle)`
+then puts in the context as `caches`, a channel, a rate limit or an idempotency:
+
+```ts
+defineRedis({ uri, prefix: 'shop', caches: { users } });
+defineRedis({ uri, prefix: 'shop', limits: { api } });
+```
+
+### `TypeError: redisStore: the definition "…" is not the one that wired this limit`
+
+**When:** `redisStore(handle.limits.api, other)` is given a definition whose
+`name` is not the one `handle.limits.api` was wired from. The message adds the
+key the limit counts under:
+
+```text
+TypeError: redisStore: the definition "other" is not the one that wired this limit (it counts under "shop:api:probe")
+```
+
+**Why:** the definition gives `rateLimit` its `limit` and `windowMs`, and a
+definition of another limit would write headers for a rate Redis does not
+count by. A bound limit's keys are `<prefix>:<name>:<key>`, which is how the
+store checks the pair.
+
+**Fix:** give the definition `handle.limits.api` was wired from:
+
+```ts
+app.use(rateLimit({ store: redisStore(handle.limits.api, api) }));
+```
+
+### `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.`
+
+**When:** the `defineRedis(...)` of an app that gives `caches`, `limits` and
+`idempotency` one `name` on one instance: here the cache exported as `users`
+and the rate limit exported as `login`, both named `user`. The sentence says
+which two, and the export keys they are wired under. It is thrown at wiring
+time, before the app serves; with the same kind twice it reads `wires the rate
+limit named "user" twice, under "a" and "b"`.
+
+**Why:** a cache, a rate limit and an idempotency all write
+`<prefix>:<name>:<key>`, so one name is one keyspace, and they would
+overwrite each other's values or meet as `WRONGTYPE`. The same wiring that lets
+`redisStore(handle.limits.login)` and `idempotency(handle.idempotency.orders)`
+write the layout `@nxgt/redis` writes refuses the clash.
+
+**Fix:** rename one: the **definition's** `name`, not its export:
+
+```ts
+export const login = defineRateLimit({ name: 'login.limit', key: (ip: string) => ip, limit: 5, per: 60_000 });
+```
+
 ## Runtime: a 500, with this in the log
 
 Each of these makes the request answer `500 {"error":"internal"}`; the
@@ -239,7 +322,7 @@ TypeError: defineRateLimit: "api:1000000/31536000000" has a burst of 1000000 and
 
 **Why:** the script counts in exact integers; `limit × windowMs` past that
 bound would lose precision. `redisStore` hands each policy to
-`@nxgt/redis-guard` when it first counts under it, and a refused policy is
+`@nxgt/redis` when it first counts under it, and a refused policy is
 not kept, so it is checked again, and refused again, on each request.
 
 **Fix:** state the same rate over a shorter window:
@@ -451,7 +534,7 @@ number, or below 1.
 TypeError: defineRateLimit: "api:5/1.5" has a per of 1.5; it is a whole number of milliseconds, and must be at least 1
 ```
 
-**Why:** `redisStore` hands each `limit`/`windowMs` to `@nxgt/redis-guard`
+**Why:** `redisStore` hands each `limit`/`windowMs` to `@nxgt/redis`
 the first time it counts under it, and the guard counts in whole
 milliseconds. `rateLimit` never passes such a value: it refuses it at
 startup, with [`TypeError: rateLimit: windowMs 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-).
@@ -650,3 +733,56 @@ idempotency(connection.client, {
 
 [Scope](guide/idempotency.md#scope-whose-key-it-is) shows the `ip` option
 behind a proxy.
+
+### Counts and kept responses vanish after moving to a handle with a `prefix`
+
+**Symptom:** after `redisStore(client, …)` becomes `redisStore(handle, …)`,
+rate-limit counts start from zero, kept responses miss and an idempotent
+repeat runs again.
+
+**Why:** the handle's `prefix` is in front of every key, so the keys are
+new: `api:…` is now `shop:api:…`. The old ones expire on their own.
+
+**Fix:** none is needed beyond waiting for the longest `ttl`; switch during a
+quiet period, or keep the bare client until then.
+
+### Counts restart after moving a rate limit to the wired form
+
+**Symptom:** after `redisStore(handle, { name: 'api' })` becomes
+`redisStore(handle.limits.api)`, every client's allowance starts full again.
+An idempotent route does not do this: `idempotency(handle, { name: 'orders' })`
+and `idempotency(handle.idempotency.orders)` write the same keys, so a kept
+response is still replayed.
+
+**Why:** the two layouts differ. The by-name store keeps one bucket per policy,
+`shop:api:<limit>/<windowMs>:<key>` and `shop:api:policies`; the wired limit
+is `@nxgt/redis`'s own, `shop:api:<key>`, the layout every other consumer of
+the handle shares. The old buckets are not read any more and expire by
+themselves.
+
+**Fix:** none is needed but the wait, within `burst × per ÷ limit` of the
+limit; switch at a quiet moment. `redisStore(handle.limits.api)` counts by the
+definition's rate, not by the `limit` and `windowMs` the middleware is given,
+which only write the headers: if the `RateLimit-Policy` header says another
+rate than the limit enforces, give the definition as the second argument,
+`redisStore(handle.limits.api, api)`, and leave `limit` and `windowMs` out of
+`rateLimit`: the store declares the definition's rate and the headers come
+from it. A `limit` or `windowMs` that differs from it throws
+[`rateLimit: limit … differs from the store's policy of …`](https://github.com/softistx/alxia/blob/develop/packages/rate-limit/docs/troubleshooting.md#typeerror-ratelimit-limit--differs-from-the-stores-policy-of-)
+at startup; a definition that is not the one that wired the limit throws
+`redisStore: the definition "…" is not the one that wired this limit`.
+
+### The handle is closed while something still uses it
+
+**Symptom:** after the app stopped, or in a second app sharing the handle,
+commands fail with `RedisError: Connection closed`.
+
+**Why:** `redis(handle)` closes the handle when its app stops. Two apps
+given one handle close it with the first.
+
+**Fix:** pass `{ close: false }` to every `redis(handle, …)` but the one that
+owns the handle's life, or close it yourself:
+
+```ts
+app.plugin(redis(handle, { close: false }));
+```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@alxia/redis",
-	"version": "0.2.0",
-	"description": "Redis for alxia on @nxgt/redis and @nxgt/redis-guard: a rate-limit store every process shares, idempotent routes, caches and locks in the context",
+	"version": "0.4.0",
+	"description": "Redis for alxia on @nxgt/redis: a rate-limit store every process shares, idempotent routes, caches and locks in the context",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -41,20 +41,18 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/cache": "^0.2.0",
-		"@alxia/core": "^0.4.0",
-		"@alxia/rate-limit": "^0.2.0",
-		"@nxgt/redis": "^0.3.1",
-		"@nxgt/redis-guard": "^0.3.1",
+		"@alxia/cache": "^0.3.0",
+		"@alxia/core": "^0.5.0",
+		"@alxia/rate-limit": "^0.4.0",
+		"@nxgt/redis": "^0.6.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@alxia/cache": "^0.2.0",
-		"@alxia/core": "^0.4.0",
-		"@alxia/rate-limit": "^0.2.0",
-		"@nxgt/redis": "^0.3.1",
-		"@nxgt/redis-guard": "^0.3.1",
+		"@alxia/cache": "^0.3.0",
+		"@alxia/core": "^0.5.0",
+		"@alxia/rate-limit": "^0.4.0",
+		"@nxgt/redis": "^0.5.0 || ^0.6.0",
 		"typescript": "^6.0.3 || ^7.0.0",
 		"zod": "^4.6.5"
 	},