Unverified Commit 9b6e563f authored by Jimmy Lai's avatar Jimmy Lai Committed by GitHub

refactor(app-render): extract stream-ops and debug-channel modules (5/8) (#89858)

## Summary

Pure refactor: extract stream operations and debug-channel code from
`app-render.tsx` into separate compile-time switchable modules. Web-only
at this stage.

- **`stream-ops.web.ts`**: extracted web stream operations
(continueFizzStream, renderToFlightStream, renderToFizzStream, etc.)
- **`stream-ops.ts`**: re-export switcher (web-only for now, conditional
added in next PR)
- **`debug-channel-server.web.ts`**: extracted web debug channel
implementation
- **`debug-channel-server.ts`**: re-export switcher
- **`app-render.tsx`**: net reduction via imports from
stream-ops/debug-channel instead of inline
- **`node-web-streams-helper.ts`**: added
`createRuntimePrefetchTransformStream`

## Test plan

- [ ] `pnpm --filter=next types` passes
- [ ] Existing app-dir e2e tests pass (smoke test: `pnpm test-dev-turbo
test/e2e/app-dir/app/`)
- [ ] No runtime behavior changes: identical web stream paths

---------
Co-authored-by: 's avatarTim Neutkens <tim@timneutkens.nl>
parent f93a867d
...@@ -1068,5 +1068,6 @@ ...@@ -1068,5 +1068,6 @@
"1067": "The Next.js unhandled rejection filter is being installed more than once. This is a bug in Next.js.", "1067": "The Next.js unhandled rejection filter is being installed more than once. This is a bug in Next.js.",
"1068": "Expected workStore to be initialized", "1068": "Expected workStore to be initialized",
"1069": "Invariant: cache entry \"%s\" not found in dir \"%s\"", "1069": "Invariant: cache entry \"%s\" not found in dir \"%s\"",
"1070": "image of size %s could not be tracked by lru cache" "1070": "image of size %s could not be tracked by lru cache",
"1071": "toNodeDebugChannel cannot be used in edge/web runtime, this is a bug in the Next.js codebase"
} }
export type DebugChannelPair = { /**
serverSide: DebugChannelServer * Compile-time switcher for debug channel operations.
clientSide: DebugChannelClient *
} * Simple re-export from the web implementation.
* A future change will add a conditional branch for node streams.
export type DebugChannelServer = { */
readable?: ReadableStream<Uint8Array> export type {
writable: WritableStream<Uint8Array> DebugChannelPair,
} DebugChannelServer,
export type DebugChannelClient = { } from './debug-channel-server.web'
readable: ReadableStream<Uint8Array>
writable?: WritableStream<Uint8Array> export {
} createDebugChannel,
toNodeDebugChannel,
export function createDebugChannel(): DebugChannelPair | undefined { } from './debug-channel-server.web'
if (process.env.NODE_ENV === 'production') {
return undefined
}
let readableController: ReadableStreamDefaultController | undefined
let clientSideReadable = new ReadableStream<Uint8Array>({
start(controller) {
readableController = controller
},
})
return {
serverSide: {
writable: new WritableStream<Uint8Array>({
write(chunk) {
readableController?.enqueue(chunk)
},
close() {
readableController?.close()
},
abort(err) {
readableController?.error(err)
},
}),
},
clientSide: { readable: clientSideReadable },
}
}
/**
* Web debug channel implementation.
* Loaded by debug-channel-server.ts.
*/
// Types defined inline for now; will move to debug-channel-server.node.ts later.
export type DebugChannelPair = {
serverSide: DebugChannelServer
clientSide: DebugChannelClient
}
export type DebugChannelServer = {
readable?: ReadableStream<Uint8Array>
writable: WritableStream<Uint8Array>
}
type DebugChannelClient = {
readable: ReadableStream<Uint8Array>
writable?: WritableStream<Uint8Array>
}
export function createDebugChannel(): DebugChannelPair | undefined {
if (process.env.NODE_ENV === 'production') {
return undefined
}
return createWebDebugChannel()
}
export function createWebDebugChannel(): DebugChannelPair {
let readableController: ReadableStreamDefaultController | undefined
const clientSideReadable = new ReadableStream<Uint8Array>({
start(controller) {
readableController = controller
},
})
return {
serverSide: {
writable: new WritableStream<Uint8Array>({
write(chunk) {
readableController?.enqueue(chunk)
},
close() {
readableController?.close()
},
abort(err) {
readableController?.error(err)
},
}),
},
clientSide: { readable: clientSideReadable },
}
}
/**
* toNodeDebugChannel is a no-op stub on the web path.
* It should never be called in edge/web builds.
*/
export function toNodeDebugChannel(
_webDebugChannel: DebugChannelServer
): never {
throw new Error(
'toNodeDebugChannel cannot be used in edge/web runtime, this is a bug in the Next.js codebase'
)
}
/**
* Compile-time switcher for stream operations.
*
* PR2: Simple re-export from the web implementation.
* A future change will add a conditional branch for node streams.
*/
export type {
AnyStream,
ContinueFizzStreamOptions,
ContinueStaticPrerenderOptions,
ContinueStreamSharedOptions,
ContinueDynamicHTMLResumeOptions,
FlightComponentMod,
ServerPrerenderComponentMod,
FlightPayload,
FlightClientModules,
FlightRenderOptions,
FizzStreamResult,
} from './stream-ops.web'
export {
continueFizzStream,
continueStaticPrerender,
continueDynamicPrerender,
continueStaticFallbackPrerender,
continueDynamicHTMLResume,
streamToBuffer,
chainStreams,
createDocumentClosingStream,
processPrelude,
nodeReadableToWeb,
createInlinedDataStream,
createPendingStream,
createOnHeadersCallback,
resumeAndAbort,
renderToFlightStream,
streamToString,
renderToFizzStream,
resumeToFizzStream,
getServerPrerender,
getClientPrerender,
pipeRuntimePrefetchTransform,
} from './stream-ops.web'
/**
* Web stream operations for the rendering pipeline.
* Loaded by stream-ops.ts (re-export in this PR, conditional switcher later).
*/
import type { PostponedState, PrerenderOptions } from 'react-dom/static'
import { resume, renderToReadableStream } from 'react-dom/server'
import { prerender } from 'react-dom/static'
import {
renderToInitialFizzStream,
streamToString as webStreamToString,
createRuntimePrefetchTransformStream,
continueFizzStream as webContinueFizzStream,
} from '../stream-utils/node-web-streams-helper'
import { createInlinedDataReadableStream } from './use-flight-response'
// ---------------------------------------------------------------------------
// Shared types (web-only for now; will move to stream-ops.node.ts later)
// ---------------------------------------------------------------------------
type FlightRenderToReadableStream = (
model: any,
webpackMap: any,
options?: any
) => ReadableStream<Uint8Array>
export type AnyStream = ReadableStream<Uint8Array>
export type ContinueStreamSharedOptions = {
deploymentId: string | undefined
getServerInsertedHTML: () => Promise<string>
getServerInsertedMetadata: () => Promise<string>
}
export type ContinueFizzStreamOptions = ContinueStreamSharedOptions & {
inlinedDataStream: AnyStream | undefined
isStaticGeneration: boolean
allReady?: Promise<void>
validateRootLayout?: boolean
suffix?: string
}
export type ContinueStaticPrerenderOptions = ContinueStreamSharedOptions & {
inlinedDataStream: AnyStream
}
export type ContinueDynamicHTMLResumeOptions = ContinueStreamSharedOptions & {
inlinedDataStream: AnyStream
delayDataUntilFirstHtmlChunk: boolean
}
export type FlightComponentMod = {
renderToReadableStream: FlightRenderToReadableStream
}
export type ServerPrerenderComponentMod = {
prerender: (...args: any[]) => Promise<any>
}
export type FlightPayload = Parameters<FlightRenderToReadableStream>[0]
export type FlightClientModules = Parameters<FlightRenderToReadableStream>[1]
export type FlightRenderOptions = Parameters<FlightRenderToReadableStream>[2]
export type FizzStreamResult = {
stream: AnyStream
allReady: Promise<void>
abort?: (reason?: unknown) => void
}
// ---------------------------------------------------------------------------
// Continue functions
// ---------------------------------------------------------------------------
export {
continueStaticPrerender,
continueDynamicPrerender,
continueStaticFallbackPrerender,
continueDynamicHTMLResume,
streamToBuffer,
chainStreams,
createDocumentClosingStream,
} from '../stream-utils/node-web-streams-helper'
export { processPrelude } from './app-render-prerender-utils'
/**
* Wrapper for continueFizzStream that accepts AnyStream.
* The underlying implementation expects ReactDOMServerReadableStream but at
* the stream-ops boundary we only expose AnyStream.
*/
export function continueFizzStream(
renderStream: AnyStream,
opts: ContinueFizzStreamOptions
): Promise<ReadableStream<Uint8Array>> {
return webContinueFizzStream(renderStream as any, opts)
}
// Not available in web bundles
export const nodeReadableToWeb:
| ((readable: import('node:stream').Readable) => ReadableStream<Uint8Array>)
| undefined = undefined
// ---------------------------------------------------------------------------
// Composed helpers
// ---------------------------------------------------------------------------
export function createInlinedDataStream(
source: AnyStream,
nonce: string | undefined,
formState: unknown | null
): AnyStream {
return createInlinedDataReadableStream(
source as ReadableStream<Uint8Array>,
nonce,
formState
)
}
export function createPendingStream(): AnyStream {
return new ReadableStream<Uint8Array>()
}
export function createOnHeadersCallback(
appendHeader: (key: string, value: string) => void
): NonNullable<PrerenderOptions['onHeaders']> {
return (headers: Headers) => {
headers.forEach((value, key) => {
appendHeader(key, value)
})
}
}
export async function resumeAndAbort(
element: React.ReactElement,
postponed: PostponedState | null,
opts: Parameters<typeof resume>[2] & { nonce?: string }
): Promise<AnyStream> {
return resume(
element,
postponed as PostponedState,
opts as Parameters<typeof resume>[2]
)
}
export function renderToFlightStream(
ComponentMod: FlightComponentMod,
payload: FlightPayload,
clientModules: FlightClientModules,
opts: FlightRenderOptions,
runInContext?: <T>(fn: () => T) => T
): AnyStream {
const run: <T>(fn: () => T) => T = runInContext ?? ((fn) => fn())
return run(() =>
ComponentMod.renderToReadableStream(payload, clientModules, opts)
)
}
export async function streamToString(stream: AnyStream): Promise<string> {
return webStreamToString(stream as ReadableStream<Uint8Array>)
}
export async function renderToFizzStream(
element: React.ReactElement,
streamOptions: any,
runInContext?: <T>(fn: () => T) => T
): Promise<FizzStreamResult> {
const run: <T>(fn: () => T) => T = runInContext ?? ((fn) => fn())
const stream = await run(() =>
renderToInitialFizzStream({
ReactDOMServer: { renderToReadableStream },
element,
streamOptions,
})
)
return { stream, allReady: stream.allReady, abort: undefined }
}
export async function resumeToFizzStream(
element: React.ReactElement,
postponedState: PostponedState,
streamOptions: any,
runInContext?: <T>(fn: () => T) => T
): Promise<FizzStreamResult> {
const run: <T>(fn: () => T) => T = runInContext ?? ((fn) => fn())
const stream = await run(() => resume(element, postponedState, streamOptions))
return { stream, allReady: stream.allReady, abort: undefined }
}
export function getServerPrerender(
ComponentMod: ServerPrerenderComponentMod
): (...args: any[]) => any {
return ComponentMod.prerender
}
export const getClientPrerender: typeof import('react-dom/static').prerender =
prerender
export function pipeRuntimePrefetchTransform(
stream: AnyStream,
sentinel: number,
isPartial: boolean,
staleTime: number
): AnyStream {
return (stream as ReadableStream<Uint8Array>).pipeThrough(
createRuntimePrefetchTransformStream(sentinel, isPartial, staleTime)
)
}
...@@ -1038,3 +1038,119 @@ export async function continueDynamicHTMLResume( ...@@ -1038,3 +1038,119 @@ export async function continueDynamicHTMLResume(
export function createDocumentClosingStream(): ReadableStream<Uint8Array> { export function createDocumentClosingStream(): ReadableStream<Uint8Array> {
return streamFromString(CLOSE_TAG) return streamFromString(CLOSE_TAG)
} }
// ---------------------------------------------------------------------------
// Runtime prefetch transform (Web streams)
// ---------------------------------------------------------------------------
/**
* Web TransformStream that replaces the runtime prefetch sentinel in an RSC
* payload stream: `[<sentinel>]` -> `[<isPartial>,<staleTime>]`.
*
* This is the web equivalent of createRuntimePrefetchNodeTransform
* in node-stream-helpers.ts.
*/
export function createRuntimePrefetchTransformStream(
sentinel: number,
isPartial: boolean,
staleTime: number
): TransformStream<Uint8Array, Uint8Array> {
const enc = new TextEncoder()
// Search for: [<sentinel>]
// Replace with: [<isPartial>,<staleTime>]
const search = enc.encode(`[${sentinel}]`)
const first = search[0]
const replace = enc.encode(`[${isPartial},${staleTime}]`)
const searchLen = search.length
let currentChunk: Uint8Array | null = null
let found = false
function processChunk(
controller: TransformStreamDefaultController<Uint8Array>,
nextChunk: null | Uint8Array
) {
if (found) {
if (nextChunk) {
controller.enqueue(nextChunk)
}
return
}
if (currentChunk) {
// We can't search past the index that can contain a full match
let exclusiveUpperBound = currentChunk.length - (searchLen - 1)
if (nextChunk) {
// If we have any overflow bytes we can search up to the chunk's final byte
exclusiveUpperBound += Math.min(nextChunk.length, searchLen - 1)
}
if (exclusiveUpperBound < 1) {
// we can't match the current chunk.
controller.enqueue(currentChunk)
currentChunk = nextChunk // advance so we don't process this chunk again
return
}
let currentIndex = currentChunk.indexOf(first)
// check the current candidate match if it is within the bounds of our search space for the currentChunk
candidateLoop: while (
-1 < currentIndex &&
currentIndex < exclusiveUpperBound
) {
// We already know index 0 matches because we used indexOf to find the candidateIndex so we start at index 1
let matchIndex = 1
while (matchIndex < searchLen) {
const candidateIndex = currentIndex + matchIndex
const candidateValue =
candidateIndex < currentChunk.length
? currentChunk[candidateIndex]
: // if we ever hit this condition it is because there is a nextChunk we can read from
nextChunk![candidateIndex - currentChunk.length]
if (candidateValue !== search[matchIndex]) {
// No match, reset and continue the search from the next position
currentIndex = currentChunk.indexOf(first, currentIndex + 1)
continue candidateLoop
}
matchIndex++
}
// We found a complete match. currentIndex is our starting point to replace the value.
found = true
// enqueue everything up to the match
controller.enqueue(currentChunk.subarray(0, currentIndex))
// enqueue the replacement value
controller.enqueue(replace)
// If there are bytes in the currentChunk after the match enqueue them
if (currentIndex + searchLen < currentChunk.length) {
controller.enqueue(currentChunk.slice(currentIndex + searchLen))
}
// If we have a next chunk we enqueue it now
if (nextChunk) {
// if replacement spills over to the next chunk we first exclude the replaced bytes
const overflowBytes = currentIndex + searchLen - currentChunk.length
const truncatedChunk =
overflowBytes > 0 ? nextChunk!.subarray(overflowBytes) : nextChunk
controller.enqueue(truncatedChunk)
}
// We are now in found mode and don't need to track currentChunk anymore
currentChunk = null
return
}
// No match found in this chunk, emit it and wait for the next one
controller.enqueue(currentChunk)
}
// Advance to the next chunk
currentChunk = nextChunk
}
return new TransformStream<Uint8Array, Uint8Array>({
transform(chunk, controller) {
processChunk(controller, chunk)
},
flush(controller) {
processChunk(controller, null)
},
})
}
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