diff --git a/README.md b/README.md index 703e83e..929c088 100644 --- a/README.md +++ b/README.md @@ -17,166 +17,102 @@ memory by default, with revalidation shared across all of them. > ElastiCache IAM. 16.4.2 setups keep working with deprecation warnings, and `^16.4.2` installs get > it automatically. Read [Upgrading from 16.4.2](./docs/migrating.md) before you deploy. -## Quick start +## Start here -```bash -npm install --save-exact @mrjasonroy/cache-components-cache-handler -``` +1. **Install** the release for your Next.js minor, pinned exact. For Next 16.4.x: -The package version follows Next.js. Pin it to the exact release for your Next.js version -(`--save-exact`; Next 16.4.3 → `16.4.3`) and upgrade the two together. A range such as `^16.4.3` -also accepts the 16.5 releases, which follow Next.js 16.5 and remove the APIs deprecated in -16.4.3. From the next release, the `next` peer dependency is `~..0` of the -package's own version (for example `~16.4.0` for 16.4.x), so npm refuses a handler whose minor -does not match your Next.js with an `ERESOLVE` error, and pnpm and Yarn warn. + ```bash + npm install --save-exact @mrjasonroy/cache-components-cache-handler@16.4 + ``` -```js -// next.config.mjs -import { withCache } from "@mrjasonroy/cache-components-cache-handler"; + `@16.4` picks the newest 16.4.x and `--save-exact` pins it. Needs Node.js 22.3+. -export default withCache({ cacheComponents: true }); -``` +2. **Wrap your config:** -```bash -REDIS_URL=redis://cache:6379 # unset → everything stays in memory (dev, CI, previews) -``` + ```js + // next.config.mjs + import { withCache } from "@mrjasonroy/cache-components-cache-handler"; + + export default withCache({ cacheComponents: true }); + ``` -That's it. You keep writing `"use cache"`, `cacheTag` and `revalidateTag` as Next documents them -([examples](./docs/usage.md)). `ioredis` is installed automatically as an optional dependency -([unless optionals are skipped](./docs/installation.md#install)). +3. **Pick your setup:** + + | Setup | What to do | + |---|---| + | Local dev, CI, previews, one instance | Nothing. Without `REDIS_URL` everything stays in memory. | + | Redis or Valkey | Set `REDIS_URL=redis://cache:6379` on the running app. [Installation](./docs/installation.md#point-it-at-redis) | + | AWS ElastiCache, Serverless or cluster mode disabled | Set `ELASTICACHE_ENDPOINT` and `ELASTICACHE_AUTH_TOKEN`, or the IAM variables. [AWS ElastiCache](./docs/redis.md#aws-elasticache) | + | AWS ElastiCache, cluster mode enabled (with or without IAM) | Your own `Cluster` in custom handler files. [Redis Cluster](./docs/redis.md#redis-cluster), [IAM on your own client](./docs/redis.md#iam-on-your-own-client) | + | Your own client (Sentinel, other ioredis options or timeouts) | [Custom handlers](./docs/custom-handlers.md) | + | Upgrading from 16.4.2 | [Migrating](./docs/migrating.md) | + +Then keep writing `"use cache"`, `cacheTag` and `revalidateTag` as Next documents them +([examples](./docs/usage.md)). + +**Setting it up with a coding agent?** Paste the prompt in [docs/agent-setup.md](./docs/agent-setup.md) +into Claude Code, Cursor or similar. + +The package version follows Next.js. A range such as `^16.4.3` would also accept the 16.5 +releases, which remove the APIs deprecated in 16.4.3, so pin it and upgrade the two together +([why](./docs/installation.md#install)). `ioredis` is installed with the package as an optional +dependency ([unless optionals are skipped](./docs/installation.md#install)). ## What you get - **Pages and route handlers** (and cached `fetch`) stored in Redis, shared by every instance. Prerendered pages are served from the build output after a restart. -- **Storage by directive.** `"use cache: remote"` entries live in Redis, shared by every - instance; plain `"use cache"` defaults to each instance's memory, with tag invalidation shared - through Redis. `"use cache: private"` is Next's own and never reaches a handler. Set - `useCache: "redis"` to share plain `"use cache"` values too. Next's deprecated - `experimental.useCache` flag works as well as - `cacheComponents`. +- **Next's directives, one to one.** `"use cache: remote"` entries live in Redis, shared by every + instance. Plain `"use cache"` stays in each instance's memory, with tag invalidation shared + through Redis; set `useCache: "redis"` to share it too. `"use cache: private"` is Next's own and + never reaches a handler. - **Revalidation across instances.** `revalidateTag`, `updateTag` and `revalidatePath` reach - every instance and every handler, including each instance's in-memory `"use cache"` values. + every instance and every handler. - **Redis outage safety.** A request never fails because of the cache. Commands time out after - 1 s, and while Redis is down the app serves from per-instance memory, then goes back to Redis. + 1 s, and while Redis is down the app serves from per-instance memory. - **Entries scoped by build**, so a deploy never serves the previous build's pages. - **`next build` never connects to Redis.** -[How it works](./docs/how-it-works.md) has the details: what goes where, tag coordination, page -lifetimes and the outage table. +[How it works](./docs/how-it-works.md) has the details. ## Configuration -### `withCache(nextConfig, options?)` +Runtime settings come from the environment of the running app. The main variables: -These options are read when `next.config` loads. Runtime settings come from the environment, except `memory`. +| Variable | Meaning | +|---|---| +| `REDIS_URL` (or `VALKEY_URL`) | `redis://` or `rediss://` URL. Unset → memory only. | +| `ELASTICACHE_ENDPOINT`, `ELASTICACHE_AUTH_TOKEN` | ElastiCache host form, TLS on. For IAM, see [IAM authentication](./docs/redis.md#iam-authentication). | +| `CACHE_KEY_PREFIX` | Prefix for every key (default `nextjs:`). | +| `CACHE_REDIS=off` | Memory everywhere, even with a URL set. | +| `CACHE_DEBUG=1` | Log hits, misses, writes and state changes. | + +The [installation guide](./docs/installation.md#environment-variables) has the full table. There +are no variables for timeouts or TTLs; for those, or your own client, see +[Custom handlers](./docs/custom-handlers.md). + +`withCache(nextConfig, options?)` takes three options: | Option | Default | What it does | |---|---|---| -| `pages` | `true` | Set `cacheHandler` (pages, route handlers, cached `fetch`) and `cacheMaxMemorySize: 0`. A `cacheMaxMemorySize` you set yourself is kept, with a warning if it is not `0`. `false` leaves `cacheHandler` and `cacheMaxMemorySize` as your config has them. | -| `useCache` | `"memory"` | `"redis"` stores plain `"use cache"` values in Redis too. Each read checks Redis; fresh instances of the same build reuse existing values. `handlers.default` overrides this choice. `handlers.remote` only changes `"use cache: remote"`. | +| `pages` | `true` | Also handle pages, route handlers and cached `fetch` (`cacheHandler`). `false` leaves them to Next. | +| `useCache` | `"memory"` | `"redis"` stores plain `"use cache"` values in Redis too, so instances of the same build share them. `handlers.default` overrides it. | | `handlers` | built-in files | `{ page?, default?, remote? }`: paths to [your own handler files](./docs/custom-handlers.md). | -| `memory` | `{ heapPercent: 10 }` | The in-process cache budget per runtime: `heapPercent` of V8's heap limit (a little above `--max-old-space-size`), or `maxMiB` (an absolute budget, which wins). Wins over the `CACHE_MEMORY_*` variables. Not seen by a standalone `server.js`, which never loads `next.config`: use the variables there. See [Memory](./docs/operations.md#memory). | - -```js -// Share plain "use cache" values across instances (REDIS_URL required) -export default withCache({ cacheComponents: true }, { useCache: "redis" }); -``` - -```js -// "use cache" only; leave pages to Next's default cache -export default withCache({ cacheComponents: true }, { pages: false }); -``` +| `memory` | `{ heapPercent: 10 }` | The in-process cache budget. Not seen by a standalone `server.js`: use the `CACHE_MEMORY_*` variables there. See [Memory](./docs/operations.md#memory). | `withCache` throws if the config already sets `cacheHandlers`, or `cacheHandler` unless -`pages: false`, because two configs fighting over the cache is always a bug. Use `handlers` -instead. It also accepts a function-form `next.config`. - -### Environment variables - -| Variable | Default | Meaning | -|---|---|---| -| `REDIS_URL` (or `VALKEY_URL`) | unset → memory only | `redis://` or `rediss://` URL, password included. | -| `REDIS_PASSWORD` | — | Password when the URL has none. | -| `ELASTICACHE_ENDPOINT`, `ELASTICACHE_PORT`, `ELASTICACHE_AUTH_TOKEN`, `ELASTICACHE_TLS` | port `6379`, TLS on | Host form, used when no URL is set. `ELASTICACHE_TLS=false` turns TLS off. | -| `ELASTICACHE_IAM_USER` | unset | ElastiCache IAM authentication as this user id, instead of an auth token, with tokens refreshed by the package ([details](./docs/redis.md#iam-authentication)). Needs TLS. | -| `ELASTICACHE_CACHE_NAME` | — | With IAM: the replication group id or serverless cache name the token is signed for. Required. | -| `ELASTICACHE_REGION` | `AWS_REGION`, then `AWS_DEFAULT_REGION` | With IAM: the cache's region. | -| `ELASTICACHE_SERVERLESS` | from the hostname | With IAM: `true` for ElastiCache Serverless; unset, on for a `.serverless.` endpoint. | -| `CACHE_KEY_PREFIX` | `nextjs:` | Prefix for every key. Use it to share one Redis between apps. | -| `CACHE_REDIS` | `on` | `off` forces memory everywhere, even with a URL set. | -| `CACHE_DEBUG` | unset | `1` logs hits, misses, writes and state changes. It never logs the URL. | -| `CACHE_COMPRESSION` | `on` | Entries of 16 KB and more are Brotli-compressed. `off` stores them uncompressed. | -| `CACHE_MEMORY_HEAP_PERCENT` | `10` | In-process cache budget as a share of the V8 heap limit, in percent (more than 0, less than 100). | -| `CACHE_MEMORY_MAX_MIB` | unset | In-process cache budget in MiB. Wins over `CACHE_MEMORY_HEAP_PERCENT`. `withCache`'s `memory` wins over both. | - -There are no tuning variables for timeouts or TTLs. The [installation guide](./docs/installation.md#environment-variables) -has the full table; for your own client or timeouts, see [Custom handlers](./docs/custom-handlers.md). - -## Tested against Next.js's own tests - -Every PR that changes the package's source runs the caching e2e suites from the -[`vercel/next.js`](https://github.com/vercel/next.js) repo, using Next's deploy-mode test harness -for deployment adapters. Each suite runs twice: once against a plain `next start`, and once with -this package, two instances behind a round-robin proxy (one instance where a fixture keeps its own -handler), sharing one Redis. CI fails if a suite (or a test) that passes on `next start` does not -pass with the package. - -At Next 16.4.2 that is **0 regressions outside one known Next bug**: apart from `app-static` -(below), every suite and test that passes on `next start` also passes with the package. 28 -suites, 18 of which run tests in deploy mode -([results](./tests/next-deploy/results/baseline-v16.4.2.md); live results on the -[deploy-tests workflow](https://github.com/mrjasonroy/cache-components-cache-handler/actions/workflows/next-deploy-tests.yml)). -The limits: - -- `test/e2e/app-dir/app-static` fails with any custom cache handler, because of a Next bug - (Turbopack's edge `cacheHandlers` registration, fixed in a later Next canary, - vercel/next.js#100046). It is listed as a known failure. -- 10 suites, such as `use-cache` and `ppr-full`, run no tests in deploy mode, so they are not - covered here. - -The package's own tests add an e2e matrix on production builds (memory, Redis, Valkey, and the -ElastiCache host form: Redis with TLS and an auth token), including two instances sharing Redis -and Redis stopped mid-run, and an outage suite on real Redis 7 and Valkey 8 (down at boot, lost -mid-run, stalled, back). - -ElastiCache IAM authentication is tested against a real ElastiCache Serverless cache (Valkey 8.1): -connecting with a token, re-authenticating the live connection, reconnecting, a tag revalidation -across two connections and `flushCache`. That needs an AWS account and a runner in the cache's -VPC, so it is not in per-PR CI: it is a manual gate before a release -(`scripts/aws-iam-e2e/run.sh`, see [development](./docs/development.md#elasticache-iam-against-a-real-cache)). -The token signing and refresh are unit-tested on every PR. -See [the harness README](./tests/next-deploy/README.md) and -[how it's tested](./docs/development.md#how-its-tested). - -## Supported backends - -| Backend | How | -|---|---| -| **Memory** | No `REDIS_URL`: dev, CI, previews, single instance | -| **Redis 6.2+** | `REDIS_URL=redis://…` or `rediss://…` | -| **Valkey** | `VALKEY_URL` or `REDIS_URL`, same URL format | -| **AWS ElastiCache** | `ELASTICACHE_ENDPOINT` + `ELASTICACHE_AUTH_TOKEN`, TLS on (`ELASTICACHE_TLS=false` turns it off) | -| **AWS ElastiCache, IAM auth** | `ELASTICACHE_ENDPOINT` (or a `rediss://` `REDIS_URL`) + `ELASTICACHE_IAM_USER`, `ELASTICACHE_CACHE_NAME`, `ELASTICACHE_REGION`. TLS required; Valkey 7.2+ or Redis OSS 7.0+; node-based or serverless (detected from a `.serverless.` endpoint, or `ELASTICACHE_SERVERLESS`). Needs the optional peer dependencies `@smithy/signature-v4`, `@aws-crypto/sha256-js` and `@aws-sdk/credential-provider-node`. [Details](./docs/redis.md#iam-authentication) | -| **Redis Cluster, Sentinel** | Your own ioredis client through a [custom handler](./docs/custom-handlers.md). `flushCache` scans every master. | - -The minimum is Redis 6.2 (or any Valkey): revalidations use `ZADD GT` and a single-key Lua -script, so the server must allow `EVAL`/`EVALSHA`. CI runs Redis 7 and Valkey 8. -[Redis Configuration](./docs/redis.md) covers connections, key layout and sizing. - -## Migrating - -From 16.4.2, replace your handler files and `cacheHandlers` config with -`withCache({ cacheComponents: true })` and delete the files. `"use cache"` then goes to memory and -`"use cache: remote"` to Redis (or set `useCache: "redis"` to share plain `"use cache"` too), and -pages go through Redis too. The cache starts cold, and -revalidations do not cross between 16.4.2 and 16.4.3 instances during a rolling deploy: deploy -with recreate, or revalidate once afterwards. `RedisCacheHandler` subclasses keep working. - -From `@fortedigital/nextjs-cache-handler` or `@neshca/cache-handler`, replace `cacheHandler` and -`cacheMaxMemorySize` with `withCache`. - -The [migration guide](./docs/migrating.md) has the details. +`pages: false`. Use `handlers` instead. The [API reference](./docs/api-reference.md#withcachenextconfig-options) +has the details. + +## Requirements and testing + +Redis 6.2+ or any Valkey, with Lua scripting allowed (revalidations use `ZADD GT` and a +single-key script). CI runs Redis 7 and Valkey 8, a production-build e2e matrix (memory, Redis, +Valkey, ElastiCache with TLS and an auth token) and an outage suite. Every PR that changes the +package also runs Next.js's own caching e2e suites, with two instances sharing Redis, and fails +on any regression against plain `next start`. ElastiCache IAM is tested by hand against a real +ElastiCache Serverless cache before each release. +[How it's tested](./docs/development.md#how-its-tested) has the details and known limits. ## Documentation diff --git a/docs/agent-setup.md b/docs/agent-setup.md new file mode 100644 index 0000000..e0bc6a4 --- /dev/null +++ b/docs/agent-setup.md @@ -0,0 +1,89 @@ +# Set it up with a coding agent + +Paste this prompt into Claude Code, Cursor, Codex or another coding agent, from the root of your +Next.js app. It installs and configures the handler, then reports what it changed. + +````text +Install and configure @mrjasonroy/cache-components-cache-handler in this Next.js app. +Docs: https://github.com/mrjasonroy/cache-components-cache-handler/tree/v/docs +(the tag of the version you install in step 2; main if the tag is missing). + +1. Check the versions. + - Read the installed Next.js version (node_modules/next/package.json, else package.json). + It must be 16.x. If it is not, stop and tell me. + - Run `node --version`. It must be 22.3 or later. If it is not, stop and tell me. + +2. Install the handler release with the same major.minor as Next.js, pinned exact, with this + project's package manager. For Next 16.4.x: + npm install --save-exact @mrjasonroy/cache-components-cache-handler@16.4 + pnpm add --save-exact @mrjasonroy/cache-components-cache-handler@16.4 + yarn add --exact @mrjasonroy/cache-components-cache-handler@16.4 + bun add --exact @mrjasonroy/cache-components-cache-handler@16.4 + Never save a ^ or ~ range: the 16.5 releases remove APIs. + +3. Configure next.config (.mjs, .js or .ts): + - Wrap the exported config: `export default withCache({ ...config, cacheComponents: true })`, + importing `withCache` from "@mrjasonroy/cache-components-cache-handler". A config function + can be wrapped as it is. `experimental.useCache` also works if the app already uses it. + - Remove `cacheHandler`, `cacheHandlers` and `cacheMaxMemorySize` from the config: + withCache sets them and throws if `cacheHandler` or `cacheHandlers` is already set. + - If those pointed at handler files from this package (16.4.2) or from + @neshca/cache-handler or @fortedigital/nextjs-cache-handler, follow docs/migrating.md and + delete the old handler files. + - Do not put connection settings in next.config. The handlers read them from the + environment of the running app. + +4. Work out the backing store from the app's env files and deployment config (.env*, + Dockerfile, docker-compose, Kubernetes manifests, Terraform, the hosting platform's settings). + Answer these in order and take the first path that matches: + a. Is a Redis, Valkey or ElastiCache configured at all (REDIS_URL, VALKEY_URL or + ELASTICACHE_ENDPOINT), and not turned off with CACHE_REDIS=off? If not: no Redis. + Everything stays in memory. Done. + b. Is it a cluster: ElastiCache with cluster mode enabled (a `clustercfg.` endpoint), a Redis + Cluster, or Sentinel? Then write custom handler files with one shared ioredis client, as in + docs/custom-handlers.md. For IAM there, follow "IAM on your own client" in docs/redis.md. + Done. + c. Is ELASTICACHE_IAM_USER set (IAM, on Serverless or cluster mode disabled, with either + ELASTICACHE_ENDPOINT or a rediss:// REDIS_URL)? Then install @smithy/signature-v4, + @aws-crypto/sha256-js and @aws-sdk/credential-provider-node (the package throws without + them), and make sure ELASTICACHE_CACHE_NAME and a region (ELASTICACHE_REGION or AWS_REGION) + are set. See "IAM authentication" in docs/redis.md. Done. + d. Otherwise (REDIS_URL, VALKEY_URL, or ELASTICACHE_ENDPOINT with ELASTICACHE_AUTH_TOKEN): + nothing to add. Done. + If it is unclear which applies, ask me instead of guessing. + +5. Do not use the deprecated API. These still work in 16.4.x but are removed in 16.5: + createCacheHandler, createCacheConfig, createCacheConfigWithProfiles, + createRedisDataCacheHandler, createMemoryDataCacheHandler, createIoredisAdapter, + createCompositeHandler, CompositeHandler, createMemoryCacheHandler, MemoryCacheHandler, + RedisCacheHandler#close(), the page handler's `redis` and `tagPrefix` options, and the + helpers bufferToString, stringToBuffer, jsonReplacer, jsonReviver, isImplicitTag, + calculateLifespan, isExpired and IMPLICIT_TAG_PREFIX. The current API is withCache, plus + createPageCacheHandler, createRemoteCacheHandler, createLocalCacheHandler, + attachElastiCacheIamAuth, flushCache, closeCache and setCacheLogger for custom setups. + +6. Verify. Run Next through the app's own scripts or the package manager (`npm run build`, or + `npx next build` / `pnpm exec next build`); a bare `next` is usually not on the PATH. + - Build. It never connects to Redis, so it needs no Redis. Turning on cacheComponents can + surface errors in routes that read request data outside a Suspense boundary. Report those + to me with the routes named; do not rewrite pages to silence them. + - If the configured Redis is reachable from here, start the app with its real connection + settings and `CACHE_DEBUG=1`, load a cached page twice and check the log shows + `[PageCache]: set ... redis` and then `[PageCache]: get ... hit` (a prerendered page's first + read logs `build output`). That log is the check. Only if you can also reach that same + Redis with redis-cli, using its host, port, TLS and auth (`redis-cli -u `, adding + `--tls` for rediss://), confirm `--scan --pattern '*'` (default + `nextjs:*`) lists keys. Skip redis-cli for IAM and cluster setups. + + - With cacheComponents on, a route handler that reads no request data is prerendered and + never runs again, so a health, readiness or metrics route goes stale. Look for those routes + (for example `/api/health`, `/api/actuator/*`, `/api/metrics`). If one has no + `await connection()` (from next/server) or other request data, tell me. Do not change probe + paths or deployment config yourself. See "Health checks" in docs/operations.md. + +7. Tell me what you changed: the files, the package and version installed, the path you chose + in step 4 and why, and anything you could not verify. +```` + +The steps follow [Installation](./installation.md), [Redis Configuration](./redis.md) and +[Migrating](./migrating.md). The agent reads the docs at the tag of the version it installs. diff --git a/docs/api-reference.md b/docs/api-reference.md index 14ae6ca..b0ba19c 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -39,6 +39,8 @@ function withCache( interface WithCacheOptions { /** Set cacheHandler and cacheMaxMemorySize: 0. @default true */ pages?: boolean; + /** Storage for plain "use cache": "redis" shares values across instances. @default "memory" */ + useCache?: "memory" | "redis"; /** Your own handler files. Relative paths resolve against process.cwd(). */ handlers?: { page?: string; default?: string; remote?: string }; /** @@ -60,12 +62,12 @@ Returns `nextConfig` plus: |---|---| | `cacheHandler` | `handlers.page`, or the built-in page handler. Omitted with `pages: false`. | | `cacheHandlers.remote` | `handlers.remote`, or the built-in remote handler. | -| `cacheHandlers.default` | `handlers.default`, or the built-in local handler. | +| `cacheHandlers.default` | `handlers.default`, or the built-in local handler (memory), or with `useCache: "redis"` the built-in remote handler, which falls back to memory without Redis. | | `cacheMaxMemorySize` | `0`, unless `nextConfig` sets it: then that value is kept, with a warning if it is not `0` (it has no effect once `withCache` sets the handlers). Omitted with `pages: false`. | Throws if `nextConfig` already sets `cacheHandlers`, or `cacheHandler` unless `pages: false` (then yours is kept), and if `memory` has a `heapPercent` outside (0, 100), a `maxMiB` that is -not a finite number above 0, or any other key. `memory` adds no key to the config: it is handed to the handlers +not a finite number above 0, a `useCache` other than `"memory"` or `"redis"`, or any other key. `memory` adds no key to the config: it is handed to the handlers through the environment of the process that loaded `next.config` (`next dev`, `next start`), so a standalone `server.js` does not see it; `withCache` warns when `output: "standalone"` is set with it. See [Memory](./operations.md#memory). A config function is wrapped @@ -76,7 +78,8 @@ The built-in handlers read the [environment](./installation.md#environment-varia ## `CacheOptions` Shared by every factory below and by `flushCache`. Each defaults to the environment, so a factory -called with no options behaves like the built-in handler. +called with no options behaves like the built-in handler. The table form, with notes, is in +[Custom handlers](./custom-handlers.md#cacheoptions). ```ts interface CacheOptions { @@ -155,7 +158,7 @@ alias until 16.5) is Next's constructor context plus `CacheOptions` and: |---|---|---| | `buildId` | the app's deployment ID if set, else its `BUILD_ID` | The build that scopes entry keys. | | `defaultTTL` | `31536000` (365 days) | Lifetime in seconds of an entry with neither `revalidate` nor `expire`, at most 365 days. | -| `redis` | — | The 16.4.2 form: an ioredis client, a URL or an ioredis options object. Prefer `client` / `url`. | +| `redis` | — | Deprecated (removed in 16.5): the 16.4.2 form of `client` / `url`, an ioredis client, a URL or an ioredis options object. Use `client` or `url`. | | `tagPrefix` | — | Deprecated and ignored. Tag records live in the `tags` hash. | The constructor has the same shape as in 16.4.2, so subclasses keep working. `close()` is deprecated: @@ -176,9 +179,11 @@ handler is created). Every entry is kept at most 365 days. ### `createLocalCacheHandler(options?)` -For `"use cache"`. Values live in this process's memory (up to 10,000 entries and 32/98 of the -[memory budget](./operations.md#memory), about 27 MiB at `--max-old-space-size=768` on Node 22; a larger value is not kept) until their `revalidate` period. When Redis is configured, tag invalidations are shared across instances. -Takes `CacheOptions`; only the connection, `keyPrefix`, `debug` and `logger` matter. +For `"use cache"`. Values live in this process's memory until their `revalidate` period: up to +10,000 entries and 32/98 of the [memory budget](./operations.md#memory) (about 27 MiB at +`--max-old-space-size=768` on Node 22). A larger value is not kept. When Redis is configured, +tag invalidations are shared across instances. Takes `CacheOptions`; only the connection, +`keyPrefix`, `debug` and `logger` matter. ```js // cache/default.mjs @@ -227,13 +232,10 @@ function closeCache(): Promise; ``` For test runs, scripts and CLIs, so Node can exit; a Next server never needs it. Closes every -Redis connection the package opened in this process and empties its memory stores. It first -waits for tag writes in flight and sends any Redis has not acknowledged once more; one still -refused is kept, applied by this process and sent by the handlers once Redis takes it, if they -are used again. It never rejects because Redis is down. Safe to call more than once, and -concurrently: a call made while a close runs closes, after it, any connection opened meanwhile. A `client` you passed in is never closed. -Handlers created before it reconnect on their next call, onto one new connection; the deprecated -`createCacheHandler` does not, and serves from memory until it is created again. +Redis connection the package opened in this process and empties its memory stores. A `client` +you passed in is never closed. It never rejects because Redis is down, and is safe to call more +than once. Handlers created before it reconnect on their next call. The details, including what +happens to revalidations in flight, are under [Closing the cache](./operations.md#closing-the-cache). ```ts import { afterAll } from "vitest"; @@ -273,19 +275,25 @@ function attachElastiCacheIamAuth( ): { refresh(): Promise; stop(): void }; ``` -For a client you build yourself, such as a `Cluster` for cluster-mode-enabled ElastiCache. Create -it with `lazyConnect: true` and TLS and do not connect it: this connects it once the first IAM -token is in its options, makes a new token every 10 minutes for reconnects (every node's options -on a `Cluster`) and sends `AUTH` with it on every connected node. Options left out come from the -environment, as in [IAM authentication](./redis.md#iam-authentication). Throws when IAM cannot work -(TLS off, no user, cache name or region) or the AWS packages are not installed. `stop()` ends the -refresh; the client keeps its connections. +For a client you build yourself, such as a `Cluster` for cluster-mode-enabled ElastiCache. +Create the client with `lazyConnect: true` and TLS, and do not connect it. Then this: + +- connects it once the first IAM token is in its options; +- makes a new token every 10 minutes, puts it in the options for reconnects (every node's options + on a `Cluster`) and sends `AUTH` with it on every connected node. + +Options left out come from the environment, as in +[IAM authentication](./redis.md#iam-authentication). Throws when IAM cannot work (TLS off, no +user, cache name or region) or the AWS packages are not installed. `refresh()` makes a new token +now; `stop()` ends the refresh and leaves the client connected. Call it once per client: +[IAM on your own client](./redis.md#iam-on-your-own-client) has the full handler-file example. ## Legacy data cache API -The data cache API of 16.4.2 and earlier. Deprecated in 16.4.3: it keeps working in 16.4.x, logs a one-time deprecation warning on first -use, and is removed in 16.5. Use `withCache`, or `createRemoteCacheHandler` / `createLocalCacheHandler`. `createCacheHandler` keeps its own key layout (`nextjs:data-cache:`, -`nextjs:tags:`) and covers `"use cache"` only, not pages. +The data cache API of 16.4.2 and earlier. Deprecated in 16.4.3: it keeps working in 16.4.x, +logs a one-time deprecation warning on first use, and is removed in 16.5. Use `withCache`, or +`createRemoteCacheHandler` / `createLocalCacheHandler`. `createCacheHandler` keeps its own key +layout (`nextjs:data-cache:`, `nextjs:tags:`) and covers `"use cache"` only, not pages. ### `createCacheHandler(options)` @@ -301,9 +309,8 @@ connection, fall back to memory during an outage, and use memory during `next bu `CACHE_REDIS=off`. The 16.4.2 wiring still works: a handler file that exports `createCacheHandler({ type })`, wired -with `createCacheConfig` or by hand into `cacheHandlers`. It covers `"use cache"` only, not -pages. In production it logs a one-time reminder to use `withCache`; pass -`suppressIsrWarning: true` to silence it. +with `createCacheConfig` or by hand into `cacheHandlers`. In production it logs a one-time +reminder to use `withCache`; pass `suppressIsrWarning: true` to silence it. `createCacheHandler` reads `REDIS_URL` / `VALKEY_URL`, `REDIS_PASSWORD` and the `ELASTICACHE_*` variables, and honours `CACHE_REDIS=off` and the build phase. It does not read `CACHE_KEY_PREFIX` @@ -370,11 +377,12 @@ log a one-time deprecation warning (once per process, per API) on first use. The | `createRedisDataCacheHandler`, `createIoredisAdapter` | `createRemoteCacheHandler({ client })` | It takes an ioredis client directly; no adapter. | | `createMemoryDataCacheHandler` | `createLocalCacheHandler` | Memory with tag invalidation shared across instances. | | `RedisCacheHandler#close()` | `closeCache()` | The same, without needing a handler. | +| The page handler's `redis` and `tagPrefix` options, and a `defaultTTL` that is not a number | `client` or `url`; nothing for `tagPrefix`; a number of seconds | 16.4.2 forms. `tagPrefix` is ignored: tag records live in the `tags` hash. | | `RedisCacheHandlerOptions` | `PageCacheHandlerOptions` | Renamed with `createPageCacheHandler`; the same type. | -| `createCacheConfig`, `createCacheConfigWithProfiles` | `withCache` | Both make you write and wire handler files yourself. They keep working. | +| `createCacheConfig`, `createCacheConfigWithProfiles` | `withCache` | Both make you write and wire handler files yourself. | | `CompositeHandler`, `createCompositeHandler` | built in | The memory fallback is now inside every handler. | | `MemoryCacheHandler`, `createMemoryCacheHandler` | `withCache` without `REDIS_URL` | Memory only is the no-URL mode. | -| `bufferToString`, `stringToBuffer`, `jsonReplacer`, `jsonReviver`, `isImplicitTag`, `calculateLifespan`, `isExpired`, `IMPLICIT_TAG_PREFIX`, and the Next 14 `CacheHandler*` / `CacheValue` / `LifespanParameters` types | none | Internals of the Next 14 handlers. They still work. | +| `bufferToString`, `stringToBuffer`, `jsonReplacer`, `jsonReviver`, `isImplicitTag`, `calculateLifespan`, `isExpired`, `IMPLICIT_TAG_PREFIX`, and the Next 14 `CacheHandler*` / `CacheValue` / `LifespanParameters` types | none | Internals of the Next 14 handlers. | `RedisCacheHandler` is **not** deprecated. It is the page handler `withCache` uses. @@ -408,7 +416,9 @@ replacements. `AwsCredentialsProvider`, `PageCacheHandlerOptions`, `RedisCacheHandlerOptions` (deprecated), `RemoteCacheHandlerOptions`, `LocalCacheHandlerOptions`, `FlushCacheOptions`, `FlushCacheResult`, `PageCacheControl`, `PageCacheGetContext`, `PageCacheHandlerContext`, `PageCacheHandlerValue`, -`PageCacheSetContext`, `PageCacheValue`, `DataCacheHandler`, `DataCacheEntry`, `Timestamp`, +`PageCacheSetContext`, `PageCacheValue`, `DataCacheHandler`, `DataCacheEntry`, `Timestamp`. + +Types of the deprecated legacy data cache API, removed with it in 16.5: `DataCacheHandlerOptions`, `CacheHandlerType`, `MemoryDataCacheHandlerOptions`, `RedisDataCacheHandlerOptions`, `RedisClient`, `IoredisLike`, `CacheHandlerConfig`. diff --git a/docs/custom-handlers.md b/docs/custom-handlers.md index 2ae18d9..10a2a06 100644 --- a/docs/custom-handlers.md +++ b/docs/custom-handlers.md @@ -1,21 +1,26 @@ # Custom handlers -Use your own handler files when you need a client you built yourself (Sentinel, a custom Cluster) -or different timeouts. ElastiCache IAM authentication needs neither: the environment turns it on -(see [IAM authentication](./redis.md#iam-authentication)), and the `iam` option sets it in a -handler file. Write one file per handler and give the paths to `withCache`. Each file keeps its -directive's role: `page` for pages, route handlers and cached `fetch`, `remote` for -`"use cache: remote"` (Redis), `default` for `"use cache"` (per-instance memory, shared tag -invalidation): +Use your own handler files when you need a client you built yourself (Sentinel, a Cluster) or +different timeouts. ElastiCache IAM on a serverless or cluster-mode-disabled cache needs neither: +the environment turns it on ([IAM authentication](./redis.md#iam-authentication)). + +Write one file per handler and give the paths to `withCache`. Each file keeps its directive's +role: + +- `page`: pages, route handlers and cached `fetch`. +- `remote`: `"use cache: remote"` (Redis). +- `default`: `"use cache"` (per-instance memory, shared tag invalidation). ```js -// cache/redis.mjs: one client for all three files, parked on globalThis because Next can load -// the three handler modules separately +// cache/redis.mjs import Redis from "ioredis"; -const key = Symbol.for("my-app.redis"); -globalThis[key] ??= new Redis(process.env.REDIS_URL, { commandTimeout: 1000 }); -export const client = globalThis[key]; +function createClient() { + return new Redis(process.env.REDIS_URL, { commandTimeout: 1000 }); +} + +// One client per process: Next can load each handler file in its own module graph. +export const client = (globalThis.myAppRedis ??= createClient()); ``` ```js @@ -64,49 +69,25 @@ runs), not against `next.config`; when the two can differ, pass an absolute path Handlers that share a client and key prefix share one connection and one tag store. A handler you don't replace keeps reading the environment. So if you pass a `client` and leave `REDIS_URL` -unset, also provide `default`; otherwise `"use cache"` tag invalidation stays local to each -instance. +unset, replace all three: a handler you leave out runs without Redis. For `default`, that means +`"use cache"` tag invalidation stays local to each instance. A client you pass in is yours: the package never closes, disconnects or reconfigures it. The -package's own commands reach it through a proxy that bounds them by `commandTimeout`. After 3 -timeouts in a row the handlers serve from memory for 2 s at a time, until a command succeeds -again. Your other uses of the client are unaffected, so set its own `commandTimeout` (and a -`retryStrategy`) for those. [Redis Configuration](./redis.md#your-own-client) has Sentinel and -Cluster clients. - -For ElastiCache IAM authentication on a client of your own, which is the way to use IAM with -cluster-mode-enabled ElastiCache (a `Cluster`), create the client with `lazyConnect: true` and TLS, -do not connect it, and call `attachElastiCacheIamAuth(client, { userId, cacheName, region })` -once: it connects the client when the first token is ready, refreshes the token every 10 minutes -and re-authenticates the live connections. Fields you leave out come from the `ELASTICACHE_*` -environment. Then pass the client as `client` (not `iam`, which throws with `client`): - -```js -// cache/redis.mjs -import { Cluster } from "ioredis"; -import { attachElastiCacheIamAuth } from "@mrjasonroy/cache-components-cache-handler"; - -const key = Symbol.for("my-app.redis"); -globalThis[key] ??= (() => { - const client = new Cluster([{ host: process.env.ELASTICACHE_ENDPOINT, port: 6379 }], { - lazyConnect: true, - dnsLookup: (address, callback) => callback(null, address), - redisOptions: { tls: {}, commandTimeout: 1000 }, - }); - attachElastiCacheIamAuth(client, { userId: "app-user", cacheName: "my-cache", region: "us-east-1" }); - return client; -})(); -export const client = globalThis[key]; -``` +package's own commands on it are bounded by `commandTimeout`. After 3 timeouts in a row the +handlers serve from memory for 2 s at a time, until a command succeeds again. Your other uses of +the client are unaffected, so set its own `commandTimeout` and `retryStrategy` for those. +[Redis Configuration](./redis.md#your-own-client) has Sentinel and Cluster clients. -ElastiCache Serverless and cluster-mode-disabled caches need none of this: the environment's -connection handles them. +For ElastiCache IAM on a client of your own (the only way to use IAM with cluster-mode-enabled +ElastiCache), call `attachElastiCacheIamAuth` on it inside `createClient`. Do not pass `iam` +with `client`: that throws. [IAM on your own client](./redis.md#iam-on-your-own-client) has the +example. All commands share one connection, so a large value on a slow link delays the commands queued -behind it. At 1000 ms, a 5 MB entry needs about 40 Mbit/s (compression usually makes a page -entry much smaller than the page); on a slower link (cross-region, or an -ElastiCache node out of network burst credits) raise `commandTimeout`, or 3 timeouts in a row -send the handlers to memory. +behind it. At 1000 ms, a 5 MB entry needs about 40 Mbit/s. Compression usually makes a page +entry much smaller than the page. On a slower link (cross-region, or an ElastiCache node out of +network burst credits) raise `commandTimeout`, or 3 timeouts in a row send the handlers to +memory. ## `CacheOptions` @@ -127,16 +108,18 @@ All three factories take `CacheOptions`: | `logger` | `setCacheLogger`'s, else the console | Where this handler's warnings, errors and debug lines go (see [Logging](./operations.md#logging)). | Handlers given the same connection settings share one connection and one tag state. Give every -handler file the same `url`, timeouts and `maxConsecutiveTimeouts`: different settings open a -second connection to the same server, and the package logs a warning when that happens. - -`createPageCacheHandler` and `createRemoteCacheHandler` also take `buildId` (default: the app's -deployment ID when one is set, else its `BUILD_ID`; see -[skew protection](./how-it-works.md#skew-protection-and-the-deployment-id)), the build that -scopes entry keys. Both also take `defaultTTL`, in seconds: -`createPageCacheHandler` keeps an entry with neither `revalidate` nor `expire` that long (default -and maximum 365 days), and `createRemoteCacheHandler` keeps an entry whose `expire` is infinite -that long (default 24 hours, maximum 365 days; anything but a number greater than 0 throws). +handler file the same `url`, `iam`, timeouts and `maxConsecutiveTimeouts`: different settings +open a second connection to the same server, and the package logs a warning when that happens. + +`createPageCacheHandler` and `createRemoteCacheHandler` also take: + +- `buildId`: the build that scopes entry keys. Default: the app's deployment ID when one is set, + else its `BUILD_ID` (see + [skew protection](./how-it-works.md#skew-protection-and-the-deployment-id)). +- `defaultTTL`, in seconds. The page handler keeps an entry with neither `revalidate` nor + `expire` that long (default and maximum 365 days). The remote handler keeps an entry whose + `expire` is infinite that long (default 24 hours, maximum 365 days); anything but a finite + number greater than 0 throws. `CACHE_REDIS=off` and the build phase apply to custom handlers too: they never use Redis then. diff --git a/docs/development.md b/docs/development.md index 7d8b609..5083b85 100644 --- a/docs/development.md +++ b/docs/development.md @@ -38,8 +38,8 @@ pnpm format # Format all code pnpm typecheck # TypeScript type checking # Docker -pnpm docker:up # Start Redis -pnpm docker:down # Stop Redis +pnpm docker:up # Start Redis (6379), Valkey (6380) and Redis Commander (8081) +pnpm docker:down # Stop them # Cleanup pnpm clean # Remove all build artifacts @@ -123,8 +123,27 @@ ELASTICACHE_CACHE_NAME= ELASTICACHE_REGION= \ ### Next.js's own caching suites -`tests/next-deploy/` runs Next.js's caching e2e suites in deploy mode against the package. It runs -in CI; see [tests/next-deploy/README.md](../tests/next-deploy/README.md). +`tests/next-deploy/` runs the caching e2e suites from the +[`vercel/next.js`](https://github.com/vercel/next.js) repo, using Next's deploy-mode test harness +for deployment adapters. Every PR that changes the package's source runs them. Each suite runs +twice: once against a plain `next start`, and once with this package, two instances behind a +round-robin proxy (one instance where a fixture keeps its own handler), sharing one Redis. CI +fails if a suite (or a test) that passes on `next start` does not pass with the package. + +At Next 16.4.2 that is 0 regressions outside one known Next bug: apart from `app-static`, every +suite and test that passes on `next start` also passes with the package. 28 suites, 18 of which +run tests in deploy mode ([results](../tests/next-deploy/results/baseline-v16.4.2.md); live +results on the +[deploy-tests workflow](https://github.com/mrjasonroy/cache-components-cache-handler/actions/workflows/next-deploy-tests.yml)). +The limits: + +- `test/e2e/app-dir/app-static` fails with any custom cache handler, because of a Next bug + (Turbopack's edge `cacheHandlers` registration, fixed in a later Next canary, + vercel/next.js#100046). It is listed as a known failure. +- 10 suites, such as `use-cache` and `ppr-full`, run no tests in deploy mode, so they are not + covered here. + +See [tests/next-deploy/README.md](../tests/next-deploy/README.md). ## How it's tested diff --git a/docs/how-it-works.md b/docs/how-it-works.md index e09841a..f8cca9f 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -2,7 +2,7 @@ What `withCache` sets up, how invalidation reaches every instance, how pages and route handlers are cached, and what happens when Redis goes down. Setup is in the -[README](../README.md#quick-start) and the [installation guide](./installation.md). +[README](../README.md#start-here) and the [installation guide](./installation.md). ## What goes where @@ -126,24 +126,23 @@ Limits worth knowing: removal 365 days plus 10 seconds after the later of its last update and its hard expiration deadline. A custom delayed revalidation extends retention by its full duration; `"max"` therefore needs about two years. Flush barriers are kept permanently. -- **Redis 7.4+ and Valkey 9+** expire tag hash fields themselves. Support is probed once per - connection in the background, by command capability rather than server version. Subsequent - writes set the merged record's field deadline atomically in the existing write script. - Startup writes use the same guarded script before the prompt background probe completes, so - they cannot strip a supported server's field TTL. A failed probe selects the fallback; a - transient failure is retried once on the next connection-ready event. +- **Redis 7.4+ and Valkey 9+** expire tag hash fields themselves. The package probes for this + once per connection, in the background, by command rather than by server version. Once it + knows, each tag write sets the field's deadline in the same script. Writes made before the + probe finishes cannot remove a field TTL the server already has. A failed probe selects the + fallback below; a transient failure is retried once on the next connection. - **Standalone Redis / Valkey** also checks up to 1,000 old index members once per minute, atomically deleting eligible hash records and index members. It checks the record's deadline too, so a concurrent revalidation is preserved. Maintenance adds no request-path command and stops with `closeCache()`. With `CACHE_DEBUG=1`, its `tag retention` line reports `pruned`, `tagFields` and `tagIndexMembers` without an extra command. -- **Cluster limitation:** the existing hash and index may occupy different slots. Automatic - fallback pruning is skipped on Cluster or after `CROSSSLOT`. Without hash-field TTL support, - tag records grow until `flushCache({ scope: "all" })`, with a warning at most hourly by - default. On a supported Cluster the hash fields expire, but index members remain until a flush; syncing - an expired field returns no record, which is safe after its full retention window. `tag-index` - grows by one small member per distinct revalidated tag until a flush. Standalone gets the - full prune; existing fields written by an older package gain a TTL only on a later update. +- **Cluster limitation:** the tag hash and the index may sit in different slots, so the + fallback pruning is skipped on a Cluster (or after a `CROSSSLOT` error). Without hash-field + TTLs, tag records grow until `flushCache({ scope: "all" })`, with a warning at most hourly. + With them, the hash fields expire, but `tag-index` keeps one small member per distinct + revalidated tag until a flush. That is safe: an expired field reads as no record, which is + only possible after its full retention window. +- Fields written by an older package gain a TTL only when that tag is next updated. - **Unstamped build output:** build output with no surviving stamp can come back after its tag record is pruned. This only happens to a deployment serving the same build for over 365 days after the tag's last invalidation. Redeploy or flush within a year. Missing-stamp diff --git a/docs/installation.md b/docs/installation.md index 2201669..3c68a3b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -11,15 +11,17 @@ ## Install ```bash -npm install --save-exact @mrjasonroy/cache-components-cache-handler +# Next 16.4.x: the newest 16.4 release, pinned exact +npm install --save-exact @mrjasonroy/cache-components-cache-handler@16.4 ``` -The package version follows Next.js. Pin it to the exact release for your Next.js version -(`--save-exact`; Next 16.4.3 → `16.4.3`) and upgrade the two together. A range such as `^16.4.3` -also accepts the 16.5 releases, which follow Next.js 16.5 and remove the APIs deprecated in -16.4.3. From the next release, the `next` peer dependency is `~..0` of the -package's own version (for example `~16.4.0` for 16.4.x), so npm refuses a handler whose minor -does not match your Next.js with an `ERESOLVE` error, and pnpm and Yarn warn. +The package version follows Next.js: use the release with the same major.minor as your Next.js, +pin it exact, and upgrade the two together. A range such as `^16.4.3` would also accept the 16.5 +releases, which follow Next.js 16.5 and remove the APIs deprecated in 16.4.3. + +From the release after 16.4.3, the `next` peer dependency is `~..0` of the +package's own version (`~16.4.0` for 16.4.x). npm then refuses a handler whose minor does not +match your Next.js with an `ERESOLVE` error, and pnpm and Yarn warn. `ioredis` is an optional dependency, so it is installed with the package unless your package manager skips optional dependencies (`npm install --omit=optional`, `pnpm install --no-optional`, @@ -38,17 +40,22 @@ export default withCache({ }); ``` -That one call sets `cacheHandler` (pages, route handlers, cached `fetch`), `cacheHandlers.default` -(`"use cache"`: each instance's memory, tag invalidation shared through Redis), -`cacheHandlers.remote` (`"use cache: remote"`: Redis) and `cacheMaxMemorySize: 0`. -`"use cache: private"` is Next's own and needs nothing. Don't -set any of those yourself: `withCache` throws if the config already has `cacheHandlers`, or -`cacheHandler` unless you pass `pages: false`. The [What goes where](./how-it-works.md#what-goes-where) table says what each one does. +That one call sets: + +- `cacheHandler`: pages, route handlers and cached `fetch`, in Redis. +- `cacheHandlers.default`: `"use cache"`, in each instance's memory, with tag invalidation shared + through Redis. +- `cacheHandlers.remote`: `"use cache: remote"`, in Redis. +- `cacheMaxMemorySize: 0`. + +`"use cache: private"` is Next's own and needs nothing. Don't set any of those yourself: +`withCache` throws if the config already has `cacheHandlers`, or `cacheHandler` unless you pass +`pages: false`. The [What goes where](./how-it-works.md#what-goes-where) table has more. `nextConfig` can also be a config function, `(phase, { defaultConfig }) => config`, sync or async. `withCache` then returns an async function that applies the same settings to its result. -The options (`pages`, `handlers`, `memory`) are in the [README](../README.md#withcachenextconfig-options) -and the [API reference](./api-reference.md#withcachenextconfig-options). +The options (`pages`, `handlers`, `memory`) are in the +[API reference](./api-reference.md#withcachenextconfig-options). The handler files ship inside the package, so there are no handler files to write. For your own client or timeouts, see [Custom handlers](./custom-handlers.md). @@ -82,12 +89,13 @@ ELASTICACHE_AUTH_TOKEN=... # ELASTICACHE_TLS=false (TLS is on by default) ``` -For IAM authentication instead of an auth token, set `ELASTICACHE_IAM_USER`, -`ELASTICACHE_CACHE_NAME` and `ELASTICACHE_REGION` (see -[IAM authentication](./redis.md#iam-authentication)). +This covers Serverless and cluster-mode-disabled caches (use the primary endpoint). For IAM +instead of an auth token, set `ELASTICACHE_IAM_USER`, `ELASTICACHE_CACHE_NAME` and +`ELASTICACHE_REGION`, and install the AWS signing packages +([IAM authentication](./redis.md#iam-authentication)). Cluster-mode-enabled ElastiCache needs +your own `Cluster` ([Redis Cluster](./redis.md#redis-cluster)). -A URL takes precedence over the endpoint when both are set. For cluster-mode-enabled ElastiCache, -see [Redis Cluster](./redis.md#redis-cluster). +A URL takes precedence over the endpoint when both are set. ## Environment variables @@ -132,6 +140,8 @@ If a dev `.env` file carries `REDIS_URL`, the dev server will use Redis; remove ``` 2. Load a page twice. The log shows `[PageCache]: set ... redis`, then `[PageCache]: get ... hit`. + A prerendered page's first read logs `build output` instead: it is served from `.next` and + copied to Redis. 3. Look at the keys: ```bash diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000..2a65bff --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,15 @@ +# @mrjasonroy/cache-components-cache-handler + +> Redis-backed cache handlers for Next.js 16+: pages, route handlers and "use cache: remote" in Redis; "use cache" in each instance's memory with tag invalidation shared through Redis. One call: withCache(nextConfig). Install the release with the same major.minor as Next.js, pinned exact. + +## Docs + +- [Agent setup](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/agent-setup.md): a copy-paste prompt that installs and configures the handler +- [Installation](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/installation.md): install, withCache, environment variables, verifying +- [Usage](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/usage.md): which directive lands in which cache, revalidation examples +- [Redis Configuration](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md): Valkey, ElastiCache (Serverless, cluster mode), IAM, Sentinel, Cluster, key layout, sizing +- [Custom handlers](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/custom-handlers.md): your own ioredis client or timeouts, CacheOptions +- [How it works](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/how-it-works.md): tag coordination, page lifetimes, Redis outages +- [Operations](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/operations.md): flushCache, closeCache, memory budget, health checks under cacheComponents, logging +- [API Reference](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/api-reference.md): every export, including the deprecated ones +- [Migrating](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/migrating.md): from 16.4.2, @neshca/cache-handler or @fortedigital/nextjs-cache-handler diff --git a/docs/operations.md b/docs/operations.md index 02b35c8..0f4a833 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -1,7 +1,7 @@ # Operations -Flushing the cache, closing it in tests and scripts, how much memory it holds, and sending its -logs to your own logger. +Flushing the cache, closing it in tests and scripts, how much memory it holds, health checks, and +sending its logs to your own logger. What sits in Redis, and how to size it, is in [Redis Configuration](./redis.md#whats-in-redis). ## Flushing the cache @@ -145,6 +145,47 @@ it still competes with the app for the same heap: measure your app's own baselin memory after warm-up with the cache empty) and check that it plus the budget (per runtime) leaves the heap room to spare. If it does not, lower `heapPercent` or raise the limit. +## Health checks + +With `cacheComponents`, a route handler that reads no request data is prerendered at build time. +A health check like this one never runs on a request: + +```ts +// app/api/health/route.ts: frozen at build time +export function GET() { + return Response.json({ status: "UP" }); +} +``` + +Next writes the response into the build output, and the page handler serves it from there +(`CACHE_DEBUG=1` logs `build output`). Every call answers `x-nextjs-cache: HIT` with +`cache-control: s-maxage=31536000`. A pass only shows that the port is open. It says nothing about +whether the app can run a request, so a pod reports ready before it has warmed up. It never fails +either. A metrics or uptime route has the same problem: it returns the values from the build. + +Make probe and metrics routes dynamic with `await connection()`, and send `no-store`: + +```ts +// app/api/health/live/route.ts +import { connection } from "next/server"; + +export async function GET() { + await connection(); + return Response.json({ status: "UP" }, { headers: { "Cache-Control": "no-store" } }); +} +``` + +Do not reach for `export const dynamic = "force-dynamic"`: Next's +[Cache Components migration guide](https://nextjs.org/docs/app/guides/migrating-to-cache-components) +says to remove it, and a request-time API such as `connection()` is what makes a route dynamic. To check a route is live, look for no `x-nextjs-cache` header +on its response, and check that it is missing from `.next/prerender-manifest.json` after +`next build`. + +Keep Redis out of liveness and readiness. A request never fails because of the cache: while Redis +is down, the handlers serve from each instance's memory. A probe that fails on Redis would turn a +Redis blip into a full outage, because every pod leaves the load balancer at once. If you want a +Redis check, put it on a separate endpoint for people and monitors, not for probes. + ## Logging Warnings, errors and `CACHE_DEBUG` lines go to the console by default. To send them to your own @@ -182,15 +223,20 @@ through the logger of the handler that opened them, so give every handler the sa `setCacheLogger`. The package never logs a Redis URL or the connection options, which can hold a password. What it -logs is scrubbed on the way out: an error (and each error in its `cause` chain) keeps only its -name, message, stack, `code`, `errno`, `syscall`, `address` and `port`, so the failed command -ioredis attaches to an error (a rejected `AUTH` carries the password it tried) is dropped; objects -lose `command`, `password` and similar keys; other values (a `Buffer`, a class instance) are logged -as a placeholder such as `[Buffer 12 bytes]`; and URLs in any text lose their user information. With ElastiCache IAM the token is never logged, -and the signature, credential and session token of a presigned AWS query -(`X-Amz-Signature`, `X-Amz-Credential`, `X-Amz-Security-Token`) are removed from any text. A -refused IAM token (`WRONGPASS`, `NOAUTH`, `NOPERM`) or one that cannot be made is logged as an -error naming IAM and what to check. +logs is scrubbed on the way out: + +- An error (and each error in its `cause` chain) keeps only its name, message, stack, `code`, + `errno`, `syscall`, `address` and `port`. So the failed command ioredis attaches to an error + is dropped (a rejected `AUTH` carries the password it tried). +- Objects lose `command`, `password` and similar keys. +- Other values (a `Buffer`, a class instance) are logged as a placeholder such as + `[Buffer 12 bytes]`. +- URLs in any text lose their user information. +- With ElastiCache IAM the token is never logged, and the signature, credential and session token + of a presigned AWS query (`X-Amz-Signature`, `X-Amz-Credential`, `X-Amz-Security-Token`) are + removed from any text. A refused IAM token (`WRONGPASS`, `NOAUTH`, `NOPERM`) or one that cannot + be made is logged as an error naming IAM and what to check. + Other free text in a message is not scrubbed: a credential an error message spells out some other way reaches the log. A logger that throws never fails a cache call: the line goes to the console instead, with one note that the logger threw. diff --git a/docs/redis.md b/docs/redis.md index de42173..f5c9cab 100644 --- a/docs/redis.md +++ b/docs/redis.md @@ -50,68 +50,166 @@ ELASTICACHE_ENDPOINT=master.my-cache.abc123.use1.cache.amazonaws.com ELASTICACHE_AUTH_TOKEN=... ``` -That covers cluster-mode-disabled ElastiCache (one primary with replicas). Use the primary -endpoint, not a reader endpoint. For cluster-mode-enabled ElastiCache, use a `Cluster` client as -shown below. +What to do depends on the kind of cache: + +| Cache | Auth token | IAM | +|---|---|---| +| Serverless | The environment above. | [The environment](#iam-from-the-environment). | +| Cluster mode disabled (one primary, with replicas) | The environment above, with the primary endpoint (not a reader endpoint). | [The environment](#iam-from-the-environment). | +| Cluster mode enabled | [Your own `Cluster`](#redis-cluster). | [Your own `Cluster`](#iam-on-your-own-client) with `attachElastiCacheIamAuth`. | + +ElastiCache Serverless needs no `Cluster`, but it is sharded behind its endpoint, so a command +over keys in different slots is refused with `CROSSSLOT`. The handlers only send single-key +commands. `flushCache` falls back to one `UNLINK` per key, pipelined, when its batched `UNLINK` +is refused. The background tag pruning (a two-key script) is skipped with a warning, so tag +records are bounded by field TTLs where the server has them, and otherwise grow until a flush, +as on a Cluster. ### IAM authentication -ElastiCache can authenticate a connection with AWS IAM instead of an auth token. The package does -this itself: set the IAM user instead of `ELASTICACHE_AUTH_TOKEN` and install the AWS signing -packages, which are optional dependencies loaded only when IAM is on: +ElastiCache can authenticate with short-lived AWS IAM tokens instead of an auth token. The +package signs the tokens and keeps them fresh. First install the AWS signing packages. They are +optional peer dependencies, loaded only when IAM is on: ```bash npm install @smithy/signature-v4 @aws-crypto/sha256-js @aws-sdk/credential-provider-node ``` +Then pick your path: + +| Your setup | Do this | +|---|---| +| Serverless or cluster-mode-disabled cache, built-in handlers (`withCache` alone) | [Set the environment](#iam-from-the-environment). No code. | +| The same caches, with the settings in code ([custom handler files](./custom-handlers.md)) or your own credentials provider | [Pass `iam`](#iam-in-a-custom-handler-file) to every handler. | +| Cluster-mode-enabled cache, or any client you build yourself | [Call `attachElastiCacheIamAuth`](#iam-on-your-own-client) on the client, then pass it as `client`. | + +On every path: + +- Settings you leave out come from the environment variables below. +- A client you pass in is never authenticated for you. `ELASTICACHE_IAM_USER` does not apply to + it, and the `iam` option together with `client` throws. +- IAM that cannot work throws at startup: TLS off (`ELASTICACHE_TLS=false`, a `redis://` URL), + no user, no cache name, no region, or the AWS packages missing. The handlers throw when Next + loads them, `attachElastiCacheIamAuth` when you call it. The handlers skip Redis during + `next build`, so on the first two paths the build needs none of this. +- AWS credentials come from the AWS SDK's default chain (environment variables, SSO, web + identity, ECS and EKS pod identity, EC2 instance metadata), unless you pass `credentials`. + +#### IAM from the environment + ```bash ELASTICACHE_ENDPOINT=master.my-cache.abc123.use1.cache.amazonaws.com -ELASTICACHE_IAM_USER=app-user # the IAM-enabled ElastiCache user id (= its user name) -ELASTICACHE_CACHE_NAME=my-cache # replication group id, or serverless cache name -ELASTICACHE_REGION=us-east-1 # else AWS_REGION, else AWS_DEFAULT_REGION -# ELASTICACHE_SERVERLESS=true # detected from a ".serverless." endpoint hostname +ELASTICACHE_IAM_USER=app-user +ELASTICACHE_CACHE_NAME=my-cache +ELASTICACHE_REGION=us-east-1 ``` | Variable | Meaning | |---|---| -| `ELASTICACHE_IAM_USER` | Turns IAM on. The user id, which ElastiCache requires to equal the user name. | -| `ELASTICACHE_CACHE_NAME` | The replication group id (node-based cache) or serverless cache name the token is signed for. Required; it is not parsed out of the endpoint. Lowercased, as ElastiCache stores it. | +| `ELASTICACHE_IAM_USER` | Turns IAM on. The ElastiCache user id, which ElastiCache requires to equal the user name. | +| `ELASTICACHE_CACHE_NAME` | The replication group id (node-based cache) or serverless cache name the token is signed for. Required: it is not parsed from the endpoint. Lowercased, as ElastiCache stores it. | | `ELASTICACHE_REGION` | The cache's region. Falls back to `AWS_REGION`, then `AWS_DEFAULT_REGION`. Required. | | `ELASTICACHE_SERVERLESS` | `true` for ElastiCache Serverless. Unset: on when the endpoint's hostname contains `.serverless.`. | -A `rediss://` URL in `REDIS_URL` works too, with `ELASTICACHE_IAM_USER` and the variables above; -any password in it is replaced by the token. AWS credentials come from the AWS SDK's default -chain: environment variables, SSO, web identity, ECS and EKS pod identity, and EC2 instance -metadata. In a custom handler file, pass the same settings as `iam` (`{ userId, cacheName, -region, serverless, credentials }`); fields you leave out come from the environment. - -The handlers throw at startup when IAM cannot work: TLS off (`ELASTICACHE_TLS=false`, a -`redis://` URL), no cache name, no region, or the AWS packages not installed. They never connect -to Redis during `next build`, so the build does not need these variables. - -**What the package does about the token's limits.** A token is valid for 15 minutes, and -ElastiCache closes an IAM-authenticated connection after 12 hours unless it re-authenticates. So a -token generated once and passed as a password stops working on the first reconnect after 15 -minutes, and the app then serves from memory. Instead, the package: - -- connects only once the first token is ready (until then, and if it takes longer than 500 ms, the - handlers serve from memory, as during an outage). `flushCache`, which needs Redis rather than - memory, waits up to 5 s for that first connection, so a one-off script on a cold pod (credentials - from web identity or instance metadata) does not give up before the token is signed; -- makes a new token every 10 minutes, for every reconnect to use, and sends `AUTH` with it on the - live connection, which keeps ElastiCache's 12-hour limit moving; -- makes a new token before a reconnect if the last one is more than 10 minutes old (a process - that was suspended, for example); -- logs a refused `AUTH` (`WRONGPASS`, `NOAUTH`) as an error that names IAM as the likely cause, - and a token it could not make (no credentials, a wrong region) as an error too, both at most once - a minute, and tries again on the next reconnect or refresh. A cache call never fails because of - it. The token itself is never logged, and a token that takes over 10 s to make (a credentials - provider that does not answer) counts as one it could not make. - -ioredis's own debug output (`DEBUG=ioredis:*`) logs each command's arguments, `AUTH` included, -truncated, so it can print part of a token. Don't turn it on in production with IAM. - -**On the AWS side** (see [Authenticating with IAM](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/auth-iam.html)): +A `rediss://` URL in `REDIS_URL` works in place of `ELASTICACHE_ENDPOINT`. The token replaces +any password in the URL, and `ELASTICACHE_AUTH_TOKEN` is ignored. + +#### IAM in a custom handler file + +The `iam` option takes the same settings in code: `{ userId, cacheName, region, serverless, +credentials }`. `credentials` is an AWS credentials provider, such as the AWS SDK's +`fromTemporaryCredentials()`. The connection still comes from `url` or the environment. Give +every handler file the same `iam`, from one module: + +```js +// cache/options.mjs +export const cacheOptions = { + iam: { userId: "app-user", cacheName: "my-cache", region: "us-east-1" }, +}; +``` + +```js +// cache/page.mjs +import { createPageCacheHandler } from "@mrjasonroy/cache-components-cache-handler"; +import { cacheOptions } from "./options.mjs"; + +export default createPageCacheHandler(cacheOptions); +``` + +```js +// cache/remote.mjs +import { createRemoteCacheHandler } from "@mrjasonroy/cache-components-cache-handler"; +import { cacheOptions } from "./options.mjs"; + +export default createRemoteCacheHandler(cacheOptions); +``` + +```js +// cache/default.mjs +import { createLocalCacheHandler } from "@mrjasonroy/cache-components-cache-handler"; +import { cacheOptions } from "./options.mjs"; + +export default createLocalCacheHandler(cacheOptions); +``` + +Then pass the three files to `withCache` as in [Custom handlers](./custom-handlers.md). + +#### IAM on your own client + +Create the client with `lazyConnect: true` and TLS, and call `attachElastiCacheIamAuth` on it +once. Do not call `connect()`: the client connects once the first token is ready. This is the +only way to use IAM with cluster-mode-enabled ElastiCache: + +```js +// cache/redis.mjs +import { Cluster } from "ioredis"; +import { attachElastiCacheIamAuth } from "@mrjasonroy/cache-components-cache-handler"; + +function createClient() { + const client = new Cluster( + [{ host: "clustercfg.my-cache.abc123.use1.cache.amazonaws.com", port: 6379 }], + { + lazyConnect: true, + dnsLookup: (address, callback) => callback(null, address), // keep hostnames for TLS + redisOptions: { tls: {}, commandTimeout: 1000 }, + }, + ); + attachElastiCacheIamAuth(client, { userId: "app-user", cacheName: "my-cache", region: "us-east-1" }); + return client; +} + +// One client per process: Next can load each handler file in its own module graph. +export const client = (globalThis.myAppRedis ??= createClient()); +``` + +Then pass `client` to every handler, as in [Custom handlers](./custom-handlers.md). The same +works for a plain `Redis` client. `attachElastiCacheIamAuth` returns `{ refresh(), stop() }`; +`stop()` ends the refresh and leaves the client connected. + +#### What the package does with the tokens + +A token is valid for 15 minutes, and ElastiCache closes an IAM connection after 12 hours unless +it re-authenticates. So a token passed once as a password stops working on the first reconnect +after 15 minutes, and the app then serves from memory. Instead, on every path above: + +- The first connection waits for the first token. Meanwhile the handlers serve from memory, as + during an outage. On a connection the package opens, the handlers wait at most 500 ms for it + and `flushCache` up to 5 s, so a one-off script on a cold pod does not give up before the + token is signed. +- A new token is made every 10 minutes. It is kept for reconnects and sent as `AUTH` on every + live connection (every node of a `Cluster`), which restarts the 12-hour limit. +- A reconnect whose token is more than 10 minutes old (after a suspended process, say) makes a + new one first. +- A token that cannot be made (no credentials, a wrong region, or more than 10 s to sign) and a + refused `AUTH` (`WRONGPASS`, `NOAUTH`, `NOPERM`) are logged as errors naming IAM, at most once + a minute. The package tries again on the next reconnect or refresh. A cache call never fails + because of it. +- The token is never logged. ioredis's own debug output (`DEBUG=ioredis:*`) does log each + command's arguments, `AUTH` included, so don't turn it on in production with IAM. + +#### On the AWS side + +See [Authenticating with IAM](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/auth-iam.html). - Valkey 7.2+ or Redis OSS 7.0+, with in-transit encryption (TLS) on. - An ElastiCache user with IAM authentication, whose user id and user name are the same, in a @@ -152,102 +250,76 @@ truncated, so it can print part of a token. Don't turn it on in production with For a serverless cache the first resource is `arn:aws:elasticache:us-east-1:123456789012:serverlesscache:my-cache`. -A refused token is nearly always one of: the user id is not in the cache's user group, the policy -is missing one of the two resources, or the cache name, region or serverless setting does not -match the cache (the token is signed for them). - -For cluster-mode-enabled ElastiCache, build a `Cluster` yourself and keep it authenticated with -`attachElastiCacheIamAuth` (see [Your own client](#your-own-client)). - -ElastiCache Serverless works with the environment's plain connection (no `Cluster` needed). It is -sharded behind its endpoint, so a command over keys in different slots is refused with -`CROSSSLOT`. The handlers send single-key commands only; `flushCache` falls back to one `UNLINK` -per key, pipelined, when its batched `UNLINK` is refused; and the background tag pruning (a -two-key script) is skipped with a warning, so tag records are bounded by field TTLs where the -server has them and otherwise grow until a flush, as on a Cluster. +A refused token is nearly always one of these: the user is not in the cache's user group, the +policy is missing one of the two resources, or the cache name, region or serverless setting does +not match the cache (the token is signed for them). ## Your own client For Sentinel, Cluster or other ioredis options, build the client yourself and pass it to -[custom handler files](./custom-handlers.md). Give all three handlers the same client so -they share one connection and one tag store. - -A client you pass in is yours: the package never closes, disconnects or reconfigures it. Its own -commands reach the client through a proxy bounded by `commandTimeout`; after 3 timeouts in a row -the handlers serve from memory for 2 s at a time, until a command succeeds again. Your other uses -of the client are unaffected, so set the timeouts and retry strategy on the client too: +[custom handler files](./custom-handlers.md). Give all three handlers the same client, so they +share one connection and one tag store. Create it once per process and keep it on `globalThis`: +Next can load each handler file in its own module graph, and a module-level client would then +open one connection per file. ```js // cache/redis.mjs import Redis from "ioredis"; -const key = Symbol.for("my-app.redis"); -globalThis[key] ??= new Redis(process.env.REDIS_URL, { - commandTimeout: 1000, - maxRetriesPerRequest: 1, - retryStrategy: (times) => Math.min(times * 200, 5000), -}); -export const client = globalThis[key]; +function createClient() { + return new Redis(process.env.REDIS_URL, { + commandTimeout: 1000, + maxRetriesPerRequest: 1, + retryStrategy: (times) => Math.min(times * 200, 5000), + }); +} + +// One client per process: Next can load each handler file in its own module graph. +export const client = (globalThis.myAppRedis ??= createClient()); ``` -Parking the client on `globalThis` keeps it to one connection when Next loads the handler modules -separately. +A client you pass in is yours: the package never closes, disconnects or reconfigures it. The +package's own commands on it are bounded by `commandTimeout`. After 3 timeouts in a row the +handlers serve from memory for 2 s at a time, until a command succeeds again. Your other uses of +the client are unaffected, so set the timeouts and retry strategy on the client too, as above. ### Redis Sentinel +The same `cache/redis.mjs`, with this `createClient`: + ```js -globalThis[key] ??= new Redis({ - sentinels: [ - { host: "sentinel-1", port: 26379 }, - { host: "sentinel-2", port: 26379 }, - { host: "sentinel-3", port: 26379 }, - ], - name: "mymaster", - commandTimeout: 1000, -}); +function createClient() { + return new Redis({ + sentinels: [ + { host: "sentinel-1", port: 26379 }, + { host: "sentinel-2", port: 26379 }, + { host: "sentinel-3", port: 26379 }, + ], + name: "mymaster", + commandTimeout: 1000, + }); +} ``` ### Redis Cluster -```js -import { Cluster } from "ioredis"; - -globalThis[key] ??= new Cluster( - [ - { host: "node1", port: 6379 }, - { host: "node2", port: 6379 }, - { host: "node3", port: 6379 }, - ], - { redisOptions: { commandTimeout: 1000 } }, -); -``` - -For cluster-mode-enabled ElastiCache with IAM authentication, create the `Cluster` with -`lazyConnect: true` and TLS, and attach the package's token refresh to it. It connects once the -first token is ready, puts a fresh token in every node's options every 10 minutes and sends `AUTH` -to every connected node; settings you leave out come from the `ELASTICACHE_*` environment: +The same `cache/redis.mjs`, importing `Cluster` from `ioredis`, with this `createClient`: ```js -import { Cluster } from "ioredis"; -import { attachElastiCacheIamAuth } from "@mrjasonroy/cache-components-cache-handler"; - -globalThis[key] ??= new Cluster( - [{ host: "clustercfg.my-cache.abc123.use1.cache.amazonaws.com", port: 6379 }], - { - lazyConnect: true, - dnsLookup: (address, callback) => callback(null, address), - redisOptions: { tls: {}, commandTimeout: 1000 }, - }, -); -attachElastiCacheIamAuth(globalThis[key], { - userId: "app-user", - cacheName: "my-cache", - region: "us-east-1", -}); +function createClient() { + return new Cluster( + [ + { host: "node1", port: 6379 }, + { host: "node2", port: 6379 }, + { host: "node3", port: 6379 }, + ], + { redisOptions: { commandTimeout: 1000 } }, + ); +} ``` -Call it once per client (inside the same `??=` guard in real code), and do not call `connect()` -yourself. +For cluster-mode-enabled ElastiCache with IAM, see +[IAM on your own client](#iam-on-your-own-client). Cluster mode needs no hash tags. Every command the handlers send touches a single key, so none can fail with `CROSSSLOT`. `flushCache` scans every master. The two tag keys live on one shard @@ -283,7 +355,8 @@ barriers stay until a full flush. Run Redis with `maxmemory-policy noeviction` o policy (`volatile-lru`), never `allkeys-*` (such as `allkeys-lru`): an evicted tag hash brings every invalidated entry back. Entries are binary and not human-readable. -`createCacheHandler` keeps its 16.4.2 layout: `nextjs:data-cache:` and `nextjs:tags:`. +The deprecated `createCacheHandler` keeps its 16.4.2 layout: `nextjs:data-cache:` and +`nextjs:tags:`. `CACHE_DEBUG=1` (or `true`) on the app logs what is read and written, with each value's size: `bytes` (the value; the uncompressed entry for pages) and, for pages and `"use cache: remote"`, `encodedBytes` (as stored in Redis). @@ -361,6 +434,7 @@ Upstash's Redis endpoint (not its REST API). Services that only offer an HTTP AP ## The legacy data handler -`createRedisDataCacheHandler` (the handler behind `createCacheHandler`) takes a node-redis-style -client. Pass node-redis directly, or wrap ioredis with `createIoredisAdapter`. See the -[API reference](./api-reference.md#legacy-data-cache-api). +Deprecated in 16.4.3 and removed in 16.5: use `withCache`, or `createRemoteCacheHandler({ client })` +with an ioredis client. Until then, `createRedisDataCacheHandler` (the handler behind +`createCacheHandler`) takes a node-redis-style client: node-redis directly, or ioredis wrapped +with `createIoredisAdapter`. See the [API reference](./api-reference.md#legacy-data-cache-api). diff --git a/packages/cache-handler/README.md b/packages/cache-handler/README.md index 8652ac7..9149c0e 100644 --- a/packages/cache-handler/README.md +++ b/packages/cache-handler/README.md @@ -17,166 +17,102 @@ memory by default, with revalidation shared across all of them. > ElastiCache IAM. 16.4.2 setups keep working with deprecation warnings, and `^16.4.2` installs get > it automatically. Read [Upgrading from 16.4.2](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/migrating.md) before you deploy. -## Quick start +## Start here -```bash -npm install --save-exact @mrjasonroy/cache-components-cache-handler -``` +1. **Install** the release for your Next.js minor, pinned exact. For Next 16.4.x: -The package version follows Next.js. Pin it to the exact release for your Next.js version -(`--save-exact`; Next 16.4.3 → `16.4.3`) and upgrade the two together. A range such as `^16.4.3` -also accepts the 16.5 releases, which follow Next.js 16.5 and remove the APIs deprecated in -16.4.3. From the next release, the `next` peer dependency is `~..0` of the -package's own version (for example `~16.4.0` for 16.4.x), so npm refuses a handler whose minor -does not match your Next.js with an `ERESOLVE` error, and pnpm and Yarn warn. + ```bash + npm install --save-exact @mrjasonroy/cache-components-cache-handler@16.4 + ``` -```js -// next.config.mjs -import { withCache } from "@mrjasonroy/cache-components-cache-handler"; + `@16.4` picks the newest 16.4.x and `--save-exact` pins it. Needs Node.js 22.3+. -export default withCache({ cacheComponents: true }); -``` +2. **Wrap your config:** -```bash -REDIS_URL=redis://cache:6379 # unset → everything stays in memory (dev, CI, previews) -``` + ```js + // next.config.mjs + import { withCache } from "@mrjasonroy/cache-components-cache-handler"; + + export default withCache({ cacheComponents: true }); + ``` -That's it. You keep writing `"use cache"`, `cacheTag` and `revalidateTag` as Next documents them -([examples](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/usage.md)). `ioredis` is installed automatically as an optional dependency -([unless optionals are skipped](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/installation.md#install)). +3. **Pick your setup:** + + | Setup | What to do | + |---|---| + | Local dev, CI, previews, one instance | Nothing. Without `REDIS_URL` everything stays in memory. | + | Redis or Valkey | Set `REDIS_URL=redis://cache:6379` on the running app. [Installation](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/installation.md#point-it-at-redis) | + | AWS ElastiCache, Serverless or cluster mode disabled | Set `ELASTICACHE_ENDPOINT` and `ELASTICACHE_AUTH_TOKEN`, or the IAM variables. [AWS ElastiCache](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md#aws-elasticache) | + | AWS ElastiCache, cluster mode enabled (with or without IAM) | Your own `Cluster` in custom handler files. [Redis Cluster](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md#redis-cluster), [IAM on your own client](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md#iam-on-your-own-client) | + | Your own client (Sentinel, other ioredis options or timeouts) | [Custom handlers](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/custom-handlers.md) | + | Upgrading from 16.4.2 | [Migrating](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/migrating.md) | + +Then keep writing `"use cache"`, `cacheTag` and `revalidateTag` as Next documents them +([examples](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/usage.md)). + +**Setting it up with a coding agent?** Paste the prompt in [docs/agent-setup.md](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/agent-setup.md) +into Claude Code, Cursor or similar. + +The package version follows Next.js. A range such as `^16.4.3` would also accept the 16.5 +releases, which remove the APIs deprecated in 16.4.3, so pin it and upgrade the two together +([why](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/installation.md#install)). `ioredis` is installed with the package as an optional +dependency ([unless optionals are skipped](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/installation.md#install)). ## What you get - **Pages and route handlers** (and cached `fetch`) stored in Redis, shared by every instance. Prerendered pages are served from the build output after a restart. -- **Storage by directive.** `"use cache: remote"` entries live in Redis, shared by every - instance; plain `"use cache"` defaults to each instance's memory, with tag invalidation shared - through Redis. `"use cache: private"` is Next's own and never reaches a handler. Set - `useCache: "redis"` to share plain `"use cache"` values too. Next's deprecated - `experimental.useCache` flag works as well as - `cacheComponents`. +- **Next's directives, one to one.** `"use cache: remote"` entries live in Redis, shared by every + instance. Plain `"use cache"` stays in each instance's memory, with tag invalidation shared + through Redis; set `useCache: "redis"` to share it too. `"use cache: private"` is Next's own and + never reaches a handler. - **Revalidation across instances.** `revalidateTag`, `updateTag` and `revalidatePath` reach - every instance and every handler, including each instance's in-memory `"use cache"` values. + every instance and every handler. - **Redis outage safety.** A request never fails because of the cache. Commands time out after - 1 s, and while Redis is down the app serves from per-instance memory, then goes back to Redis. + 1 s, and while Redis is down the app serves from per-instance memory. - **Entries scoped by build**, so a deploy never serves the previous build's pages. - **`next build` never connects to Redis.** -[How it works](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/how-it-works.md) has the details: what goes where, tag coordination, page -lifetimes and the outage table. +[How it works](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/how-it-works.md) has the details. ## Configuration -### `withCache(nextConfig, options?)` +Runtime settings come from the environment of the running app. The main variables: -These options are read when `next.config` loads. Runtime settings come from the environment, except `memory`. +| Variable | Meaning | +|---|---| +| `REDIS_URL` (or `VALKEY_URL`) | `redis://` or `rediss://` URL. Unset → memory only. | +| `ELASTICACHE_ENDPOINT`, `ELASTICACHE_AUTH_TOKEN` | ElastiCache host form, TLS on. For IAM, see [IAM authentication](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md#iam-authentication). | +| `CACHE_KEY_PREFIX` | Prefix for every key (default `nextjs:`). | +| `CACHE_REDIS=off` | Memory everywhere, even with a URL set. | +| `CACHE_DEBUG=1` | Log hits, misses, writes and state changes. | + +The [installation guide](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/installation.md#environment-variables) has the full table. There +are no variables for timeouts or TTLs; for those, or your own client, see +[Custom handlers](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/custom-handlers.md). + +`withCache(nextConfig, options?)` takes three options: | Option | Default | What it does | |---|---|---| -| `pages` | `true` | Set `cacheHandler` (pages, route handlers, cached `fetch`) and `cacheMaxMemorySize: 0`. A `cacheMaxMemorySize` you set yourself is kept, with a warning if it is not `0`. `false` leaves `cacheHandler` and `cacheMaxMemorySize` as your config has them. | -| `useCache` | `"memory"` | `"redis"` stores plain `"use cache"` values in Redis too. Each read checks Redis; fresh instances of the same build reuse existing values. `handlers.default` overrides this choice. `handlers.remote` only changes `"use cache: remote"`. | +| `pages` | `true` | Also handle pages, route handlers and cached `fetch` (`cacheHandler`). `false` leaves them to Next. | +| `useCache` | `"memory"` | `"redis"` stores plain `"use cache"` values in Redis too, so instances of the same build share them. `handlers.default` overrides it. | | `handlers` | built-in files | `{ page?, default?, remote? }`: paths to [your own handler files](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/custom-handlers.md). | -| `memory` | `{ heapPercent: 10 }` | The in-process cache budget per runtime: `heapPercent` of V8's heap limit (a little above `--max-old-space-size`), or `maxMiB` (an absolute budget, which wins). Wins over the `CACHE_MEMORY_*` variables. Not seen by a standalone `server.js`, which never loads `next.config`: use the variables there. See [Memory](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/operations.md#memory). | - -```js -// Share plain "use cache" values across instances (REDIS_URL required) -export default withCache({ cacheComponents: true }, { useCache: "redis" }); -``` - -```js -// "use cache" only; leave pages to Next's default cache -export default withCache({ cacheComponents: true }, { pages: false }); -``` +| `memory` | `{ heapPercent: 10 }` | The in-process cache budget. Not seen by a standalone `server.js`: use the `CACHE_MEMORY_*` variables there. See [Memory](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/operations.md#memory). | `withCache` throws if the config already sets `cacheHandlers`, or `cacheHandler` unless -`pages: false`, because two configs fighting over the cache is always a bug. Use `handlers` -instead. It also accepts a function-form `next.config`. - -### Environment variables - -| Variable | Default | Meaning | -|---|---|---| -| `REDIS_URL` (or `VALKEY_URL`) | unset → memory only | `redis://` or `rediss://` URL, password included. | -| `REDIS_PASSWORD` | — | Password when the URL has none. | -| `ELASTICACHE_ENDPOINT`, `ELASTICACHE_PORT`, `ELASTICACHE_AUTH_TOKEN`, `ELASTICACHE_TLS` | port `6379`, TLS on | Host form, used when no URL is set. `ELASTICACHE_TLS=false` turns TLS off. | -| `ELASTICACHE_IAM_USER` | unset | ElastiCache IAM authentication as this user id, instead of an auth token, with tokens refreshed by the package ([details](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md#iam-authentication)). Needs TLS. | -| `ELASTICACHE_CACHE_NAME` | — | With IAM: the replication group id or serverless cache name the token is signed for. Required. | -| `ELASTICACHE_REGION` | `AWS_REGION`, then `AWS_DEFAULT_REGION` | With IAM: the cache's region. | -| `ELASTICACHE_SERVERLESS` | from the hostname | With IAM: `true` for ElastiCache Serverless; unset, on for a `.serverless.` endpoint. | -| `CACHE_KEY_PREFIX` | `nextjs:` | Prefix for every key. Use it to share one Redis between apps. | -| `CACHE_REDIS` | `on` | `off` forces memory everywhere, even with a URL set. | -| `CACHE_DEBUG` | unset | `1` logs hits, misses, writes and state changes. It never logs the URL. | -| `CACHE_COMPRESSION` | `on` | Entries of 16 KB and more are Brotli-compressed. `off` stores them uncompressed. | -| `CACHE_MEMORY_HEAP_PERCENT` | `10` | In-process cache budget as a share of the V8 heap limit, in percent (more than 0, less than 100). | -| `CACHE_MEMORY_MAX_MIB` | unset | In-process cache budget in MiB. Wins over `CACHE_MEMORY_HEAP_PERCENT`. `withCache`'s `memory` wins over both. | - -There are no tuning variables for timeouts or TTLs. The [installation guide](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/installation.md#environment-variables) -has the full table; for your own client or timeouts, see [Custom handlers](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/custom-handlers.md). - -## Tested against Next.js's own tests - -Every PR that changes the package's source runs the caching e2e suites from the -[`vercel/next.js`](https://github.com/vercel/next.js) repo, using Next's deploy-mode test harness -for deployment adapters. Each suite runs twice: once against a plain `next start`, and once with -this package, two instances behind a round-robin proxy (one instance where a fixture keeps its own -handler), sharing one Redis. CI fails if a suite (or a test) that passes on `next start` does not -pass with the package. - -At Next 16.4.2 that is **0 regressions outside one known Next bug**: apart from `app-static` -(below), every suite and test that passes on `next start` also passes with the package. 28 -suites, 18 of which run tests in deploy mode -([results](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/tests/next-deploy/results/baseline-v16.4.2.md); live results on the -[deploy-tests workflow](https://github.com/mrjasonroy/cache-components-cache-handler/actions/workflows/next-deploy-tests.yml)). -The limits: - -- `test/e2e/app-dir/app-static` fails with any custom cache handler, because of a Next bug - (Turbopack's edge `cacheHandlers` registration, fixed in a later Next canary, - vercel/next.js#100046). It is listed as a known failure. -- 10 suites, such as `use-cache` and `ppr-full`, run no tests in deploy mode, so they are not - covered here. - -The package's own tests add an e2e matrix on production builds (memory, Redis, Valkey, and the -ElastiCache host form: Redis with TLS and an auth token), including two instances sharing Redis -and Redis stopped mid-run, and an outage suite on real Redis 7 and Valkey 8 (down at boot, lost -mid-run, stalled, back). - -ElastiCache IAM authentication is tested against a real ElastiCache Serverless cache (Valkey 8.1): -connecting with a token, re-authenticating the live connection, reconnecting, a tag revalidation -across two connections and `flushCache`. That needs an AWS account and a runner in the cache's -VPC, so it is not in per-PR CI: it is a manual gate before a release -(`scripts/aws-iam-e2e/run.sh`, see [development](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/development.md#elasticache-iam-against-a-real-cache)). -The token signing and refresh are unit-tested on every PR. -See [the harness README](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/tests/next-deploy/README.md) and -[how it's tested](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/development.md#how-its-tested). - -## Supported backends - -| Backend | How | -|---|---| -| **Memory** | No `REDIS_URL`: dev, CI, previews, single instance | -| **Redis 6.2+** | `REDIS_URL=redis://…` or `rediss://…` | -| **Valkey** | `VALKEY_URL` or `REDIS_URL`, same URL format | -| **AWS ElastiCache** | `ELASTICACHE_ENDPOINT` + `ELASTICACHE_AUTH_TOKEN`, TLS on (`ELASTICACHE_TLS=false` turns it off) | -| **AWS ElastiCache, IAM auth** | `ELASTICACHE_ENDPOINT` (or a `rediss://` `REDIS_URL`) + `ELASTICACHE_IAM_USER`, `ELASTICACHE_CACHE_NAME`, `ELASTICACHE_REGION`. TLS required; Valkey 7.2+ or Redis OSS 7.0+; node-based or serverless (detected from a `.serverless.` endpoint, or `ELASTICACHE_SERVERLESS`). Needs the optional peer dependencies `@smithy/signature-v4`, `@aws-crypto/sha256-js` and `@aws-sdk/credential-provider-node`. [Details](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md#iam-authentication) | -| **Redis Cluster, Sentinel** | Your own ioredis client through a [custom handler](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/custom-handlers.md). `flushCache` scans every master. | - -The minimum is Redis 6.2 (or any Valkey): revalidations use `ZADD GT` and a single-key Lua -script, so the server must allow `EVAL`/`EVALSHA`. CI runs Redis 7 and Valkey 8. -[Redis Configuration](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/redis.md) covers connections, key layout and sizing. - -## Migrating - -From 16.4.2, replace your handler files and `cacheHandlers` config with -`withCache({ cacheComponents: true })` and delete the files. `"use cache"` then goes to memory and -`"use cache: remote"` to Redis (or set `useCache: "redis"` to share plain `"use cache"` too), and -pages go through Redis too. The cache starts cold, and -revalidations do not cross between 16.4.2 and 16.4.3 instances during a rolling deploy: deploy -with recreate, or revalidate once afterwards. `RedisCacheHandler` subclasses keep working. - -From `@fortedigital/nextjs-cache-handler` or `@neshca/cache-handler`, replace `cacheHandler` and -`cacheMaxMemorySize` with `withCache`. - -The [migration guide](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/migrating.md) has the details. +`pages: false`. Use `handlers` instead. The [API reference](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/api-reference.md#withcachenextconfig-options) +has the details. + +## Requirements and testing + +Redis 6.2+ or any Valkey, with Lua scripting allowed (revalidations use `ZADD GT` and a +single-key script). CI runs Redis 7 and Valkey 8, a production-build e2e matrix (memory, Redis, +Valkey, ElastiCache with TLS and an auth token) and an outage suite. Every PR that changes the +package also runs Next.js's own caching e2e suites, with two instances sharing Redis, and fails +on any regression against plain `next start`. ElastiCache IAM is tested by hand against a real +ElastiCache Serverless cache before each release. +[How it's tested](https://github.com/mrjasonroy/cache-components-cache-handler/blob/main/docs/development.md#how-its-tested) has the details and known limits. ## Documentation diff --git a/packages/cache-handler/src/helpers/elasticache-iam.ts b/packages/cache-handler/src/helpers/elasticache-iam.ts index 84ed841..bde6795 100644 --- a/packages/cache-handler/src/helpers/elasticache-iam.ts +++ b/packages/cache-handler/src/helpers/elasticache-iam.ts @@ -56,15 +56,25 @@ function startupHost(node: unknown): string | undefined { * * @example * ```js + * // cache/redis.mjs: pass `client` to every custom handler file * import { Cluster } from "ioredis"; * import { attachElastiCacheIamAuth } from "@mrjasonroy/cache-components-cache-handler"; * - * const client = new Cluster([{ host: "clustercfg.my-cache.abc123.use1.cache.amazonaws.com", port: 6379 }], { - * lazyConnect: true, - * dnsLookup: (address, callback) => callback(null, address), - * redisOptions: { tls: {}, commandTimeout: 1000 }, - * }); - * attachElastiCacheIamAuth(client, { userId: "app-user", cacheName: "my-cache", region: "us-east-1" }); + * function createClient() { + * const client = new Cluster( + * [{ host: "clustercfg.my-cache.abc123.use1.cache.amazonaws.com", port: 6379 }], + * { + * lazyConnect: true, + * dnsLookup: (address, callback) => callback(null, address), // keep hostnames for TLS + * redisOptions: { tls: {}, commandTimeout: 1000 }, + * }, + * ); + * attachElastiCacheIamAuth(client, { userId: "app-user", cacheName: "my-cache", region: "us-east-1" }); + * return client; + * } + * + * // One client per process: Next can load each handler file in its own module graph. + * export const client = (globalThis.myAppRedis ??= createClient()); * ``` */ export function attachElastiCacheIamAuth( diff --git a/packages/cache-handler/src/shared/logger.ts b/packages/cache-handler/src/shared/logger.ts index ab9d0ab..8c1212a 100644 --- a/packages/cache-handler/src/shared/logger.ts +++ b/packages/cache-handler/src/shared/logger.ts @@ -64,7 +64,7 @@ function getState(): LoggerState { * import { logger } from "./lib/logger"; * * export function register() { - * setCacheLogger(logger); + * if (process.env.NEXT_RUNTIME === "nodejs") setCacheLogger(logger); * } * ``` */