feat: add on demand revalidation by tags and path (#53)

* feat: add on demand revalidation by tags and path

* chore: fix tests

Author: lukasholzer

package-lock.json

@@ -9,6 +9,7 @@ import type {
   CacheHandlerContext,
   IncrementalCache,
 } from 'next/dist/server/lib/incremental-cache/index.js'
+import { NEXT_CACHE_TAGS_HEADER } from 'next/dist/lib/constants.js'
 import { join } from 'node:path/posix'
 // @ts-expect-error This is a type only import
 import type { CacheEntryValue } from '../../build/content/prerendered.js'
@@ -51,12 +52,11 @@ export default class NetlifyCacheHandler implements CacheHandler {
     }
 
     const revalidateAfter = this.calculateRevalidate(cacheKey, blob.lastModified, ctx)
-    // first check if there is a tag manifest
-    // if not => stale check with revalidateAfter
-    // yes => check with manifest
     const isStale = revalidateAfter !== false && revalidateAfter < Date.now()
-    console.debug(`!!! CHACHE KEY: ${cacheKey} - is stale: `, { isStale })
-    if (isStale) {
+    const staleByTags = await this.checkCacheEntryStaleByTags(blob, ctx.softTags)
+    console.debug(`!!! CHACHE KEY: ${cacheKey} - is stale: `, { isStale, staleByTags })
+
+    if (staleByTags || isStale) {
       return null
     }
 
@@ -116,20 +116,23 @@ export default class NetlifyCacheHandler implements CacheHandler {
     }
   }
 
-  async revalidateTag(tag: string) {
-    console.debug('NetlifyCacheHandler.revalidateTag', tag)
+  async revalidateTag(tag: string, ...args: any) {
+    console.debug('NetlifyCacheHandler.revalidateTag', tag, args)
 
     const data: TagManifest = {
       revalidatedAt: Date.now(),
     }
 
     try {
+      console.log('set cache tag for ', { tag: this.tagManifestPath(tag), data })
       await blobStore.setJSON(this.tagManifestPath(tag), data)
     } catch (error) {
       console.warn(`Failed to update tag manifest for ${tag}`, error)
     }
 
-    purgeCache({ tags: [tag] })
+    purgeCache({ tags: [tag] }).catch(() => {
+      // noop
+    })
   }
 
   // eslint-disable-next-line class-methods-use-this
@@ -192,6 +195,45 @@ export default class NetlifyCacheHandler implements CacheHandler {
     return cacheEntry || null
   }
 
+  /**
+   * Checks if a page is stale through on demand revalidated tags
+   */
+  private async checkCacheEntryStaleByTags(cacheEntry: CacheEntryValue, softTags: string[] = []) {
+    const tags =
+      'headers' in cacheEntry.value
+        ? cacheEntry.value.headers?.[NEXT_CACHE_TAGS_HEADER]?.split(',') || []
+        : []
+
+    const cacheTags = [...tags, ...softTags]
+    const allManifests = await Promise.all(
+      cacheTags.map(async (tag) => {
+        const key = this.tagManifestPath(tag)
+        const res = await blobStore
+          .get(key, { type: 'json' })
+          .then((value) => ({ [key]: value }))
+          .catch(console.error)
+        return res || { [key]: null }
+      }),
+    )
+
+    const tagsManifest = Object.assign({}, ...allManifests) as Record<
+      string,
+      null | { revalidatedAt: number }
+    >
+
+    const isStale = cacheTags.some((tag) => {
+      // TODO: test for this case
+      if (this.revalidatedTags.includes(tag)) {
+        return true
+      }
+
+      const { revalidatedAt } = tagsManifest[this.tagManifestPath(tag)] || {}
+      return revalidatedAt && revalidatedAt >= (cacheEntry.lastModified || Date.now())
+    })
+
+    return isStale
+  }
+
   /**
    * Retrieves the milliseconds since midnight, January 1, 1970 when it should revalidate for a path.
    */

src/run/handlers/cache.cts

@@ -0,0 +1,9 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { revalidatePath } from 'next/cache'
+
+export async function GET(request: NextRequest) {
+  revalidatePath('/static-fetch/[id]', 'page')
+  return NextResponse.json({ revalidated: true, now: new Date().toISOString() })
+}
+
+export const dynamic = 'force-dynamic'

tests/fixtures/server-components/app/api/on-demand-revalidate/path/route.ts

@@ -0,0 +1,9 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { revalidateTag } from 'next/cache'
+
+export async function GET(request: NextRequest) {
+  revalidateTag('collection')
+  return NextResponse.json({ revalidated: true, now: new Date().toISOString() })
+}
+
+export const dynamic = 'force-dynamic'

tests/fixtures/server-components/app/api/on-demand-revalidate/tag/route.ts

@@ -10,12 +10,12 @@ export default async function Page() {
 
   return (
     <>
-      <h1>Hello, Statically Rendered Server Component</h1>
+      <h1>Hello, Static Fetch 1</h1>
       <dl>
         <dt>Quote</dt>
         <dd>{data[0].quote}</dd>
         <dt>Time</dt>
-        <dd>{Date.now()}</dd>
+        <dd data-testid="date-now">{new Date().toISOString()}</dd>
       </dl>
     </>
   )

tests/fixtures/server-components/app/static-fetch-1/page.js

@@ -10,12 +10,12 @@ export default async function Page() {
 
   return (
     <>
-      <h1>Hello, Statically Rendered Server Component (same as static-fetch-1)</h1>
+      <h1>Hello, Static Fetch 2</h1>
       <dl>
         <dt>Quote</dt>
         <dd>{data[0].quote}</dd>
         <dt>Time</dt>
-        <dd>{Date.now()}</dd>
+        <dd data-testid="date-now">{new Date().toISOString()}</dd>
       </dl>
     </>
   )

tests/fixtures/server-components/app/static-fetch-2/page.js

@@ -0,0 +1,22 @@
+async function getData() {
+  const res = await fetch(`https://strangerthings-quotes.vercel.app/api/quotes`, {
+    next: { tags: ['collection'] },
+  })
+  return res.json()
+}
+
+export default async function Page() {
+  const data = await getData()
+
+  return (
+    <>
+      <h1>Hello, Static Fetch 3</h1>
+      <dl>
+        <dt>Quote</dt>
+        <dd>{data[0].quote}</dd>
+        <dt>Time</dt>
+        <dd data-testid="date-now">{new Date().toISOString()}</dd>
+      </dl>
+    </>
+  )
+}

tests/fixtures/server-components/app/static-fetch-3/page.js

@@ -0,0 +1,27 @@
+export async function generateStaticParams() {
+  return [{ id: '1' }, { id: '2' }]
+}
+
+async function getData(params) {
+  const res = await fetch(`https://api.tvmaze.com/shows/${params.id}`)
+  return res.json()
+}
+
+export default async function Page({ params }) {
+  const data = await getData(params)
+
+  return (
+    <>
+      <h1>Hello, Statically fetched show {data.id}</h1>
+      <p>Paths /1 and /2 prerendered; other paths not found</p>
+      <dl>
+        <dt>Show</dt>
+        <dd>{data.name}</dd>
+        <dt>Param</dt>
+        <dd>{params.id}</dd>
+        <dt>Time</dt>
+        <dd data-testid="date-now">{new Date().toISOString()}</dd>
+      </dl>
+    </>
+  )
+}

tests/fixtures/server-components/app/static-fetch/[id]/page.js

@@ -17,7 +17,9 @@ beforeEach<FixtureTestContext>(async (ctx) => {
   // set for each test a new deployID and siteID
   ctx.deployID = generateRandomObjectID()
   ctx.siteID = v4()
+  vi.stubEnv('SITE_ID', ctx.siteID)
   vi.stubEnv('DEPLOY_ID', ctx.deployID)
+  vi.stubEnv('NETLIFY_PURGE_API_TOKEN', 'fake-token')
   // hide debug logs in tests
   // vi.spyOn(console, 'debug').mockImplementation(() => {})
 
@@ -163,21 +165,19 @@ describe('plugin', () => {
     await runPlugin(ctx)
     // check if the blob entries where successful set on the build plugin
     const blobEntries = await getBlobEntries(ctx)
-    expect(blobEntries).toEqual([
-      {
-        key: 'cache/fetch-cache/460ed46cd9a194efa197be9f2571e51b729a039d1cff9834297f416dce5ada29',
-        etag: expect.any(String),
-      },
-      {
-        key: 'cache/fetch-cache/ac26c54e17c3018c17bfe5ae6adc0e6d37dbfaf28445c1f767ff267144264ac9',
-        etag: expect.any(String),
-      },
-      { key: 'server/app/_not-found', etag: expect.any(String) },
-      { key: 'server/app/api/revalidate-handler', etag: expect.any(String) },
-      { key: 'server/app/index', etag: expect.any(String) },
-      { key: 'server/app/revalidate-fetch', etag: expect.any(String) },
-      { key: 'server/app/static-fetch-1', etag: expect.any(String) },
-      { key: 'server/app/static-fetch-2', etag: expect.any(String) },
+    expect(blobEntries.map((entry) => entry.key)).toEqual([
+      'cache/fetch-cache/460ed46cd9a194efa197be9f2571e51b729a039d1cff9834297f416dce5ada29',
+      'cache/fetch-cache/ac26c54e17c3018c17bfe5ae6adc0e6d37dbfaf28445c1f767ff267144264ac9',
+      'cache/fetch-cache/ad74683e49684ff4fe3d01ba1bef627bc0e38b61fa6bd8244145fbaca87f3c49',
+      'server/app/_not-found',
+      'server/app/api/revalidate-handler',
+      'server/app/index',
+      'server/app/revalidate-fetch',
+      'server/app/static-fetch/1',
+      'server/app/static-fetch/2',
+      'server/app/static-fetch-1',
+      'server/app/static-fetch-2',
+      'server/app/static-fetch-3',
     ])
   })
 })

tests/integration/cache-handler.test.ts

@@ -24,6 +24,7 @@ beforeEach<FixtureTestContext>(async (ctx) => {
   // set for each test a new deployID and siteID
   ctx.deployID = generateRandomObjectID()
   ctx.siteID = v4()
+  vi.stubEnv('SITE_ID', ctx.siteID)
   vi.stubEnv('DEPLOY_ID', ctx.deployID)
   // hide debug logs in tests
   // vi.spyOn(console, 'debug').mockImplementation(() => {})

tests/integration/fetch-handler.test.ts

@@ -0,0 +1,90 @@
+import { load } from 'cheerio'
+import { getLogger } from 'lambda-local'
+import { v4 } from 'uuid'
+import { beforeEach, expect, test, vi } from 'vitest'
+import {
+  createFixture,
+  invokeFunction,
+  runPlugin,
+  type FixtureTestContext,
+} from '../utils/fixture.js'
+import { generateRandomObjectID, getBlobEntries, startMockBlobStore } from '../utils/helpers.js'
+
+// Disable the verbose logging of the lambda-local runtime
+getLogger().level = 'alert'
+
+beforeEach<FixtureTestContext>(async (ctx) => {
+  // set for each test a new deployID and siteID
+  ctx.deployID = generateRandomObjectID()
+  ctx.siteID = v4()
+  vi.stubEnv('SITE_ID', ctx.siteID)
+  vi.stubEnv('DEPLOY_ID', ctx.deployID)
+  vi.stubEnv('NETLIFY_PURGE_API_TOKEN', 'fake-token')
+  // hide debug logs in tests
+  // vi.spyOn(console, 'debug').mockImplementation(() => {})
+
+  await startMockBlobStore(ctx)
+})
+
+test<FixtureTestContext>('should revalidate a route by path', async (ctx) => {
+  await createFixture('server-components', ctx)
+  await runPlugin(ctx)
+
+  expect(await ctx.blobStore.get('server/app/static-fetch/1')).not.toBeNull()
+  expect(await ctx.blobStore.get('.netlfiy/cache/tags/_N_T_/static-fetch/[id]/page')).toBeNull()
+
+  // test the function call
+  const [post1, post1Route2] = await Promise.all([
+    invokeFunction(ctx, { url: '/static-fetch/1' }),
+    invokeFunction(ctx, { url: '/static-fetch/2' }),
+  ])
+  const post1Date = load(post1.body)('[data-testid="date-now"]').text()
+  expect(post1.statusCode).toBe(200)
+  expect(post1Route2.statusCode).toBe(200)
+  expect(load(post1.body)('h1').text()).toBe('Hello, Statically fetched show 1')
+  expect(post1.headers, 'a cache hit on the first invocation of a prerendered page').toEqual(
+    expect.objectContaining({
+      'x-nextjs-cache': 'HIT',
+      'netlify-cdn-cache-control': 's-maxage=31536000, stale-while-revalidate',
+    }),
+  )
+  expect(post1Route2.headers, 'a cache hit on the first invocation of a prerendered page').toEqual(
+    expect.objectContaining({
+      'x-nextjs-cache': 'HIT',
+      'netlify-cdn-cache-control': 's-maxage=31536000, stale-while-revalidate',
+    }),
+  )
+
+  const revalidate = await invokeFunction(ctx, { url: '/api/on-demand-revalidate/path' })
+  expect(revalidate.statusCode).toBe(200)
+  expect(JSON.parse(revalidate.body)).toEqual({ revalidated: true, now: expect.any(String) })
+  // expect(calledPurge).toBe(1)
+  // it does not wait for the cache.set so we have to manually wait here until the blob storage got populated
+  await new Promise<void>((resolve) => setTimeout(resolve, 1000))
+
+  const entries = await getBlobEntries(ctx)
+  expect(await ctx.blobStore.get('.netlfiy/cache/tags/_N_T_/static-fetch/[id]/page')).not.toBeNull()
+
+  console.log(entries)
+  const [post2, post2Route2] = await Promise.all([
+    invokeFunction(ctx, { url: '/static-fetch/1' }),
+    invokeFunction(ctx, { url: '/static-fetch/2' }),
+  ])
+  const post2Date = load(post2.body)('[data-testid="date-now"]').text()
+  expect(post2.statusCode).toBe(200)
+  expect(post2Route2.statusCode).toBe(200)
+  expect(load(post2.body)('h1').text()).toBe('Hello, Statically fetched show 1')
+  expect(post2.headers, 'a cache miss on the on demand revalidated path /1').toEqual(
+    expect.objectContaining({
+      'x-nextjs-cache': 'MISS',
+      'netlify-cdn-cache-control': 's-maxage=31536000, stale-while-revalidate',
+    }),
+  )
+  expect(post2Route2.headers, 'a cache miss on the on demand revalidated path /2').toEqual(
+    expect.objectContaining({
+      'x-nextjs-cache': 'MISS',
+      'netlify-cdn-cache-control': 's-maxage=31536000, stale-while-revalidate',
+    }),
+  )
+  expect(post2Date).not.toBe(post1Date)
+})