Add response handling in app route handler

Author: ijjk

packages/next/errors.json

@@ -699,5 +699,10 @@
   "698": "Next DevTools: Can't dispatch %s in this environment. This is a bug in Next.js",
   "699": "Next DevTools: App Dev Overlay is already mounted. This is a bug in Next.js",
   "700": "Next DevTools: Pages Dev Overlay is already mounted. This is a bug in Next.js",
-  "701": "Failed to persist Chrome DevTools workspace UUID. The Chrome DevTools Workspace needs to be reconnected after the next page reload."
+  "701": "Invariant: app-route received invalid cache entry %s",
+  "702": "Invariant: unexpected APP_ROUTE cache data",
+  "703": "Route is configured with dynamic = error which cannot be statically generated.",
+  "704": "Route is configured with dynamic = error be statically generated.",
+  "705": "Route is configured with dynamic = error that cannot be statically generated.",
+  "706": "Failed to persist Chrome DevTools workspace UUID. The Chrome DevTools Workspace needs to be reconnected after the next page reload."
 }

packages/next/src/build/templates/app-route.ts

@@ -8,7 +8,6 @@ import { patchFetch as _patchFetch } from '../../server/lib/patch-fetch'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { getRequestMeta } from '../../server/request-meta'
 import { getTracer, type Span, SpanKind } from '../../server/lib/trace/tracer'
