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(
// should also be the case for a resume request because it's completed
// as a server render (rather than a static render).
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({
req,
res,
......@@ -1093,7 +1103,7 @@ export async function handler(
if (isDebugStaticShell || isDebugDynamicAccesses) {
// Since we're not resuming the render, we need to at least add the
// closing body and html tags to create valid HTML.
body.chain(
body.push(
new ReadableStream({
start(controller) {
controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML)
......@@ -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
// dynamic data can pipe to that will attach the dynamic data to the end
// of the response.
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.
// We don't await because we want the result to start streaming now, and
......@@ -1208,3 +1225,20 @@ export async function handler(
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(
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
// 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
......
......@@ -3586,7 +3586,7 @@ export default abstract class Server<
if (isDebugStaticShell || isDebugDynamicAccesses) {
// Since we're not resuming the render, we need to at least add the
// closing body and html tags to create valid HTML.
body.chain(
body.push(
new ReadableStream({
start(controller) {
controller.enqueue(ENCODED_TAGS.CLOSED.BODY_AND_HTML)
......@@ -3606,7 +3606,7 @@ export default abstract class Server<
// dynamic data can pipe to that will attach the dynamic data to the end
// of the response.
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.
// We don't await because we want the result to start streaming now, and
......
......@@ -212,35 +212,57 @@ export default class RenderResult<
}
/**
* 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.
* Coerces the response to an array of streams. This will convert the response
* to an array of streams if it is not already one.
*
* @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) {
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') {
responses = [streamFromString(this.response)]
return [streamFromString(this.response)]
} else if (Array.isArray(this.response)) {
responses = this.response
return this.response
} else if (Buffer.isBuffer(this.response)) {
responses = [streamFromBuffer(this.response)]
return [streamFromBuffer(this.response)]
} 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 array.
responses.push(readable)
// Add the new stream to the start of the array.
this.response.unshift(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.
this.response = responses
// Add the new stream to the end of the array.
this.response.push(readable)
}
/**
......
import { setTimeout } from 'timers/promises'
// import { setTimeout } from 'timers/promises'
export default async function Page(props) {
const params = await props.params
await setTimeout(1000)
// await setTimeout(1000)
return <div data-slug={params.slug.join('/')}>{params.slug.join('/')}</div>
}
'use client'
import { useParams } from 'next/navigation'
import { use } from 'react'
export default function Page() {
const params = useParams()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={params.slug.join('/')}>{params.slug.join('/')}</div>
}
'use client'
import { usePathname } from 'next/navigation'
import { use } from 'react'
export default function Page() {
const pathname = usePathname()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={pathname}>{pathname}</div>
}
'use client'
import { useSelectedLayoutSegment } from 'next/navigation'
import { Suspense, use } from 'react'
import { Suspense } from 'react'
function Dynamic() {
const segment = useSelectedLayoutSegment()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segment}>{segment}</div>
}
......
'use client'
import { useSelectedLayoutSegments } from 'next/navigation'
import { Suspense, use } from 'react'
import { Suspense } from 'react'
function Dynamic() {
const segments = useSelectedLayoutSegments()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segments.join('/')}>{segments.join('/')}</div>
}
......
'use client'
import { useParams } from 'next/navigation'
import { use } from 'react'
export default function Page() {
const params = useParams()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={params.slug}>{params.slug}</div>
}
'use client'
import { usePathname } from 'next/navigation'
import { use } from 'react'
export default function Page() {
const pathname = usePathname()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={pathname}>{pathname}</div>
}
'use client'
import { useSelectedLayoutSegment } from 'next/navigation'
import { Suspense, use } from 'react'
import { Suspense } from 'react'
function Dynamic() {
const segment = useSelectedLayoutSegment()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segment}>{segment}</div>
}
......
'use client'
import { useSelectedLayoutSegments } from 'next/navigation'
import { Suspense, use } from 'react'
import { Suspense } from 'react'
function Dynamic() {
const segments = useSelectedLayoutSegments()
use(new Promise((resolve) => setTimeout(resolve, 1000)))
return <div data-slug={segments.join('/')}>{segments.join('/')}</div>
}
......
import React, { use } from 'react'
import React from 'react'
import * as next from 'next/headers'
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) })
}
const delay = headers.get('x-delay')
if (delay) {
use(new Promise((resolve) => setTimeout(resolve, parseInt(delay, 10))))
}
return (
<dl>
{pathname && (
......
import { nextTestSetup, isNextStart } from 'e2e-utils'
import { measurePPRTimings } from 'e2e-utils/ppr'
import { splitResponseWithPPRSentinel } from 'e2e-utils/ppr'
import { links } from './components/links'
import cheerio from 'cheerio'
import { retry } from 'next-test-utils'
......@@ -179,40 +179,29 @@ describe('ppr-full', () => {
if (dynamic === true && !isNextDev && !isNextDeploy) {
it('should cache the static part', async () => {
const delay = 500
const dynamicValue = `${Date.now()}:${Math.random()}`
const {
timings: { streamFirstChunk, streamEnd, start },
chunks,
} = await measurePPRTimings(async () => {
const res = await next.fetch(pathname, {
headers: {
'X-Delay': delay.toString(),
'X-Test-Input': dynamicValue,
},
const [staticPart, dynamicPart] =
await splitResponseWithPPRSentinel(async () => {
const res = await next.fetch(pathname, {
headers: {
'X-Test-Input': dynamicValue,
},
})
expect(res.status).toBe(200)
return res.body
})
expect(res.status).toBe(200)
return res.body
}, delay)
if (emptyStaticPart) {
expect(streamFirstChunk - start).toBeGreaterThanOrEqual(delay)
} else {
expect(streamFirstChunk - start).toBeLessThan(delay)
}
expect(streamEnd - start).toBeGreaterThanOrEqual(delay)
// The dynamic part should contain the dynamic input.
expect(dynamicPart).toContain(dynamicValue)
// The static part should not contain the dynamic input.
expect(chunks.dynamic).toContain(dynamicValue)
// Ensure static part contains what we expect.
if (emptyStaticPart) {
expect(chunks.static).toBe('')
expect(staticPart).toBe('')
} else {
expect(chunks.static).toContain('Dynamic Loading...')
expect(chunks.static).not.toContain(dynamicValue)
expect(staticPart).toContain('Dynamic Loading...')
expect(staticPart).not.toContain(dynamicValue)
}
})
}
......@@ -315,25 +304,21 @@ describe('ppr-full', () => {
'for $pathname',
({ pathname, slug, client }) => {
it('should render the fallback HTML immediately', async () => {
const delay = 1000
const {
timings: { streamFirstChunk, start, streamEnd },
chunks,
} = await measurePPRTimings(async () => {
const res = await next.fetch(pathname)
expect(res.status).toBe(200)
const [staticPart, dynamicPart] =
await splitResponseWithPPRSentinel(async () => {
const res = await next.fetch(pathname)
expect(res.status).toBe(200)
return res.body
}, delay)
return res.body
})
// Expect that the first chunk should be emitted before the delay is
// complete, implying that the fallback shell was sent immediately.
expect(streamFirstChunk - start).toBeLessThan(delay)
// Expect that there is a static part of the response, implying that
// the fallback shell was sent immediately.
expect(staticPart.length).toBeGreaterThan(0)
// Expect that the last chunk should be emitted after the delay is
// complete.
expect(streamEnd - start).toBeGreaterThanOrEqual(delay)
// Expect that there is a dynamic part of the response, implying that
// the dynamic part was sent after the static part.
expect(dynamicPart.length).toBeGreaterThan(0)
if (client) {
const browser = await next.browser(pathname)
......@@ -347,19 +332,19 @@ describe('ppr-full', () => {
}
} else {
// The static part should not contain the dynamic parameter.
let $ = cheerio.load(chunks.static)
let $ = cheerio.load(staticPart)
let data = $('[data-slug]').text()
expect(data).not.toContain(slug)
expect($('[data-slug]').closest('[hidden]').length).toBe(0)
// The dynamic part should contain the dynamic parameter.
$ = cheerio.load(chunks.dynamic)
$ = cheerio.load(dynamicPart)
data = $('[data-slug]').text()
expect(data).toContain(slug)
expect($('[data-slug]').closest('[hidden]').length).toBe(1)
// 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', () => {
}
describe('Navigation Signals', () => {
const delay = 500
describe.each([
{
signal: 'notFound()' as const,
statusCode: 404,
pathnames: ['/navigation/not-found', '/navigation/not-found/dynamic'],
},
{
signal: 'redirect()' as const,
statusCode: 307,
pathnames: ['/navigation/redirect', '/navigation/redirect/dynamic'],
},
])('$signal', ({ signal, pathnames }) => {
])('$signal', ({ signal, statusCode, pathnames }) => {
describe.each(pathnames)('for %s', (pathname) => {
it('should have correct headers', async () => {
const res = await next.fetch(pathname, {
......@@ -525,27 +510,19 @@ describe('ppr-full', () => {
if (pathname.endsWith('/dynamic') && !isNextDeploy) {
it('should cache the static part', async () => {
const {
timings: { streamFirstChunk, streamEnd, start },
} = await measurePPRTimings(async () => {
const res = await next.fetch(pathname, {
redirect: 'manual',
headers: {
'X-Delay': delay.toString(),
},
})
const [staticPart, dynamicPart] =
await splitResponseWithPPRSentinel(async () => {
const res = await next.fetch(pathname, {
redirect: 'manual',
})
return res.body
}, delay)
expect(streamFirstChunk - start).toBeLessThan(delay)
expect(res.status).toBe(statusCode)
if (isNextDev) {
// This is because the signal should throw and interrupt the
// delay timer.
expect(streamEnd - start).toBeGreaterThanOrEqual(delay)
} else {
expect(streamEnd - start).toBeLessThan(delay)
}
return res.body
})
expect(staticPart.length).toBeGreaterThan(0)
expect(dynamicPart.length).toEqual(0)
})
}
})
......
export async function measurePPRTimings(
fn: () => Promise<NodeJS.ReadableStream>,
delay: number
) {
const start = Date.now()
// Create the stream so we can measure it.
/**
* Measures and separates static and dynamic content in a response stream
* by splitting on PPR boundary sentinel markers.
*
* 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.
*
* @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()
let streamFirstChunk = 0
let streamEnd = 0
const chunks: {
chunk: string
emittedAt: number
}[] = []
const chunks: string[] = []
await new Promise<void>((resolve, reject) => {
stream.on('data', (chunk: Buffer | string) => {
if (!streamFirstChunk) {
streamFirstChunk = Date.now()
}
if (typeof chunk !== 'string') {
chunk = chunk.toString()
chunk = chunk.toString('utf8')
}
chunks.push({ chunk, emittedAt: Date.now() })
})
stream.on('end', () => {
streamEnd = Date.now()
resolve()
chunks.push(chunk)
})
stream.on('end', resolve)
stream.on('error', reject)
})
return {
// Find all the chunks that arrived before the delay, and split
// it into the static and dynamic parts.
chunks: chunks.reduce<{
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,
},
}
// Combine all chunks and split on the PPR boundary sentinel
// The sentinel marks the boundary between static and dynamic content
const parts = chunks.join('').split('<!-- PPR_BOUNDARY_SENTINEL -->', 2)
return [parts[0] ?? '', parts[1] ?? '']
}
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