compute cache key according to persistentDataCache

Author: Nicolas Dorseuil

packages/open-next/src/adapters/cache.ts

@@ -3,7 +3,11 @@ import type {
   IncrementalCacheContext,
   IncrementalCacheValue,
 } from "types/cache";
-import { getTagsFromValue, hasBeenRevalidated } from "utils/cache";
+import {
+  createCacheKey,
+  getTagsFromValue,
+  hasBeenRevalidated,
+} from "utils/cache";
 import { isBinaryContentType } from "../utils/binary";
 import { debug, error, warn } from "./logger";
 
@@ -31,7 +35,7 @@ function isFetchCache(
 // We need to use globalThis client here as this class can be defined at load time in next 12 but client is not available at load time
 export default class Cache {
   public async get(
-    key: string,
+    baseKey: string,
     // fetchCache is for next 13.5 and above, kindHint is for next 14 and above and boolean is for earlier versions
     options?:
       | boolean
@@ -49,7 +53,9 @@ export default class Cache {
 
     const softTags = typeof options === "object" ? options.softTags : [];
     const tags = typeof options === "object" ? options.tags : [];
-    return isFetchCache(options)
+    const isDataCache = isFetchCache(options);
+    const key = createCacheKey(baseKey, isDataCache);
+    return isDataCache
       ? this.getFetchCache(key, softTags, tags)
       : this.getIncrementalCache(key);
   }
@@ -191,20 +197,22 @@ export default class Cache {
   }
 
   async set(
-    key: string,
+    baseKey: string,
     data?: IncrementalCacheValue,
     ctx?: IncrementalCacheContext,
   ): Promise<void> {
     if (globalThis.openNextConfig.dangerous?.disableIncrementalCache) {
       return;
     }
+    const key = createCacheKey(baseKey, data?.kind === "FETCH");
     // This one might not even be necessary anymore
     // Better be safe than sorry
     const detachedPromise = globalThis.__openNextAls
       .getStore()
       ?.pendingPromiseRunner.withResolvers<void>();
     try {
       if (data === null || data === undefined) {
+        // only case where we delete the cache is for ISR/SSG cache
         await globalThis.incrementalCache.delete(key);
       } else {
         const revalidate = this.extractRevalidateForSet(ctx);

packages/open-next/src/adapters/composable-cache.ts

@@ -2,9 +2,33 @@ import type { ComposableCacheEntry, ComposableCacheHandler } from "types/cache";
 import { fromReadableStream, toReadableStream } from "utils/stream";
 import { debug } from "./logger";
 
+/**
+ * Get the cache key for a composable entry.
+ * Composable cache keys are a special cases as they are a stringified version of a tuple composed of a representation of the BUILD_ID and the actual key.
+ * @param key The composable cache key
+ * @returns The composable cache key.
+ */
+function getComposableCacheKey(key: string): string {
+  try {
+    const shouldPrependBuildId =
+      globalThis.openNextConfig.dangerous?.persistentDataCache !== true;
+    if (shouldPrependBuildId) {
+      return key;
+    }
+    const [_buildId, ...rest] = JSON.parse(key);
+    return JSON.stringify([...rest]);
+  } catch (e) {
+    debug("Error while parsing composable cache key", e);
+    // If we fail to parse the key, we just return it as is
+    // This is not ideal, but we don't want to crash the application
+    return key;
+  }
+}
+
 export default {
-  async get(cacheKey: string) {
+  async get(key: string) {
     try {
+      const cacheKey = getComposableCacheKey(key);
       const result = await globalThis.incrementalCache.get(
         cacheKey,
         "composable",
@@ -47,7 +71,8 @@ export default {
     }
   },
 
-  async set(cacheKey: string, pendingEntry: Promise<ComposableCacheEntry>) {
+  async set(key: string, pendingEntry: Promise<ComposableCacheEntry>) {
+    const cacheKey = getComposableCacheKey(key);
     const entry = await pendingEntry;
     const valueToStore = await fromReadableStream(entry.value);
     await globalThis.incrementalCache.set(

packages/open-next/src/types/open-next.ts

@@ -77,6 +77,16 @@ export interface DangerousOptions {
   headersAndCookiesPriority?: (
     event: InternalEvent,
   ) => "middleware" | "handler";
+
+  /**
+   * Persist data cache between deployments.
+   * Next.js claims that the data cache is persistent (not true for `use cache` and it depends on how you build/deploy otherwise).
+   * By default, every entry will be prepended with the BUILD_ID, when enabled it will not.
+   * This means that the data cache will be persistent between deployments.
+   * This is useful in a lot of cases, but be aware that it could cause issues, especially with `use cache` or `unstable_cache` (Some external change may not be reflected in the key, leading to stale data)
+   * @default false
+   */
+  persistentDataCache?: boolean;
 }
 
 export type BaseOverride = {

packages/open-next/src/utils/cache.ts

@@ -39,3 +39,19 @@ export function getTagsFromValue(value?: CacheValue<"cache">) {
     return [];
   }
 }
+
+export function createCacheKey(key: string, isDataCache: boolean): string {
+  // We always prepend the build ID to the cache key for ISR/SSG cache entry
+  // For data cache, we only prepend the build ID if the persistentDataCache is not enabled
+  const shouldPrependBuildId =
+    globalThis.openNextConfig.dangerous?.persistentDataCache !== true ||
+    !isDataCache;
+  if (shouldPrependBuildId) {
+    // If we don't have a build ID, we just return the key as is
+    if (!process.env.NEXT_BUILD_ID) {
+      return key;
+    }
+    return `${process.env.NEXT_BUILD_ID}/${key}`;
+  }
+  return key;
+}

packages/tests-unit/tests/adapters/cache.test.ts

@@ -4,7 +4,11 @@ import { vi } from "vitest";
 
 declare global {
   var openNextConfig: {
-    dangerous: { disableIncrementalCache?: boolean; disableTagCache?: boolean };
+    dangerous: {
+      disableIncrementalCache?: boolean;
+      disableTagCache?: boolean;
+      persistentDataCache?: boolean;
+    };
   };
   var isNextAfter15: boolean;
 }

packages/tests-unit/tests/utils/cache.test.ts

@@ -0,0 +1,62 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { createCacheKey } from "@opennextjs/aws/utils/cache.js";
+
+describe("createCacheKey", () => {
+  const originalEnv = process.env;
+  const originalGlobalThis = globalThis as any;
+
+  beforeEach(() => {
+    vi.resetModules();
+    process.env = { ...originalEnv };
+
+    // Mock globalThis.openNextConfig
+    if (!globalThis.openNextConfig) {
+      globalThis.openNextConfig = {
+        dangerous: {},
+      };
+    }
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    globalThis.openNextConfig = originalGlobalThis.openNextConfig;
+  });
+
+  test("prepends build ID for non-data cache entries", () => {
+    process.env.NEXT_BUILD_ID = "test-build-id";
+    const key = "test-key";
+
+    const result = createCacheKey(key, false);
+
+    expect(result).toBe("test-build-id/test-key");
+  });
+
+  test("prepends build ID for data cache when persistentDataCache is not enabled", () => {
+    process.env.NEXT_BUILD_ID = "test-build-id";
+    globalThis.openNextConfig.dangerous.persistentDataCache = false;
+    const key = "test-key";
+
+    const result = createCacheKey(key, true);
+
+    expect(result).toBe("test-build-id/test-key");
+  });
+
+  test("does not prepend build ID for data cache when persistentDataCache is enabled", () => {
+    process.env.NEXT_BUILD_ID = "test-build-id";
+    globalThis.openNextConfig.dangerous.persistentDataCache = true;
+    const key = "test-key";
+
+    const result = createCacheKey(key, true);
+
+    expect(result).toBe("test-key");
+  });
+
+  test("handles missing build ID", () => {
+    process.env.NEXT_BUILD_ID = undefined;
+    const key = "test-key";
+
+    const result = createCacheKey(key, false);
+
+    expect(result).toBe("test-key");
+  });
+});