feat: refresh hooks api implementation (#1950)

* feat: subclass NextServer to override request handler

* feat: add revalidate API route

* feat: subclass NextServer to override request handler

* feat: add revalidate API route

* feat: add refresh hooks api implementation

* chore: increase revalidate ttl for testing

* chore: add time to page for testing

* feat: add error reporting for caught exceptions

* fix: use req.url verbatim

* chore: test throw in revalidate handler

* chore: fix lint issue

* fix: update revalidate error handling

* fix: error handling in revalidate api function

* chore: refactor revalidate handling for easier testing

* test: add tests for refresh hooks

* test: add e2e test for refresh hooks revalidate

* feat: revalidate data routes

* fix: export named NetlifyNextServer for module interop

* fix: revalidate error messaging in demo

* fix: remove revalidate data routes for milestone 1

* fix: amend test for revalidate success/failure

* feat: add additional paths for routes

* chore: refactor tests

* chore: add tests for handlerUtils

* chore: remove eslint directive

* test: remove rsc trailing slash

* Revert "test: remove rsc trailing slash"

This reverts commit 6b4a2ce.

* feat: source and transform data routes from prerenderManifest

* feat: update revalidate page with more test scenarios

* fix: revalidate api endpoint path order

* chore: update revalidate test paths

* fix: cache and normalize manifest routes

* chore: update tests for caching and localizing routes

* chore: fix eslint complaint

* chore: update cypress tests

* fix: consolidated static route matching for revalidate with i18n

* chore: improve comments on revalidate api route

* chore: update snapshots and cypress tests

* chore: reset with-revalidate TTL after testing

* chore: add comment about paths to revalidate endpoint

* chore: update cypress test to match old ttl for revalidate api

* chore: move tests to resolve edge clash

* chore: add comments to functions generation

Author: orinokai

cypress/integration/default/revalidate.spec.ts

@@ -0,0 +1,69 @@
+describe('On-demand revalidation', () => {
+  it('revalidates static ISR route with default locale', () => {
+    cy.request({ url: '/api/revalidate/?select=0' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('revalidates static ISR route with non-default locale', () => {
+    cy.request({ url: '/api/revalidate/?select=1' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('revalidates root static ISR route with default locale', () => {
+    cy.request({ url: '/api/revalidate/?select=2' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('revalidates root static ISR route with non-default locale', () => {
+    cy.request({ url: '/api/revalidate/?select=3' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('revalidates dynamic prerendered ISR route with default locale', () => {
+    cy.request({ url: '/api/revalidate/?select=4' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('fails to revalidate dynamic non-prerendered ISR route with fallback false', () => {
+    cy.request({ url: '/api/revalidate/?select=5', failOnStatusCode: false }).then((res) => {
+      expect(res.status).to.eq(500)
+      expect(res.body).to.have.property('message')
+      expect(res.body.message).to.include('Invalid response 404')
+    })
+  })
+  it('revalidates dynamic non-prerendered ISR route with fallback blocking', () => {
+    cy.request({ url: '/api/revalidate/?select=6' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('revalidates dynamic non-prerendered ISR route with fallback blocking and non-default locale', () => {
+    cy.request({ url: '/api/revalidate/?select=7' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('revalidates dynamic prerendered appDir route', () => {
+    cy.request({ url: '/api/revalidate/?select=8' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('fails to revalidate dynamic non-prerendered appDir route', () => {
+    cy.request({ url: '/api/revalidate/?select=9' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+  it('revalidates dynamic prerendered appDir route with catch-all params', () => {
+    cy.request({ url: '/api/revalidate/?select=10' }).then((res) => {
+      expect(res.status).to.eq(200)
+      expect(res.body).to.have.property('message', 'success')
+    })
+  })
+})

demos/default/pages/api/revalidate.js

@@ -0,0 +1,26 @@
+export default async function handler(req, res) {
+  const query = req.query
+  const select = Number(query.select) || 0
+
+  // these paths are used for e2e testing res.revalidate()
+  const paths = [
+    '/getStaticProps/with-revalidate/', // valid path
+    '/fr/getStaticProps/with-revalidate/', // valid path (with locale)
+    '/', // valid path (index)
+    '/fr/', // valid path (index with locale)
+    '/getStaticProps/withRevalidate/2/', // valid path (with dynamic route)
+    '/getStaticProps/withRevalidate/3/', // invalid path (fallback false with dynamic route)
+    '/getStaticProps/withRevalidate/withFallbackBlocking/3/', // valid path (fallback blocking with dynamic route)
+    '/fr/getStaticProps/withRevalidate/withFallbackBlocking/3/', // valid path (fallback blocking with dynamic route and locale)
+    '/blog/nick/', // valid path (with prerendered appDir dynamic route)
+    '/blog/greg/', // invalid path (with non-prerendered appDir dynamic route)
+    '/blog/rob/hello/', // valid path (with appDir dynamic route catch-all)
+  ]
+
+  try {
+    await res.revalidate(paths[select])
+    return res.json({ code: 200, message: 'success' })
+  } catch (err) {
+    return res.status(500).send({ code: 500, message: err.message })
+  }
+}

demos/default/pages/getStaticProps/with-revalidate.js

@@ -1,8 +1,8 @@
 import Link from 'next/link'
 
-const Show = ({ show }) => (
+const Show = ({ show, time }) => (
   <div>
-    <p>This page uses getStaticProps() to pre-fetch a TV show.</p>
+    <p>This page uses getStaticProps() to pre-fetch a TV show at {time}</p>
 
     <hr />
 
@@ -22,6 +22,7 @@ export async function getStaticProps(context) {
   return {
     props: {
       show: data,
+      time: new Date().toISOString(),
     },
     // ODB handler will use the minimum TTL=60s
     revalidate: 1,

packages/runtime/src/helpers/functions.ts

@@ -45,8 +45,16 @@ export const generateFunctions = async (
     })
     const functionName = getFunctionNameForPage(route, config.type === ApiRouteType.BACKGROUND)
     await ensureDir(join(functionsDir, functionName))
+
+    // write main API handler file
     await writeFile(join(functionsDir, functionName, `${functionName}.js`), apiHandlerSource)
+
+    // copy handler dependencies (VercelNodeBridge, NetlifyNextServer, etc.)
     await copyFile(bridgeFile, join(functionsDir, functionName, 'bridge.js'))
+    await copyFile(
+      join(__dirname, '..', '..', 'lib', 'templates', 'server.js'),
+      join(functionsDir, functionName, 'server.js'),
+    )
     await copyFile(
       join(__dirname, '..', '..', 'lib', 'templates', 'handlerUtils.js'),
       join(functionsDir, functionName, 'handlerUtils.js'),
@@ -65,8 +73,16 @@ export const generateFunctions = async (
   const writeHandler = async (functionName: string, isODB: boolean) => {
     const handlerSource = await getHandler({ isODB, publishDir, appDir: relative(functionDir, appDir) })
     await ensureDir(join(functionsDir, functionName))
+
+    // write main handler file (standard or ODB)
     await writeFile(join(functionsDir, functionName, `${functionName}.js`), handlerSource)
+
+    // copy handler dependencies (VercelNodeBridge, NetlifyNextServer, etc.)
     await copyFile(bridgeFile, join(functionsDir, functionName, 'bridge.js'))
+    await copyFile(
+      join(__dirname, '..', '..', 'lib', 'templates', 'server.js'),
+      join(functionsDir, functionName, 'server.js'),
+    )
     await copyFile(
       join(__dirname, '..', '..', 'lib', 'templates', 'handlerUtils.js'),
       join(functionsDir, functionName, 'handlerUtils.js'),

packages/runtime/src/templates/getHandler.ts

@@ -5,10 +5,7 @@ import { outdent as javascript } from 'outdent'
 
 import type { NextConfig } from '../helpers/config'
 
-import type { NextServerType } from './handlerUtils'
-
 /* eslint-disable @typescript-eslint/no-var-requires */
-
 const { promises } = require('fs')
 const { Server } = require('http')
 const path = require('path')
@@ -22,17 +19,17 @@ const {
   getMaxAge,
   getMultiValueHeaders,
   getPrefetchResponse,
-  getNextServer,
   normalizePath,
 } = require('./handlerUtils')
+const { NetlifyNextServer } = require('./server')
 /* eslint-enable @typescript-eslint/no-var-requires */
 
 type Mutable<T> = {
   -readonly [K in keyof T]: T[K]
 }
 
 // We return a function and then call `toString()` on it to serialise it as the launcher function
-// eslint-disable-next-line max-params
+// eslint-disable-next-line max-params, max-lines-per-function
 const makeHandler = (conf: NextConfig, app, pageRoot, staticManifest: Array<[string, string]> = [], mode = 'ssr') => {
   // Change working directory into the site root, unless using Nx, which moves the
   // dist directory and handles this itself
@@ -68,22 +65,30 @@ const makeHandler = (conf: NextConfig, app, pageRoot, staticManifest: Array<[str
   // We memoize this because it can be shared between requests, but don't instantiate it until
   // the first request because we need the host and port.
   let bridge: NodeBridge
-  const getBridge = (event: HandlerEvent): NodeBridge => {
+  const getBridge = (event: HandlerEvent, context: HandlerContext): NodeBridge => {
+    const {
+      clientContext: { custom: customContext },
+    } = context
+
     if (bridge) {
       return bridge
     }
     const url = new URL(event.rawUrl)
     const port = Number.parseInt(url.port) || 80
     base = url.origin
 
-    const NextServer: NextServerType = getNextServer()
-    const nextServer = new NextServer({
-      conf,
-      dir,
-      customServer: false,
-      hostname: url.hostname,
-      port,
-    })
+    const nextServer = new NetlifyNextServer(
+      {
+        conf,
+        dir,
+        customServer: false,
+        hostname: url.hostname,
+        port,
+      },
+      {
+        revalidateToken: customContext.odb_refresh_hooks,
+      },
+    )
     const requestHandler = nextServer.getRequestHandler()
     const server = new Server(async (req, res) => {
       try {
@@ -119,7 +124,7 @@ const makeHandler = (conf: NextConfig, app, pageRoot, staticManifest: Array<[str
       process.env._NETLIFY_GRAPH_TOKEN = graphToken
     }
 
-    const { headers, ...result } = await getBridge(event).launcher(event, context)
+    const { headers, ...result } = await getBridge(event, context).launcher(event, context)
 
     // Convert all headers to multiValueHeaders
 
@@ -180,6 +185,7 @@ export const getHandler = ({ isODB = false, publishDir = '../../../.next', appDi
   // We copy the file here rather than requiring from the node module
   const { Bridge } = require("./bridge");
   const { augmentFsModule, getMaxAge, getMultiValueHeaders, getPrefetchResponse, getNextServer, normalizePath } = require('./handlerUtils')
+  const { NetlifyNextServer } = require('./server')
 
   ${isODB ? `const { builder } = require("@netlify/functions")` : ''}
   const { config }  = require("${publishDir}/required-server-files.json")

packages/runtime/src/templates/handlerUtils.ts

@@ -1,4 +1,5 @@
 import fs, { createWriteStream, existsSync } from 'fs'
+import { ServerResponse } from 'http'
 import { tmpdir } from 'os'
 import path from 'path'
 import { pipeline } from 'stream'
@@ -222,3 +223,71 @@ export const normalizePath = (event: HandlerEvent) => {
   // Ensure that paths are encoded - but don't double-encode them
   return new URL(event.rawUrl).pathname
 }
+
+// Simple Netlify API client
+export const netlifyApiFetch = <T>({
+  endpoint,
+  payload,
+  token,
+  method = 'GET',
+}: {
+  endpoint: string
+  payload: unknown
+  token: string
+  method: 'GET' | 'POST'
+}): Promise<T> =>
+  new Promise((resolve, reject) => {
+    const body = JSON.stringify(payload)
+
+    const req = https.request(
+      {
+        hostname: 'api.netlify.com',
+        port: 443,
+        path: `/api/v1/${endpoint}`,
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': body.length,
+          Authorization: `Bearer ${token}`,
+        },
+      },
+      (res: ServerResponse) => {
+        let data = ''
+        res.on('data', (chunk) => {
+          data += chunk
+        })
+        res.on('end', () => {
+          resolve(JSON.parse(data))
+        })
+      },
+    )
+
+    req.on('error', reject)
+
+    req.write(body)
+    req.end()
+  })
+
+// Remove trailing slash from a route (except for the root route)
+export const normalizeRoute = (route: string): string => (route.endsWith('/') ? route.slice(0, -1) || '/' : route)
+
+// Check if a route has a locale prefix (including the root route)
+const isLocalized = (route: string, i18n: { defaultLocale: string; locales: string[] }): boolean =>
+  i18n.locales.some((locale) => route === `/${locale}` || route.startsWith(`/${locale}/`))
+
+// Remove the locale prefix from a route (if any)
+export const unlocalizeRoute = (route: string, i18n: { defaultLocale: string; locales: string[] }): string =>
+  isLocalized(route, i18n) ? `/${route.split('/').slice(2).join('/')}` : route
+
+// Add the default locale prefix to a route (if necessary)
+export const localizeRoute = (route: string, i18n: { defaultLocale: string; locales: string[] }): string =>
+  isLocalized(route, i18n) ? route : normalizeRoute(`/${i18n.defaultLocale}${route}`)
+
+// Normalize a data route to include the locale prefix and remove the index suffix
+export const localizeDataRoute = (dataRoute: string, localizedRoute: string): string => {
+  if (dataRoute.endsWith('.rsc')) return dataRoute
+  const locale = localizedRoute.split('/').find(Boolean)
+  return dataRoute
+    .replace(new RegExp(`/_next/data/(.+?)/(${locale}/)?`), `/_next/data/$1/${locale}/`)
+    .replace(/\/index\.json$/, '.json')
+}