Unverified Commit e6180250 authored by Wyatt Johnson's avatar Wyatt Johnson Committed by GitHub

fix(server): fix pages router resume router matching (#84158)

### What?

Prevents PPR resume requests on Pages Router data routes by rejecting
them with a 422 status code and adds debug cache entry handlers for
testing PPR cache behavior in standalone mode.

### Why?

PPR (Partial Pre-Rendering) is an App Router-specific feature that
should not be used with Pages Router routes. When a request includes
both:
1. PPR resume headers (`next-resume: 1`)
2. A Pages Router data route URL (`/_next/data/...`)

This represents an invalid request combination that could cause
unexpected behavior. The server should explicitly reject these
unprocessable requests rather than attempting to handle them.

Additionally, testing PPR cache behavior in standalone mode requires
debug cache entry handlers that can track cache hits/misses during PPR
rendering scenarios.

### How?

**Main Fix (packages/next/src/server/base-server.ts:1102-1117):**
- Added validation after parsing PPR resume headers to check if the
request is also a next data request
- If both conditions are true, immediately return HTTP 422
(Unprocessable Entity) with empty response
- This prevents the request from proceeding to the render pipeline where
it could cause issues

**Debug Infrastructure:**
- Added support for `NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS`
environment variable in test mode
- Enhanced build tracing and required server files manifest to include
debug handlers
- Modified render server to use debug cache entry handlers when
available for testing PPR cache behavior
parent 2921fb33
...@@ -818,5 +818,6 @@ ...@@ -818,5 +818,6 @@
"817": "`cacheLifeProfiles` should always be provided.", "817": "`cacheLifeProfiles` should always be provided.",
"818": "`cacheLife()` can only be called inside a \"use cache\" function.", "818": "`cacheLife()` can only be called inside a \"use cache\" function.",
"819": "`cacheTag()` can only be called inside a \"use cache\" function.", "819": "`cacheTag()` can only be called inside a \"use cache\" function.",
"820": "`cacheLife()` can only be called during App Router rendering at the moment." "820": "`cacheLife()` can only be called during App Router rendering at the moment.",
"821": "Unprocessable request"
} }
...@@ -141,6 +141,25 @@ export async function collectBuildTraces({ ...@@ -141,6 +141,25 @@ export async function collectBuildTraces({
) )
} }
// Under standalone mode, we need to ensure that the cache entry debug
// handler is traced so it can be copied. This is only used for testing,
// and is not used in production.
if (
process.env.__NEXT_TEST_MODE &&
process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
) {
sharedEntriesSet.push(
require.resolve(
path.isAbsolute(process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS)
? process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
: path.join(
dir,
process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
)
)
)
}
if (cacheHandlers) { if (cacheHandlers) {
for (const handlerPath of Object.values(cacheHandlers)) { for (const handlerPath of Object.values(cacheHandlers)) {
if (handlerPath) { if (handlerPath) {
......
...@@ -2704,6 +2704,28 @@ export default async function build( ...@@ -2704,6 +2704,28 @@ export default async function build(
) )
} }
// Under standalone mode, we need to ensure that the cache entry debug
// handler is copied so that it can be used in the test. This is required
// for the turbopack test to run as it's more strict about the build
// directories. This is only used for testing and is not used in
// production.
if (
process.env.__NEXT_TEST_MODE &&
process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
) {
requiredServerFilesManifest.files.push(
path.relative(
dir,
path.isAbsolute(process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS)
? process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
: path.join(
dir,
process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
)
)
)
}
const features: EventBuildFeatureUsage[] = [ const features: EventBuildFeatureUsage[] = [
{ {
featureName: 'experimental/cacheComponents', featureName: 'experimental/cacheComponents',
......
...@@ -1078,9 +1078,10 @@ export default abstract class Server< ...@@ -1078,9 +1078,10 @@ export default abstract class Server<
if (this.normalizers.data?.match(urlPathname)) { if (this.normalizers.data?.match(urlPathname)) {
addRequestMeta(req, 'isNextDataReq', true) addRequestMeta(req, 'isNextDataReq', true)
} }
// In minimal mode, if PPR is enabled, then we should check to see if
// the request should be a resume request. // It's important to execute the following block even it the request
else if ( // matches a pages data route from above.
if (
this.isAppPPREnabled && this.isAppPPREnabled &&
this.minimalMode && this.minimalMode &&
req.headers[NEXT_RESUME_HEADER] === '1' && req.headers[NEXT_RESUME_HEADER] === '1' &&
...@@ -1098,6 +1099,22 @@ export default abstract class Server< ...@@ -1098,6 +1099,22 @@ export default abstract class Server<
addRequestMeta(req, 'postponed', postponed) addRequestMeta(req, 'postponed', postponed)
} }
// If the request is a next data request and it has a postponed state,
// we should error, as it represents an unprocessable request.
if (
getRequestMeta(req, 'isNextDataReq') &&
getRequestMeta(req, 'postponed')
) {
// The server understood that this is a PPR resume request, as the
// headers were included to correctly indicate a resume request, but
// because the request URL indicates that this should render a next
// data route (a pages router route), this represents an
// unprocessable request.
res.statusCode = 422
res.send()
return
}
matchedPath = this.normalize(matchedPath) matchedPath = this.normalize(matchedPath)
const normalizedUrlPath = this.stripNextDataPath(urlPathname) const normalizedUrlPath = this.stripNextDataPath(urlPathname)
......
...@@ -4,6 +4,10 @@ import type { PropagateToWorkersField } from './router-utils/types' ...@@ -4,6 +4,10 @@ import type { PropagateToWorkersField } from './router-utils/types'
import next from '../next' import next from '../next'
import type { Span } from '../../trace' import type { Span } from '../../trace'
import type { ServerResponse } from 'http'
import type { OnCacheEntryHandler } from '../request-meta'
import { interopDefault } from '../../lib/interop-default'
import { formatDynamicImportPath } from '../../lib/format-dynamic-import-path'
export type ServerInitResult = { export type ServerInitResult = {
requestHandler: RequestHandler requestHandler: RequestHandler
...@@ -103,8 +107,55 @@ async function initializeImpl(opts: { ...@@ -103,8 +107,55 @@ async function initializeImpl(opts: {
httpServer: opts.server, httpServer: opts.server,
port: opts.port, port: opts.port,
}) as NextServer // should return a NextServer when `customServer: false` }) as NextServer // should return a NextServer when `customServer: false`
requestHandler = server.getRequestHandler()
upgradeHandler = server.getUpgradeHandler() // If we're in test mode and there's a debug cache entry handler available,
// then use it to wrap the request handler instead of using the default one.
if (
process.env.__NEXT_TEST_MODE &&
process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
) {
// This mirrors the sole implementation of this over in:
// test/production/standalone-mode/required-server-files/cache-entry-handler.js
const createOnCacheEntryHandlers = interopDefault(
await import(
formatDynamicImportPath(
opts.dir,
process.env.NEXT_PRIVATE_DEBUG_CACHE_ENTRY_HANDLERS
)
)
) as (res: ServerResponse) => {
// TODO: remove onCacheEntry once onCacheEntryV2 is the default.
onCacheEntry: OnCacheEntryHandler
onCacheEntryV2: OnCacheEntryHandler
}
// This is not to be used in any environment other than testing, as it is
// not memoized and is subject to constant change.
requestHandler = async (req, res, parsedUrl) => {
// Re re-create the entry handler for each request. This is not
// performant, and is only used in testing environments.
const {
// TODO: remove onCacheEntry once onCacheEntryV2 is the default.
onCacheEntry,
onCacheEntryV2,
} = createOnCacheEntryHandlers(res)
// Get the request handler, using the entry handler as the metadata each
// request.
const handler = server.getRequestHandlerWithMetadata({
// TODO: remove onCacheEntry once onCacheEntryV2 is the default.
onCacheEntry,
onCacheEntryV2,
})
return handler(req, res, parsedUrl)
}
upgradeHandler = server.getUpgradeHandler()
} else {
requestHandler = server.getRequestHandler()
upgradeHandler = server.getUpgradeHandler()
}
await server.prepare(opts.serverFields) await server.prepare(opts.serverFields)
......
...@@ -30,6 +30,7 @@ enum LoadComponentsSpan { ...@@ -30,6 +30,7 @@ enum LoadComponentsSpan {
enum NextServerSpan { enum NextServerSpan {
getRequestHandler = 'NextServer.getRequestHandler', getRequestHandler = 'NextServer.getRequestHandler',
getRequestHandlerWithMetadata = 'NextServer.getRequestHandlerWithMetadata',
getServer = 'NextServer.getServer', getServer = 'NextServer.getServer',
getServerRequestHandler = 'NextServer.getServerRequestHandler', getServerRequestHandler = 'NextServer.getServerRequestHandler',
createServer = 'createServer.createServer', createServer = 'createServer.createServer',
......
...@@ -13,7 +13,11 @@ import type RenderResult from './render-result' ...@@ -13,7 +13,11 @@ import type RenderResult from './render-result'
import type { FetchEventResult } from './web/types' import type { FetchEventResult } from './web/types'
import type { PrerenderManifest, RoutesManifest } from '../build' import type { PrerenderManifest, RoutesManifest } from '../build'
import type { PagesManifest } from '../build/webpack/plugins/pages-manifest-plugin' import type { PagesManifest } from '../build/webpack/plugins/pages-manifest-plugin'
import type { NextParsedUrlQuery, NextUrlWithParsedQuery } from './request-meta' import type {
NextParsedUrlQuery,
NextUrlWithParsedQuery,
RequestMeta,
} from './request-meta'
import type { Params } from './request/params' import type { Params } from './request/params'
import type { MiddlewareRouteMatch } from '../shared/lib/router/utils/middleware-route-matcher' import type { MiddlewareRouteMatch } from '../shared/lib/router/utils/middleware-route-matcher'
import type { RouteMatch } from './route-matches/route-match' import type { RouteMatch } from './route-matches/route-match'
...@@ -27,7 +31,7 @@ import type { WaitUntil } from './after/builtin-request-context' ...@@ -27,7 +31,7 @@ import type { WaitUntil } from './after/builtin-request-context'
import fs from 'fs' import fs from 'fs'
import { join, relative } from 'path' import { join, relative } from 'path'
import { getRouteMatcher } from '../shared/lib/router/utils/route-matcher' import { getRouteMatcher } from '../shared/lib/router/utils/route-matcher'
import { addRequestMeta, getRequestMeta } from './request-meta' import { addRequestMeta, getRequestMeta, setRequestMeta } from './request-meta'
import { import {
PAGES_MANIFEST, PAGES_MANIFEST,
BUILD_ID_FILE, BUILD_ID_FILE,
...@@ -1273,6 +1277,17 @@ export default class NextNodeServer extends BaseServer< ...@@ -1273,6 +1277,17 @@ export default class NextNodeServer extends BaseServer<
return handler return handler
} }
/**
* @internal - this method is internal to Next.js and should not be used directly by end-users
*/
public getRequestHandlerWithMetadata(meta: RequestMeta): NodeRequestHandler {
const handler = this.makeRequestHandler()
return (req, res, parsedUrl) => {
setRequestMeta(req, meta)
return handler(req, res, parsedUrl)
}
}
private makeRequestHandler(): NodeRequestHandler { private makeRequestHandler(): NodeRequestHandler {
// This is just optimization to fire prepare as soon as possible. It will be // This is just optimization to fire prepare as soon as possible. It will be
// properly awaited later. We add the catch here to ensure that it does not // properly awaited later. We add the catch here to ensure that it does not
......
...@@ -6,7 +6,7 @@ import type { ...@@ -6,7 +6,7 @@ import type {
import type { UrlWithParsedQuery } from 'url' import type { UrlWithParsedQuery } from 'url'
import type { IncomingMessage, ServerResponse } from 'http' import type { IncomingMessage, ServerResponse } from 'http'
import type { Duplex } from 'stream' import type { Duplex } from 'stream'
import type { NextUrlWithParsedQuery } from './request-meta' import type { NextUrlWithParsedQuery, RequestMeta } from './request-meta'
import './require-hook' import './require-hook'
import './node-polyfill-crypto' import './node-polyfill-crypto'
...@@ -148,6 +148,27 @@ export class NextServer implements NextWrapperServer { ...@@ -148,6 +148,27 @@ export class NextServer implements NextWrapperServer {
} }
} }
/**
* @internal - this method is internal to Next.js and should not be used
* directly by end-users, only used in testing
*/
getRequestHandlerWithMetadata(meta: RequestMeta): RequestHandler {
return async (
req: IncomingMessage,
res: ServerResponse,
parsedUrl?: UrlWithParsedQuery
) => {
return getTracer().trace(
NextServerSpan.getRequestHandlerWithMetadata,
async () => {
const server = await this.getServer()
const handler = server.getRequestHandlerWithMetadata(meta)
return handler(req, res, parsedUrl)
}
)
}
}
getUpgradeHandler(): UpgradeHandler { getUpgradeHandler(): UpgradeHandler {
return async (req: IncomingMessage, socket: any, head: any) => { return async (req: IncomingMessage, socket: any, head: any) => {
const server = await this.getServer() const server = await this.getServer()
......
...@@ -21,6 +21,28 @@ export type NextIncomingMessage = (BaseNextRequest | IncomingMessage) & { ...@@ -21,6 +21,28 @@ export type NextIncomingMessage = (BaseNextRequest | IncomingMessage) & {
[NEXT_REQUEST_META]?: RequestMeta [NEXT_REQUEST_META]?: RequestMeta
} }
/**
* The callback function to call when a response cache entry was generated or
* looked up in the cache. When it returns true, the server assumes that the
* handler has already responded to the request and will not do so itself.
*/
export type OnCacheEntryHandler = (
/**
* The response cache entry that was generated or looked up in the cache.
*/
cacheEntry: ResponseCacheEntry,
/**
* The request metadata.
*/
requestMeta: {
/**
* The URL that was used to make the request.
*/
url: string | undefined
}
) => Promise<boolean | void> | boolean | void
export interface RequestMeta { export interface RequestMeta {
/** /**
* The query that was used to make the request. * The query that was used to make the request.
...@@ -126,23 +148,13 @@ export interface RequestMeta { ...@@ -126,23 +148,13 @@ export interface RequestMeta {
* *
* @deprecated Use `onCacheEntryV2` instead. * @deprecated Use `onCacheEntryV2` instead.
*/ */
onCacheEntry?: ( onCacheEntry?: OnCacheEntryHandler
cacheEntry: ResponseCacheEntry,
requestMeta: {
url: string | undefined
}
) => Promise<boolean | void> | boolean | void
/** /**
* If provided, this will be called when a response cache entry was generated * If provided, this will be called when a response cache entry was generated
* or looked up in the cache. * or looked up in the cache.
*/ */
onCacheEntryV2?: ( onCacheEntryV2?: OnCacheEntryHandler
cacheEntry: ResponseCacheEntry,
requestMeta: {
url: string | undefined
}
) => Promise<boolean | void> | boolean | void
/** /**
* The previous revalidate before rendering 404 page for notFound: true * The previous revalidate before rendering 404 page for notFound: true
......
export default function Loading() {
return <p id="slot-loading">/[...catchAll]</p>
}
export default async function Page({ params }) {
return (
<>
<p id="slot-page">/@slot/[[...catchAll]]/page.js</p>
<p id="slot-params">{JSON.stringify(await params)}</p>
</>
)
}
export default function Default() {
return '/@slot/default.js'
}
export default function Default() {
return '/default.js'
}
export default function Layout({ children }) { import { Suspense } from 'react'
export default function Layout({ children, slot }) {
return ( return (
<html lang="en"> <html lang="en">
<head /> <head />
<body>{children}</body> <body>
<Suspense>
<div id="children-slot">{children}</div>
<div id="slot-slot">{slot}</div>
</Suspense>
</body>
</html> </html>
) )
} }
...@@ -2,7 +2,7 @@ export default async function Page({ params }) { ...@@ -2,7 +2,7 @@ export default async function Page({ params }) {
return ( return (
<> <>
<p id="page">/postpone/isr/[slug]</p> <p id="page">/postpone/isr/[slug]</p>
<p id="params">{JSON.stringify(params)}</p> <p id="params">{JSON.stringify(await params)}</p>
<p id="now">{Date.now()}</p> <p id="now">{Date.now()}</p>
</> </>
) )
......
// @ts-check
/**
* @param {import('http').ServerResponse} res
* @returns {{
* onCacheEntry: import('next/dist/server/request-meta').OnCacheEntryHandler,
* onCacheEntryV2: import('next/dist/server/request-meta').OnCacheEntryHandler
* }}
*/
module.exports = (res) => ({
onCacheEntry: (cacheEntry, meta) => {
// If this isn't a static app page response from the response cache, then
// mark it as a miss.
if (
!cacheEntry.value ||
cacheEntry.value.kind !== 'APP_PAGE' ||
!cacheEntry.value.html ||
typeof cacheEntry.value.html.toUnchunkedString !== 'function' ||
!cacheEntry.value.postponed ||
!meta.url ||
typeof meta.url !== 'string'
) {
res.setHeader('x-nextjs-cache-entry-handler', 'MISS_1')
return false
}
// If this is for a RSC request, then mark it as a miss.
if (meta.url.endsWith('.rsc')) {
res.setHeader('x-nextjs-cache-entry-handler', 'MISS_1')
return false
}
// Mark this as a hit against the cache entry handler.
res.setHeader('x-nextjs-cache-entry-handler', 'HIT_1')
return false
},
onCacheEntryV2: (cacheEntry, meta) => {
// If this isn't a static app page response from the response cache, then
// mark it as a miss.
if (
!cacheEntry.value ||
cacheEntry.value.kind !== 'APP_PAGE' ||
!cacheEntry.value.html ||
typeof cacheEntry.value.html.toUnchunkedString !== 'function' ||
!cacheEntry.value.postponed ||
!meta.url ||
typeof meta.url !== 'string'
) {
res.setHeader('x-nextjs-cache-entry-handler', 'MISS_2')
return false
}
// If this is for a prefetch or segment request, then mark it as a miss.
if (
meta.url.endsWith('.prefetch.rsc') ||
meta.url.endsWith('.segment.rsc')
) {
res.setHeader('x-nextjs-cache-entry-handler', 'MISS_2')
return false
}
// Mark this as a hit against the cache entry handler.
res.setHeader('x-nextjs-cache-entry-handler', 'HIT_2')
return false
},
})
import { connection } from 'next/server'
export default async function NotFound() {
await connection()
return (
<>
<p id="not-found">/not-found</p>
</>
)
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment