fix: mark prerendered content as less stale now that expire setting is enforced for marking for blocking re-render (#3510)

Co-authored-by: Philippe Serhal <philippe.serhal@netlify.com>

Author: pieh

src/build/content/prerendered.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path'
 import { trace } from '@opentelemetry/api'
 import { wrapTracer } from '@opentelemetry/api/experimental'
 import { glob } from 'fast-glob'
+import type { PrerenderManifestRoute } from 'next-with-cache-handler-v2/dist/build/index.js'
 import type { RouteMetadata } from 'next-with-cache-handler-v2/dist/export/routes/types.js'
 import pLimit from 'p-limit'
 import { satisfies } from 'semver'
@@ -56,9 +57,34 @@ const routeToFilePath = (path: string) => {
   return `/${path}`
 }
 
+function prerenderManifestRouteToRevalidateAndCacheControlProperties(
+  prerenderManifestRoute: PrerenderManifestRoute | undefined,
+) {
+  if (!prerenderManifestRoute) {
+    return {}
+  }
+
+  return {
+    revalidate: prerenderManifestRoute.initialRevalidateSeconds,
+    cacheControl: prerenderManifestRoute.initialRevalidateSeconds
+      ? {
+          revalidate: prerenderManifestRoute.initialRevalidateSeconds,
+          expire:
+            typeof prerenderManifestRoute.initialExpireSeconds === 'number'
+              ? prerenderManifestRoute.initialExpireSeconds +
+                (prerenderManifestRoute.initialExpireSeconds ===
+                prerenderManifestRoute.initialRevalidateSeconds
+                  ? 31536000000
+                  : 0)
+              : undefined,
+        }
+      : undefined,
+  }
+}
+
 const buildPagesCacheValue = async (
   path: string,
-  initialRevalidateSeconds: number | false | undefined,
+  prerenderManifestRoute: PrerenderManifestRoute | undefined,
   shouldUseEnumKind: boolean,
   shouldSkipJson = false,
 ): Promise<NetlifyCachedPageValue> => ({
@@ -67,14 +93,15 @@ const buildPagesCacheValue = async (
   pageData: shouldSkipJson ? {} : JSON.parse(await readFile(`${path}.json`, 'utf-8')),
   headers: undefined,
   status: undefined,
-  revalidate: initialRevalidateSeconds,
+  ...prerenderManifestRouteToRevalidateAndCacheControlProperties(prerenderManifestRoute),
 })
 
 const RSC_SEGMENTS_DIR_SUFFIX = '.segments'
 const RSC_SEGMENT_SUFFIX = '.segment.rsc'
 
 const buildAppCacheValue = async (
   path: string,
+  prerenderManifestRoute: PrerenderManifestRoute | undefined,
   shouldUseAppPageKind: boolean,
   rscIsRequired = true,
 ): Promise<NetlifyCachedAppPageValue | NetlifyCachedPageValue> => {
@@ -117,6 +144,7 @@ const buildAppCacheValue = async (
         }),
       segmentData,
       ...meta,
+      ...prerenderManifestRouteToRevalidateAndCacheControlProperties(prerenderManifestRoute),
     }
   }
 
