Unverified Commit 26b2bbe0 authored by Joseph's avatar Joseph Committed by GitHub

example: Use a Redis cacheHandler w/o dependencies (#95346)

Verify locally:

- Copy the example to a local directory
- Install deps
- docker compose up -d
- npm run build && npm run start 
- navigate to localhost:3000/cet (or gmt)
- open the Redis view (link in localhost:3000/cet)
- revalidate data on /cet or /gmt
- verify it on the Redis view

I had to update the app to async params, updateTag, and write the
handler in such a way that it solved:

```
⨯ TypeError: p.segmentData.get is not a function
    at ignore-listed frames
⨯ Error: failed to pipe response
```

Also adding docs edits with this caveat.

An agent review, and cross checking with a community implementation,
surfaced, that we had to read tags from
`data.headers['x-next-cache-tags']`. This agent review added a few
comments, I think they are useful, but can cut down if needed.

Last but not least, had to update the Time API endpoint (former no
longer worked).
parent 3c8e9c38
...@@ -166,6 +166,8 @@ Using a custom cache handler will allow you to ensure consistency across all pod ...@@ -166,6 +166,8 @@ Using a custom cache handler will allow you to ensure consistency across all pod
> **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.
> - 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.
## Build Cache ## Build Cache
......
# Next.js Redis Cache Integration Example # Next.js Redis Cache Integration Example
This example is tailored for self-hosted setups and demonstrates how to use Redis as a shared cache. It is built on the principles of the `@neshca/cache-handler` package, which replaces the default Next.js cache handler and adds advanced caching features. This example is tailored for self-hosted setups and demonstrates how to back Next.js caching with Redis, using no third-party adapter. It wires up **both** of Next.js's cache handler APIs against the [`redis`](https://github.com/redis/node-redis) client, storing everything in a single Redis instance:
- **[`cacheHandler`](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandler) (singular)** — the ISR / incremental cache for pages, route handlers, and images. Implemented in [`cache-handler.js`](./cache-handler.js) with `get`, `set`, `revalidateTag`, and `resetRequestCache`.
- **[`cacheHandlers`](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers) (plural)** — the [`'use cache'`](https://nextjs.org/docs/app/api-reference/directives/use-cache) family. The [`remote`](https://nextjs.org/docs/app/api-reference/directives/use-cache-remote) handler in [`remote-cache-handler.js`](./remote-cache-handler.js) stores `'use cache: remote'` entries with `get`, `set`, `refreshTags`, `getExpiration`, and `updateTags`.
Both are configured in [`next.config.js`](./next.config.js), which enables `cacheComponents: true` (required for `'use cache'`) and sets `cacheMaxMemorySize: 0` so Redis is the single shared source of truth across instances.
Check out this [repository](https://github.com/ezeparziale/nextjs-k8s) that contains a comprehensive setup for Kubernetes. Check out this [repository](https://github.com/ezeparziale/nextjs-k8s) that contains a comprehensive setup for Kubernetes.
...@@ -20,40 +25,66 @@ yarn create next-app --example cache-handler-redis cache-handler-redis-app ...@@ -20,40 +25,66 @@ yarn create next-app --example cache-handler-redis cache-handler-redis-app
pnpm create next-app --example cache-handler-redis cache-handler-redis-app pnpm create next-app --example cache-handler-redis cache-handler-redis-app
``` ```
Once you have installed the dependencies, you can begin running the example Redis Stack server by using the following command: Once you have installed the dependencies, you can begin running the example Redis server by using the following command:
```bash ```bash
docker compose up -d docker compose up -d
``` ```
Then, build and start the Next.js app as usual. Then, build and start the Next.js app as usual. The custom cache handlers are only used for production builds (`next start`), so run:
```bash
npm run build
npm run start
```
To see the cache logs, set `NEXT_PRIVATE_DEBUG_CACHE=1` when starting the app.
To see the cache logs use NEXT_PRIVATE_DEBUG_CACHE=1 [troubleshooting](https://caching-tools.github.io/next-shared-cache/troubleshooting) ## How it works
## Documentation The `/[timezone]` page renders a mostly static shell and, inside it, a `'use cache: remote'` function (`getCurrentTime`) that fetches the current time. This exercises both handlers at once:
- **ISR cache (`cache-handler.js`):** stores the prerendered page entries as JSON under a `nextjs:cache:` prefix, and tracks which keys belong to each tag in a Redis set (`nextjs:tag:<tag>`). `revalidateTag` deletes every key associated with a tag.
For detailed information on configuration and usage, please refer to our comprehensive [Documentation ↗](https://caching-tools.github.io/next-shared-cache). - **Remote cache (`remote-cache-handler.js`):** stores each `'use cache: remote'` entry under a `nextjs:use-cache:` prefix (the streamed value is base64-encoded). Tag revalidation is timestamp-based: `updateTags` records `nextjs:use-cache-tag:<tag>` = now, and `getExpiration` reports the latest time so Next treats older entries as stale. Clicking **Revalidate** calls [`updateTag('time-data')`](https://nextjs.org/docs/app/api-reference/functions/updateTag), which regenerates the remote entry.
## Key Features and Considerations - **Building without Redis:** both handlers skip connecting during `next build` (they check `NEXT_PHASE`) and degrade gracefully when Redis is unavailable, so the app still builds and runs, just without a shared cache.
- **Handlers:** The `@neshca/cache-handler` package includes [Handlers](https://caching-tools.github.io/next-shared-cache/handlers/redis-stack) for seamless integration with Redis. - **Redis server setup:** ensure your Redis server is running before starting the app. Configure the connection with `REDIS_URL` (defaults to `redis://localhost:6379`).
- **Create Your Own Handlers:** Take a look at [Custom Redis Handler](https://caching-tools.github.io/next-shared-cache/usage/creating-a-custom-handler) and use it as a basis to create your own handler. > **Note:** This example fetches the current time from a public API (`timeapi.io`) purely as sample data to demonstrate caching and revalidation. It is included for learning purposes only. If you reuse it, review and respect that API's terms of use and rate limits, and swap in your own data source for real applications.
- **Redis Server Setup:** Ensure your Redis server is running and properly configured before starting your Next.js application. ## Revalidation: paths, soft tags, and advisory parameters
- **Configure Redis Credentials:** Update the `cache-handler-redis*` files with your Redis credentials. Connection details can be found [here](https://redis.io/docs/connect/clients/nodejs/). The **Revalidate** button ([`revalidate-from.tsx`](./app/revalidate-from.tsx)) calls [`updateTag('time-data')`](https://nextjs.org/docs/app/api-reference/functions/updateTag), but that is only one entry point into the remote handler's tag machinery. Two related capabilities are handled without extra code, and two handler parameters are intentionally unused:
- **Building Without Redis:** To build the app without connecting to Redis use conditions inside `onCreation` callback. Check the [documentation](https://caching-tools.github.io/next-shared-cache/configuration/opt-out-cache-on-build) for more details. - **[`revalidatePath`](https://nextjs.org/docs/app/api-reference/functions/revalidatePath) works without extra code.** Next.js derives implicit _soft tags_ from the route path (prefixed `_N_T_`, e.g. `_N_T_/[timezone]`) and routes path revalidation through the same tags as `revalidateTag`. A `revalidatePath('/…')` call therefore reaches `updateTags(['_N_T_/…'])`, and the next read calls `getExpiration(['_N_T_/…'])`. Because both methods operate generically over any tag string, path revalidation propagates across instances through Redis exactly like an explicit tag.
- **`get(cacheKey, softTags)` ignores `softTags` by design.** A handler can honor soft tags one of two ways: implement `getExpiration` to return the most recent revalidation timestamp (Next.js then performs the soft-tag staleness check itself), or return `Infinity` from `getExpiration` and compare timestamps inside `get`. This handler does the former, so it never needs to read the `softTags` argument.
- **`updateTags(tags, durations)` ignores `durations` by design.** `durations` (`{ expire }`) is only populated when a revalidation call carries a [`cacheLife`](https://nextjs.org/docs/app/api-reference/functions/cacheLife) profile, such as `revalidateTag(tag, 'max')`; it defers a tag's expiration into the future instead of expiring it immediately. This example performs only immediate revalidation, so `durations` is always `undefined` — equivalent to recording the current timestamp, which is what `updateTags` already does.
See the [Soft Tags](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers#soft-tags) section of the `cacheHandlers` documentation for the full tag architecture.
## Documentation
For detailed information, see the official Next.js documentation:
- [`cacheHandler` (ISR / incremental cache) ↗](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandler)
- [`cacheHandlers` (`'use cache'`) ↗](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers)
- [`'use cache: remote'` ↗](https://nextjs.org/docs/app/api-reference/directives/use-cache-remote)
- [Self-hosting: configuring caching ↗](https://nextjs.org/docs/app/guides/self-hosting#configuring-caching)
## Development and Production Considerations ## Development and Production Considerations
- The provided `compose.yaml` is intended for local development. For production deployment, refer to the official [Redis installation](https://redis.io/docs/install/) and [management](https://redis.io/docs/management/) guidelines. - The provided `compose.yaml` is intended for local development. For production deployment, refer to the official [Redis installation](https://redis.io/docs/install/) and [management](https://redis.io/docs/management/) guidelines.
- **Inspecting the cache:** The `redis-stack` image bundles RedisInsight on port `8001`. Open it in your browser (linked from the example UI) to watch both the `nextjs:cache:` (ISR) and `nextjs:use-cache:` (remote) keys appear and expire.
- **Clearing Redis Cache:** To clear the Redis cache, use RedisInsight Workbench or the following CLI command: - **Clearing Redis Cache:** To clear the Redis cache, use RedisInsight Workbench or the following CLI command:
```bash ```bash
docker exec -it redis-stack redis-cli docker exec -it cache-handler-redis redis-cli
127.0.0.1:6379> flushall 127.0.0.1:6379> flushall
OK OK
``` ```
import { notFound } from "next/navigation"; import { notFound } from "next/navigation";
import { cacheLife, cacheTag } from "next/cache";
import { CacheStateWatcher } from "../cache-state-watcher"; import { CacheStateWatcher } from "../cache-state-watcher";
import { Suspense } from "react"; import { Suspense } from "react";
import { RevalidateFrom } from "../revalidate-from"; import { RevalidateFrom } from "../revalidate-from";
import Link from "next/link"; import Link from "next/link";
type TimeData = { type TimeData = {
unixtime: number; dateTime: string;
datetime: string; timeZone: string;
timezone: string;
}; };
const timeZones = ["cet", "gmt"]; type CachedTime = {
time: TimeData;
generatedAt: number;
};
export const revalidate = 500; // Map the friendly route segment to an IANA timezone for the time API.
const timeZones = {
cet: "Europe/Amsterdam",
gmt: "Etc/UTC",
} as const;
export async function generateStaticParams() { // How long the cached time stays fresh (seconds). Shared with the countdown UI.
return timeZones.map((timezone) => ({ timezone })); const REVALIDATE_SECONDS = 500;
}
export default async function Page({ params: { timezone } }) { // Cache the upstream time in the `remote` cache handler (Redis) rather than the
const data = await fetch( // default in-memory cache, so it's shared across instances and survives
`https://worldtimeapi.org/api/timezone/${timezone}`, // restarts. `updateTag("time-data")` invalidates it on demand.
{ async function getCurrentTime(
next: { tags: ["time-data"] }, ianaTimeZone: string,
}, ): Promise<CachedTime | null> {
"use cache: remote";
cacheTag("time-data");
cacheLife({ stale: 60, revalidate: REVALIDATE_SECONDS, expire: 3600 });
const response = await fetch(
`https://timeapi.io/api/time/current/zone?timeZone=${ianaTimeZone}`,
); );
if (!data.ok) { if (!response.ok) {
return null;
}
// `Date.now()` is allowed here because this is a cached function: the value
// is baked into the remote cache entry and refreshes when it revalidates.
return { time: await response.json(), generatedAt: Date.now() };
}
export function generateStaticParams() {
return Object.keys(timeZones).map((timezone) => ({ timezone }));
}
export default async function Page({ params }: PageProps<"/[timezone]">) {
const { timezone } = await params;
const ianaTimeZone = timeZones[timezone as keyof typeof timeZones];
if (!ianaTimeZone) {
notFound();
}
const cached = await getCurrentTime(ianaTimeZone);
if (!cached) {
notFound(); notFound();
} }
const timeData: TimeData = await data.json(); const { time: timeData, generatedAt } = cached;
return ( return (
<> <>
<header className="header"> <header className="header">
{timeZones.map((timeZone) => ( {Object.keys(timeZones).map((timeZone) => (
<Link key={timeZone} className="link" href={`/${timeZone}`}> <Link key={timeZone} className="link" href={`/${timeZone}`}>
{timeZone.toUpperCase()} Time {timeZone.toUpperCase()} Time
</Link> </Link>
...@@ -43,12 +78,12 @@ export default async function Page({ params: { timezone } }) { ...@@ -43,12 +78,12 @@ export default async function Page({ params: { timezone } }) {
</header> </header>
<main className="widget"> <main className="widget">
<div className="pre-rendered-at"> <div className="pre-rendered-at">
{timeData.timezone} Time {timeData.datetime} {timezone.toUpperCase()} Time {timeData.dateTime}
</div> </div>
<Suspense fallback={null}> <Suspense fallback={null}>
<CacheStateWatcher <CacheStateWatcher
revalidateAfter={revalidate * 1000} revalidateAfter={REVALIDATE_SECONDS * 1000}
time={timeData.unixtime * 1000} time={generatedAt}
/> />
</Suspense> </Suspense>
<RevalidateFrom /> <RevalidateFrom />
......
"use server"; "use server";
import { revalidateTag } from "next/cache"; import { updateTag } from "next/cache";
export default async function revalidate() { export default async function revalidate() {
revalidateTag("time-data"); updateTag("time-data");
} }
const { CacheHandler } = require("@neshca/cache-handler");
const createRedisHandler = require("@neshca/cache-handler/redis-stack").default;
const createLruHandler = require("@neshca/cache-handler/local-lru").default;
const { createClient } = require("redis"); const { createClient } = require("redis");
const { PHASE_PRODUCTION_BUILD } = require("next/constants"); const { PHASE_PRODUCTION_BUILD } = require("next/constants");
/* from https://caching-tools.github.io/next-shared-cache/redis */ // A custom Next.js cache handler backed by Redis. This implements the cache
CacheHandler.onCreation(async () => { // handler interface (`get`, `set`, `revalidateTag`, `resetRequestCache`)
let client; // directly, so no third-party adapter is required.
// use redis client during build could cause issue https://github.com/caching-tools/next-shared-cache/issues/284#issuecomment-1919145094 //
if (PHASE_PRODUCTION_BUILD !== process.env.NEXT_PHASE) { // See https://nextjs.org/docs/app/guides/self-hosting#configuring-caching
try { // and https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandler
// Create a Redis client.
client = createClient({ // Prefix cache entries and tag indexes so they're easy to find (and flush)
url: process.env.REDIS_URL ?? "redis://localhost:6379", // in Redis and don't collide with other keys.
}); const CACHE_PREFIX = "nextjs:cache:";
const TAG_PREFIX = "nextjs:tag:";
// Redis won't work without error handling.
// NB do not throw exceptions in the redis error listener, // App page/route entries carry their cache tags in this response header
// because it will prevent reconnection after a socket exception. // rather than in `ctx.tags` (which is only populated for fetch entries).
client.on("error", (e) => { const NEXT_CACHE_TAGS_HEADER = "x-next-cache-tags";
if (typeof process.env.NEXT_PRIVATE_DEBUG_CACHE !== "undefined") {
console.warn("Redis error", e); // Cache entries aren't plain JSON: app page entries contain `Buffer`s
} // (e.g. `rscData`) and a `Map` (`segmentData`). Plain `JSON.stringify` would
}); // turn a `Map` into `{}` and lose the buffer types, so we tag those values on
} catch (error) { // the way out and rebuild them on the way back in.
console.warn("Failed to create Redis client:", error); function serialize(entry) {
return JSON.stringify(entry, (_key, value) => {
if (value instanceof Map) {
return { __type: "Map", value: Array.from(value.entries()) };
} }
} return value;
});
}
if (client) { function deserialize(text) {
try { return JSON.parse(text, (_key, value) => {
console.info("Connecting Redis client..."); if (value && value.__type === "Map") {
return new Map(value.value);
// Wait for the client to connect.
// Caveat: This will block the server from starting until the client is connected.
// And there is no timeout. Make your own timeout if needed.
await client.connect();
console.info("Redis client connected.");
} catch (error) {
console.warn("Failed to connect Redis client:", error);
console.warn("Disconnecting the Redis client...");
// Try to disconnect the client to stop it from reconnecting.
client
.disconnect()
.then(() => {
console.info("Redis client disconnected.");
})
.catch(() => {
console.warn(
"Failed to quit the Redis client after failing to connect.",
);
});
} }
} // `Buffer#toJSON()` produces `{ type: "Buffer", data: [...] }`.
if (value && value.type === "Buffer" && Array.isArray(value.data)) {
return Buffer.from(value.data);
}
return value;
});
}
module.exports = class CacheHandler {
constructor(options) {
this.options = options;
/** @type {import("@neshca/cache-handler").Handler | null} */ this.client = createClient({
let redisHandler = null; url: process.env.REDIS_URL ?? "redis://localhost:6379",
if (client?.isReady) {
// Create the `redis-stack` Handler if the client is available and connected.
redisHandler = await createRedisHandler({
client,
keyPrefix: "prefix:",
timeoutMs: 1000,
}); });
// Redis won't work without error handling. Do not throw here, otherwise
// the client won't reconnect after a connection drop.
this.client.on("error", (error) => {
if (process.env.NEXT_PRIVATE_DEBUG_CACHE) {
console.warn("Redis client error:", error);
}
});
// Connecting to Redis during `next build` can cause issues, so we only
// connect at runtime. `this.connection` resolves once the client is ready.
this.connection =
process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD
? Promise.resolve()
: this.client.connect().catch((error) => {
console.warn("Failed to connect to Redis:", error);
});
}
// Resolve a connected client, or `null` when Redis is unavailable so the
// app keeps working (without a shared cache) instead of crashing.
async getClient() {
await this.connection;
return this.client.isReady ? this.client : null;
}
async get(key) {
const client = await this.getClient();
if (!client) return null;
const entry = await client.get(CACHE_PREFIX + key);
return entry ? deserialize(entry) : null;
}
async set(key, data, ctx) {
const client = await this.getClient();
if (!client || !data) return;
// Collect tags from both sources: `ctx.tags` (fetch entries) and the
// `x-next-cache-tags` header (app page/route entries).
const headerTags = (data.headers?.[NEXT_CACHE_TAGS_HEADER] ?? "")
.split(",")
.filter(Boolean);
const tags = [...new Set([...(ctx?.tags ?? []), ...headerTags])];
// Let Redis auto-expire the entry when it carries a finite `expire`. Key
// the TTL on `expire`, never `revalidate`: past `revalidate` the entry is
// only stale (Next.js serves it while refreshing), so evicting it there
// would defeat that. ISR entries often omit `expire` entirely, in which
// case we set no TTL and rely on `revalidateTag` to invalidate.
const expire = ctx?.cacheControl?.expire;
const options = Number.isFinite(expire)
? { expiration: { type: "EX", value: Math.max(1, Math.ceil(expire)) } }
: {};
await client.set(
CACHE_PREFIX + key,
serialize({ value: data, lastModified: Date.now(), tags }),
options,
);
// Index this key under each of its tags so `revalidateTag` can find it.
await Promise.all(tags.map((tag) => client.sAdd(TAG_PREFIX + tag, key)));
} }
// Fallback to LRU handler if Redis client is not available.
// The application will still work, but the cache will be in memory only and not shared. async revalidateTag(tags) {
const LRUHandler = createLruHandler(); const client = await this.getClient();
console.warn( if (!client) return;
"Falling back to LRU handler because Redis client is not available.",
); // `tags` is either a single tag or an array of tags.
for (const tag of [tags].flat()) {
return { const tagKey = TAG_PREFIX + tag;
handlers: [redisHandler, LRUHandler], const keys = await client.sMembers(tagKey);
};
}); if (keys.length) {
await client.del(keys.map((key) => CACHE_PREFIX + key));
module.exports = CacheHandler; }
await client.del(tagKey);
}
}
// Used for an in-memory, per-request cache. Redis is the source of truth
// here, so there's nothing to reset between requests.
resetRequestCache() {}
};
# The cache handler only needs plain Redis. We use the redis-stack image so
# the bundled RedisInsight viewer (port 8001) is available for inspecting the
# cache during local development.
services: services:
redis-stack: redis-stack:
image: redis/redis-stack:latest image: redis/redis-stack:latest
......
/** @type {import('next').NextConfig} */ /** @type {import('next').NextConfig} */
const nextConfig = { const nextConfig = {
// Enable Cache Components so the `'use cache: remote'` directive is available.
cacheComponents: true,
// The singular `cacheHandler` backs the ISR/incremental cache (pages, route
// handlers, images).
cacheHandler: cacheHandler:
process.env.NODE_ENV === "production" process.env.NODE_ENV === "production"
? require.resolve("./cache-handler.js") ? require.resolve("./cache-handler.js")
: undefined, : undefined,
// The plural `cacheHandlers` back the `'use cache'` family. Here the `remote`
// handler stores `'use cache: remote'` entries in the same Redis instance.
cacheHandlers: {
remote: require.resolve("./remote-cache-handler.js"),
},
// Disable the default in-memory cache so Redis is the single shared source
// of truth across instances.
cacheMaxMemorySize: 0,
env: { env: {
NEXT_PUBLIC_REDIS_INSIGHT_URL: NEXT_PUBLIC_REDIS_INSIGHT_URL:
process.env.REDIS_INSIGHT_URL ?? "http://localhost:8001", process.env.REDIS_INSIGHT_URL ?? "http://localhost:8001",
......
...@@ -6,7 +6,6 @@ ...@@ -6,7 +6,6 @@
"start": "next start" "start": "next start"
}, },
"dependencies": { "dependencies": {
"@neshca/cache-handler": "^1.3.2",
"next": "latest", "next": "latest",
"react": "^18.2.0", "react": "^18.2.0",
"react-dom": "^18.2.0", "react-dom": "^18.2.0",
......
const { createClient } = require("redis");
const { PHASE_PRODUCTION_BUILD } = require("next/constants");
// A custom `cacheHandlers.remote` handler backed by Redis. This is a different
// interface from the singular `cacheHandler` (in `cache-handler.js`): it backs
// the `'use cache: remote'` directive, its entries are streams, and it tracks
// tag revalidation by timestamp.
//
// See https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers
const ENTRY_PREFIX = "nextjs:use-cache:";
const TAG_PREFIX = "nextjs:use-cache-tag:";
const client = createClient({
url: process.env.REDIS_URL ?? "redis://localhost:6379",
});
client.on("error", (error) => {
if (process.env.NEXT_PRIVATE_DEBUG_CACHE) {
console.warn("Redis client error (remote cache):", error);
}
});
const connection =
process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD
? Promise.resolve()
: client.connect().catch((error) => {
console.warn("Failed to connect to Redis (remote cache):", error);
});
async function getClient() {
await connection;
return client.isReady ? client : null;
}
module.exports = {
async get(cacheKey) {
const redis = await getClient();
if (!redis) return undefined;
const stored = await redis.get(ENTRY_PREFIX + cacheKey);
if (!stored) return undefined;
const data = JSON.parse(stored);
// Only `expire` means the entry is unusable. Past `revalidate` it's stale,
// not expired: return it so Next.js can serve it while it refreshes in the
// background. (`expire: Infinity` never trips this, which is intended.)
if (Date.now() > data.timestamp + data.expire * 1000) {
return undefined;
}
return {
// `value` must be a stream; rebuild it from the stored bytes.
value: new ReadableStream({
start(controller) {
controller.enqueue(Buffer.from(data.value, "base64"));
controller.close();
},
}),
tags: data.tags,
stale: data.stale,
timestamp: data.timestamp,
expire: data.expire,
revalidate: data.revalidate,
};
},
async set(cacheKey, pendingEntry) {
const redis = await getClient();
if (!redis) return;
// The entry may still be streaming, so await it, then drain the stream.
const entry = await pendingEntry;
const reader = entry.value.getReader();
const chunks = [];
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
chunks.push(value);
}
} finally {
reader.releaseLock();
}
const bytes = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
// A TTL needs a positive integer. By definition, `expire: Infinity`
// ("never expire") maps to no TTL at all, so omit it and let Redis persist
// the key.
const options = Number.isFinite(entry.expire)
? {
expiration: {
type: "EX",
value: Math.max(1, Math.ceil(entry.expire)),
},
}
: {};
await redis.set(
ENTRY_PREFIX + cacheKey,
JSON.stringify({
value: bytes.toString("base64"),
tags: entry.tags,
stale: entry.stale,
timestamp: entry.timestamp,
expire: entry.expire,
revalidate: entry.revalidate,
}),
options,
);
},
// Redis is the single source of truth and every read hits it, so there's no
// local tag state to sync between requests.
async refreshTags() {},
// Return the most recent revalidation time across `tags`. Next treats an
// entry as stale when this is newer than the entry's `timestamp`.
async getExpiration(tags) {
const redis = await getClient();
if (!redis || !tags.length) return 0;
const values = await redis.mGet(tags.map((tag) => TAG_PREFIX + tag));
const timestamps = values.filter(Boolean).map(Number);
return timestamps.length ? Math.max(...timestamps) : 0;
},
// Record when each tag was last revalidated so `getExpiration` can report
// it. There's one key per distinct tag, overwritten in place, so a small
// fixed tag set (like this example's single `time-data` tag) never grows.
//
// An app that mints many distinct, short-lived tags (e.g. `user-<id>`) would
// instead keep a key per tag forever. To bound that, give each key a TTL
// (`{ expiration: { type: "EX", value } }`) at least as long as your longest
// entry `expire`: the timestamp only needs to outlive entries created before
// this revalidation, so a shorter TTL could drop it while such an entry is
// still cached and serve it as fresh when it should be stale.
async updateTags(tags) {
const redis = await getClient();
if (!redis) return;
const now = String(Date.now());
await Promise.all(tags.map((tag) => redis.set(TAG_PREFIX + tag, now)));
},
};
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