Unverified Commit 0accb03c authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Use React's debug channel to transport debug info via WebSocket connection (#82748)

In dev mode, React is sending debug info (owners, stacks, console logs
etc.) from the server to the client so that they can be displayed in dev
tools. By default, this info is sent as part of the main RSC payload
(inlined into the HTML, or fetched after interaction). With this PR,
we're now transporting the debug info in a separate debug channel. This
channel currently consists of a unidirectional stream (writable on the
server, readable in the client) that is serialized as binary WebSocket
messages, which are sent through the existing WebSocket connection that
Next.js uses for HMR messages etc.

In a follow up, we will also implement the return channel (writable in
the client, readable on the server). This allows the client to retrieve
debug info lazily and on demand during inspection/introspection.

One benefit of this approach is, that it will allow us to change our
dynamic validation strategy. We should then be able to tee and cut off
the dynamic RSC stream at different points in time (representing the
static prerender, runtime prerender, and dynamic render stages), while
still letting the complete debug info stream in through the separate
channel. This allows us to show the same dynamic validation error
details as before, while reducing the number of renders needed to
accomplish that.

For dogfooding purposes, the feature can be disabled by setting
`experimental.reactDebugChannel` to `false`, in case of unexpected
regressions in dev mode.

### An implementation note on the request ID handling

On the server, at the beginning of the rendering process, we determine a
`requestId` and an `htmlRequestId`.

1. The `requestId` is a UUID that's newly generated for each incoming
request.
2. The `htmlRequestId` is one of two things:
    1. For the HTML request, it's the same as the `requestId`.
2. For subsequent RSC requests (for navigations or server actions), it's
the ID of the HTML document from where the request originates. It is
sent as the `x-nextjs-html-request-id` request header.

