@alxia/redis 0.1.0

package/docs/guide/rate-limits.md

@@ -0,0 +1,198 @@
+# Rate limits
+
+This page covers `redisStore`: an
+[`@alxia/rate-limit`](https://www.npmjs.com/package/@alxia/rate-limit)
+store that every process sharing a Redis counts in, and how it differs
+from the memory store.
+
+```ts
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { 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' }) }))
+	.get('/search', ({ reply }) => reply(200, []));
+```
+
+`@alxia/rate-limit` is an optional peer: install it beside this package to
+use `redisStore`.
+
+```sh
+bun add @alxia/rate-limit
+```
+
+## The signature
+
+```ts
+function redisStore(client: RedisClient, options: RedisStoreOptions): RateLimitStore;
+
+interface RedisStoreOptions {
+	/** Prepended to every key it counts: one name per limit, so two never share a count. */
+	readonly name: string;
+}
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | required | the prefix of every key it writes: `<name>:<limit>/<windowMs>:<key>` for a count, and `<name>:policies` for the policies counted under the name |
+
+`limit`, `windowMs`, the `key` counted (the client's address by default),
+`skip` and the headers are `rateLimit`'s options, not the store's: see
+`@alxia/rate-limit`'s guide. The 429 and its type are unchanged — a typed
+`429 { error: 'rate_limited', retryAfter }` with `Retry-After`, the same as
+with the memory store.
+
+## What changes with Redis
+
+- **Every process counts together.** Behind a load balancer, a client gets
+  `limit` requests in all, not `limit` per process; a restart forgets
+  nothing.
+- **It is GCRA, not a fixed window.** The memory store counts `limit`
+  requests, then refuses until its window ends. `redisStore` refills
+  continuously, at `limit` per `windowMs`, from a bucket that holds
+  `limit`. A client that has been idle can send `limit` at once, then one
+  more each `windowMs / limit`: in the first `windowMs` after an idle
+  spell, up to `2 × limit − 1` requests pass, never more than `limit` at
+  once.
+- **The clock is the Redis server's**, not each process's, so processes
+  whose clocks differ still agree.
+- **A refused request counts nothing**, as with the memory store.
+
+Measured with `limit: 5, windowMs: 2_000`: seven requests at once answer
+five `200` then two `429`; one second later, two more pass.
+
+```ts
+import { expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { redisStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+test('a full bucket, then a steady refill', async () => {
+	await connection.client.send('FLUSHDB', []);
+	const app = alxia({ ip: () => '1.2.3.4' })
+		.use(rateLimit({ limit: 5, windowMs: 2_000, store: redisStore(connection.client, { name: 'demo' }) }))
+		.get('/', ({ reply }) => reply(200, 'ok'));
+
+	const burst = [];
+	for (let i = 0; i < 7; i++) burst.push((await app.request('/')).status);
+	expect(burst).toEqual([200, 200, 200, 200, 200, 429, 429]);
+
+	await Bun.sleep(1_000);                                // half a window: 2.5 requests' worth
+	expect((await app.request('/')).status).toBe(200);
+});
+```
+
+If a hard ceiling per fixed window is a requirement, GCRA is not it: halve
+`limit` and `windowMs` together to keep the rate and halve the burst.
+
+## Choosing `name`
+
+The key is `<name>:<limit>/<windowMs>:<key>`. Two `rateLimit`s with the
+same `name` and the same `limit` and `windowMs` share one count; with a
+different policy they do not. Give each limit its own name:
+
+```ts
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { redisStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const app = alxia()
+	.group('/auth', (auth) =>
+		auth
+			.use(rateLimit({ limit: 5, windowMs: 15 * 60_000, store: redisStore(connection.client, { name: 'login' }) }))
+			.post('/login', ({ reply }) => reply(200, 'ok')),
+	)
+	.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(connection.client, { name: 'api' }) }))
+	.get('/search', ({ reply }) => reply(200, []));
+```
+
+Every process must agree on `name`, `limit` and `windowMs`: the same three
+are the same count.
+
+## Policies Redis refuses
+
+`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
+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
+is not kept, so each request checks it again:
+
+| Policy | Logged |
+| --- | --- |
+| `limit × windowMs` above 9,007,199,254,740 (about 9e12) | `TypeError: defineRateLimit: "api:1000000/31536000000" has a burst of 1000000 and a per of 31536000000ms; burst × per must be at most 9007199254740 for the script to count exactly` |
+| `windowMs` above ten 365-day years, 315,360,000,000, with `limit × windowMs` inside the bound above | `TypeError: defineRateLimit: "api:1/315360000001" would take longer than ten years to refill from empty (burst × per ÷ limit); check that per is in milliseconds` |
+
+`limit: 1_000, windowMs: 86_400_000` — a thousand a day — is well inside
+both; a million a year is not. Troubleshooting has the fix for each:
+[burst × per](../troubleshooting.md#typeerror-defineratelimit--has-a-burst-of--and-a-per-of-ms-burst--per-must-be-at-most-9007199254740-for-the-script-to-count-exactly)
+and [ten years](../troubleshooting.md#typeerror-defineratelimit--would-take-longer-than-ten-years-to-refill-from-empty-burst--per--limit-check-that-per-is-in-milliseconds).
+
+## Resetting a key
+
+`store.reset(key)` forgets a key — after a successful login, say:
+
+```ts
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { redisStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+import { z } from 'zod';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+const attempts = redisStore(connection.client, { name: 'login' });
+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 }) => {
+			if (passwords.get(body.name) !== body.password) {
+				return reply(401, { error: 'invalid_credentials' as const });
+			}
+			if (ip !== undefined) await attempts.reset(ip);
+			return reply(200, { name: body.name });
+		}),
+);
+```
+
+`reset` forgets the key under **every policy ever counted under the
+store's `name`**, by any store object and any process: each policy is
+recorded in a Redis set, `<name>:policies`, the first time a process counts
+under it. So a process that only resets — an admin endpoint, a worker —
+needs no count of its own:
+
+```ts
+import { redisStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+// Another process: the login limit above is counted elsewhere.
+export async function unblock(ip: string) {
+	await redisStore(connection.client, { name: 'login' }).reset(ip);
+}
+```
+
+The policies set holds one short member per `limit`/`windowMs` pair and is
+kept without an expiry. A name used for several policies over time — a
+limit you tuned — keeps the old ones in it; `reset` then also deletes the
+key under them, which costs a command each and nothing else.
+
+## Next
+
+- [Idempotency](idempotency.md) — and where to declare the rate limit
+  relative to it.
+- [Testing](testing.md) — specs against a real Redis.

package/docs/guide/response-cache.md

@@ -0,0 +1,129 @@
+# Response cache
+
+This page covers `redisCacheStore`: an
+[`@alxia/cache`](https://www.npmjs.com/package/@alxia/cache) store that
+every process sharing a Redis serves from, and invalidates together.
+
+```ts
+import { cache } from '@alxia/cache';
+import { alxia } from '@alxia/core';
+import { redisCacheStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+
+const products = cache({ ttl: 60, store: redisCacheStore(connection.client, { name: 'shop' }), tags: () => ['products'] });
+
+const app = alxia()
+	.use(products)
+	.get('/products', ({ reply }) => reply(200, [{ id: '1', name: 'Kettle' }]));
+```
+
+`@alxia/cache` is an optional peer: install it beside this package to use
+`redisCacheStore`.
+
+```sh
+bun add @alxia/cache
+```
+
+## The signature
+
+```ts
+function redisCacheStore(client: RedisClient, options: RedisCacheStoreOptions): CacheStore;
+
+interface RedisCacheStoreOptions {
+	/** Prepended to every key it writes: one name per app or deployment. */
+	readonly name: string;
+}
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | required | the prefix of every key: `<name>:response:<key>` for a response, `<name>:tag:<tag>` for a tag |
+
+Everything else — `ttl`, `staleWhileRevalidate`, `key`, `vary`, `statuses`,
+`tags` — is `cache()`'s, and behaves as with the memory store: see
+`@alxia/cache`'s guide.
+
+## What it stores
+
+- **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
+  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>` —
+  the tag `invalidate(path)` deletes. It expires with the longest-kept response it names: each `set`
+  gives a new tag set its expiry, and only ever lengthens it after that.
+  On a Redis older than 7, which cannot compare expiries, the last
+  response written sets it.
+- **Reading** checks the record against its schema: a record that no
+  longer reads as a response — written by another version, or by hand — is
+  a miss, and is deleted.
+
+Measured with `cache({ ttl: 2, tags: () => ['products'] })` after one
+`GET /products`:
+
+```text
+shop:response:/products            string   TTL 2
+shop:tag:alxia:path:/products      set      TTL 2
+shop:tag:products                  set      TTL 2
+```
+
+## Invalidating across processes
+
+`invalidate(path)` and `invalidateTag(tag)` delete from Redis, so every
+process sharing it misses on its next request:
+
+```ts
+import { cache } from '@alxia/cache';
+import { alxia } from '@alxia/core';
+import { redisCacheStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+import { z } from 'zod';
+
+const connection = await connectRedis(Bun.env['REDIS_URL']!);
+const Product = z.object({ id: z.string(), name: z.string() });
+const catalogue = new Map<string, z.infer<typeof Product>>();
+
+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 }) => {
+		catalogue.set(body.id, body);
+		await products.invalidateTag('products');      // forgotten in every process
+		return reply(201, body);
+	})
+	.use(products)
+	.get('/products', ({ reply }) => reply(200, [...catalogue.values()]));
+```
+
+`invalidateTag` reads the tag's set, deletes every key in it, then the set.
+`invalidate(path)` does the same with the path's tag, so it forgets every
+response kept for that path — each `vary` value, a `key` of your own:
+
+```ts
+await products.invalidate('/products');          // every language, every key, in every process
+await products.invalidate('/products?page=2');   // another path: its query is part of it
+```
+
+Two `cache()` given stores with the same `name` share responses and tags;
+give each app or deployment its own `name`.
+
+## What changes with Redis
+
+- **Concurrent misses** run the route once per process, not once overall:
+  `@alxia/cache` coalesces them in memory.
+- **A Redis that does not answer costs the cache, not the response.** A
+  read that fails is a miss, so the route runs; a write that fails keeps
+  nothing; the first error of an outage is logged with `console.error`. `invalidate` and
+  `invalidateTag` do reject, so a write that empties the cache learns that
+  it could not — see `@alxia/cache`'s
+  [Stores](https://github.com/softistx/alxia/blob/develop/packages/cache/docs/guide/stores.md#when-the-store-cannot-answer).
+
+## Next
+
+- [Caches and locks](caches-and-locks.md) — `redis()` adds typed caches to
+  the context, as `caches`, beside this one's `cache`.
+- [Testing](testing.md).

package/docs/guide/testing.md

@@ -0,0 +1,135 @@
+# Testing
+
+This page covers specs for routes that use `@alxia/redis`: against a real
+Redis, emptied between tests, with the app built once the client is
+connected.
+
+```ts
+// payments.spec.ts
+import { beforeAll, beforeEach, expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { idempotency } from '@alxia/redis';
+import { connectRedis, type RedisConnection } from '@nxgt/redis';
+
+let connection: RedisConnection;
+let app: ReturnType<typeof makeApp>;
+
+const makeApp = (client: RedisConnection['client']) =>
+	alxia({ ip: () => '1.2.3.4' })
+		.use(idempotency(client, { name: 'payments' }))
+		.post('/payments', ({ reply }) => reply(201, { id: crypto.randomUUID() }));
+
+beforeAll(async () => {
+	connection = await connectRedis(Bun.env['REDIS_URL'] ?? 'redis://127.0.0.1:6379');
+	app = makeApp(connection.client);
+});
+beforeEach(async () => {
+	await connection.client.send('FLUSHDB', []);
+});
+
+test('a repeat replays the first response', async () => {
+	const pay = () => app.request('/payments', { method: 'POST', headers: { 'idempotency-key': 'k-1' } });
+	const first = await pay();
+	const again = await pay();
+	expect(await again.json()).toEqual(await first.json());
+	expect(again.headers.get('idempotent-replayed')).toBe('true');
+});
+```
+
+## A Redis to test against
+
+There is no in-memory fake: the stores and the guard run Lua scripts and
+read the Redis server's clock, which only a Redis answers. Point
+`REDIS_URL` at a disposable one:
+
+```sh
+docker run --rm -d -p 6379:6379 redis:8-alpine
+REDIS_URL=redis://127.0.0.1:6379 bun test
+```
+
+In CI, a Redis service container and `REDIS_URL` do the same. Use a
+database nothing else uses: `FLUSHDB` empties all of it.
+
+## Build the app after connecting
+
+Each export binds the client it is given when it is called. An app built
+at the top of the file, while the variable that `beforeAll` fills is still
+unset, binds `undefined`, and its first request fails. Build it in
+`beforeAll`, as above, or connect with a top-level `await` before building
+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
+clients:
+
+```ts
+import { expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { rateLimit } from '@alxia/rate-limit';
+import { redisStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env['REDIS_URL'] ?? 'redis://127.0.0.1:6379');
+
+test('two processes share one count', async () => {
+	await connection.client.send('FLUSHDB', []);
+	const make = () =>
+		alxia({ ip: () => '1.2.3.4' })
+			.use(rateLimit({ limit: 2, windowMs: 60_000, store: redisStore(connection.client, { name: 'api' }) }))
+			.get('/', ({ reply }) => reply(200, 'ok'));
+	const [one, two] = [make(), make()];             // two apps stand for two processes
+	expect((await one.request('/')).status).toBe(200);
+	expect((await two.request('/')).status).toBe(200);
+	expect((await one.request('/')).status).toBe(429);
+});
+```
+
+## Typed refusals
+
+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:
+
+```ts
+import { expect, expectTypeOf, test } from 'bun:test';
+import { client } from '@alxia/client';
+import { alxia } from '@alxia/core';
+import { idempotency } 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()
+	.post('/open', ({ reply }) => reply(201, 'ok'))
+	.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();
+});
+```
+
+## Close at the end
+
+Close the connections once the file is done:
+
+```ts
+import { afterAll } from 'bun:test';
+import { closeRedis } from '@nxgt/redis';
+
+afterAll(async () => {
+	await closeRedis();
+});
+```
+
+## Next
+
+- [Connecting](connecting.md).
+- [Idempotency](idempotency.md) — what each request gets.

package/docs/roadmap.md

@@ -0,0 +1,46 @@
+# Roadmap
+
+What `@alxia/redis` gives an app, and what is coming. This page is a
+direction, not a commitment: the version something shipped in is the only
+number on it. Every release, with each change it made, is in
+[`CHANGELOG.md`](https://github.com/softistx/alxia/blob/develop/packages/redis/CHANGELOG.md).
+
+## Now
+
+Nothing scheduled yet.
+
+## Next
+
+Nothing scheduled yet.
+
+## Later
+
+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.
+  They run on Bun's built-in `RedisClient`, so there is no driver to
+  install, and it does not run on Node.
+
+## Shipped
+
+### 0.1.0
+
+- **A rate limit every process shares.** `redisStore` is an
+  `@alxia/rate-limit` store with GCRA in one atomic script, timed by the
+  Redis server's clock; a refused request counts nothing, and the 429
+  stays typed.
+- **A response cache every process shares.** `redisCacheStore` is an
+  `@alxia/cache` store on `@nxgt/redis`'s typed caches; a record that no
+  longer reads as a response is a miss, and `invalidateTag` reaches every
+  process.
+- **Idempotent routes.** `idempotency` runs a `POST` or `PATCH` once per
+  `Idempotency-Key`, replays its response with `Idempotent-Replayed: true`
+  from any process, and answers a typed `409`, `422` or `400` for the
+  repeats it cannot; a `5xx` or a stream is not kept.
+- **Redis in the context.** `redis` gives routes the client, typed caches
+  bound once, and a lock every process respects.