feat: add cdn-cache-control headers to cacheable route handler responses (#399)

* test: add test cases for cacheable route handlers

* refactor: add cache related types modules and adjust ROUTE variant to match our current usage

* feat: add cdn-cache-control headers to cacheable route handler responses

* fix: set revalidate setting on request context for Route responses and set cdn-cache-control header based on that

* chore: format with prettier

* chore: pass just revalidate time not entire meta

---------

Co-authored-by: pieh <pieh@users.noreply.github.com>

Author: pieh

src/build/content/prerendered.ts

@@ -5,33 +5,34 @@ import { join } from 'node:path'
 import { trace } from '@opentelemetry/api'
 import { wrapTracer } from '@opentelemetry/api/experimental'
 import { glob } from 'fast-glob'
-import type { CacheHandlerValue } from 'next/dist/server/lib/incremental-cache/index.js'
-import type { IncrementalCacheValue } from 'next/dist/server/response-cache/types.js'
 import pLimit from 'p-limit'
 
 import { encodeBlobKey } from '../../shared/blobkey.js'
+import type {
+  CachedFetchValue,
+  CachedPageValue,
+  NetlifyCacheHandlerValue,
+  NetlifyCachedRouteValue,
+  NetlifyIncrementalCacheValue,
+} from '../../shared/cache-types.cjs'
 import type { PluginContext } from '../plugin-context.js'
 
-type CachedPageValue = Extract<IncrementalCacheValue, { kind: 'PAGE' }>
-type CachedRouteValue = Extract<IncrementalCacheValue, { kind: 'ROUTE' }>
-type CachedFetchValue = Extract<IncrementalCacheValue, { kind: 'FETCH' }>
-
 const tracer = wrapTracer(trace.getTracer('Next runtime'))
 
 /**
  * Write a cache entry to the blob upload directory.
  */
 const writeCacheEntry = async (
   route: string,
-  value: IncrementalCacheValue,
+  value: NetlifyIncrementalCacheValue,
   lastModified: number,
   ctx: PluginContext,
 ): Promise<void> => {
   const path = join(ctx.blobDir, await encodeBlobKey(route))
   const entry = JSON.stringify({
     lastModified,
     value,
-  } satisfies CacheHandlerValue)
+  } satisfies NetlifyCacheHandlerValue)
 
   await writeFile(path, entry, 'utf-8')
 }
@@ -68,10 +69,14 @@ const buildAppCacheValue = async (path: string): Promise<CachedPageValue> => {
   }
 }
 
