@alxia/redis 0.1.3 → 0.3.0

package/docs/roadmap.md

@@ -7,11 +7,16 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing scheduled yet.
+Nothing in progress: `idempotency` as a middleware, the last change planned,
+shipped in 0.2.0 and finished in 0.3.0.
 
 ## Next
 
-Nothing scheduled yet.
+- **A rate limit that reads its policy from the store.** With
+  `redisStore(handle.limits.api)` the rate lives in the definition, and
+  `rateLimit({ limit, windowMs })` still repeats it for its headers. The store
+  telling `rateLimit` its own policy, so the numbers are written once, is
+  planned for `@alxia/rate-limit` and this package together.
 
 ## Later
 
@@ -20,14 +25,52 @@ 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.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,11 @@
 
 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. What prints nothing is under [Traps](#traps), by symptom.
+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**
 
@@ -21,6 +23,10 @@ each through. What prints nothing is under [Traps](#traps), by symptom.
 - [`RedisError: Connection closed`](#rediserror-connection-closed)
 - [`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)
@@ -32,6 +38,10 @@ each through. What prints nothing is under [Traps](#traps), by symptom.
 - [`RedisError: The lock "…" expired before its work finished: it ran longer than the …ms ttl, so it may have run beside another holder`](#rediserror-the-lock--expired-before-its-work-finished-it-ran-longer-than-the-ms-ttl-so-it-may-have-run-beside-another-holder)
 - [`TypeError: undefined is not an object (evaluating 'cache.…')`](#typeerror-undefined-is-not-an-object-evaluating-cache)
 
+**Runtime: a warning in the log**
+
+- [`idempotency "…": 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().`](#idempotency--no-client-scope-could-be-derived-ctxip-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)
+
 **Calling the store yourself**
 
 - [`TypeError: defineRateLimit: "…" has a per of …; it is a whole number of milliseconds, and must be at least 1`](#typeerror-defineratelimit--has-a-per-of--it-is-a-whole-number-of-milliseconds-and-must-be-at-least-1)
@@ -50,6 +60,9 @@ each through. What prints nothing is under [Traps](#traps), by symptom.
 - [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
 
@@ -106,7 +119,7 @@ never meet `@alxia/cache`'s `cache`.
 
 ```ts
 alxia()
-	.use(redis(connection.client, { caches: { users } }))
+	.plugin(redis(connection.client, { caches: { users } }))
 	.get('/users/:id', async ({ caches, params, reply }) =>
 		reply.ok(await caches.users.remember(params.id, () => loadUser(params.id))),
 	);
@@ -217,6 +230,59 @@ 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: 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
@@ -234,7 +300,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:
@@ -277,7 +343,7 @@ with a fraction or below 0.
 TypeError: run on "payments": wait is a whole number of milliseconds, 0 or more
 ```
 
-**Why:** `wait` is checked when it is used, not when the plugin is made.
+**Why:** `wait` is checked when it is used, not when the middleware is made.
 
 **Fix:**
 
@@ -398,6 +464,38 @@ with `undefined`.
 **Fix:** read `caches.<name>`, drop the `derive`, and typecheck:
 `tsc --noEmit` finds every place.
 
+## Runtime: a warning in the log
+
+### `idempotency "…": 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().`
+
+**When:** a guarded request carries an `Idempotency-Key`, and the
+middleware has no client to scope it by: `ctx.ip` is `undefined` — under
+`app.request()` in a test, or a server that cannot see the address — and
+there is no `scope` option, or it returned `undefined`. Printed once per
+`idempotency(…)`, with its `name`.
+
+**Why:** keys are scoped by the client, so two clients choosing the same key
+never see each other's response. With no client, the request runs
+unguarded: the route runs, nothing is stored, a repeat runs it again.
+Sharing one key space between every client would replay one client's
+response to another.
+
+**Fix:** scope by the user where there is one, or give `alxia()` an `ip`
+option that reads the address:
+
+```ts
+idempotency(connection.client, {
+	name: 'payments',
+	scope: ({ request }) => request.headers.get('x-user-id') ?? undefined,
+});
+```
+
+or, behind a proxy you trust:
+
+```ts
+alxia({ ip: (request) => request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() });
+```
+
 ## Calling the store yourself
 
 A policy `rateLimit` would refuse at startup still reaches the store when
@@ -414,7 +512,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-).
@@ -567,7 +665,8 @@ rateLimit({ limit: 5, windowMs: 60_000, store: redisStore(connection.client, { n
 ### A `401` or a `429` is replayed, with `Idempotent-Replayed: true`, after the client fixed it
 
 **When:** a request under a key was refused with a `4xx` — by the route, or
-by a rate limit or an authentication check declared after `idempotency` —
+by a rate limit or an authentication check declared after `idempotency`,
+or by an error handler —
 and the client, once allowed, retries with the same key and body.
 
 **Why:** every response below `500` is kept and replayed for `ttl`, not
@@ -596,8 +695,9 @@ behind a proxy, or with keys that are not random — `1`, `order-1`.
 
 **Why:** keys are scoped by `scope(ctx)`, the client's address by default.
 Behind a proxy that the app's `ip` option does not see through, every
-client has the proxy's address; with no address at all, the scope is
-`anyone`. Clients then share one key space.
+client has the proxy's address, and they then share one key space. (With
+no address at all and no `scope`, the request runs unguarded instead, with
+a [warning](#runtime-a-warning-in-the-log).)
 
 **Fix:** scope by the user where there is one, and have clients send
 random keys:
@@ -611,3 +711,50 @@ 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, make the two numbers equal.
+
+### 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.1.3",
-	"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.3.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,21 +41,18 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/cache": "^0.1.2",
-		"@alxia/client": "^0.2.1",
-		"@alxia/core": "^0.3.0",
-		"@alxia/rate-limit": "^0.1.2",
-		"@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.3.0",
+		"@nxgt/redis": "^0.6.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@alxia/cache": "^0.1.2",
-		"@alxia/core": "^0.3.0",
-		"@alxia/rate-limit": "^0.1.2",
-		"@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.3.0",
+		"@nxgt/redis": "^0.5.0 || ^0.6.0",
 		"typescript": "^6.0.3 || ^7.0.0",
 		"zod": "^4.6.5"
 	},