Commit a822c66f authored by Jimmy Lai's avatar Jimmy Lai

feat(node-streams): add conditional Node stream support to instant-validation

Makes instant-validation.tsx conditionally use Node.js native streams
(renderToPipeableStream) instead of web streams (renderToReadableStream)
when __NEXT_USE_NODE_STREAMS is enabled. This prevents hangs that occurred
when instant-validation bypassed the stream API wrappers.

Changes:
- Remove static import of renderToReadableStream
- Add conditional lazy requires for both web and Node Flight APIs
- Use renderToFlightPipeableStream wrapper for Node path (handles debug channel conversion)
- Handle stream iteration differences (Node Readable vs web ReadableStream.values())
- Apply pattern at both rendering call sites: collectStagedSegmentData and createCombinedPayloadStream

Known limitation:
- Debug channel at segment level disabled with Node streams to avoid parallel bridge issues
- Combined payload level debug channel still enabled
- 4/5 instant-validation tests pass; debug channel interaction needs further investigation

Test results with __NEXT_USE_NODE_STREAMS + __NEXT_CACHE_COMPONENTS + __NEXT_EXPERIMENTAL_DEBUG_CHANNEL:
- instant-validation-static-shells: 4 passed, 1 failing (debug channel interaction)
- Without debug channel: all tests pass
Co-Authored-By: 's avatarClaude Sonnet 4.5 <noreply@anthropic.com>
parent 523fce89
export type DebugChannelPair = { export type DebugChannelPair = {
// serverSide is passed opaquely as options.debugChannel to React's // serverSide is always in the web shape ({ writable: WritableStream }).
// renderToReadableStream (web) or renderToPipeableStream (Node). // Consumers that need a Node Writable (for renderToPipeableStream) should
// The two APIs expect different shapes: // call toNodeDebugChannel() to convert.
// - Web: { readable?, writable: WritableStream }
// - Node: a Writable stream (has .write() directly on the object)
// Consumers should not access properties on serverSide directly.
serverSide: DebugChannelServer serverSide: DebugChannelServer
clientSide: DebugChannelClient clientSide: DebugChannelClient
} }
// Passed directly as options.debugChannel to React's render functions. // Always the web shape: React's renderToReadableStream reads .writable from it.
// React's web API (renderToReadableStream) reads .writable from it. // For renderToPipeableStream (Node), use toNodeDebugChannel() to convert.
// React's Node API (renderToPipeableStream) checks .write() on it directly. export type DebugChannelServer = {
export type DebugChannelServer =
| {
readable?: ReadableStream<Uint8Array> readable?: ReadableStream<Uint8Array>
writable: WritableStream<Uint8Array> writable: WritableStream<Uint8Array>
} }
| import('node:stream').Writable
export type DebugChannelClient = { export type DebugChannelClient = {
readable: ReadableStream<Uint8Array> readable: ReadableStream<Uint8Array>
writable?: WritableStream<Uint8Array> writable?: WritableStream<Uint8Array>
} }
export function createDebugChannel(): DebugChannelPair | undefined { /**
if (process.env.NODE_ENV === 'production') { * Converts a web-shaped debug channel to a Node Writable for use with
return undefined * React's renderToPipeableStream, which checks typeof debugChannel.write
} * to find its debug destination.
*/
let readableController: ReadableStreamDefaultController | undefined export function toNodeDebugChannel(
webDebugChannel: DebugChannelServer
const clientSideReadable = new ReadableStream<Uint8Array>({ ): import('node:stream').Writable {
start(controller) {
readableController = controller
},
})
// When node streams are enabled, create a Node.js Writable as the server
// side. React's renderToPipeableStream checks typeof debugChannel.write
// to find its debug destination. A web WritableStream doesn't have .write()
// on the object, so it must be a Node Writable.
if (process.env.__NEXT_USE_NODE_STREAMS) {
const { Writable } = require('node:stream') as typeof import('node:stream') const { Writable } = require('node:stream') as typeof import('node:stream')
const serverSide = new Writable({ const writer = webDebugChannel.writable.getWriter()
return new Writable({
write( write(
chunk: Buffer | Uint8Array, chunk: Buffer | Uint8Array,
_encoding: string, _encoding: string,
callback: (error?: Error | null) => void callback: (error?: Error | null) => void
) { ) {
readableController?.enqueue(chunk) writer.write(chunk).then(() => callback(), callback)
callback()
}, },
final(callback: (error?: Error | null) => void) { final(callback: (error?: Error | null) => void) {
readableController?.close() writer.close().then(() => callback(), callback)
callback()
}, },
destroy(_err, callback) { destroy(_err, callback) {
readableController?.error(_err) writer.abort(_err).then(
callback(_err) () => callback(_err),
() => callback(_err)
)
}, },
}) })
return { serverSide, clientSide: { readable: clientSideReadable } } }
export function createDebugChannel(): DebugChannelPair | undefined {
if (process.env.NODE_ENV === 'production') {
return undefined
} }
let readableController: ReadableStreamDefaultController | undefined
const clientSideReadable = new ReadableStream<Uint8Array>({
start(controller) {
readableController = controller
},
})
return { return {
serverSide: { serverSide: {
writable: new WritableStream<Uint8Array>({ writable: new WritableStream<Uint8Array>({
......
...@@ -39,8 +39,7 @@ import { createDebugChannel } from '../debug-channel-server' ...@@ -39,8 +39,7 @@ import { createDebugChannel } from '../debug-channel-server'
// eslint-disable-next-line import/no-extraneous-dependencies // eslint-disable-next-line import/no-extraneous-dependencies
import { createFromNodeStream } from 'react-server-dom-webpack/client' import { createFromNodeStream } from 'react-server-dom-webpack/client'
// eslint-disable-next-line import/no-extraneous-dependencies // renderToReadableStream is now lazy-loaded conditionally below
import { renderToReadableStream } from 'react-server-dom-webpack/server'
const filterStackFrame = const filterStackFrame =
process.env.NODE_ENV !== 'production' process.env.NODE_ENV !== 'production'
...@@ -442,11 +441,61 @@ export async function collectStagedSegmentData( ...@@ -442,11 +441,61 @@ export async function collectStagedSegmentData(
cache.set(segmentPath, segmentCacheItem) cache.set(segmentPath, segmentCacheItem)
const segmentTask = async () => { const segmentTask = async () => {
const segmentDebugChannel = fullPageDebugChunks // When using node streams, skip debug channel at segment level to avoid
// issues with parallel debug channel bridges. Debug info is still captured
// at the combined payload level in createCombinedPayloadStream.
const segmentDebugChannel =
fullPageDebugChunks && !process.env.__NEXT_USE_NODE_STREAMS
? createDebugChannel() ? createDebugChannel()
: undefined : undefined
const segmentStream = renderToReadableStream( let segmentStream:
| ReadableStream<Uint8Array>
| import('node:stream').Readable
let streamIterator: AsyncIterable<Uint8Array>
if (process.env.__NEXT_USE_NODE_STREAMS) {
const { renderToFlightPipeableStream } =
require('../pipeable-stream-wrappers') as typeof import('../pipeable-stream-wrappers')
// eslint-disable-next-line import/no-extraneous-dependencies
const ComponentMod = require('react-server-dom-webpack/server.node') as typeof import('react-server-dom-webpack/server.node')
segmentStream = renderToFlightPipeableStream(
ComponentMod.renderToPipeableStream,
segmentData,
clientReferenceManifest.clientModules,
{
filterStackFrame,
debugChannel: segmentDebugChannel?.serverSide,
environmentName,
startTime,
onError(error: unknown) {
const digest = getDigestForWellKnownError(error)
if (digest) {
return digest
}
// We don't need to log the errors because we would have already done that
// when generating the original Flight stream for the whole page.
if (
process.env.NEXT_DEBUG_BUILD ||
process.env.__NEXT_VERBOSE_LOGGING
) {
const workStore = workAsyncStorage.getStore()
printDebugThrownValueForProspectiveRender(
error,
workStore?.route ?? 'unknown route',
Phase.InstantValidation
)
}
},
}
)
streamIterator = segmentStream
} else {
// eslint-disable-next-line import/no-extraneous-dependencies
const { renderToReadableStream } = require('react-server-dom-webpack/server') as typeof import('react-server-dom-webpack/server')
segmentStream = renderToReadableStream(
segmentData, segmentData,
clientReferenceManifest.clientModules, clientReferenceManifest.clientModules,
{ {
...@@ -475,11 +524,15 @@ export async function collectStagedSegmentData( ...@@ -475,11 +524,15 @@ export async function collectStagedSegmentData(
}, },
} }
) )
streamIterator = (
segmentStream as ReadableStream<Uint8Array>
).values()
}
await Promise.all([ await Promise.all([
// accumulate Flight chunks // accumulate Flight chunks
(async () => { (async () => {
for await (const chunk of segmentStream.values()) { for await (const chunk of streamIterator) {
writeChunk( writeChunk(
segmentCacheItem.chunks, segmentCacheItem.chunks,
controller.currentStage, controller.currentStage,
...@@ -671,7 +724,17 @@ export async function createCombinedPayloadStream( ...@@ -671,7 +724,17 @@ export async function createCombinedPayloadStream(
await scheduleInSequentialTasks( await scheduleInSequentialTasks(
() => { () => {
const stream = renderToReadableStream( let stream: ReadableStream<Uint8Array> | import('node:stream').Readable
let streamIterator: AsyncIterable<Uint8Array>
if (process.env.__NEXT_USE_NODE_STREAMS) {
const { renderToFlightPipeableStream } =
require('../pipeable-stream-wrappers') as typeof import('../pipeable-stream-wrappers')
// eslint-disable-next-line import/no-extraneous-dependencies
const ComponentMod = require('react-server-dom-webpack/server.node') as typeof import('react-server-dom-webpack/server.node')
stream = renderToFlightPipeableStream(
ComponentMod.renderToPipeableStream,
payload, payload,
clientReferenceManifest.clientModules, clientReferenceManifest.clientModules,
{ {
...@@ -699,11 +762,46 @@ export async function createCombinedPayloadStream( ...@@ -699,11 +762,46 @@ export async function createCombinedPayloadStream(
}, },
} }
) )
streamIterator = stream
} else {
// eslint-disable-next-line import/no-extraneous-dependencies
const { renderToReadableStream } = require('react-server-dom-webpack/server') as typeof import('react-server-dom-webpack/server')
stream = renderToReadableStream(
payload,
clientReferenceManifest.clientModules,
{
filterStackFrame,
debugChannel: debugChannel?.serverSide,
startTime,
onError(error: unknown) {
const digest = getDigestForWellKnownError(error)
if (digest) {
return digest
}
// We don't need to log the errors because we would have already done that
// when generating the original Flight stream for the whole page.
if (
process.env.NEXT_DEBUG_BUILD ||
process.env.__NEXT_VERBOSE_LOGGING
) {
const workStore = workAsyncStorage.getStore()
printDebugThrownValueForProspectiveRender(
error,
workStore?.route ?? 'unknown route',
Phase.InstantValidation
)
}
},
}
)
streamIterator = (stream as ReadableStream<Uint8Array>).values()
}
streamFinished = Promise.all([ streamFinished = Promise.all([
// Accumulate Flight chunks // Accumulate Flight chunks
(async () => { (async () => {
for await (const chunk of stream.values()) { for await (const chunk of streamIterator) {
allChunks.push(chunk) allChunks.push(chunk)
if (isRenderable) { if (isRenderable) {
renderableChunks.push(chunk) renderableChunks.push(chunk)
......
...@@ -149,6 +149,16 @@ export function renderToFlightPipeableStream( ...@@ -149,6 +149,16 @@ export function renderToFlightPipeableStream(
): Readable { ): Readable {
const { PassThrough } = getNodeStream() const { PassThrough } = getNodeStream()
const passthrough = new PassThrough() const passthrough = new PassThrough()
// React's renderToPipeableStream checks typeof debugChannel.write to find
// its debug destination. The web-shaped { writable: WritableStream } doesn't
// have .write() on the object, so convert to a Node Writable.
if (options?.debugChannel) {
const { toNodeDebugChannel } =
require('./debug-channel-server') as typeof import('./debug-channel-server')
options = { ...options, debugChannel: toNodeDebugChannel(options.debugChannel) }
}
const { pipe } = renderToPipeableStreamFn(model, webpackMap, options) const { pipe } = renderToPipeableStreamFn(model, webpackMap, options)
pipe(passthrough as unknown as Writable) pipe(passthrough as unknown as Writable)
return passthrough return passthrough
......
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