Unverified Commit 212e7b1e authored by Joseph's avatar Joseph Committed by GitHub

docs: replace unbounded cacheHandler snippets and fix tag handling in examples (#100186)

Fixes #100173
parent 7bd26a42
...@@ -108,9 +108,7 @@ If you want to host static assets on a different domain or CDN, you can use the ...@@ -108,9 +108,7 @@ If you want to host static assets on a different domain or CDN, you can use the
By default, generated cache assets will be stored in memory (defaults to 50mb) and on disk. On ephemeral compute platforms (common serverless setups), local disk is often non-persistent or unavailable, so this cache is effectively short-lived and per-instance. If you are hosting Next.js using a container orchestration platform like Kubernetes, each pod will have a copy of the cache. To prevent stale data from being shown since the cache is not shared between pods by default, you can configure the Next.js cache to provide a cache handler and disable in-memory caching. By default, generated cache assets will be stored in memory (defaults to 50mb) and on disk. On ephemeral compute platforms (common serverless setups), local disk is often non-persistent or unavailable, so this cache is effectively short-lived and per-instance. If you are hosting Next.js using a container orchestration platform like Kubernetes, each pod will have a copy of the cache. To prevent stale data from being shown since the cache is not shared between pods by default, you can configure the Next.js cache to provide a cache handler and disable in-memory caching.
To configure the cache location when self-hosting, you can configure a custom handler in your `next.config.js` file: To configure the cache location when self-hosting, set a custom handler in your `next.config.js` file:
For production deployments, use this as a starting point and extend it with durable storage, eviction policies, error handling, and distributed tag coordination. See [Custom Next.js Cache Handler](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath) and the [Redis `cacheHandler` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis). If you are configuring backends for `'use cache'` directives, use [`cacheHandlers`](/docs/app/api-reference/config/next-config-js/cacheHandlers).
```jsx filename="next.config.js" ```jsx filename="next.config.js"
module.exports = { module.exports = {
...@@ -119,55 +117,20 @@ module.exports = { ...@@ -119,55 +117,20 @@ module.exports = {
} }
``` ```
Then, create `cache-handler.js` in the root of your project, for example: The handler file exports a class that implements `get`, `set`, `revalidateTag`, and `resetRequestCache`. See [`cacheHandler`](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath) for each method's signature, and the [Redis `cacheHandler` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) for a working implementation.
```jsx filename="cache-handler.js"
const cache = new Map()
module.exports = class CacheHandler {
constructor(options) {
this.options = options
}
async get(key) {
// This could be stored anywhere, like durable storage
return cache.get(key)
}
async set(key, data, ctx) {
// This could be stored anywhere, like durable storage
cache.set(key, {
value: data,
lastModified: Date.now(),
tags: ctx.tags,
})
}
async revalidateTag(tags) {
// tags is either a string or an array of strings
tags = [tags].flat()
// Iterate over all entries in the cache
for (let [key, value] of cache) {
// If the value's tags include the specified tag, delete this entry
if (value.tags.some((tag) => tags.includes(tag))) {
cache.delete(key)
}
}
}
// If you want to have temporary in memory cache for a single request that is reset For production deployments, the handler must:
// before the next request you can leverage this method
resetRequestCache() {}
}
```
Using a custom cache handler will allow you to ensure consistency across all pods hosting your Next.js application. For instance, you can save the cached values anywhere, like [Redis](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) or AWS S3. - **Store entries where every instance can reach them**, like [Redis](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) or AWS S3. A store inside the process, such as a `Map`, gives each pod its own copy of the cache again.
- **Bound the store's size.** Use a TTL or size-based eviction to remove entries for paths and `fetch` keys that are no longer requested.
- **Serialize entries.** Any store outside the process needs this. An entry can contain `Buffer` (for example `rscData`) and `Map` (for example `segmentData`) values that `JSON.stringify`/`JSON.parse` can't serialize and restore on their own. Not handling this serialization results in errors like `segmentData.get is not a function` or `failed to pipe response` on client-side navigation or prefetch (RSC) requests.
- **Index entries by tag.** `APP_PAGE`, `APP_ROUTE`, and `PAGES` entries carry their tags in the `x-next-cache-tags` response header (`data.headers`), while `ctx.tags` carries tags for `fetch` entries. Keep the index in the shared store, so a `revalidateTag` call on one instance invalidates the entry on every instance.
- **Handle storage errors**, such as timeouts and dropped connections.
> **Good to know:** > **Good to know:**
> >
> - `revalidatePath` is a convenience layer on top of cache tags. Calling `revalidatePath` will call the `revalidateTag` function with a special default tag for the provided page. > - `revalidatePath` is a convenience layer on top of cache tags. Calling `revalidatePath` will call the `revalidateTag` function with a special default tag for the provided page.
> - The example above keeps entries in memory. A handler backed by durable storage (like the [Redis example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis)) must serialize entries itself, and an entry can contain `Buffer` (for example `rscData`) and `Map` (for example `segmentData`) values that `JSON.stringify`/`JSON.parse` can't serialize and restore on their own. Not handling this serialization results in errors like `segmentData.get is not a function` or `failed to pipe response` on client-side navigation or prefetch (RSC) requests. > - If you are configuring backends for `'use cache'` directives, use [`cacheHandlers`](/docs/app/api-reference/config/next-config-js/cacheHandlers).
> - When indexing entries for `revalidateTag`, read cache tags from the right place: `APP_PAGE`, `APP_ROUTE`, and `PAGES` entries carry them in the `x-next-cache-tags` response header (`data.headers`), while `ctx.tags` carries tags for `fetch` entries.
> - Production-oriented community Redis handlers (GET timeouts, in-memory coalescing, multi-instance tag coordination) are listed in the [Redis example README](https://github.com/vercel/next.js/blob/canary/examples/cache-handler-redis/README.md#production-community-handlers), including [`@trieb.work/nextjs-turbo-redis-cache`](https://github.com/trieb-work/nextjs-turbo-redis-cache) and [`@mrjasonroy/cache-components-cache-handler`](https://github.com/mrjasonroy/cache-components-cache-handler). > - Production-oriented community Redis handlers (GET timeouts, in-memory coalescing, multi-instance tag coordination) are listed in the [Redis example README](https://github.com/vercel/next.js/blob/canary/examples/cache-handler-redis/README.md#production-community-handlers), including [`@trieb.work/nextjs-turbo-redis-cache`](https://github.com/trieb-work/nextjs-turbo-redis-cache) and [`@mrjasonroy/cache-components-cache-handler`](https://github.com/mrjasonroy/cache-components-cache-handler).
## Build Cache ## Build Cache
......
...@@ -284,16 +284,25 @@ Whether `durations` is present tells you which kind of invalidation this is: ...@@ -284,16 +284,25 @@ Whether `durations` is present tells you which kind of invalidation this is:
Returns `Promise<void>`. Returns `Promise<void>`.
When tags are revalidated, your handler should invalidate all cache entries that have any of those tags. Iterate through your cache and remove entries whose tags match the provided list. Your handler should record when each tag was invalidated. [`get()`](#get) compares those times against an entry's `timestamp`, and [`getExpiration()`](#getexpiration) does the same for [soft tags](#soft-tags). Soft tags are not stored in an entry's `tags`, so deleting the entries that carry a tag does not cover [`revalidatePath()`](/docs/app/api-reference/functions/revalidatePath).
```js ```js
const cacheHandler = { const cacheHandler = {
async updateTags(tags, durations) { async updateTags(tags, durations) {
// Invalidate all cache entries with matching tags const now = Date.now()
for (const [key, entry] of cache.entries()) { for (const tag of tags) {
if (entry.tags.some((tag) => tags.includes(tag))) { const timestamps = tagTimestamps.get(tag) ?? {}
cache.delete(key) if (durations) {
// Serve while refreshing, and expire after `durations.expire` seconds
timestamps.stale = now
if (durations.expire !== undefined) {
timestamps.expired = now + durations.expire * 1000
}
} else {
// Expire immediately
timestamps.expired = now
} }
tagTimestamps.set(tag, timestamps)
} }
}, },
} }
...@@ -375,14 +384,18 @@ Cache operations should be implemented defensively: ...@@ -375,14 +384,18 @@ Cache operations should be implemented defensively:
## Examples ## Examples
### Basic in-memory cache handler The examples below show how a handler meets the API contract. They leave out the eviction, error handling, and multi-instance coordination that a production handler must add. The [`cache-handler-redis` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) is a fuller Redis implementation of both cache APIs, and its README lists community handlers that cover more cases.
### In-memory handler for learning and debugging
Here's a minimal implementation using a `Map` for storage. This example demonstrates the core concepts, but for a production-ready implementation with LRU eviction, error handling, and tag management, see the [default cache handler](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/cache-handlers/default.ts). This handler keeps entries in a `Map`, which makes it a place to log or inspect what Next.js stores and how tags invalidate it. It runs per process and has no eviction. The [built-in handler](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/cache-handlers/default.ts) is also in memory, and adds a size-bounded LRU and error handling.
```js filename="cache-handlers/memory-handler.js" ```js filename="cache-handlers/memory-handler.js"
// Entries hold the serialized bytes, never the stream they arrived on // Entries hold the serialized bytes, never the stream they arrived on
const cache = new Map() const cache = new Map()
const pendingSets = new Map() const pendingSets = new Map()
// Tag invalidation times in milliseconds: { stale, expired }
const tagTimestamps = new Map()
function streamFromBytes(bytes) { function streamFromBytes(bytes) {
return new ReadableStream({ return new ReadableStream({
...@@ -407,10 +420,21 @@ module.exports = { ...@@ -407,10 +420,21 @@ module.exports = {
} }
// No age check: Next.js compares `timestamp` against `expire` itself. // No age check: Next.js compares `timestamp` against `expire` itself.
// Soft tags are checked by Next.js through `getExpiration()`.
// This `Map` also has no eviction, which a real handler needs. // This `Map` also has no eviction, which a real handler needs.
let revalidate = entry.revalidate
for (const tag of entry.tags) {
const { stale = 0, expired = 0 } = tagTimestamps.get(tag) ?? {}
if (expired > entry.timestamp && expired <= Date.now()) {
return undefined
}
if (stale > entry.timestamp) {
revalidate = -1
}
}
// Every hit gets its own stream over the stored bytes // Every hit gets its own stream over the stored bytes
return { ...entry, value: streamFromBytes(entry.value) } return { ...entry, revalidate, value: streamFromBytes(entry.value) }
}, },
async set(cacheKey, pendingEntry) { async set(cacheKey, pendingEntry) {
...@@ -439,20 +463,31 @@ module.exports = { ...@@ -439,20 +463,31 @@ module.exports = {
}, },
async refreshTags() { async refreshTags() {
// No-op for in-memory cache // Tag state lives in this process, so there is nothing to sync
}, },
async getExpiration(tags) { async getExpiration(tags) {
// Return 0 to indicate no tags have been revalidated return Math.max(
return 0 ...tags.map((tag) => tagTimestamps.get(tag)?.expired ?? 0),
0
)
}, },
async updateTags(tags, durations) { async updateTags(tags, durations) {
// Implement tag-based invalidation const now = Date.now()
for (const [key, entry] of cache.entries()) { for (const tag of tags) {
if (entry.tags.some((tag) => tags.includes(tag))) { const timestamps = tagTimestamps.get(tag) ?? {}
cache.delete(key) if (durations) {
// Serve while refreshing, and expire after `durations.expire` seconds
timestamps.stale = now
if (durations.expire !== undefined) {
timestamps.expired = now + durations.expire * 1000
}
} else {
// Expire immediately
timestamps.expired = now
} }
tagTimestamps.set(tag, timestamps)
} }
}, },
} }
...@@ -460,7 +495,7 @@ module.exports = { ...@@ -460,7 +495,7 @@ module.exports = {
### External storage pattern ### External storage pattern
For durable storage like Redis or a database, you'll need to serialize the cache entries. Here's a simple Redis example: A handler backed by Redis or a database must serialize each entry. Drain the stream in `set()`, and rebuild one from the stored bytes in `get()`:
```js filename="cache-handlers/redis-handler.js" ```js filename="cache-handlers/redis-handler.js"
const { createClient } = require('redis') const { createClient } = require('redis')
...@@ -532,26 +567,11 @@ module.exports = { ...@@ -532,26 +567,11 @@ module.exports = {
) )
}, },
async refreshTags() { // refreshTags(), getExpiration(), and updateTags() also need shared state.
// No-op for basic Redis implementation // See Distributed Tag Coordination for that half of the handler.
// Could sync with external tag service if needed
},
async getExpiration(tags) {
// Return 0 to indicate no tags have been revalidated
// Could query Redis for tag expiration timestamps if tracking them
return 0
},
async updateTags(tags, durations) {
// Implement tag-based invalidation if needed
// Could iterate over keys with matching tags and delete them
},
} }
``` ```
A complete Redis wiring of both cache APIs lives in the [`cache-handler-redis` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis). Production community handlers are listed in that example's README.
## Platform Support ## Platform Support
| Deployment Option | Supported | | Deployment Option | Supported |
......
...@@ -15,7 +15,7 @@ module.exports = { ...@@ -15,7 +15,7 @@ module.exports = {
} }
``` ```
View an example of a [custom cache handler](/docs/app/guides/self-hosting#configuring-caching) and learn more about the implementation. See the [Redis `cacheHandler` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) for a working implementation, and [Configuring Caching](/docs/app/guides/self-hosting#configuring-caching) for what a handler backed by a shared store needs.
## API Reference ## API Reference
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment