Implement persistent data cache option and update cache key logic

.changeset/slow-walls-allow.md

@@ -0,0 +1,5 @@
+---
+"@opennextjs/aws": minor
+---
+
+Add an option to keep the data cache persistent between deployments

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

@@ -3,7 +3,12 @@ import type {
   IncrementalCacheContext,
   IncrementalCacheValue,
 } from "types/cache";
-import { getTagsFromValue, hasBeenRevalidated, writeTags } from "utils/cache";
+import {
+  createCacheKey,
+  getTagsFromValue,
+  hasBeenRevalidated,
+  writeTags,
+} from "utils/cache";
 import { isBinaryContentType } from "../utils/binary";
 import { debug, error, warn } from "./logger";
 
@@ -31,7 +36,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,22 +54,24 @@ export default class Cache {
 
     const softTags = typeof options === "object" ? options.softTags : [];
     const tags = typeof options === "object" ? options.tags : [];
-    return isFetchCache(options)
-      ? this.getFetchCache(key, softTags, tags)
-      : this.getIncrementalCache(key);
+    const isDataCache = isFetchCache(options);
+    return isDataCache
+      ? this.getFetchCache(baseKey, softTags, tags)
+      : this.getIncrementalCache(baseKey);
   }
 
-  async getFetchCache(key: string, softTags?: string[], tags?: string[]) {
-    debug("get fetch cache", { key, softTags, tags });
+  async getFetchCache(baseKey: string, softTags?: string[], tags?: string[]) {
+    debug("get fetch cache", { baseKey, softTags, tags });
     try {
+      const key = createCacheKey(baseKey, true);
       const cachedEntry = await globalThis.incrementalCache.get(key, "fetch");
 
       if (cachedEntry?.value === undefined) return null;
 
       const _tags = [...(tags ?? []), ...(softTags ?? [])];
       const _lastModified = cachedEntry.lastModified ?? Date.now();
       const _hasBeenRevalidated = await hasBeenRevalidated(
-        key,
+        baseKey,
         _tags,
         cachedEntry,
       );
@@ -105,8 +112,11 @@ export default class Cache {
     }
   }
 
-  async getIncrementalCache(key: string): Promise<CacheHandlerValue | null> {
+  async getIncrementalCache(
+    baseKey: string,
+  ): Promise<CacheHandlerValue | null> {
     try {
+      const key = createCacheKey(baseKey, false);
       const cachedEntry = await globalThis.incrementalCache.get(key, "cache");
 
       if (!cachedEntry?.value) {
@@ -119,7 +129,7 @@ export default class Cache {
       const tags = getTagsFromValue(cacheData);
       const _lastModified = cachedEntry.lastModified ?? Date.now();
       const _hasBeenRevalidated = await hasBeenRevalidated(
-        key,
+        baseKey,
         tags,
         cachedEntry,
       );
@@ -191,20 +201,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);
@@ -302,7 +314,7 @@ export default class Cache {
         }
       }
 
-      await this.updateTagsOnSet(key, data, ctx);
+      await this.updateTagsOnSet(baseKey, data, ctx);
       debug("Finished setting cache");
     } catch (e) {
       error("Failed to set cache", e);

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

@@ -4,10 +4,33 @@ import { fromReadableStream, toReadableStream } from "utils/stream";
 import { debug } from "./logger";
 
 const pendingWritePromiseMap = new Map<string, Promise<ComposableCacheEntry>>();
+/**
+ * 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);
       // We first check if we have a pending write for this cache key
       // If we do, we return the pending promise instead of fetching the cache
       if (pendingWritePromiseMap.has(cacheKey)) {
@@ -55,7 +78,8 @@ export default {
     }
   },
 
-  async set(cacheKey: string, pendingEntry: Promise<ComposableCacheEntry>) {
+  async set(key: string, pendingEntry: Promise<ComposableCacheEntry>) {
+    const cacheKey = getComposableCacheKey(key);
     pendingWritePromiseMap.set(cacheKey, pendingEntry);
     const entry = await pendingEntry.finally(() => {
       pendingWritePromiseMap.delete(cacheKey);

packages/open-next/src/overrides/incrementalCache/fs-dev.ts

@@ -4,8 +4,7 @@ import path from "node:path";
 import type { IncrementalCache } from "types/overrides.js";
 import { getMonorepoRelativePath } from "utils/normalize-path";
 
-const buildId = process.env.NEXT_BUILD_ID;
-const basePath = path.join(getMonorepoRelativePath(), `cache/${buildId}`);
+const basePath = path.join(getMonorepoRelativePath(), "cache");
 
 const getCacheKey = (key: string) => {
   return path.join(basePath, `${key}.cache`);

packages/open-next/src/overrides/incrementalCache/multi-tier-ddb-s3.ts

@@ -41,8 +41,7 @@ const awsFetch = (body: RequestInit["body"], type: "get" | "set" = "get") => {
 };
 
 const buildDynamoKey = (key: string) => {
-  const { NEXT_BUILD_ID } = process.env;
-  return `__meta_${NEXT_BUILD_ID}_${key}`;
+  return `__meta_${key}`;
 };
 
 /**

packages/open-next/src/overrides/incrementalCache/s3-lite.ts

@@ -34,11 +34,10 @@ const awsFetch = async (key: string, options: RequestInit) => {
 };
 
 function buildS3Key(key: string, extension: Extension) {
-  const { CACHE_BUCKET_KEY_PREFIX, NEXT_BUILD_ID } = process.env;
+  const { CACHE_BUCKET_KEY_PREFIX } = process.env;
   return path.posix.join(
     CACHE_BUCKET_KEY_PREFIX ?? "",
     extension === "fetch" ? "__fetch" : "",
-    NEXT_BUILD_ID ?? "",
     extension === "fetch" ? key : `${key}.${extension}`,
   );
 }

packages/open-next/src/overrides/incrementalCache/s3.ts

@@ -13,12 +13,8 @@ import type { IncrementalCache } from "types/overrides";
 import { awsLogger } from "../../adapters/logger";
 import { parseNumberFromEnv } from "../../adapters/util";
 
-const {
-  CACHE_BUCKET_REGION,
-  CACHE_BUCKET_KEY_PREFIX,
-  NEXT_BUILD_ID,
-  CACHE_BUCKET_NAME,
-} = process.env;
+const { CACHE_BUCKET_REGION, CACHE_BUCKET_KEY_PREFIX, CACHE_BUCKET_NAME } =
+  process.env;
 
 function parseS3ClientConfigFromEnv(): S3ClientConfig {
   return {
@@ -34,7 +30,6 @@ function buildS3Key(key: string, extension: Extension) {
   return path.posix.join(
     CACHE_BUCKET_KEY_PREFIX ?? "",
     extension === "fetch" ? "__fetch" : "",
-    NEXT_BUILD_ID ?? "",
     extension === "fetch" ? key : `${key}.${extension}`,
   );
 }

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

@@ -78,6 +78,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

@@ -80,3 +80,19 @@ export async function writeTags(
   // Here we know that we have the correct type
   await globalThis.tagCache.writeTags(tagsToWrite as any);
 }
+
+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 { createCacheKey } from "@opennextjs/aws/utils/cache.js";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+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");
+  });
+});