Unverified Commit 5c7daf5a authored by Wyatt Johnson's avatar Wyatt Johnson Committed by GitHub

fix(ppr): ensure fallback route params trigger dynamic resume (#81812)

### What?

This PR fixes an issue where pages with fallback route params weren't
triggering dynamic resume behavior in PPR (Partial Pre-Rendering).

### Why?

When fallback route params exist, the RSC (React Server Components) data
is inherently dynamic because the params are encoded into the flight
router state. Without this fix, pages with fallback route params would
incorrectly be treated as fully static, leading to incorrect behavior.

### How?

- Added a check in `app-render.tsx` to ensure that pages with fallback
route params (`workStore.fallbackRouteParams.size > 0`) always perform a
dynamic resume after the static prerender
- Refactored PPR tests to use deterministic sentinel markers (`<\!--
PPR_BOUNDARY_SENTINEL -->`) instead of time-based measurements for more
reliable testing
- Updated the test utilities to split responses based on the sentinel
marker rather than timing delays

This ensures that:
1. Pages with fallback route params correctly trigger dynamic behavior
2. PPR tests are more reliable and deterministic
3. The boundary between static and dynamic content is clearly marked in
test mode

Fixes #
parent d3ed546f
...@@ -1075,6 +1075,16 @@ export async function handler( ...@@ -1075,6 +1075,16 @@ export async function handler(
// should also be the case for a resume request because it's completed // should also be the case for a resume request because it's completed
// as a server render (rather than a static render). // as a server render (rather than a static render).
if (!didPostpone || minimalMode) { if (!didPostpone || minimalMode) {
// If we're in test mode, we should add a sentinel chunk to the response
// that's between the static and dynamic parts so we can compare the
// chunks and add assertions.
if (process.env.__NEXT_TEST_MODE && minimalMode && isRoutePPREnabled) {
// As we're in minimal mode, the static part would have already been
// streamed first. The only part that this streams is the dynamic part
// so we should FIRST stream the sentinel and THEN the dynamic part.
body.unshift(createPPRBoundarySentinel())
}
return sendRenderResult({ return sendRenderResult({
req, req,
res, res,
...@@ -1093,7 +1103,7 @@ export async function handler( ...@@ -1093,7 +1103,7 @@ export async function handler(
if (isDebugStaticShell || isDebugDynamicAccesses) { if (isDebugStaticShell || isDebugDynamicAccesses) {
// Since we're not resuming the render, we need to at least add the // Since we're not resuming the render, we need to at least add the
// closing body and html tags to create valid HTML. // closing body and html tags to create valid HTML.
body.chain( body.push(
new ReadableStream({ new ReadableStream({
start(controller) { start(controller) {
controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML) controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML)
...@@ -1113,11 +1123,18 @@ export async function handler( ...@@ -1113,11 +1123,18 @@ export async function handler(
}) })
} }
// If we're in test mode, we should add a sentinel chunk to the response
// that's between the static and dynamic parts so we can compare the
// chunks and add assertions.
if (process.env.__NEXT_TEST_MODE) {
body.push(createPPRBoundarySentinel())
}
// This request has postponed, so let's create a new transformer that the // This request has postponed, so let's create a new transformer that the
// dynamic data can pipe to that will attach the dynamic data to the end // dynamic data can pipe to that will attach the dynamic data to the end
// of the response. // of the response.
const transformer = new TransformStream<Uint8Array, Uint8Array>() const transformer = new TransformStream<Uint8Array, Uint8Array>()
body.chain(transformer.readable) body.push(transformer.readable)
// Perform the render again, but this time, provide the postponed state. // Perform the render again, but this time, provide the postponed state.
// We don't await because we want the result to start streaming now, and // We don't await because we want the result to start streaming now, and
...@@ -1208,3 +1225,20 @@ export async function handler( ...@@ -1208,3 +1225,20 @@ export async function handler(
throw err throw err
} }
} }
// TODO: omit this from production builds, only test builds should include it
/**
* Creates a readable stream that emits a PPR boundary sentinel.
*
* @returns A readable stream that emits a PPR boundary sentinel.
*/
function createPPRBoundarySentinel() {
return new ReadableStream({
start(controller) {
controller.enqueue(
new TextEncoder().encode('<!-- PPR_BOUNDARY_SENTINEL -->')
)
controller.close()
},
})
}
...@@ -3491,7 +3491,14 @@ async function prerenderToStream( ...@@ -3491,7 +3491,14 @@ async function prerenderToStream(
fallbackRouteParams fallbackRouteParams
) )
if (serverIsDynamic) { // If there are fallback route params, the RSC data is inherently dynamic
// today because it's encoded into the flight router state. Until we can
// move the fallback route params out of the flight router state, we need
// to always perform a dynamic resume after the static prerender.
const hasFallbackRouteParams =
workStore.fallbackRouteParams && workStore.fallbackRouteParams.size > 0
if (serverIsDynamic || hasFallbackRouteParams) {
// Dynamic case // Dynamic case
// We will always need to perform a "resume" render of some kind when this route is accessed // We will always need to perform a "resume" render of some kind when this route is accessed
// because the RSC data itself is dynamic. We determine if there are any HTML holes or not // because the RSC data itself is dynamic. We determine if there are any HTML holes or not
......
...@@ -3586,7 +3586,7 @@ export default abstract class Server< ...@@ -3586,7 +3586,7 @@ export default abstract class Server<
if (isDebugStaticShell || isDebugDynamicAccesses) { if (isDebugStaticShell || isDebugDynamicAccesses) {
// Since we're not resuming the render, we need to at least add the // Since we're not resuming the render, we need to at least add the
// closing body and html tags to create valid HTML. // closing body and html tags to create valid HTML.
body.chain( body.push(
new ReadableStream({ new ReadableStream({
start(controller) { start(controller) {
controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML) controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML)
...@@ -3606,7 +3606,7 @@ export default abstract class Server< ...@@ -3606,7 +3606,7 @@ export default abstract class Server<
// dynamic data can pipe to that will attach the dynamic data to the end // dynamic data can pipe to that will attach the dynamic data to the end
// of the response. // of the response.
const transformer = new TransformStream<Uint8Array, Uint8Array>() const transformer = new TransformStream<Uint8Array, Uint8Array>()
body.chain(transformer.readable) body.push(transformer.readable)
// Perform the render again, but this time, provide the postponed state. // Perform the render again, but this time, provide the postponed state.
// We don't await because we want the result to start streaming now, and // We don't await because we want the result to start streaming now, and
......
...@@ -212,35 +212,57 @@ export default class RenderResult< ...@@ -212,35 +212,57 @@ export default class RenderResult<
} }
/** /**
* Chains a new stream to the response. This will convert the response to an * Coerces the response to an array of streams. This will convert the response
* array of streams if it is not already one and will add the new stream to * to an array of streams if it is not already one.
* the end. When this response is piped, all of the streams will be piped
* one after the other.
* *
* @param readable The new stream to chain * @returns An array of streams
*/ */
public chain(readable: ReadableStream<Uint8Array>) { private coerce(): ReadableStream<Uint8Array>[] {
if (this.response === null) { if (this.response === null) {
throw new Error('Invariant: response is null. This is a bug in Next.js') throw new Error('Invariant: response is null. This is a bug in Next.js')
} }
// If the response is not an array of streams already, make it one.
let responses: ReadableStream<Uint8Array>[]
if (typeof this.response === 'string') { if (typeof this.response === 'string') {
responses = [streamFromString(this.response)] return [streamFromString(this.response)]
} else if (Array.isArray(this.response)) { } else if (Array.isArray(this.response)) {
responses = this.response return this.response
} else if (Buffer.isBuffer(this.response)) { } else if (Buffer.isBuffer(this.response)) {
responses = [streamFromBuffer(this.response)] return [streamFromBuffer(this.response)]
} else { } else {
responses = [this.response] return [this.response]
}
}
/**
* Unshifts a new stream to the response. This will convert the response to an
* array of streams if it is not already one and will add the new stream to
* the start of the array. When this response is piped, all of the streams
* will be piped one after the other.
*
* @param readable The new stream to unshift
*/
public unshift(readable: ReadableStream<Uint8Array>): void {
// Coerce the response to an array of streams.
this.response = this.coerce()
// Add the new stream to the start of the array.
this.response.unshift(readable)
} }
// Add the new stream to the array. /**
responses.push(readable) * Chains a new stream to the response. This will convert the response to an
* array of streams if it is not already one and will add the new stream to
* the end. When this response is piped, all of the streams will be piped
* one after the other.
*
* @param readable The new stream to chain
*/
public push(readable: ReadableStream<Uint8Array>): void {
// Coerce the response to an array of streams.
this.response = this.coerce()
// Update the response. // Add the new stream to the end of the array.
this.response = responses this.response.push(readable)
} }
/** /**
......
import { setTimeout } from 'timers/promises' // import { setTimeout } from 'timers/promises'
export default async function Page(props) { export default async function Page(props) {
const params = await props.params const params = await props.params
await setTimeout(1000) // await setTimeout(1000)
return <div data-slug={params.slug.join('/')}>{params.slug.join('/')}</div> return <div data-slug={params.slug.join('/')}>{params.slug.join('/')}</div>
} }
'use client' 'use client'
import { useParams } from 'next/navigation' import { useParams } from 'next/navigation'
import { use } from 'react'
export default function Page() { export default function Page() {
const params = useParams() const params = useParams()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={params.slug.join('/')}>{params.slug.join('/')}</div> return <div data-slug={params.slug.join('/')}>{params.slug.join('/')}</div>
} }
'use client' 'use client'
import { usePathname } from 'next/navigation' import { usePathname } from 'next/navigation'
import { use } from 'react'
export default function Page() { export default function Page() {
const pathname = usePathname() const pathname = usePathname()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={pathname}>{pathname}</div> return <div data-slug={pathname}>{pathname}</div>
} }
'use client' 'use client'
import { useSelectedLayoutSegment } from 'next/navigation' import { useSelectedLayoutSegment } from 'next/navigation'
import { Suspense, use } from 'react' import { Suspense } from 'react'
function Dynamic() { function Dynamic() {
const segment = useSelectedLayoutSegment() const segment = useSelectedLayoutSegment()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segment}>{segment}</div> return <div data-slug={segment}>{segment}</div>
} }
......
'use client' 'use client'
import { useSelectedLayoutSegments } from 'next/navigation' import { useSelectedLayoutSegments } from 'next/navigation'
import { Suspense, use } from 'react' import { Suspense } from 'react'
function Dynamic() { function Dynamic() {
const segments = useSelectedLayoutSegments() const segments = useSelectedLayoutSegments()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segments.join('/')}>{segments.join('/')}</div> return <div data-slug={segments.join('/')}>{segments.join('/')}</div>
} }
......
'use client' 'use client'
import { useParams } from 'next/navigation' import { useParams } from 'next/navigation'
import { use } from 'react'
export default function Page() { export default function Page() {
const params = useParams() const params = useParams()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={params.slug}>{params.slug}</div> return <div data-slug={params.slug}>{params.slug}</div>
} }
'use client' 'use client'
import { usePathname } from 'next/navigation' import { usePathname } from 'next/navigation'
import { use } from 'react'
export default function Page() { export default function Page() {
const pathname = usePathname() const pathname = usePathname()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={pathname}>{pathname}</div> return <div data-slug={pathname}>{pathname}</div>
} }
'use client' 'use client'
import { useSelectedLayoutSegment } from 'next/navigation' import { useSelectedLayoutSegment } from 'next/navigation'
import { Suspense, use } from 'react' import { Suspense } from 'react'
function Dynamic() { function Dynamic() {
const segment = useSelectedLayoutSegment() const segment = useSelectedLayoutSegment()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segment}>{segment}</div> return <div data-slug={segment}>{segment}</div>
} }
......
'use client' 'use client'
import { useSelectedLayoutSegments } from 'next/navigation' import { useSelectedLayoutSegments } from 'next/navigation'
import { Suspense, use } from 'react' import { Suspense } from 'react'
function Dynamic() { function Dynamic() {
const segments = useSelectedLayoutSegments() const segments = useSelectedLayoutSegments()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segments.join('/')}>{segments.join('/')}</div> return <div data-slug={segments.join('/')}>{segments.join('/')}</div>
} }
......
import React, { use } from 'react' import React from 'react'
import * as next from 'next/headers' import * as next from 'next/headers'
export const Dynamic = ({ pathname, fallback = null, params = null }) => { export const Dynamic = ({ pathname, fallback = null, params = null }) => {
...@@ -12,11 +12,6 @@ export const Dynamic = ({ pathname, fallback = null, params = null }) => { ...@@ -12,11 +12,6 @@ export const Dynamic = ({ pathname, fallback = null, params = null }) => {
messages.push({ name, value: headers.get(name) }) messages.push({ name, value: headers.get(name) })
} }
const delay = headers.get('x-delay')
if (delay) {
use(new Promise((resolve) => setTimeout(resolve, parseInt(delay, 10))))
}
return ( return (
<dl> <dl>
{pathname && ( {pathname && (
......
import { nextTestSetup, isNextStart } from 'e2e-utils' import { nextTestSetup, isNextStart } from 'e2e-utils'
import { measurePPRTimings } from 'e2e-utils/ppr' import { splitResponseWithPPRSentinel } from 'e2e-utils/ppr'
import { links } from './components/links' import { links } from './components/links'
import cheerio from 'cheerio' import cheerio from 'cheerio'
import { retry } from 'next-test-utils' import { retry } from 'next-test-utils'
...@@ -179,40 +179,29 @@ describe('ppr-full', () => { ...@@ -179,40 +179,29 @@ describe('ppr-full', () => {
if (dynamic === true && !isNextDev && !isNextDeploy) { if (dynamic === true && !isNextDev && !isNextDeploy) {
it('should cache the static part', async () => { it('should cache the static part', async () => {
const delay = 500
const dynamicValue = `${Date.now()}:${Math.random()}` const dynamicValue = `${Date.now()}:${Math.random()}`
const { const [staticPart, dynamicPart] =
timings: { streamFirstChunk, streamEnd, start }, await splitResponseWithPPRSentinel(async () => {
chunks,
} = await measurePPRTimings(async () => {
const res = await next.fetch(pathname, { const res = await next.fetch(pathname, {
headers: { headers: {
'X-Delay': delay.toString(),
'X-Test-Input': dynamicValue, 'X-Test-Input': dynamicValue,
}, },
}) })
expect(res.status).toBe(200) expect(res.status).toBe(200)
return res.body return res.body
}, delay) })
if (emptyStaticPart) {
expect(streamFirstChunk - start).toBeGreaterThanOrEqual(delay)
} else {
expect(streamFirstChunk - start).toBeLessThan(delay)
}
expect(streamEnd - start).toBeGreaterThanOrEqual(delay)
// The static part should not contain the dynamic input. // The dynamic part should contain the dynamic input.
expect(chunks.dynamic).toContain(dynamicValue) expect(dynamicPart).toContain(dynamicValue)
// Ensure static part contains what we expect. // The static part should not contain the dynamic input.
if (emptyStaticPart) { if (emptyStaticPart) {
expect(chunks.static).toBe('') expect(staticPart).toBe('')
} else { } else {
expect(chunks.static).toContain('Dynamic Loading...') expect(staticPart).toContain('Dynamic Loading...')
expect(chunks.static).not.toContain(dynamicValue) expect(staticPart).not.toContain(dynamicValue)
} }
}) })
} }
...@@ -315,25 +304,21 @@ describe('ppr-full', () => { ...@@ -315,25 +304,21 @@ describe('ppr-full', () => {
'for $pathname', 'for $pathname',
({ pathname, slug, client }) => { ({ pathname, slug, client }) => {
it('should render the fallback HTML immediately', async () => { it('should render the fallback HTML immediately', async () => {
const delay = 1000 const [staticPart, dynamicPart] =
await splitResponseWithPPRSentinel(async () => {
const {
timings: { streamFirstChunk, start, streamEnd },
chunks,
} = await measurePPRTimings(async () => {
const res = await next.fetch(pathname) const res = await next.fetch(pathname)
expect(res.status).toBe(200) expect(res.status).toBe(200)
return res.body return res.body
}, delay) })
// Expect that the first chunk should be emitted before the delay is // Expect that there is a static part of the response, implying that
// complete, implying that the fallback shell was sent immediately. // the fallback shell was sent immediately.
expect(streamFirstChunk - start).toBeLessThan(delay) expect(staticPart.length).toBeGreaterThan(0)
// Expect that the last chunk should be emitted after the delay is // Expect that there is a dynamic part of the response, implying that
// complete. // the dynamic part was sent after the static part.
expect(streamEnd - start).toBeGreaterThanOrEqual(delay) expect(dynamicPart.length).toBeGreaterThan(0)
if (client) { if (client) {
const browser = await next.browser(pathname) const browser = await next.browser(pathname)
...@@ -347,19 +332,19 @@ describe('ppr-full', () => { ...@@ -347,19 +332,19 @@ describe('ppr-full', () => {
} }
} else { } else {
// The static part should not contain the dynamic parameter. // The static part should not contain the dynamic parameter.
let $ = cheerio.load(chunks.static) let $ = cheerio.load(staticPart)
let data = $('[data-slug]').text() let data = $('[data-slug]').text()
expect(data).not.toContain(slug) expect(data).not.toContain(slug)
expect($('[data-slug]').closest('[hidden]').length).toBe(0) expect($('[data-slug]').closest('[hidden]').length).toBe(0)
// The dynamic part should contain the dynamic parameter. // The dynamic part should contain the dynamic parameter.
$ = cheerio.load(chunks.dynamic) $ = cheerio.load(dynamicPart)
data = $('[data-slug]').text() data = $('[data-slug]').text()
expect(data).toContain(slug) expect(data).toContain(slug)
expect($('[data-slug]').closest('[hidden]').length).toBe(1) expect($('[data-slug]').closest('[hidden]').length).toBe(1)
// The static part should contain the fallback shell. // The static part should contain the fallback shell.
expect(chunks.static).toContain('data-fallback') expect(staticPart).toContain('data-fallback')
} }
}) })
} }
...@@ -477,18 +462,18 @@ describe('ppr-full', () => { ...@@ -477,18 +462,18 @@ describe('ppr-full', () => {
} }
describe('Navigation Signals', () => { describe('Navigation Signals', () => {
const delay = 500
describe.each([ describe.each([
{ {
signal: 'notFound()' as const, signal: 'notFound()' as const,
statusCode: 404,
pathnames: ['/navigation/not-found', '/navigation/not-found/dynamic'], pathnames: ['/navigation/not-found', '/navigation/not-found/dynamic'],
}, },
{ {
signal: 'redirect()' as const, signal: 'redirect()' as const,
statusCode: 307,
pathnames: ['/navigation/redirect', '/navigation/redirect/dynamic'], pathnames: ['/navigation/redirect', '/navigation/redirect/dynamic'],
}, },
])('$signal', ({ signal, pathnames }) => { ])('$signal', ({ signal, statusCode, pathnames }) => {
describe.each(pathnames)('for %s', (pathname) => { describe.each(pathnames)('for %s', (pathname) => {
it('should have correct headers', async () => { it('should have correct headers', async () => {
const res = await next.fetch(pathname, { const res = await next.fetch(pathname, {
...@@ -525,27 +510,19 @@ describe('ppr-full', () => { ...@@ -525,27 +510,19 @@ describe('ppr-full', () => {
if (pathname.endsWith('/dynamic') && !isNextDeploy) { if (pathname.endsWith('/dynamic') && !isNextDeploy) {
it('should cache the static part', async () => { it('should cache the static part', async () => {
const { const [staticPart, dynamicPart] =
timings: { streamFirstChunk, streamEnd, start }, await splitResponseWithPPRSentinel(async () => {
} = await measurePPRTimings(async () => {
const res = await next.fetch(pathname, { const res = await next.fetch(pathname, {
redirect: 'manual', redirect: 'manual',
headers: {
'X-Delay': delay.toString(),
},
}) })
expect(res.status).toBe(statusCode)
return res.body return res.body
}, delay) })
expect(streamFirstChunk - start).toBeLessThan(delay)
if (isNextDev) { expect(staticPart.length).toBeGreaterThan(0)
// This is because the signal should throw and interrupt the expect(dynamicPart.length).toEqual(0)
// delay timer.
expect(streamEnd - start).toBeGreaterThanOrEqual(delay)
} else {
expect(streamEnd - start).toBeLessThan(delay)
}
}) })
} }
}) })
......
export async function measurePPRTimings( /**
fn: () => Promise<NodeJS.ReadableStream>, * Measures and separates static and dynamic content in a response stream
delay: number * by splitting on PPR boundary sentinel markers.
) { *
const start = Date.now() * This function is used in Partial Prerendering (PPR) tests to analyze the output
* of Next.js pages and verify that static and dynamic content are properly separated.
// Create the stream so we can measure it. *
* @param fn - A function that returns a Promise resolving to a readable stream
* containing HTML with PPR boundary markers
* @returns An object containing the separated static and dynamic chunks
*
* @example
* const [staticPart, dynamicPart] = await splitResponseWithPPRSentinel(async () => {
* return fetch('/some-ppr-page').then(res => res.body)
* })
* console.log(staticPart) // Content before the boundary
* console.log(dynamicPart) // Content after the boundary
*/
export async function splitResponseWithPPRSentinel(
fn: () => Promise<NodeJS.ReadableStream>
): Promise<[staticPart: string, dynamicPart: string]> {
const stream = await fn() const stream = await fn()
const chunks: string[] = []
let streamFirstChunk = 0
let streamEnd = 0
const chunks: {
chunk: string
emittedAt: number
}[] = []
await new Promise<void>((resolve, reject) => { await new Promise<void>((resolve, reject) => {
stream.on('data', (chunk: Buffer | string) => { stream.on('data', (chunk: Buffer | string) => {
if (!streamFirstChunk) {
streamFirstChunk = Date.now()
}
if (typeof chunk !== 'string') { if (typeof chunk !== 'string') {
chunk = chunk.toString() chunk = chunk.toString('utf8')
} }
chunks.push({ chunk, emittedAt: Date.now() }) chunks.push(chunk)
})
stream.on('end', () => {
streamEnd = Date.now()
resolve()
}) })
stream.on('end', resolve)
stream.on('error', reject) stream.on('error', reject)
}) })
return { // Combine all chunks and split on the PPR boundary sentinel
// Find all the chunks that arrived before the delay, and split // The sentinel marks the boundary between static and dynamic content
// it into the static and dynamic parts. const parts = chunks.join('').split('<!-- PPR_BOUNDARY_SENTINEL -->', 2)
chunks: chunks.reduce<{ return [parts[0] ?? '', parts[1] ?? '']
static: string
dynamic: string
}>(
(acc, { chunk, emittedAt }) => {
if (emittedAt < start + delay) {
acc.static += chunk
} else {
acc.dynamic += chunk
}
return acc
},
{ static: '', dynamic: '' }
),
timings: {
start,
streamFirstChunk,
streamEnd,
},
}
} }
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