-const buildRouteCacheValue = async (path: string): Promise<CachedRouteValue> => ({
+const buildRouteCacheValue = async (
+  path: string,
+  initialRevalidateSeconds: number | false,
+): Promise<NetlifyCachedRouteValue> => ({
   kind: 'ROUTE',
   body: await readFile(`${path}.body`, 'base64'),
   ...JSON.parse(await readFile(`${path}.meta`, 'utf-8')),
+  revalidate: initialRevalidateSeconds,
 })
 
 const buildFetchCacheValue = async (path: string): Promise<CachedFetchValue> => ({
@@ -100,7 +105,7 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
                 ? Date.now() - 31536000000
                 : Date.now()
               const key = routeToFilePath(route)
-              let value: IncrementalCacheValue
+              let value: NetlifyIncrementalCacheValue
               switch (true) {
                 // Parallel route default layout has no prerendered page
                 case meta.dataRoute?.endsWith('/default.rsc') &&
@@ -117,7 +122,10 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
                   value = await buildAppCacheValue(join(ctx.publishDir, 'server/app', key))
                   break
                 case meta.dataRoute === null:
-                  value = await buildRouteCacheValue(join(ctx.publishDir, 'server/app', key))
+                  value = await buildRouteCacheValue(
+                    join(ctx.publishDir, 'server/app', key),
+                    meta.initialRevalidateSeconds,
+                  )
                   break
                 default:
                   throw new Error(`Unrecognized content: ${route}`)

src/run/handlers/cache.cts

@@ -7,12 +7,15 @@ import { getDeployStore, Store } from '@netlify/blobs'
 import { purgeCache } from '@netlify/functions'
 import { type Span } from '@opentelemetry/api'
 import { NEXT_CACHE_TAGS_HEADER } from 'next/dist/lib/constants.js'
+
 import type {
   CacheHandler,
   CacheHandlerContext,
-  CacheHandlerValue,
   IncrementalCache,
-} from 'next/dist/server/lib/incremental-cache/index.js'
+  NetlifyCachedRouteValue,
+  NetlifyCacheHandlerValue,
+  NetlifyIncrementalCacheValue,
+} from '../../shared/cache-types.cjs'
 
 import { getRequestContext } from './request-context.cjs'
 import { getTracer } from './tracer.cjs'
@@ -43,7 +46,7 @@ export class NetlifyCacheHandler implements CacheHandler {
   }
 
   private captureResponseCacheLastModified(
-    cacheValue: CacheHandlerValue,
+    cacheValue: NetlifyCacheHandlerValue,
     key: string,
     getCacheKeySpan: Span,
   ) {
@@ -90,6 +93,19 @@ export class NetlifyCacheHandler implements CacheHandler {
     }
   }
 
+  private captureRouteRevalidateAndRemoveFromObject(
+    cacheValue: NetlifyCachedRouteValue,
+  ): Omit<NetlifyCachedRouteValue, 'revalidate'> {
+    const { revalidate, ...restOfRouteValue } = cacheValue
+
+    const requestContext = getRequestContext()
+    if (requestContext) {
+      requestContext.routeHandlerRevalidate = revalidate
+    }
+
+    return restOfRouteValue
+  }
+
   async get(...args: Parameters<CacheHandler['get']>): ReturnType<CacheHandler['get']> {
     return this.tracer.withActiveSpan('get cache key', async (span) => {
       const [key, ctx = {}] = args
@@ -103,7 +119,7 @@ export class NetlifyCacheHandler implements CacheHandler {
         return await this.blobStore.get(blobKey, {
           type: 'json',
         })
-      })) as CacheHandlerValue | null
+      })) as NetlifyCacheHandlerValue | null
 
       // if blob is null then we don't have a cache entry
       if (!blob) {
@@ -128,15 +144,19 @@ export class NetlifyCacheHandler implements CacheHandler {
             value: blob.value,
           }
 
-        case 'ROUTE':
+        case 'ROUTE': {
           span.addEvent('ROUTE', { lastModified: blob.lastModified, status: blob.value.status })
+
+          const valueWithoutRevalidate = this.captureRouteRevalidateAndRemoveFromObject(blob.value)
+
           return {
             lastModified: blob.lastModified,
             value: {
-              ...blob.value,
-              body: Buffer.from(blob.value.body as unknown as string, 'base64'),
+              ...valueWithoutRevalidate,
+              body: Buffer.from(valueWithoutRevalidate.body as unknown as string, 'base64'),
             },
           }
+        }
         case 'PAGE':
           span.addEvent('PAGE', { lastModified: blob.lastModified })
           return {
@@ -152,23 +172,22 @@ export class NetlifyCacheHandler implements CacheHandler {
 
   async set(...args: Parameters<IncrementalCache['set']>) {
     return this.tracer.withActiveSpan('set cache key', async (span) => {
-      const [key, data] = args
+      const [key, data, context] = args
       const blobKey = await this.encodeBlobKey(key)
       const lastModified = Date.now()
       span.setAttributes({ key, lastModified, blobKey })
 
       console.debug(`[NetlifyCacheHandler.set]: ${key}`)
 
-      let value = data
-
-      if (data?.kind === 'ROUTE') {
-        // don't mutate data, as it's used for the initial response - instead create a new object
-        value = {
-          ...data,
-          // @ts-expect-error gotta find a better solution for this
-          body: data.body.toString('base64'),
-        }
-      }
+      const value: NetlifyIncrementalCacheValue | null =
+        data?.kind === 'ROUTE'
+          ? // don't mutate data, as it's used for the initial response - instead create a new object
+            {
+              ...data,
+              revalidate: context.revalidate,
+              body: data.body.toString('base64'),
+            }
+          : data
 
       await this.blobStore.setJSON(blobKey, {
         lastModified,
@@ -217,7 +236,7 @@ export class NetlifyCacheHandler implements CacheHandler {
    * Checks if a cache entry is stale through on demand revalidated tags
    */
   private async checkCacheEntryStaleByTags(
-    cacheEntry: CacheHandlerValue,
+    cacheEntry: NetlifyCacheHandlerValue,
     tags: string[] = [],
     softTags: string[] = [],
   ) {

src/run/handlers/request-context.cts

@@ -1,12 +1,15 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 
+import type { NetlifyCachedRouteValue } from '../../shared/cache-types.cjs'
+
 export type RequestContext = {
   debug: boolean
   responseCacheGetLastModified?: number
   responseCacheKey?: string
   usedFsRead?: boolean
   didPagesRouterOnDemandRevalidate?: boolean
   serverTiming?: string
+  routeHandlerRevalidate?: NetlifyCachedRouteValue['revalidate']
 }
 
 type RequestContextAsyncLocalStorage = AsyncLocalStorage<RequestContext>

src/run/headers.ts

@@ -179,13 +179,30 @@ export const setCacheControlHeaders = (
   request: Request,
   requestContext: RequestContext,
 ) => {
+  if (
+    typeof requestContext.routeHandlerRevalidate !== 'undefined' &&
+    ['GET', 'HEAD'].includes(request.method) &&
+    !headers.has('netlify-cdn-cache-control')
+  ) {
+    // handle CDN Cache Control on Route Handler responses
+    const cdnCacheControl =
+      // if we are serving already stale response, instruct edge to not attempt to cache that response
+      headers.get('x-nextjs-cache') === 'STALE'
+        ? 'public, max-age=0, must-revalidate'
+        : `s-maxage=${requestContext.routeHandlerRevalidate === false ? 31536000 : requestContext.routeHandlerRevalidate}, stale-while-revalidate=31536000`
+
+    headers.set('netlify-cdn-cache-control', cdnCacheControl)
+    return
+  }
+
   const cacheControl = headers.get('cache-control')
   if (
     cacheControl !== null &&
     ['GET', 'HEAD'].includes(request.method) &&
     !headers.has('cdn-cache-control') &&
     !headers.has('netlify-cdn-cache-control')
   ) {
+    // handle CDN Cache Control on ISR and App Router page responses
     const browserCacheControl = omitHeaderValues(cacheControl, [
       's-maxage',
       'stale-while-revalidate',
@@ -200,6 +217,7 @@ export const setCacheControlHeaders = (
 
     headers.set('cache-control', browserCacheControl || 'public, max-age=0, must-revalidate')
     headers.set('netlify-cdn-cache-control', cdnCacheControl)
+    return
   }
 
   if (
@@ -208,6 +226,7 @@ export const setCacheControlHeaders = (
     !headers.has('netlify-cdn-cache-control') &&
     requestContext.usedFsRead
   ) {
+    // handle CDN Cache Control on static files
     headers.set('cache-control', 'public, max-age=0, must-revalidate')
     headers.set('netlify-cdn-cache-control', `max-age=31536000`)
   }

src/shared/cache-types.cts

@@ -0,0 +1,34 @@
+import type {
+  CacheHandlerValue,
+  IncrementalCache,
+} from 'next/dist/server/lib/incremental-cache/index.js'
+import type {
+  IncrementalCacheValue,
+  CachedRouteValue,
+} from 'next/dist/server/response-cache/types.js'
+
+export type {
+  CacheHandler,
+  CacheHandlerContext,
+  IncrementalCache,
+} from 'next/dist/server/lib/incremental-cache/index.js'
+
+export type NetlifyCachedRouteValue = Omit<CachedRouteValue, 'body'> & {
+  // Next.js stores body as buffer, while we store it as base64 encoded string
+  body: string
+  // Next.js doesn't produce cache-control tag we use to generate cdn cache control
+  // so store needed values as part of cached response data
+  revalidate: Parameters<IncrementalCache['set']>[2]['revalidate']
+}
+
+export type CachedPageValue = Extract<IncrementalCacheValue, { kind: 'PAGE' }>
+export type CachedFetchValue = Extract<IncrementalCacheValue, { kind: 'FETCH' }>
+
+export type NetlifyIncrementalCacheValue =
+  | Exclude<IncrementalCacheValue, CachedRouteValue>
+  | NetlifyCachedRouteValue
+
+type CachedRouteValueToNetlify<T> = T extends CachedRouteValue ? NetlifyCachedRouteValue : T
+type MapCachedRouteValueToNetlify<T> = { [K in keyof T]: CachedRouteValueToNetlify<T[K]> }
+
+export type NetlifyCacheHandlerValue = MapCachedRouteValueToNetlify<CacheHandlerValue>

tests/fixtures/simple-next-app/app/api/cached-permanent/route.js

@@ -0,0 +1,11 @@
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  return NextResponse.json({
+    message:
+      'Route handler not using request and using force-static dynamic strategy with permanent caching',
+  })
+}
+export const revalidate = false
+
+export const dynamic = 'force-static'

tests/fixtures/simple-next-app/app/api/cached-revalidate/route.js

@@ -0,0 +1,11 @@
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  return NextResponse.json({
+    message:
+      'Route handler not using request and using force-static dynamic strategy with 15 seconds revalidate',
+  })
+}
+export const revalidate = 15
+
+export const dynamic = 'force-static'

tests/integration/simple-app.test.ts

@@ -57,6 +57,8 @@ test<FixtureTestContext>('Test that the simple next app is working', async (ctx)
   const blobEntries = await getBlobEntries(ctx)
   expect(blobEntries.map(({ key }) => decodeBlobKey(key)).sort()).toEqual([
     '/404',
+    '/api/cached-permanent',
+    '/api/cached-revalidate',
     '/image/local',
     '/image/migration-from-v4-runtime',
     '/image/remote-domain',
@@ -170,6 +172,35 @@ test<FixtureTestContext>('handlers can add cookies in route handlers with the co
   expect(setCookieHeader).toContain('test2=value2; Path=/handler; HttpOnly')
 })
 
+test<FixtureTestContext>('cacheable route handler is cached on cdn (revalidate=false / permanent caching)', async (ctx) => {
+  await createFixture('simple-next-app', ctx)
+  await runPlugin(ctx)
+
+  const permanentlyCachedResponse = await invokeFunction(ctx, { url: '/api/cached-permanent' })
+  expect(permanentlyCachedResponse.headers['netlify-cdn-cache-control']).toBe(
+    's-maxage=31536000, stale-while-revalidate=31536000',
+  )
+})
+
+test<FixtureTestContext>('cacheable route handler is cached on cdn (revalidate=15)', async (ctx) => {
+  await createFixture('simple-next-app', ctx)
+  await runPlugin(ctx)
+
+  const firstTimeCachedResponse = await invokeFunction(ctx, { url: '/api/cached-revalidate' })
+  // this will be "stale" response from build
+  expect(firstTimeCachedResponse.headers['netlify-cdn-cache-control']).toBe(
+    'public, max-age=0, must-revalidate',
+  )
+
+  // allow server to regenerate fresh response in background
+  await new Promise((res) => setTimeout(res, 1_000))
+
+  const secondTimeCachedResponse = await invokeFunction(ctx, { url: '/api/cached-revalidate' })
+  expect(secondTimeCachedResponse.headers['netlify-cdn-cache-control']).toBe(
+    's-maxage=15, stale-while-revalidate=31536000',
+  )
+})
+
 // there's a bug where requests accept-encoding header
 // result in corrupted bodies
 // while that bug stands, we want to ignore accept-encoding