@@ -141,26 +169,37 @@ const buildAppCacheValue = async (
     html,
     pageData: rsc,
     ...meta,
+    ...prerenderManifestRouteToRevalidateAndCacheControlProperties(prerenderManifestRoute),
   }
 }
 
 const buildRouteCacheValue = async (
   path: string,
-  initialRevalidateSeconds: number | false,
+  prerenderManifestRoute: PrerenderManifestRoute,
   shouldUseEnumKind: boolean,
 ): Promise<NetlifyCachedRouteValue> => ({
   kind: shouldUseEnumKind ? 'APP_ROUTE' : 'ROUTE',
   body: await readFile(`${path}.body`, 'base64'),
   ...JSON.parse(await readFile(`${path}.meta`, 'utf-8')),
-  revalidate: initialRevalidateSeconds,
+  ...prerenderManifestRouteToRevalidateAndCacheControlProperties(prerenderManifestRoute),
 })
 
 const buildFetchCacheValue = async (
   path: string,
-): Promise<CachedFetchValueForMultipleVersions> => ({
-  kind: 'FETCH',
-  ...JSON.parse(await readFile(path, 'utf-8')),
-})
+): Promise<{ value: CachedFetchValueForMultipleVersions; lastModified: number }> => {
+  const data = JSON.parse(await readFile(path, 'utf-8')) as Omit<
+    CachedFetchValueForMultipleVersions,
+    'kind'
+  >
+
+  return {
+    value: {
+      kind: 'FETCH',
+      ...data,
+    },
+    lastModified: Date.now() - (data?.revalidate ?? 31536000000),
+  }
+}
 
 /**
  * Upload prerendered content to the blob store
@@ -198,43 +237,44 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
 
       await Promise.all([
         ...Object.entries(manifest.routes).map(
-          ([route, meta]): Promise<void> =>
+          ([route, prerenderManifestRoute]): Promise<void> =>
             limitConcurrentPrerenderContentHandling(async () => {
-              const lastModified = meta.initialRevalidateSeconds
-                ? Date.now() - 31536000000
+              const lastModified = prerenderManifestRoute.initialRevalidateSeconds
+                ? Date.now() - prerenderManifestRoute.initialRevalidateSeconds * 1000
                 : Date.now()
               const key = routeToFilePath(route)
               let value: NetlifyIncrementalCacheValue
               switch (true) {
                 // Parallel route default layout has no prerendered page
-                case meta.dataRoute?.endsWith('/default.rsc') &&
+                case prerenderManifestRoute.dataRoute?.endsWith('/default.rsc') &&
                   !existsSync(join(ctx.publishDir, 'server/app', `${key}.html`)):
                   return
-                case meta.dataRoute?.endsWith('.json'):
+                case prerenderManifestRoute.dataRoute?.endsWith('.json'):
                   if (manifest.notFoundRoutes.includes(route)) {
                     // if pages router returns 'notFound: true', build won't produce html and json files
                     return
                   }
                   value = await buildPagesCacheValue(
                     join(ctx.publishDir, 'server/pages', key),
-                    meta.initialRevalidateSeconds,
+                    prerenderManifestRoute,
                     shouldUseEnumKind,
                   )
                   break
-                case meta.dataRoute?.endsWith('.rsc'):
+                case prerenderManifestRoute.dataRoute?.endsWith('.rsc'):
                   value = await buildAppCacheValue(
                     join(ctx.publishDir, 'server/app', key),
+                    prerenderManifestRoute,
                     shouldUseAppPageKind,
-                    meta.renderingMode !== 'PARTIALLY_STATIC',
+                    prerenderManifestRoute.renderingMode !== 'PARTIALLY_STATIC',
                   )
                   if (route === '/_not-found') {
                     appRouterNotFoundDefinedInPrerenderManifest = true
                   }
                   break
-                case meta.dataRoute === null:
+                case prerenderManifestRoute.dataRoute === null:
                   value = await buildRouteCacheValue(
                     join(ctx.publishDir, 'server/app', key),
-                    meta.initialRevalidateSeconds,
+                    prerenderManifestRoute,
                     shouldUseEnumKind,
                   )
                   break
@@ -268,6 +308,7 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
             const key = routeToFilePath(route)
             const value = await buildAppCacheValue(
               join(ctx.publishDir, 'server/app', key),
+              undefined,
               shouldUseAppPageKind,
               // shells always have `renderingMode === 'PARTIALLY_STATIC'`
               false,
@@ -288,6 +329,7 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
         const key = '/404'
         const value = await buildAppCacheValue(
           join(ctx.publishDir, 'server/app/_not-found'),
+          undefined,
           shouldUseAppPageKind,
         )
         await writeCacheEntry(key, value, lastModified, ctx)
@@ -310,9 +352,8 @@ export const copyFetchContent = async (ctx: PluginContext): Promise<void> => {
 
     await Promise.all(
       paths.map(async (key): Promise<void> => {
-        const lastModified = Date.now() - 31536000000
         const path = join(ctx.publishDir, 'cache/fetch-cache', key)
-        const value = await buildFetchCacheValue(path)
+        const { value, lastModified } = await buildFetchCacheValue(path)
         await writeCacheEntry(key, value, lastModified, ctx)
       }),
     )

src/run/handlers/cache.cts

@@ -315,7 +315,7 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
         span?.addEvent('Stale', { staleByTags, key, ttl })
         // note that we modify this after we capture last modified to ensure that Age is correct
         // but we still let Next.js know that entry is stale
-        blob.lastModified = -1 // indicate that the entry is stale
+        this.markCacheEntryStaleByTags(blob)
       }
 
       // Next sets a kind/kindHint and fetchUrl for data requests, however fetchUrl was found to be most reliable across versions
@@ -514,6 +514,57 @@ export class NetlifyCacheHandler implements CacheHandlerForMultipleVersions {
     // see getRequestSpecificInMemoryCache
   }
 
+  /**
+   * Mutates a cache entry that was found to be stale (but not yet expired) through
+   * on-demand revalidated tags so that Next.js serves it stale while triggering a
+   * background revalidation.
+   *
+   * We can NOT signal staleness with `lastModified = -1` for full-route cache
+   * entries anymore: since Next.js 16 that sentinel means "entry is past its
+   * `expire` → do a blocking re-render" rather than "serve stale". See the
+   * `incremental-cache` `get`: `lastModified === -1` ⇒ `isStale = -1`, and the
+   * response-cache treats `isStale === -1` as "skip the early stale resolve and
+   * block on a fresh render".
+   *
+   * Instead we drive Next.js' native staleness math, which both old and new
+   * Next.js resolve to `isStale === true` (serve stale + background revalidation):
+   *  - `revalidate: 1` + a `lastModified` 2s in the past ⇒ `revalidateAfter = now - 1000 < now` ⇒ stale
+   *  - `expire: undefined`                               ⇒ `expireAfter` undefined ⇒ never the `-1` block path
+   *
+   * `revalidate` must be `>= 1` (Next.js 16 rejects `revalidate: 0` with "Invalid
+   * revalidate configuration provided: 0 < 1") and is needed because force-static
+   * entries have `revalidate: false`, which would otherwise resolve as fresh.
+   *
+   * Actual expiry is still enforced by `checkCacheEntryStaleByTags`: once the tag's
+   * `expireAt` is reached it reports the entry as expired and `get` returns `null`
+   * (cache miss → blocking re-render), so we don't need to encode `expire` here.
+   */
+  private markCacheEntryStaleByTags(blob: NetlifyCacheHandlerValue) {
+    if (!blob.value) {
+      return
+    }
+
+    if (
+      blob.value.kind === 'ROUTE' ||
+      blob.value.kind === 'APP_ROUTE' ||
+      blob.value.kind === 'PAGE' ||
+      blob.value.kind === 'PAGES' ||
+      blob.value.kind === 'APP_PAGE' ||
+      blob.value.kind === 'REDIRECT'
+    ) {
+      blob.lastModified = Date.now() - 2 * 1000
+      blob.value.cacheControl = { revalidate: 1, expire: undefined }
+      blob.value.revalidate = 1
+      return
+    }
+
+    // FETCH (and any other) entries are classified as stale by comparing their age
+    // against the entry's `revalidate` and do not use the `lastModified === -1`
+    // sentinel as a "blocking re-render" signal, so we keep using it to force
+    // staleness regardless of the entry's `revalidate`.
+    blob.lastModified = -1
+  }
+
   /**
    * Checks if a cache entry is stale through on demand revalidated tags
    */