-import type { ServerOnInstrumentationRequestError } from '../../server/app-render/types'
 import { normalizeAppPath } from '../../shared/lib/router/utils/app-paths'
 import { NodeNextRequest, NodeNextResponse } from '../../server/base-http/node'
 import {
@@ -18,11 +17,17 @@ import {
 import { BaseServerSpan } from '../../server/lib/trace/constants'
 import { getRevalidateReason } from '../../server/instrumentation/utils'
 import { sendResponse } from '../../server/send-response'
-import { toNodeOutgoingHttpHeaders } from '../../server/web/utils'
+import {
+  fromNodeOutgoingHttpHeaders,
+  toNodeOutgoingHttpHeaders,
+} from '../../server/web/utils'
+import { decodePathParams } from '../../server/lib/router-utils/decode-path-params'
+import { getCacheControlHeader } from '../../server/lib/cache-control'
 import { INFINITE_CACHE, NEXT_CACHE_TAGS_HEADER } from '../../lib/constants'
 import {
   CachedRouteKind,
   type ResponseCacheEntry,
+  type ResponseGenerator,
 } from '../../server/response-cache'
 
 import * as userland from 'VAR_USERLAND'
@@ -107,46 +112,43 @@ export async function handler(
   const {
     buildId,
     params,
-    parsedUrl,
     nextConfig,
+    parsedUrl,
     prerenderManifest,
     routerServerContext,
     isOnDemandRevalidate,
+    revalidateOnlyGenerated,
   } = prepareResult
 
-  const onInstrumentationRequestError =
-    routeModule.instrumentationOnRequestError.bind(routeModule)
+  const normalizedSrcPage = normalizeAppPath(srcPage)
 
-  const onError: ServerOnInstrumentationRequestError = (
-    err,
-    _,
-    errorContext
-  ) => {
-    if (routerServerContext?.logErrorWithOriginalStack) {
-      routerServerContext.logErrorWithOriginalStack(err, 'app-dir')
-    } else {
-      console.error(err)
-    }
-    return onInstrumentationRequestError(
-      req,
-      err,
-      {
-        path: req.url || '/',
-        headers: req.headers,
-        method: req.method || 'GET',
-      },
-      errorContext
-    )
+  // TODO: rework this to not be necessary as a middleware
+  // rewrite should not need to pass this context like this
+  // maybe we rely on rewrite header instead
+  let resolvedPathname = getRequestMeta(req, 'rewroteURL')
+
+  if (!resolvedPathname) {
+    resolvedPathname = parsedUrl.pathname || '/'
   }
 
-  const pathname = parsedUrl.pathname || '/'
-  const normalizedSrcPage = normalizeAppPath(srcPage)
+  if (resolvedPathname === '/index') {
+    resolvedPathname = '/'
+  }
+  resolvedPathname = decodePathParams(resolvedPathname)
+
   let isIsr = Boolean(
     prerenderManifest.dynamicRoutes[normalizedSrcPage] ||
-      prerenderManifest.routes[normalizedSrcPage] ||
-      prerenderManifest.routes[pathname]
+      prerenderManifest.routes[resolvedPathname]
   )
 
+  let cacheKey: string | null = null
+
+  if (isIsr && !routeModule.isDev) {
+    cacheKey = resolvedPathname
+    // ensure /index and / is normalized to one key
+    cacheKey = cacheKey === '/index' ? '/' : cacheKey
+  }
+
   const supportsDynamicResponse: boolean =
     // If we're in development, we always support dynamic HTML
     routeModule.isDev === true ||
@@ -181,7 +183,13 @@ export async function handler(
         res.on('close', cb)
       },
       onAfterTaskError: undefined,
-      onInstrumentationRequestError: onError,
+      onInstrumentationRequestError: (error, _request, errorContext) =>
+        routeModule.onRequestError(
+          req,
+          error,
+          errorContext,
+          routerServerContext
+        ),
     },
     sharedContext: {
       buildId,
@@ -238,14 +246,186 @@ export async function handler(
       })
     }
 
-    let response: Response
+    const handleResponse = async (currentSpan?: Span) => {
+      const responseGenerator: ResponseGenerator = async ({
+        previousCacheEntry,
+      }) => {
+        try {
+          if (
+            !getRequestMeta(req, 'minimalMode') &&
+            isOnDemandRevalidate &&
+            revalidateOnlyGenerated &&
+            !previousCacheEntry
+          ) {
+            res.statusCode = 404
+            // on-demand revalidate always sets this header
+            res.setHeader('x-nextjs-cache', 'REVALIDATED')
+            res.end('This page could not be found')
+            return null
+          }
+
+          const response = await invokeRouteModule(currentSpan)
+
+          ;(req as any).fetchMetrics = (context.renderOpts as any).fetchMetrics
+          let pendingWaitUntil = context.renderOpts.pendingWaitUntil
+
+          // Attempt using provided waitUntil if available
+          // if it's not we fallback to sendResponse's handling
+          if (pendingWaitUntil) {
+            if (context.renderOpts.waitUntil) {
+              context.renderOpts.waitUntil(pendingWaitUntil)
+              pendingWaitUntil = undefined
+            }
+          }
+          const cacheTags = context.renderOpts.collectedTags
+
+          // If the request is for a static response, we can cache it so long
+          // as it's not edge.
+          if (isIsr) {
+            const blob = await response.blob()
+
+            // Copy the headers from the response.
+            const headers = toNodeOutgoingHttpHeaders(response.headers)
+
+            if (cacheTags) {
+              headers[NEXT_CACHE_TAGS_HEADER] = cacheTags
+            }
+
+            if (!headers['content-type'] && blob.type) {
+              headers['content-type'] = blob.type
+            }
+
+            const revalidate =
+              typeof context.renderOpts.collectedRevalidate === 'undefined' ||
+              context.renderOpts.collectedRevalidate >= INFINITE_CACHE
+                ? false
+                : context.renderOpts.collectedRevalidate
+
+            const expire =
+              typeof context.renderOpts.collectedExpire === 'undefined' ||
+              context.renderOpts.collectedExpire >= INFINITE_CACHE
+                ? undefined
+                : context.renderOpts.collectedExpire
+
+            // Create the cache entry for the response.
+            const cacheEntry: ResponseCacheEntry = {
+              value: {
+                kind: CachedRouteKind.APP_ROUTE,
+                status: response.status,
+                body: Buffer.from(await blob.arrayBuffer()),
+                headers,
+              },
+              cacheControl: { revalidate, expire },
+            }
+
+            return cacheEntry
+          } else {
+            // send response without caching if not ISR
+            await sendResponse(
+              nodeNextReq,
+              nodeNextRes,
+              response,
+              context.renderOpts.pendingWaitUntil
+            )
+            return null
+          }
+        } catch (err) {
+          // if this is a background revalidate we need to report
+          // the request error here as it won't be bubbled
+          if (previousCacheEntry?.isStale) {
+            await routeModule.onRequestError(
+              req,
+              err,
+              {
+                routerKind: 'App Router',
+                routePath: srcPage,
+                routeType: 'route',
+                revalidateReason: getRevalidateReason({
+                  isRevalidate,
+                  isOnDemandRevalidate,
+                }),
+              },
+              routerServerContext
+            )
+          }
+          throw err
+        }
+      }
+
+      const cacheEntry = await routeModule.handleResponse({
+        req,
+        nextConfig,
+        cacheKey,
+        routeKind: RouteKind.APP_ROUTE,
+        isFallback: false,
+        prerenderManifest,
+        isRoutePPREnabled: false,
+        isOnDemandRevalidate,
+        revalidateOnlyGenerated,
+        responseGenerator,
+        waitUntil: ctx.waitUntil,
+      })
+
+      // we don't create a cacheEntry for ISR
+      if (!isIsr) {
+        return null
+      }
+
+      if (cacheEntry?.value?.kind !== CachedRouteKind.APP_ROUTE) {
+        throw new Error(
+          `Invariant: app-route received invalid cache entry ${cacheEntry?.value?.kind}`
+        )
+      }
+
+      if (!getRequestMeta(req, 'minimalMode')) {
+        res.setHeader(
+          'x-nextjs-cache',
+          isOnDemandRevalidate
+            ? 'REVALIDATED'
+            : cacheEntry.isMiss
+              ? 'MISS'
+              : cacheEntry.isStale
+                ? 'STALE'
+                : 'HIT'
+        )
+      }
+
+      const headers = fromNodeOutgoingHttpHeaders(cacheEntry.value.headers)
+
+      if (!(getRequestMeta(req, 'minimalMode') && isIsr)) {
+        headers.delete(NEXT_CACHE_TAGS_HEADER)
+      }
+
+      // If cache control is already set on the response we don't
+      // override it to allow users to customize it via next.config
+      if (
+        cacheEntry.cacheControl &&
+        !res.getHeader('Cache-Control') &&
+        !headers.get('Cache-Control')
+      ) {
+        headers.set(
+          'Cache-Control',
+          getCacheControlHeader(cacheEntry.cacheControl)
+        )
+      }
+
+      await sendResponse(
+        nodeNextReq,
+        nodeNextRes,
+        new Response(cacheEntry.value.body, {
+          headers,
+          status: cacheEntry.value.status || 200,
+        })
+      )
+      return null
+    }
 
     // TODO: activeSpan code path is for when wrapped by
     // next-server can be removed when this is no longer used
     if (activeSpan) {
-      response = await invokeRouteModule(activeSpan)
+      await handleResponse(activeSpan)
     } else {
-      response = await tracer.withPropagatedContext(req.headers, () =>
+      await tracer.withPropagatedContext(req.headers, () =>
         tracer.trace(
           BaseServerSpan.handleRequest,
           {
@@ -256,79 +436,14 @@ export async function handler(
               'http.target': req.url,
             },
           },
-          invokeRouteModule
+          handleResponse
         )
       )
     }
-
-    ;(req as any).fetchMetrics = (context.renderOpts as any).fetchMetrics
-
-    const cacheTags = context.renderOpts.collectedTags
-
-    // If the request is for a static response, we can cache it so long
-    // as it's not edge.
-    if (isIsr) {
-      const blob = await response.blob()
-
-      // Copy the headers from the response.
-      const headers = toNodeOutgoingHttpHeaders(response.headers)
-
-      if (cacheTags) {
-        headers[NEXT_CACHE_TAGS_HEADER] = cacheTags
-      }
-
-      if (!headers['content-type'] && blob.type) {
-        headers['content-type'] = blob.type
-      }
-
-      const revalidate =
-        typeof context.renderOpts.collectedRevalidate === 'undefined' ||
-        context.renderOpts.collectedRevalidate >= INFINITE_CACHE
-          ? false
-          : context.renderOpts.collectedRevalidate
-
-      const expire =
-        typeof context.renderOpts.collectedExpire === 'undefined' ||
-        context.renderOpts.collectedExpire >= INFINITE_CACHE
-          ? undefined
-          : context.renderOpts.collectedExpire
-
-      // Create the cache entry for the response.
-      const cacheEntry: ResponseCacheEntry = {
-        value: {
-          kind: CachedRouteKind.APP_ROUTE,
-          status: response.status,
-          body: Buffer.from(await blob.arrayBuffer()),
-          headers,
-        },
-        cacheControl: { revalidate, expire },
-      }
-
-      return cacheEntry
-    }
-    let pendingWaitUntil = context.renderOpts.pendingWaitUntil
-
-    // Attempt using provided waitUntil if available
-    // if it's not we fallback to sendResponse's handling
-    if (pendingWaitUntil) {
-      if (context.renderOpts.waitUntil) {
-        context.renderOpts.waitUntil(pendingWaitUntil)
-        pendingWaitUntil = undefined
-      }
-    }
-
-    // Send the response now that we have copied it into the cache.
-    await sendResponse(
-      nodeNextReq,
-      nodeNextRes,
-      response,
-      context.renderOpts.pendingWaitUntil
-    )
-    return null
   } catch (err) {
     // if we aren't wrapped by base-server handle here
     if (!activeSpan) {
-      await onError(err, req, {
+      await routeModule.onRequestError(req, err, {
         routerKind: 'App Router',
         routePath: normalizedSrcPage,
         routeType: 'route',