@alxia/cache 0.0.0-stage → 0.1.0

package/docs/guide/invalidation.md

@@ -0,0 +1,192 @@
+# Invalidation
+
+This page covers emptying the cache when the data behind it changes: by
+path, by tag, from a route or elsewhere, and across processes.
+
+```ts
+import { alxia } from '@alxia/core';
+import { cache } from '@alxia/cache';
+
+const products = cache({ ttl: 300, tags: () => ['products'] });
+
+const app = alxia()
+	.post('/products', async ({ reply }) => {
+		// … save it
+		await products.invalidateTag('products');       // every product page runs again
+		return reply(201, { saved: true });
+	})
+	.use(products)
+	.get('/products', ({ reply }) => reply(200, []))
+	.get('/products/:id', ({ params, reply }) => reply(200, { id: params.id }));
+```
+
+Without invalidation, a response is served until `ttl +
+staleWhileRevalidate` has passed. With it, the next request after a write
+runs the route.
+
+## By tag: `invalidateTag`
+
+```ts
+invalidateTag(tag: string): Promise<void>
+```
+
+Forgets every response that carries `tag`, whatever its key. A response
+carries:
+
+- the tags of the plugin's `tags(ctx)`, computed for each response kept —
+  `cache<{ user: User }>(…)` lets it read what an earlier plugin added
+  ([Reading the app's context](keys-and-vary.md#reading-the-apps-context));
+- the tags its route added with `ctx.cache.tag(…)`.
+
+```ts
+import { alxia } from '@alxia/core';
+import { cache } from '@alxia/cache';
+
+const catalogue = cache({
+	ttl: 300,
+	tags: ({ url }) => (url.pathname.startsWith('/products') ? ['products'] : []),
+});
+
+const app = alxia()
+	.use(catalogue)
+	.get('/products', ({ reply }) => reply(200, []))
+	.get('/products/:id', ({ params, cache, reply }) => {
+		cache.tag(`product:${params.id}`);
+		return reply(200, { id: params.id });
+	});
+
+await catalogue.invalidateTag('product:1');   // only /products/1, in every language and query
+await catalogue.invalidateTag('products');    // every page of the catalogue
+```
+
+A tag is on the response, not in its key, so it reaches every query
+string and every `vary` value. Tag what a write changes — the entity, its
+collection — and invalidate those tags from the write.
+
+## By path: `invalidate`
+
+```ts
+invalidate(path: string): Promise<void>
+```
+
+Forgets every response kept for `path`, whatever its key: each `vary`
+value, a `key` of your own. `path` is the path and query as the request
+asked them, prefix included.
+
+```ts
+import { alxia } from '@alxia/core';
+import { cache } from '@alxia/cache';
+
+const products = cache({ ttl: 300, vary: ['accept-language'] });
+const app = alxia({ prefix: '/api' })
+	.use(products)
+	.get('/products', ({ reply }) => reply.ok([]));
+
+await products.invalidate('/api/products');        // GET /api/products, in every language
+await products.invalidate('/api/products?page=2'); // GET /api/products?page=2, and only that
+```
+
+It works by a tag: every response is kept with `alxia:path:<path and
+query>` among its tags — `pathTag(path)` builds it — and `invalidate(path)`
+is `store.deleteTag(pathTag(path))`.
+
+```ts
+import { pathTag } from '@alxia/cache';
+
+pathTag('/api/products?page=2');   // 'alxia:path:/api/products?page=2'
+```
+
+Tags starting `alxia:` are the plugin's: do not give one of yours that
+prefix. A store of your own must remember each response's `tags`, or
+`invalidate` reaches nothing ([Writing a store](stores.md#writing-a-store)).
+
+The path is matched exactly, so it does **not** reach:
+
+| A response kept… | because its path is | Use instead |
+| --- | --- | --- |
+| at another query | `/products?page=2` is not `/products` | each path, or a tag |
+| at the same query reordered | `/products?b=2&a=1` is not `/products?a=1&b=2` | a tag |
+| with the app's prefix | `/api/products` is not `/products` | the full path |
+
+A `key` of your own that several paths share — `key: (ctx) =>
+ctx.url.pathname`, which `/products` and `/products?page=2` both write — is
+reached by the path that wrote it last: `MemoryCacheStore` replaces the
+entry with its tags, so `invalidate('/products')` misses it once
+`/products?page=2` has written it. `redisCacheStore` keeps every path that
+wrote it, and forgets it from either. Give such a key a tag, and use
+`invalidateTag`.
+
+`invalidate` resolves when nothing was kept for `path`. It rejects when the
+store does — see [When the store cannot answer](stores.md#when-the-store-cannot-answer).
+
+## From the store
+
+`cache()` exposes its store: `products.store`. Deleting one key you
+computed yourself forgets that response alone:
+
+```ts
+await products.store.delete('/api/products|accept-language=fr');   // the French one only
+```
+
+## Several caches, one store
+
+Each `cache()` without a `store` gets a memory store of its own, and its
+`invalidateTag` empties only that store. Give two caches one store, and a
+tag invalidated through either is forgotten in both:
+
+```ts
+import { alxia } from '@alxia/core';
+import { cache, MemoryCacheStore } from '@alxia/cache';
+
+const store = new MemoryCacheStore();
+const shortLived = cache({ ttl: 10, store, tags: () => ['products'] });
+const longLived = cache({ ttl: 600, store, tags: () => ['products'] });
+
+const app = alxia()
+	.group((g) => g.use(shortLived).get('/products/stock', ({ reply }) => reply(200, 5)))
+	.group((g) => g.use(longLived).get('/products', ({ reply }) => reply(200, [])));
+
+await shortLived.invalidateTag('products');  // both routes run again
+```
+
+Two caches on one store must not keep the same key: give them different
+paths, as here, or keys of their own.
+
+## Across processes
+
+The memory store lives in one process. With more than one — a cluster,
+several containers — invalidating in the process that handled the write
+leaves every other process serving its old copy until it expires.
+`@alxia/redis`'s `redisCacheStore` keeps the responses and their tags in a
+Redis every process shares, so one `invalidateTag` reaches all of them
+([Stores](stores.md#in-redis)).
+
+## In a test
+
+```ts
+import { expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { cache } from '@alxia/cache';
+
+test('invalidated by path, and by tag', async () => {
+	let runs = 0;
+	const products = cache({ ttl: 60, tags: () => ['products'] });
+	const app = alxia()
+		.use(products)
+		.get('/products', ({ reply }) => reply(200, { runs: ++runs }));
+
+	await app.request('/products');
+	await products.invalidate('/products');
+	await app.request('/products');
+	expect(runs).toBe(2);
+
+	await products.invalidateTag('products');
+	await app.request('/products');
+	expect(runs).toBe(3);
+});
+```
+
+## See also
+
+- [Keys and Vary](keys-and-vary.md): what a key is made of.
+- [Stores](stores.md): what `delete` and `deleteTag` do in each store.

package/docs/guide/keys-and-vary.md

@@ -0,0 +1,219 @@
+# Keys and Vary
+
+This page covers what makes two requests "the same" to the cache: the
+default key, `vary`, a `key` of your own, reading what an earlier plugin
+added, and keeping personal responses out.
+
+```ts
+import { alxia } from '@alxia/core';
+import { cache } from '@alxia/cache';
+
+const app = alxia()
+	.use(cache({ ttl: 60, vary: ['accept-language'] }))
+	.get('/hello', ({ request, reply }) =>
+		reply(200, request.headers.get('accept-language')?.startsWith('fr') ? 'Bonjour' : 'Hello'),
+	);
+
+// GET /hello with accept-language: fr → "Bonjour", kept under "/hello|accept-language=fr"
+// GET /hello with accept-language: en → "Hello",   kept under "/hello|accept-language=en"
+```
+
+## The default key
+
+The request's path and query, as they arrive — prefix included — then the
+value of each `vary` header:
+
+```ts
+defaultKey(path: string, vary: readonly string[], headers: Headers): string
+```
+
+```ts
+import { defaultKey } from '@alxia/cache';
+
+defaultKey('/api/products?page=2', [], new Headers());
+// '/api/products?page=2'
+
+defaultKey('/hello', ['accept-language'], new Headers({ 'accept-language': 'fr' }));
+// '/hello|accept-language=fr'
+
+defaultKey('/hello', ['accept-language'], new Headers());
+// '/hello|accept-language='   — a missing header is its own key
+```
+
+The query is taken as written: `?a=1&b=2` and `?b=2&a=1` are two keys, and
+two misses. Nothing else of the request is in the key — no cookie, no
+`Authorization` — unless it is in `vary`, or in a `key` of your own.
+
+## `vary`
+
+```ts
+cache({ ttl: 60, vary: ['accept-language'] });
+```
+
+Each header named is:
+
+- part of the default key, by its exact value;
+- appended to the response's `Vary`, so a browser or a CDN in front keys
+  its own copy the same way.
+
+Names are matched case-insensitively and written lowercased.
+
+**The response's own `Vary` is not read.** Only the names in `vary` are in
+the default key. A response that varies by a header of its own — `app.static` with
+`precompressed` varies by `Accept-Encoding` — is kept once and served to
+every client, whatever that header says. Name it here:
+`vary: ['accept-encoding']` ([troubleshooting](../troubleshooting.md#a-client-that-sent-no-accept-encoding-gets-gzip-bytes)).
+
+**Exact value means exact.** A browser sends its whole preference list —
+`Accept-Language: fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7` — and two visitors
+whose lists differ by one entry are two keys, though your route answers
+both in French. curl sends no `Accept-Language` at all, so every curl
+request shares the one key `…|accept-language=`: a test with curl shows hits
+that real traffic will not. When the route reduces a header to a few
+values, key by those values instead — [below](#a-key-of-your-own).
+
+`vary: ['cookie']` is rarely what you want: a browser sends every cookie of
+the site, analytics included, so almost every visitor has a key of their
+own and the cache keeps one copy per visitor. Keep personal responses
+[out of the cache](#personal-responses) instead.
+
+## A key of your own
+
+```ts
+key?: (ctx: BaseContext & Requires) => string | undefined;
+```
+
+`key` replaces the default key whole. It is synchronous and reads the
+`BaseContext` — `request`, `url`, `ip`, `server`, `route`, `pathParams` —
+and `Requires`, empty by default. To key by what an earlier plugin added,
+see [Reading the app's context](#reading-the-apps-context).
+
+Keyed by the language the route actually answers in, two visitors who both
+prefer French share one copy:
+
+```ts
+import { alxia } from '@alxia/core';
+import { cache } from '@alxia/cache';
+
+const supported = ['en', 'fr', 'de'] as const;
+
+function language(header: string | null): string {
+	const first = (header ?? '').split(',')[0]?.split('-')[0]?.trim().toLowerCase() ?? '';
+	return (supported as readonly string[]).includes(first) ? first : 'en';
+}
+
+const app = alxia()
+	.use(
+		cache({
+			ttl: 60,
+			vary: ['accept-language'],                   // still says `Vary: accept-language`
+			key: ({ url, request }) =>
+				`${url.pathname}${url.search}|${language(request.headers.get('accept-language'))}`,
+		}),
+	)
+	.get('/hello', ({ request, reply }) =>
+		reply(200, language(request.headers.get('accept-language')) === 'fr' ? 'Bonjour' : 'Hello'),
+	);
+```
+
+Two rules keep a custom key honest:
+
+- **The route must choose by what the key reads.** Here both call the same
+  `language()`. A route that reads more than the key would be kept under
+  one key with two different bodies, and serve whichever came first.
+- **`vary` no longer feeds the key** once `key` is set: it only writes
+  `Vary`. Use `defaultKey` inside your key to keep both:
+
+```ts
+import { cache, defaultKey } from '@alxia/cache';
+
+cache({
+	ttl: 60,
+	vary: ['accept-language'],
+	key: ({ url, request }) =>
+		request.headers.has('authorization')
+			? undefined
+			: defaultKey(`${url.pathname}${url.search}`, ['accept-language'], request.headers),
+});
+```
+
+Whatever your key, [`invalidate(path)`](invalidation.md#by-path-invalidate)
+still forgets every response kept for a path: it deletes by the path's tag,
+not by key.
+
+## Reading the app's context
+
+To key or tag by what an earlier plugin added, such as a signed-in `user`
+and its tenant, name it as `cache`'s type argument. `key` and `tags` then
+read it, and the cache is a [`definePlugin`](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/writing-a-plugin.md#a-plugin-that-needs-an-earlier-one)
+plugin: an app that does not give `user` before it cannot use it.
+
+```ts
+const perTenant = cache<{ user: { tenantId: string } }>({
+	ttl: 60,
+	key: ({ user, url }) => `${user.tenantId}:${url.pathname}${url.search}`,
+	tags: ({ user }) => [`tenant:${user.tenantId}`],
+});
+
+const auth = alxia().derive(({ request }) => ({
+	user: { tenantId: request.headers.get('x-tenant') ?? 'public' }, // your session plugin
+}));
+
+const app = alxia()
+	.use(auth)
+	.use(perTenant)
+	.get('/dashboard', ({ user, reply }) => reply(200, { tenant: user.tenantId }));
+
+await perTenant.invalidateTag('tenant:acme'); // one tenant's pages, every path
+
+alxia().use(perTenant);
+// error: the plugin reads "user", which this app's context does not give: use the plugin that adds it first
+```
+
+The rule of [a key of your own](#a-key-of-your-own) still holds: the route
+must choose by what the key reads, here the tenant, and nothing more
+personal.
+
+## Personal responses
+
+The default key does not read who is asking. A route that answers by the
+`Cookie` or `Authorization` header, behind a cache with the default key,
+and says nothing about it, serves the first visitor's answer to every later
+one. curl, sending no cookie, never shows it; a signed-in browser does.
+
+A personal response that says so is never kept, nor shared with a
+concurrent request: it answers `Cache-Control: private` (or `no-store`),
+or sets a cookie. Three ways, from the cheapest:
+
+```ts
+// 1. Declare them before the cache: it never sees them, and no lookup is made.
+alxia()
+	.get('/me', ({ reply }) => reply(200, { name: 'Grace' }))
+	.use(cache({ ttl: 60 }))
+	.get('/products', ({ reply }) => reply(200, []));
+
+// 2. No key for a request that carries a session: it is neither looked up nor kept.
+cache({
+	ttl: 60,
+	key: ({ url, request }) =>
+		request.headers.has('cookie') || request.headers.has('authorization')
+			? undefined
+			: `${url.pathname}${url.search}`,
+});
+
+// 3. Behind the cache, the route says its response is private: it is never kept.
+app.get('/me', ({ reply }) =>
+	reply(200, { name: 'Grace' }, { headers: { 'cache-control': 'private' } }),
+);
+```
+
+The second skips the cache for **every** request with a cookie, which in a
+browser is most of them once any cookie is set: prefer it for an API whose
+callers sign every request. The third is enough on its own, and worth
+sending anyway, for the browser and any proxy in front; the first also
+saves the store lookup.
+
+## See also
+
+- [Caching responses](caching.md): which responses are kept at all.
+- [Invalidation](invalidation.md): forgetting a key, or a tag.

package/docs/guide/stores.md

@@ -0,0 +1,273 @@
+# Stores
+
+This page covers where responses are kept: the memory store and its
+limits, the Redis store from `@alxia/redis`, and writing a store of your
+own.
+
+```ts
+import { alxia } from '@alxia/core';
+import { cache, MemoryCacheStore } from '@alxia/cache';
+
+const store = new MemoryCacheStore({ maxEntries: 5_000, maxBytes: 128 * 1024 * 1024 });
+
+const app = alxia()
+	.use(cache({ ttl: 60, store }))
+	.get('/products', ({ reply }) => reply(200, []));
+```
+
+The plugin does not know which store it was given: every store answers the
+same `CacheStore` contract, and freshness — `ttl`, `staleWhileRevalidate` —
+is decided by the plugin, not the store.
+
+## In memory: `MemoryCacheStore`
+
+```ts
+new MemoryCacheStore(options?: MemoryCacheOptions)
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `maxEntries` | `number` | `1_000` | the most responses kept |
+| `maxBytes` | `number` | `64 * 1024 * 1024` (64 MiB) | the most bytes of bodies kept; headers are not counted |
+
+Past either limit, the **least recently read** response goes first: reading
+a response moves it to the back of the queue. A single body larger than
+`maxBytes` is never kept, so its route answers `MISS` every time.
+
+```ts
+import { expect, test } from 'bun:test';
+import { MemoryCacheStore } from '@alxia/cache';
+
+const entry = (bytes: number) => ({
+	status: 200,
+	headers: [],
+	body: new Uint8Array(bytes),
+	storedAt: Date.now(),
+	ttl: 1000,
+	stale: 0,
+	tags: [],
+});
+
+test('the least recently read goes first', () => {
+	const store = new MemoryCacheStore({ maxEntries: 2 });
+	store.set('a', entry(10), 1000);
+	store.set('b', entry(10), 1000);
+	store.get('a');                      // a is now the most recently read
+	store.set('c', entry(10), 1000);     // b goes
+	expect(store.get('b')).toBeUndefined();
+	expect(store.get('a')).toBeDefined();
+	expect(store.size).toBe(2);
+});
+```
+
+`size` reads how many responses are kept. A response is dropped once
+`ttl + staleWhileRevalidate` has passed, when it is next read.
+
+The memory store is the default: each `cache()` without a `store` creates
+its own. It is right for one process; with several, each keeps its own copy
+and its own invalidations ([Invalidation](invalidation.md#across-processes)).
+
+## In Redis
+
+`@alxia/redis` ships `redisCacheStore`, a `CacheStore` on `@nxgt/redis`:
+every process sharing the Redis serves what one of them kept, and one
+`invalidateTag` reaches them all.
+
+```sh
+bun add @alxia/redis @nxgt/redis @nxgt/redis-guard zod
+```
+
+```ts
+import { cache } from '@alxia/cache';
+import { redisCacheStore } from '@alxia/redis';
+import { connectRedis } from '@nxgt/redis';
+
+const connection = await connectRedis(Bun.env.REDIS_URL!);
+
+const products = cache({
+	ttl: 60,
+	staleWhileRevalidate: 300,
+	store: redisCacheStore(connection.client, { name: 'shop' }),   // keys start with "shop:"
+	tags: () => ['products'],
+});
+```
+
+`name` is prepended to every key the store writes: one per app or
+deployment sharing the Redis. See `@alxia/redis`'s README for its
+connection and its other options.
+
+Two things change with Redis:
+
+- **Concurrent misses** run the route once per process, not once overall.
+- **A Redis that is down** is a store that cannot answer: the routes still
+  answer, uncached ([below](#when-the-store-cannot-answer)).
+
+## Writing a store
+
+A store implements four methods. Each may answer synchronously or with a
+promise:
+
+```ts
+interface CacheStore {
+	get(key: string): Promise<CachedResponse | undefined> | CachedResponse | undefined;
+	/** Keeps `value` for `keepFor` milliseconds: its freshness and its staleness together. */
+	set(key: string, value: CachedResponse, keepFor: number): Promise<void> | void;
+	delete(key: string): Promise<void> | void;
+	/** Forgets every response tagged `tag`. */
+	deleteTag(tag: string): Promise<void> | void;
+}
+
+interface CachedResponse {
+	readonly status: number;
+	readonly headers: readonly (readonly [string, string])[];
+	readonly body: Uint8Array;
+	readonly storedAt: number;    // milliseconds since the epoch
+	readonly ttl: number;         // milliseconds fresh, from storedAt
+	readonly stale: number;       // milliseconds served stale after that
+	readonly tags: readonly string[];
+}
+```
+
+What the plugin relies on:
+
+| Method | Must |
+| --- | --- |
+| `get` | return what `set` was given, or `undefined` — never `null` — when nothing is kept, or it expired |
+| `set` | keep `value` under `key` for `keepFor` **milliseconds**, replacing what was there, and remember its `tags` — `invalidate(path)` relies on them too |
+| `delete` | forget `key`; a key that is not there is not an error |
+| `deleteTag` | forget every key whose response carries `tag` |
+
+`get` need not check freshness: the plugin reads `storedAt`, `ttl` and
+`stale` itself. Expiring at `keepFor` only bounds what the store holds.
+
+A store over any key-value service — here a plain `Map`, standing in for
+one that serialises — looks like this:
+
+```ts
+import type { CachedResponse, CacheStore } from '@alxia/cache';
+
+interface Row {
+	value: CachedResponse;
+	expiresAt: number;
+}
+
+export function mapCacheStore(): CacheStore {
+	const rows = new Map<string, Row>();
+	const tags = new Map<string, Set<string>>();
+
+	return {
+		get(key) {
+			const row = rows.get(key);
+			if (row === undefined || row.expiresAt <= Date.now()) return undefined;
+			return row.value;
+		},
+		set(key, value, keepFor) {
+			rows.set(key, { value, expiresAt: Date.now() + keepFor });
+			for (const tag of value.tags) {
+				const keys = tags.get(tag) ?? new Set<string>();
+				keys.add(key);
+				tags.set(tag, keys);
+			}
+		},
+		delete(key) {
+			rows.delete(key);
+		},
+		deleteTag(tag) {
+			for (const key of tags.get(tag) ?? []) rows.delete(key);
+			tags.delete(tag);
+		},
+	};
+}
+```
+
+A service that stores text keeps `body` as base64 and `headers` as an array
+of pairs, and rebuilds the `Uint8Array` on `get` — as `redisCacheStore`
+does.
+
+Every kept response carries, among its `tags`, the tag of its path —
+`alxia:path:/products?page=2`, built by `pathTag` — and `invalidate(path)`
+is `deleteTag` of it. A store that drops `tags` leaves `invalidate` and
+`invalidateTag` reaching nothing.
+
+### Testing a store
+
+The plugin's own behaviour is the best test of a store: run an app on it.
+
+```ts
+import { expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { cache } from '@alxia/cache';
+import { mapCacheStore } from './map-cache-store';
+
+test('the store serves, and forgets by tag and by path', async () => {
+	let runs = 0;
+	const products = cache({ ttl: 60, store: mapCacheStore(), tags: () => ['products'] });
+	const app = alxia()
+		.use(products)
+		.get('/products', ({ reply }) => reply.ok({ runs: ++runs }));
+
+	await app.request('/products');
+	expect((await app.request('/products')).headers.get('x-cache')).toBe('HIT');
+
+	await products.invalidateTag('products');
+	expect((await app.request('/products')).headers.get('x-cache')).toBe('MISS');
+
+	await products.invalidate('/products');                 // the path's tag: kept by `set` too
+	expect((await app.request('/products')).headers.get('x-cache')).toBe('MISS');
+	expect(runs).toBe(3);
+});
+```
+
+## When the store cannot answer
+
+A store that throws or rejects costs the cache, not the response:
+
+| Store call | Fails while | Then |
+| --- | --- | --- |
+| `get` | a request is looked up | a miss: the route runs, `X-Cache: MISS` |
+| `set` | a response is kept | nothing is kept; the response is answered |
+| `deleteTag` | `invalidate` or `invalidateTag` | the call rejects with the store's error |
+
+The first two are logged with `console.error` once per outage — the first
+failure, then nothing until the store has answered again — and the request
+goes on. An invalidation rejects instead: the code that changed
+the data should know the old responses may still be served.
+
+```ts
+import { expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { cache, MemoryCacheStore } from '@alxia/cache';
+
+test('a store that cannot answer: the route answers', async () => {
+	const broken = new MemoryCacheStore();
+	broken.get = () => {
+		throw new Error('store down');
+	};
+	broken.set = () => Promise.reject(new Error('store down'));
+	broken.deleteTag = () => Promise.reject(new Error('store down'));
+
+	const products = cache({ ttl: 60, store: broken });
+	const app = alxia()
+		.use(products)
+		.get('/products', ({ reply }) => reply.ok([]));
+
+	const response = await app.request('/products');   // logs "store down" once
+	expect(response.status).toBe(200);
+	expect(response.headers.get('x-cache')).toBe('MISS');
+	await expect(products.invalidate('/products')).rejects.toThrow('store down');
+});
+```
+
+A write that must answer even when the store is down catches the
+invalidation, and keeps `ttl` short, since the old responses stay until
+they expire:
+
+```ts
+await products.invalidateTag('products').catch((error) => console.error(error));
+```
+
+## See also
+
+- [Caching responses](caching.md): the options that decide freshness.
+- [Invalidation](invalidation.md): `invalidate`, `invalidateTag`, and
+  sharing one store between caches.