The HTML request ID is used to identify connected WebSocket clients.
It's sent to the browser as the global `__next_r` variable in the script
tag that also includes the initial RSC instructions. The browser sends
it back to the server as `id` query param of the WebSocket request. On
the server, we store the clients by HTML request ID. When debug chunks
are sent to the browser, we use the HTML request ID to look up the
correct client. (There's only one client per browser tab/window.)

In the browser, we create a debug channel for each request, and we store
them keyed by request ID. For the HTML request, the request ID from
`__next_r` is used as key. For the RSC requests, the `requestId` is
received as `x-nextjs-request-id` response header, and used as key. The
server sends the current request ID as part of the WebSocket message to
the browser, so that the chunks can be enqueued into the correct debug
channel.

closes NAR-310
parent 437e5ef2
......@@ -801,5 +801,12 @@
"800": "`experimental.rdcForNavigations` is enabled, but `experimental.ppr` is not.",
"801": "> `pages` and `app` directories should be under the same folder",
"802": "Image with src \"%s\" has both \"preload\" and \"priority\" properties. Only \"preload\" should be used.",
"803": "Image with src \"%s\" has both \"preload\" and \"loading='lazy'\" properties. Only one should be used."
"803": "Image with src \"%s\" has both \"preload\" and \"loading='lazy'\" properties. Only one should be used.",
"804": "Did not start HotReloaderWebpack.",
"805": "Request ID is too long for the binary HMR message.",
"806": "Expected a request ID to be defined for the document via self.__next_r.",
"807": "Expected a %s response header.",
"808": "Invalid binary HMR message: insufficient data (expected %s bytes, got %s)",
"809": "Invalid binary HMR message of type %s",
"810": "React debug channel stream error"
}
......@@ -528,6 +528,7 @@ export async function handler(
serverActionsManifest,
clientReferenceManifest,
setIsrStatus: routerServerContext?.setIsrStatus,
setReactDebugChannel: routerServerContext?.setReactDebugChannel,
dir:
process.env.NEXT_RUNTIME === 'nodejs'
......
......@@ -53,6 +53,10 @@ type NextFlight = Omit<Array<FlightSegment>, 'push'> & {
declare global {
// If you're working in a browser environment
interface Window {
/**
* request ID, dev-only
*/
__next_r?: string
__next_f: NextFlight
}
}
......@@ -154,9 +158,20 @@ const readable = new ReadableStream({
},
})
let debugChannel:
| { readable?: ReadableStream; writable?: WritableStream }
| undefined
if (process.env.NODE_ENV !== 'production' && typeof window !== 'undefined') {
const { createDebugChannel } =
require('./dev/debug-channel') as typeof import('./dev/debug-channel')
debugChannel = createDebugChannel(undefined)
}
const initialServerResponse = createFromReadableStream<InitialRSCPayload>(
readable,
{ callServer, findSourceMapURL }
{ callServer, findSourceMapURL, debugChannel }
)
function ServerRoot({
......
......@@ -32,3 +32,5 @@ export const NEXT_REWRITTEN_PATH_HEADER = 'x-nextjs-rewritten-path' as const
export const NEXT_REWRITTEN_QUERY_HEADER = 'x-nextjs-rewritten-query' as const
export const NEXT_IS_PRERENDER_HEADER = 'x-nextjs-prerender' as const
export const NEXT_ACTION_NOT_FOUND_HEADER = 'x-nextjs-action-not-found' as const
export const NEXT_REQUEST_ID_HEADER = 'x-nextjs-request-id' as const
export const NEXT_HTML_REQUEST_ID_HEADER = 'x-nextjs-html-request-id' as const
......@@ -20,6 +20,7 @@ import {
NEXT_HMR_REFRESH_HEADER,
NEXT_DID_POSTPONE_HEADER,
NEXT_ROUTER_STALE_TIME_HEADER,
NEXT_HTML_REQUEST_ID_HEADER,
} from '../app-router-headers'
import { callServer } from '../../app-call-server'
import { findSourceMapURL } from '../../app-find-source-map-url'
......@@ -36,6 +37,16 @@ import { urlToUrlWithoutFlightMarker } from '../../route-params'
const createFromReadableStream =
createFromReadableStreamBrowser as (typeof import('react-server-dom-webpack/client.browser'))['createFromReadableStream']
let createDebugChannel:
| typeof import('../../dev/debug-channel').createDebugChannel
| undefined
if (process.env.NODE_ENV !== 'production') {
createDebugChannel = (
require('../../dev/debug-channel') as typeof import('../../dev/debug-channel')
).createDebugChannel
}
export interface FetchServerResponseOptions {
readonly flightRouterState: FlightRouterState
readonly nextUrl: string | null
......@@ -62,6 +73,7 @@ export type RequestHeaders = {
[NEXT_HMR_REFRESH_HEADER]?: '1'
// A header that is only added in test mode to assert on fetch priority
'Next-Test-Fetch-Priority'?: RequestInit['priority']
[NEXT_HTML_REQUEST_ID_HEADER]?: string // dev-only
}
function doMpaNavigation(url: string): FetchServerResponseResult {
......@@ -214,7 +226,8 @@ export async function fetchServerResponse(
? createUnclosingPrefetchStream(res.body)
: res.body
const response = await (createFromNextReadableStream(
flightStream
flightStream,
res.headers
) as Promise<NavigationFlightResponse>)
if (getAppBuildId() !== response.b) {
......@@ -283,6 +296,10 @@ export async function createFetch(
headers['x-deployment-id'] = process.env.NEXT_DEPLOYMENT_ID
}
if (process.env.NODE_ENV !== 'production' && self.__next_r) {
headers[NEXT_HTML_REQUEST_ID_HEADER] = self.__next_r
}
const fetchOptions: RequestInit = {
// Backwards compat for older browsers. `same-origin` is the default in modern browsers.
credentials: 'same-origin',
......@@ -383,11 +400,13 @@ export async function createFetch(
}
export function createFromNextReadableStream(
flightStream: ReadableStream<Uint8Array>
flightStream: ReadableStream<Uint8Array>,
responseHeaders: Headers
): Promise<unknown> {
return createFromReadableStream(flightStream, {
callServer,
findSourceMapURL,
debugChannel: createDebugChannel && createDebugChannel(responseHeaders),
})
}
......
......@@ -8,6 +8,7 @@ import {
ACTION_HEADER,
NEXT_ACTION_NOT_FOUND_HEADER,
NEXT_IS_PRERENDER_HEADER,
NEXT_HTML_REQUEST_ID_HEADER,
NEXT_ROUTER_STATE_TREE_HEADER,
NEXT_URL,
RSC_CONTENT_TYPE_HEADER,
......@@ -60,6 +61,16 @@ import { revalidateEntireCache } from '../../segment-cache'
const createFromFetch =
createFromFetchBrowser as (typeof import('react-server-dom-webpack/client.browser'))['createFromFetch']
let createDebugChannel:
| typeof import('../../../dev/debug-channel').createDebugChannel
| undefined
if (process.env.NODE_ENV !== 'production') {
createDebugChannel = (
require('../../../dev/debug-channel') as typeof import('../../../dev/debug-channel')
).createDebugChannel
}
type FetchServerActionResult = {
redirectLocation: URL | undefined
redirectType: RedirectType | undefined
......@@ -89,27 +100,27 @@ async function fetchServerAction(
const body = await encodeReply(usedArgs, { temporaryReferences })
const res = await fetch(state.canonicalUrl, {
method: 'POST',
headers: {
Accept: RSC_CONTENT_TYPE_HEADER,
[ACTION_HEADER]: actionId,
[NEXT_ROUTER_STATE_TREE_HEADER]: prepareFlightRouterStateForRequest(
state.tree
),
...(process.env.NEXT_DEPLOYMENT_ID
? {
'x-deployment-id': process.env.NEXT_DEPLOYMENT_ID,
}
: {}),
...(nextUrl
? {
[NEXT_URL]: nextUrl,
}
: {}),
},
body,
})
const headers: Record<string, string> = {
Accept: RSC_CONTENT_TYPE_HEADER,
[ACTION_HEADER]: actionId,
[NEXT_ROUTER_STATE_TREE_HEADER]: prepareFlightRouterStateForRequest(
state.tree
),
}
if (process.env.NEXT_DEPLOYMENT_ID) {
headers['x-deployment-id'] = process.env.NEXT_DEPLOYMENT_ID
}
if (nextUrl) {
headers[NEXT_URL] = nextUrl
}
if (process.env.NODE_ENV !== 'production' && self.__next_r) {
headers[NEXT_HTML_REQUEST_ID_HEADER] = self.__next_r
}
const res = await fetch(state.canonicalUrl, { method: 'POST', headers, body })
// Handle server actions that the server didn't recognize.
const unrecognizedActionHeader = res.headers.get(NEXT_ACTION_NOT_FOUND_HEADER)
......@@ -176,10 +187,16 @@ async function fetchServerAction(
let actionResult: FetchServerActionResult['actionResult']
let actionFlightData: FetchServerActionResult['actionFlightData']
if (isRscResponse) {
const response: ActionFlightResponse = await createFromFetch(
Promise.resolve(res),
{ callServer, findSourceMapURL, temporaryReferences }
{
callServer,
findSourceMapURL,
temporaryReferences,
debugChannel: createDebugChannel && createDebugChannel(res.headers),
}
)
// An internal redirect can send an RSC response, but does not have a useful `actionResult`.
......
......@@ -1431,7 +1431,8 @@ export async function fetchRouteOnCacheMiss(
}
)
const serverData = await (createFromNextReadableStream(
prefetchStream
prefetchStream,
response.headers
) as Promise<RootTreePrefetch>)
if (serverData.buildId !== getAppBuildId()) {
// The server build does not match the client. Treat as a 404. During
......@@ -1482,7 +1483,8 @@ export async function fetchRouteOnCacheMiss(
}
)
const serverData = await (createFromNextReadableStream(
prefetchStream
prefetchStream,
response.headers
) as Promise<NavigationFlightResponse>)
if (serverData.b !== getAppBuildId()) {
// The server build does not match the client. Treat as a 404. During
......@@ -1627,7 +1629,8 @@ export async function fetchSegmentOnCacheMiss(
}
)
const serverData = await (createFromNextReadableStream(
prefetchStream
prefetchStream,
response.headers
) as Promise<SegmentPrefetch>)
if (serverData.buildId !== getAppBuildId()) {
// The server build does not match the client. Treat as a 404. During
......@@ -1746,7 +1749,8 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
}
)
const serverData = await (createFromNextReadableStream(
prefetchStream
prefetchStream,
response.headers
) as Promise<NavigationFlightResponse>)
const isResponsePartial =
......
import { NEXT_REQUEST_ID_HEADER } from '../components/app-router-headers'
import { InvariantError } from '../../shared/lib/invariant-error'
export interface DebugChannelReadableWriterPair {
readonly readable: ReadableStream<Uint8Array>
readonly writer: WritableStreamDefaultWriter<Uint8Array>
}
const pairs = new Map<string, DebugChannelReadableWriterPair>()
export function getOrCreateDebugChannelReadableWriterPair(
requestId: string
): DebugChannelReadableWriterPair {
let pair = pairs.get(requestId)
if (!pair) {
const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>()
pair = { readable, writer: writable.getWriter() }
pairs.set(requestId, pair)
pair.writer.closed.finally(() => pairs.delete(requestId))
}
return pair
}
export function createDebugChannel(responseHeaders: Headers | undefined): {
writable?: WritableStream
readable?: ReadableStream
} {
let requestId: string | undefined
if (responseHeaders) {
requestId = responseHeaders.get(NEXT_REQUEST_ID_HEADER) ?? undefined
if (!requestId) {
throw new InvariantError(
`Expected a ${JSON.stringify(NEXT_REQUEST_ID_HEADER)} response header.`
)
}
} else {
requestId = self.__next_r
if (!requestId) {
throw new InvariantError(
`Expected a request ID to be defined for the document via self.__next_r.`
)
}
}
const { readable } = getOrCreateDebugChannelReadableWriterPair(requestId)
return { readable }
}
......@@ -28,6 +28,7 @@ import {
type GlobalErrorState,
} from '../../../components/app-router-instance'
import { InvariantError } from '../../../../shared/lib/invariant-error'
import { getOrCreateDebugChannelReadableWriterPair } from '../../debug-channel'
export interface StaticIndicatorState {
pathname: string | null
......@@ -451,6 +452,23 @@ export function processMessage(
dispatcher.onDevToolsConfig(message.data)
return
}
case HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK: {
const { requestId, chunk } = message
const { writer } = getOrCreateDebugChannelReadableWriterPair(requestId)
if (chunk) {
writer.ready.then(() => writer.write(chunk)).catch(console.error)
} else {
// A null chunk signals that no more chunks will be sent, which allows
// us to close the writer.
// TODO: Revisit this cleanup logic when we integrate the return channel
// that keeps the connection open to be able to lazily retrieve debug
// objects.
writer.ready.then(() => writer.close()).catch(console.error)
}
return
}
case HMR_MESSAGE_SENT_TO_BROWSER.MIDDLEWARE_CHANGES:
case HMR_MESSAGE_SENT_TO_BROWSER.CLIENT_CHANGES:
case HMR_MESSAGE_SENT_TO_BROWSER.SERVER_ONLY_CHANGES:
......
import { useContext, useEffect } from 'react'
import { GlobalLayoutRouterContext } from '../../../../shared/lib/app-router-context.shared-runtime'
import { getSocketUrl } from '../get-socket-url'
import type { TurbopackMessageSentToBrowser } from '../../../../server/dev/hot-reloader-types'
import {
HMR_MESSAGE_SENT_TO_BROWSER,
type HmrMessageSentToBrowser,
type TurbopackMessageSentToBrowser,
} from '../../../../server/dev/hot-reloader-types'
import { reportInvalidHmrMessage } from '../shared'
import {
performFullReload,
......@@ -18,8 +22,17 @@ export function createWebSocket(
assetPrefix: string,
staticIndicatorState: StaticIndicatorState
) {
const url = getSocketUrl(assetPrefix)
const webSocket = new window.WebSocket(`${url}/_next/webpack-hmr`)
if (!self.__next_r) {
throw new InvariantError(
`Expected a request ID to be defined for the document via self.__next_r.`
)
}
const webSocket = new window.WebSocket(
`${getSocketUrl(assetPrefix)}/_next/webpack-hmr?id=${self.__next_r}`
)
webSocket.binaryType = 'arraybuffer'
if (isTerminalLoggingEnabled) {
webSocket.addEventListener('open', () => {
......@@ -37,7 +50,11 @@ export function createWebSocket(
webSocket.addEventListener('message', (event) => {
try {
const message = JSON.parse(event.data)
const message: HmrMessageSentToBrowser =
event.data instanceof ArrayBuffer
? parseBinaryMessage(event.data)
: JSON.parse(event.data)
processMessage(
message,
sendMessage,
......@@ -121,3 +138,47 @@ export function useWebSocketPing(webSocket: WebSocket | undefined) {
return () => clearInterval(interval)
}, [tree, webSocket])
}
const textDecoder = new TextDecoder()
function parseBinaryMessage(data: ArrayBuffer): HmrMessageSentToBrowser {
assertByteLength(data, 1)
const view = new DataView(data)
const messageType = view.getUint8(0)
switch (messageType) {
case HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK: {
assertByteLength(data, 2)
const requestIdLength = view.getUint8(1)
assertByteLength(data, 2 + requestIdLength)
const requestId = textDecoder.decode(
new Uint8Array(data, 2, requestIdLength)
)
const chunk =
data.byteLength > 2 + requestIdLength
? new Uint8Array(data, 2 + requestIdLength)
: null
return {
type: HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK,
requestId,
chunk,
}
}
default: {
throw new InvariantError(
`Invalid binary HMR message of type ${messageType}`
)
}
}
}
function assertByteLength(data: ArrayBuffer, expectedLength: number) {
if (data.byteLength < expectedLength) {
throw new InvariantError(
`Invalid binary HMR message: insufficient data (expected ${expectedLength} bytes, got ${data.byteLength})`
)
}
}
......@@ -385,6 +385,9 @@ function processMessage(message: HmrMessageSentToBrowser) {
case HMR_MESSAGE_SENT_TO_BROWSER.DEVTOOLS_CONFIG:
dispatcher.onDevToolsConfig(message.data)
break
case HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK:
// Only relevant for app router.
break
case HMR_MESSAGE_SENT_TO_BROWSER.MIDDLEWARE_CHANGES:
case HMR_MESSAGE_SENT_TO_BROWSER.CLIENT_CHANGES:
case HMR_MESSAGE_SENT_TO_BROWSER.SERVER_ONLY_CHANGES:
......
......@@ -120,6 +120,7 @@ export function pageBootstrap(assetPrefix: string) {
case HMR_MESSAGE_SENT_TO_BROWSER.TURBOPACK_CONNECTED:
case HMR_MESSAGE_SENT_TO_BROWSER.ISR_MANIFEST:
case HMR_MESSAGE_SENT_TO_BROWSER.DEVTOOLS_CONFIG:
case HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK:
// Most of these action types are handled in
// src/client/dev/hot-reloader/pages/hot-reloader-pages.ts and
// src/client/dev/hot-reloader/app/hot-reloader-app.tsx
......
......@@ -94,6 +94,11 @@ export interface RenderOptsPartial {
isOnDemandRevalidate?: boolean
isPossibleServerAction?: boolean
setIsrStatus?: (key: string, value: boolean) => void
setReactDebugChannel?: (
debugChannel: { readable: ReadableStream<Uint8Array> },
htmlRequestId: string,
requestId: string
) => void
isRevalidate?: boolean
nextExport?: boolean
nextConfigOutput?: 'standalone' | 'export'
......
......@@ -28,8 +28,9 @@ const findSourceMapURL =
*/
export function useFlightStream<T>(
flightStream: BinaryStreamOf<T>,
debugStream: ReadableStream<Uint8Array> | undefined,
clientReferenceManifest: DeepReadonly<ClientReferenceManifest>,
nonce?: string
nonce: string | undefined
): Promise<T> {
const response = flightResponses.get(flightStream)
......@@ -52,6 +53,7 @@ export function useFlightStream<T>(
serverModuleMap: null,
},
nonce,
debugChannel: debugStream ? { readable: debugStream } : undefined,
})
// Edge pages are never prerendered so they necessarily cannot have a workUnitStore type
......@@ -101,7 +103,8 @@ export function useFlightStream<T>(
export function createInlinedDataReadableStream(
flightStream: ReadableStream<Uint8Array>,
nonce: string | undefined,
formState: unknown | null
formState: unknown | null,
requestId: string
): ReadableStream<Uint8Array> {
const startScriptTag = nonce
? `<script nonce=${JSON.stringify(nonce)}>`
......@@ -114,7 +117,12 @@ export function createInlinedDataReadableStream(
type: 'bytes',
start(controller) {
try {
writeInitialInstructions(controller, startScriptTag, formState)
writeInitialInstructions(
controller,
startScriptTag,
formState,
requestId
)
} catch (error) {
// during encoding or enqueueing forward the error downstream
controller.error(error)
......@@ -158,27 +166,25 @@ export function createInlinedDataReadableStream(
function writeInitialInstructions(
controller: ReadableStreamDefaultController,
scriptStart: string,
formState: unknown | null
formState: unknown | null,
requestId: string
) {
let scriptContents = `(self.__next_f=self.__next_f||[]).push(${htmlEscapeJsonString(
JSON.stringify([INLINE_FLIGHT_PAYLOAD_BOOTSTRAP])
)})`
if (process.env.NODE_ENV !== 'production') {
// The request ID is only needed in development mode.
scriptContents = `self.__next_r=${JSON.stringify(requestId)};${scriptContents}`
}
if (formState != null) {
controller.enqueue(
encoder.encode(
`${scriptStart}(self.__next_f=self.__next_f||[]).push(${htmlEscapeJsonString(
JSON.stringify([INLINE_FLIGHT_PAYLOAD_BOOTSTRAP])
)});self.__next_f.push(${htmlEscapeJsonString(
JSON.stringify([INLINE_FLIGHT_PAYLOAD_FORM_STATE, formState])
)})</script>`
)
)
} else {
controller.enqueue(
encoder.encode(
`${scriptStart}(self.__next_f=self.__next_f||[]).push(${htmlEscapeJsonString(
JSON.stringify([INLINE_FLIGHT_PAYLOAD_BOOTSTRAP])
)})</script>`
)
)
scriptContents += `;self.__next_f.push(${htmlEscapeJsonString(
JSON.stringify([INLINE_FLIGHT_PAYLOAD_FORM_STATE, formState])
)})`
}
controller.enqueue(encoder.encode(`${scriptStart}${scriptContents}</script>`))
}
function writeFlightDataInstruction(
......
......@@ -499,6 +499,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
})
.optional(),
]),
reactDebugChannel: z.boolean().optional(),
staticGenerationRetryCount: z.number().int().optional(),
staticGenerationMaxConcurrency: z.number().int().optional(),
staticGenerationMinPagesPerWorker: z.number().int().optional(),
......
......@@ -849,6 +849,14 @@ export interface ExperimentalConfig {
*/
reactCompiler?: boolean | ReactCompilerOptions
/**
* When enabled, in dev mode, Next.js will send React's debug info through the
* WebSocket connection, instead of including it in the main RSC payload.
*
* @default true
*/
reactDebugChannel?: boolean
/**
* The number of times to retry static generation (per page) before giving up.
*/
......@@ -1626,6 +1634,7 @@ export const defaultConfig = Object.freeze({
},
allowDevelopmentBuild: undefined,
reactCompiler: undefined,
reactDebugChannel: true,
staticGenerationRetryCount: undefined,
serverComponentsHmrCache: true,
staticGenerationMaxConcurrency: 8,
......
import { createBufferedTransformStream } from '../stream-utils/node-web-streams-helper'
import {
HMR_MESSAGE_SENT_TO_BROWSER,
type HmrMessageSentToBrowser,
} from './hot-reloader-types'
export interface ReactDebugChannelForBrowser {
readonly readable: ReadableStream<Uint8Array>
// Might also get a writable stream as return channel in the future.
}
const reactDebugChannelsByRequestId = new Map<
string,
ReactDebugChannelForBrowser
>()
export function connectReactDebugChannel(
requestId: string,
sendToClient: (message: HmrMessageSentToBrowser) => void
) {
const debugChannel = reactDebugChannelsByRequestId.get(requestId)
if (!debugChannel) {
return
}
const reader = debugChannel.readable
.pipeThrough(
// We're sending the chunks in batches to reduce overhead in the browser.
createBufferedTransformStream({ maxBufferByteLength: 128 * 1024 })
)
.getReader()
const stop = () => {
sendToClient({
type: HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK,
requestId,
chunk: null,
})
reactDebugChannelsByRequestId.delete(requestId)
}
const onError = (err: unknown) => {
console.error(new Error('React debug channel stream error', { cause: err }))
stop()
}
const progress = (entry: ReadableStreamReadResult<Uint8Array>) => {
if (entry.done) {
stop()
} else {
sendToClient({
type: HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK,
requestId,
chunk: entry.value,
})
reader.read().then(progress, onError)
}
}
reader.read().then(progress, onError)
}
export function setReactDebugChannel(
requestId: string,
debugChannel: ReactDebugChannelForBrowser
) {
reactDebugChannelsByRequestId.set(requestId, debugChannel)
}
export function deleteReactDebugChannel(requestId: string) {
reactDebugChannelsByRequestId.delete(requestId)
}
......@@ -29,6 +29,7 @@ import type { VersionInfo } from './parse-version-info'
import type { HmrMessageSentToBrowser } from './hot-reloader-types'
import { HMR_MESSAGE_SENT_TO_BROWSER } from './hot-reloader-types'
import { devIndicatorServerState } from './dev-indicator-server-state'
import { createBinaryHmrMessageData } from './messages'
function isMiddlewareStats(stats: webpack.Stats) {
for (const key of stats.compilation.entrypoints.keys()) {
......@@ -68,36 +69,10 @@ function getStatsForSyncEvent(
return serverStats.ts > clientStats.ts ? serverStats.stats : clientStats.stats
}
class EventStream {
clients: Set<ws>
constructor() {
this.clients = new Set()
}
close() {
for (const wsClient of this.clients) {
// it's okay to not cleanly close these websocket connections, this is dev
wsClient.terminate()
}
this.clients.clear()
}
handler(client: ws) {
this.clients.add(client)
client.addEventListener('close', () => {
this.clients.delete(client)
})
}
publish(message: any) {
for (const wsClient of this.clients) {
wsClient.send(JSON.stringify(message))
}
}
}
export class WebpackHotMiddleware {
eventStream: EventStream
private clients = new Set<ws>()
private clientsByRequestId: Map<string, ws> = new Map()
clientLatestStats: { ts: number; stats: webpack.Stats } | null
middlewareLatestStats: { ts: number; stats: webpack.Stats } | null
serverLatestStats: { ts: number; stats: webpack.Stats } | null
......@@ -112,7 +87,6 @@ export class WebpackHotMiddleware {
devtoolsFrontendUrl: string | undefined,
devToolsConfig: DevToolsConfig
) {
this.eventStream = new EventStream()
this.clientLatestStats = null
this.middlewareLatestStats = null
this.serverLatestStats = null
......@@ -198,9 +172,22 @@ export class WebpackHotMiddleware {
* and we still want to show the client overlay with the error while
* the error page should be rendered just fine.
*/
onHMR = (client: ws) => {
onHMR = (client: ws, requestId: string | null) => {
if (this.closed) return
this.eventStream.handler(client)
this.clients.add(client)
if (requestId) {
this.clientsByRequestId.set(requestId, client)
}
client.addEventListener('close', () => {
this.clients.delete(client)
if (requestId) {
this.clientsByRequestId.delete(requestId)
}
})
const syncStats = getStatsForSyncEvent(
this.clientLatestStats,
......@@ -250,15 +237,56 @@ export class WebpackHotMiddleware {
})
}
getClient = (requestId: string): ws | undefined => {
return this.clientsByRequestId.get(requestId)
}
publishToClient = (client: ws, message: HmrMessageSentToBrowser) => {
if (this.closed) {
return
}
const data =
typeof message.type === 'number'
? createBinaryHmrMessageData(message)
: JSON.stringify(message)
client.send(data)
}
publish = (message: HmrMessageSentToBrowser) => {
if (this.closed) return
this.eventStream.publish(message)
if (this.closed) {
return
}
for (const wsClient of this.clients) {
this.publishToClient(wsClient, message)
}
}
close = () => {
if (this.closed) return
if (this.closed) {
return
}
// Can't remove compiler plugins, so we just set a flag and noop if closed
// https://github.com/webpack/tapable/issues/32#issuecomment-350644466
this.closed = true
this.eventStream.close()
for (const wsClient of this.clients) {
// it's okay to not cleanly close these websocket connections, this is dev
wsClient.terminate()
}
this.clients.clear()
this.clientsByRequestId.clear()
}
deleteClient = (client: ws, requestId: string | null) => {
this.clients.delete(client)
if (requestId) {
this.clientsByRequestId.delete(requestId)
}
}
}
......@@ -73,7 +73,10 @@ import {
getEntryKey,
splitEntryKey,
} from '../../shared/lib/turbopack/entry-key'
import { FAST_REFRESH_RUNTIME_RELOAD } from './messages'
import {
createBinaryHmrMessageData,
FAST_REFRESH_RUNTIME_RELOAD,
} from './messages'
import { generateEncryptionKeyBase64 } from '../app-render/encryption-utils-server'
import { isAppPageRouteDefinition } from '../route-definitions/app-page-route-definition'
import { normalizeAppPath } from '../../shared/lib/router/utils/app-paths'
......@@ -103,6 +106,11 @@ import {
devToolsConfigMiddleware,
getDevToolsConfig,
} from '../../next-devtools/server/devtools-config-middleware'
import {
connectReactDebugChannel,
deleteReactDebugChannel,
setReactDebugChannel,
} from './debug-channel'
const wsServer = new ws.Server({ noServer: true })
const isTestMode = !!(
......@@ -411,10 +419,16 @@ export async function createHotReloaderTurbopack(
let hmrHash = 0
const clients = new Set<ws>()
const clientsByRequestId = new Map<string, ws>()
const clientStates = new WeakMap<ws, ClientState>()
function sendToClient(client: ws, message: HmrMessageSentToBrowser) {
client.send(JSON.stringify(message))
const data =
typeof message.type === 'number'
? createBinaryHmrMessageData(message)
: JSON.stringify(message)
client.send(data)
}
function sendEnqueuedMessages() {
......@@ -747,6 +761,15 @@ export async function createHotReloaderTurbopack(
const subscriptions: Map<string, AsyncIterator<any>> = new Map()
clients.add(client)
const requestId = req.url
? new URL(req.url, 'http://n').searchParams.get('id')
: null
if (requestId) {
clientsByRequestId.set(requestId, client)
}
clientStates.set(client, {
clientIssues,
messages: new Map(),
......@@ -761,6 +784,11 @@ export async function createHotReloaderTurbopack(
}
clientStates.delete(client)
clients.delete(client)
if (requestId) {
clientsByRequestId.delete(requestId)
deleteReactDebugChannel(requestId)
}
})
client.addEventListener('message', async ({ data }) => {
......@@ -899,17 +927,35 @@ export async function createHotReloaderTurbopack(
}
sendToClient(client, syncMessage)
if (requestId) {
connectReactDebugChannel(requestId, sendToClient.bind(null, client))
}
})()
})
},
send(action) {
const payload = JSON.stringify(action)
for (const client of clients) {
client.send(payload)
}
},
setReactDebugChannel(debugChannel, htmlRequestId, requestId) {
// Store the debug channel, regardless of whether the client is connected.
setReactDebugChannel(requestId, debugChannel)
// If the client is connected, we can connect the debug channel
// immediately. Otherwise, we'll do that when the client connects.
const client = clientsByRequestId.get(htmlRequestId)
if (client) {
connectReactDebugChannel(requestId, sendToClient.bind(null, client))
}
},
setHmrServerError(_error) {
// Not implemented yet.
},
......@@ -1145,6 +1191,7 @@ export async function createHotReloaderTurbopack(
wsClient.terminate()
}
clients.clear()
clientsByRequestId.clear()
},
}
......
......@@ -9,8 +9,10 @@ import type { VersionInfo } from './parse-version-info'
import type { DebugInfo } from '../../next-devtools/shared/types'
import type { DevIndicatorServerState } from './dev-indicator-server-state'
import type { DevToolsConfig } from '../../next-devtools/dev-overlay/shared'
import type { ReactDebugChannelForBrowser } from './debug-channel'
export const enum HMR_MESSAGE_SENT_TO_BROWSER {
// JSON messages:
ADDED_PAGE = 'addedPage',
REMOVED_PAGE = 'removedPage',
RELOAD_PAGE = 'reloadPage',
......@@ -28,6 +30,9 @@ export const enum HMR_MESSAGE_SENT_TO_BROWSER {
ISR_MANIFEST = 'isrManifest',
DEV_INDICATOR = 'devIndicator',
DEVTOOLS_CONFIG = 'devtoolsConfig',
// Binary messages:
REACT_DEBUG_CHUNK = 0,
}
export interface ServerErrorMessage {
......@@ -129,6 +134,15 @@ export interface DevToolsConfigMessage {
data: DevToolsConfig
}
export interface ReactDebugChunkMessage {
type: HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK
requestId: string
/**
* A null chunk signals to the browser that no more chunks will be sent.
*/
chunk: Uint8Array | null
}
export type HmrMessageSentToBrowser =
| TurbopackMessage
| TurbopackConnectedMessage
......@@ -146,6 +160,12 @@ export type HmrMessageSentToBrowser =
| ServerErrorMessage
| AppIsrManifestMessage
| DevToolsConfigMessage
| ReactDebugChunkMessage
export type BinaryHmrMessageSentToBrowser = Extract<
HmrMessageSentToBrowser,
{ type: number }
>
export type TurbopackMessageSentToBrowser =
| {
......@@ -171,7 +191,12 @@ export interface NextJsHotReloaderInterface {
setHmrServerError(error: Error | null): void
clearHmrServerError(): void
start(): Promise<void>
send(message: HmrMessageSentToBrowser): void
send(action: HmrMessageSentToBrowser): void
setReactDebugChannel(
debugChannel: ReactDebugChannelForBrowser,
htmlRequestId: string,
requestId: string
): void
getCompilationErrors(page: string): Promise<any[]>
onHMR(
req: IncomingMessage,
......
......@@ -95,6 +95,13 @@ import {
devToolsConfigMiddleware,
getDevToolsConfig,
} from '../../next-devtools/server/devtools-config-middleware'
import { InvariantError } from '../../shared/lib/invariant-error'
import {
connectReactDebugChannel,
deleteReactDebugChannel,
setReactDebugChannel,
type ReactDebugChannelForBrowser,
} from './debug-channel'
const MILLISECONDS_IN_NANOSECOND = BigInt(1_000_000)
......@@ -438,7 +445,15 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
callback: (client: ws.WebSocket) => void
) {
wsServer.handleUpgrade(req, req.socket, head, (client) => {
this.webpackHotMiddleware?.onHMR(client)
const requestId = req.url
? new URL(req.url, 'http://n').searchParams.get('id')
: null
if (!this.webpackHotMiddleware) {
throw new InvariantError('Did not start HotReloaderWebpack.')
}
this.webpackHotMiddleware.onHMR(client, requestId)
this.onDemandEntries?.onHMR(client, () => this.hmrServerError)
callback(client)
......@@ -605,6 +620,21 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
// invalid WebSocket message
}
})
if (requestId) {
connectReactDebugChannel(
requestId,
this.sendToClient.bind(this, client)
)
}
client.on('close', () => {
this.webpackHotMiddleware?.deleteClient(client, requestId)
if (requestId) {
deleteReactDebugChannel(requestId)
}
})
})
}
......@@ -1663,6 +1693,27 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
this.webpackHotMiddleware!.publish(message)
}
public sendToClient(client: ws, message: HmrMessageSentToBrowser): void {
this.webpackHotMiddleware!.publishToClient(client, message)
}
public setReactDebugChannel(
debugChannel: ReactDebugChannelForBrowser,
htmlRequestId: string,
requestId: string
): void {
// Store the debug channel, regardless of whether the client is connected.
setReactDebugChannel(requestId, debugChannel)
// If the client is connected, we can connect the debug channel immediately.
// Otherwise, we'll do that when the client connects.
const client = this.webpackHotMiddleware?.getClient(htmlRequestId)
if (client) {
connectReactDebugChannel(requestId, this.sendToClient.bind(this, client))
}
}
public async ensurePage({
page,
clientOnly,
......
import { InvariantError } from '../../shared/lib/invariant-error'
import {
HMR_MESSAGE_SENT_TO_BROWSER,
type BinaryHmrMessageSentToBrowser,
} from './hot-reloader-types'
export const FAST_REFRESH_RUNTIME_RELOAD =
'Fast Refresh had to perform a full reload due to a runtime error.'
const textEncoder = new TextEncoder()
export function createBinaryHmrMessageData(
message: BinaryHmrMessageSentToBrowser
): Uint8Array {
switch (message.type) {
case HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK: {
const { requestId, chunk } = message
const requestIdBytes = textEncoder.encode(requestId)
const requestIdLength = requestIdBytes.length
if (requestIdLength > 255) {
throw new InvariantError(
'Request ID is too long for the binary HMR message.'
)
}
const chunkLength = chunk ? chunk.length : 0
const totalLength = 2 + requestIdLength + chunkLength
const data = new Uint8Array(totalLength)
const view = new DataView(data.buffer)
view.setUint8(0, HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK)
view.setUint8(1, requestIdLength)
textEncoder.encodeInto(requestId, data.subarray(2, 2 + requestIdLength))
if (chunk) {
data.set(chunk, 2 + requestIdLength)
}
return data
}
default: {
throw new InvariantError(
`Invalid binary HMR message of type ${message.type}`
)
}
}
}
......@@ -5,6 +5,7 @@ import type { WorkerRequestHandler } from './types'
import { LRUCache } from './lru-cache'
import { createRequestResponseMocks } from './mock-request'
import { HMR_MESSAGE_SENT_TO_BROWSER } from '../dev/hot-reloader-types'
import type { ReactDebugChannelForBrowser } from '../dev/debug-channel'
/**
* The DevBundlerService provides an interface to perform tasks with the
......@@ -106,6 +107,18 @@ export class DevBundlerService {
})
}
public setReactDebugChannel(
debugChannel: ReactDebugChannelForBrowser,
htmlRequestId: string,
requestId: string
): void {
this.bundler.hotReloader.setReactDebugChannel(
debugChannel,
htmlRequestId,
requestId
)
}
public close() {
this.bundler.hotReloader.close()
}
......
......@@ -724,6 +724,9 @@ export async function initialize(opts: {
? handlers.server.logErrorWithOriginalStack.bind(handlers.server)
: (err: unknown) => !opts.quiet && Log.error(err),
setIsrStatus: devBundlerService?.setIsrStatus.bind(devBundlerService),
setReactDebugChannel: config.experimental.reactDebugChannel
? devBundlerService?.setReactDebugChannel.bind(devBundlerService)
: undefined,
}
const logError = async (
......
......@@ -40,6 +40,11 @@ export type RouterServerContext = Record<
logErrorWithOriginalStack?: (err: unknown, type: string) => void
// allow setting ISR status in dev
setIsrStatus?: (key: string, value: boolean) => void
setReactDebugChannel?: (
debugChannel: { readable: ReadableStream<Uint8Array> },
htmlRequestId: string,
requestId: string
) => void
}
>
......
......@@ -123,40 +123,59 @@ export async function streamToString(
return string
}
export function createBufferedTransformStream(): TransformStream<
Uint8Array,
Uint8Array
> {
export type BufferedTransformOptions = {
/**
* Flush synchronously once the buffer reaches this many bytes.
*/
readonly maxBufferByteLength?: number
}
export function createBufferedTransformStream(
options: BufferedTransformOptions = {}
): TransformStream<Uint8Array, Uint8Array> {
const { maxBufferByteLength = Infinity } = options
let bufferedChunks: Array<Uint8Array> = []
let bufferByteLength: number = 0
let pending: DetachedPromise<void> | undefined
const flush = (controller: TransformStreamDefaultController) => {
// If we already have a pending flush, then return early.
if (pending) return
try {
if (bufferedChunks.length === 0) {
return
}
const chunk = new Uint8Array(bufferByteLength)
let copiedBytes = 0
for (let i = 0; i < bufferedChunks.length; i++) {
const bufferedChunk = bufferedChunks[i]
chunk.set(bufferedChunk, copiedBytes)
copiedBytes += bufferedChunk.byteLength
}
// We just wrote all the buffered chunks so we need to reset the bufferedChunks array
// and our bufferByteLength to prepare for the next round of buffered chunks
bufferedChunks.length = 0
bufferByteLength = 0
controller.enqueue(chunk)
} catch {
// If an error occurs while enqueuing, it can't be due to this
// transformer. It's most likely caused by the controller having been
// errored (for example, if the stream was cancelled).
}
}
const scheduleFlush = (controller: TransformStreamDefaultController) => {
if (pending) {
return
}
const detached = new DetachedPromise<void>()
pending = detached
scheduleImmediate(() => {
try {
const chunk = new Uint8Array(bufferByteLength)
let copiedBytes = 0
for (let i = 0; i < bufferedChunks.length; i++) {
const bufferedChunk = bufferedChunks[i]
chunk.set(bufferedChunk, copiedBytes)
copiedBytes += bufferedChunk.byteLength
}
// We just wrote all the buffered chunks so we need to reset the bufferedChunks array
// and our bufferByteLength to prepare for the next round of buffered chunks
bufferedChunks.length = 0
bufferByteLength = 0
controller.enqueue(chunk)
} catch {
// If an error occurs while enqueuing it can't be due to this
// transformers fault. It's likely due to the controller being
// errored due to the stream being cancelled.
flush(controller)
} finally {
pending = undefined
detached.resolve()
......@@ -170,13 +189,14 @@ export function createBufferedTransformStream(): TransformStream<
bufferedChunks.push(chunk)
bufferByteLength += chunk.byteLength
// Flush the buffer to the controller.
flush(controller)
if (bufferByteLength >= maxBufferByteLength) {
flush(controller)
} else {
scheduleFlush(controller)
}
},
flush() {
if (!pending) return
return pending.promise
return pending?.promise
},
})
}
......
......@@ -104,6 +104,7 @@ declare module 'react-server-dom-webpack/client.browser' {
findSourceMapURL: FindSourceMapURLCallback | undefined
replayConsoleLogs?: boolean
temporaryReferences?: TemporaryReferenceSet
debugChannel?: { readable?: ReadableStream; writable?: WritableStream }
}
export function createFromFetch<T>(
......@@ -156,6 +157,7 @@ declare module 'react-server-dom-webpack/server.edge' {
onError?: (error: unknown) => void
onPostpone?: (reason: string) => void
signal?: AbortSignal
debugChannel?: { readable?: ReadableStream; writable?: WritableStream }
}
): ReadableStream<Uint8Array>
......@@ -305,6 +307,7 @@ declare module 'react-server-dom-webpack/client.edge' {
findSourceMapURL: FindSourceMapURLCallback | undefined
replayConsoleLogs?: boolean
environmentName?: string
debugChannel?: { readable?: ReadableStream }
}
export type EncodeFormActionCallback = <A>(
......
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