react-on-rails-pro-node-renderer 17.0.0-rc.6 → 17.0.0-rc.8

package/lib/worker/handleGracefulShutdown.js

@@ -34,6 +34,7 @@ const handleGracefulShutdown = (app) => {
     let activeRequestsCount = 0;
     let isShuttingDown = false;
     let isDestroying = false;
+    const activeRequests = new WeakSet();
     const destroyWorkerAfterShutdownHooks = (context) => {
         if (isDestroying) {
             return;
@@ -75,10 +76,29 @@ const handleGracefulShutdown = (app) => {
             }
         }
     };
-    // Helper to decrement counter and potentially kill worker
-    const decrementAndMaybeShutdown = (context) => {
+    const acknowledgeGracefulShutdown = () => {
+        try {
+            worker.send(utils_js_1.SHUTDOWN_WORKER_ACK_MESSAGE);
+        }
+        catch (error) {
+            if (errorCode(error) === 'ERR_IPC_CHANNEL_CLOSED') {
+                log_js_1.default.debug('Worker #%d IPC channel was already closed before graceful shutdown ACK', worker.id);
+            }
+            else {
+                log_js_1.default.warn({ msg: 'Error sending graceful shutdown ACK from worker', error });
+            }
+        }
+    };
+    const decrementAndMaybeShutdown = (request, context) => {
+        if (!activeRequests.delete(request)) {
+            log_js_1.default.debug('Worker #%d: request already completed before %s', worker.id, context);
+            return;
+        }
         activeRequestsCount -= 1;
-        if (isShuttingDown && activeRequestsCount === 0) {
+        if (activeRequestsCount < 0) {
+            log_js_1.default.warn('Worker #%d active request count is negative after %s', worker.id, context);
+        }
+        if (isShuttingDown && activeRequestsCount <= 0) {
             log_js_1.default.debug('Worker #%d has no active requests after %s, killing the worker', worker.id, context);
             destroyWorkerAfterShutdownHooks(context);
         }
@@ -86,8 +106,9 @@ const handleGracefulShutdown = (app) => {
     process.on('message', (msg) => {
         if (msg === utils_js_1.SHUTDOWN_WORKER_MESSAGE) {
             log_js_1.default.debug('Worker #%d received graceful shutdown message', worker.id);
+            acknowledgeGracefulShutdown();
             isShuttingDown = true;
-            if (activeRequestsCount === 0) {
+            if (activeRequestsCount <= 0) {
                 log_js_1.default.debug('Worker #%d has no active requests, killing the worker', worker.id);
                 destroyWorkerAfterShutdownHooks('shutdown message');
             }
@@ -97,24 +118,23 @@ const handleGracefulShutdown = (app) => {
             }
         }
     });
-    app.addHook('onRequest', (_req, _reply, done) => {
+    app.addHook('onRequest', (req, _reply, done) => {
+        activeRequests.add(req);
         activeRequestsCount += 1;
         done();
     });
-    app.addHook('onResponse', (_req, _reply, done) => {
-        decrementAndMaybeShutdown('onResponse');
+    app.addHook('onResponse', (req, _reply, done) => {
+        decrementAndMaybeShutdown(req, 'onResponse');
         done();
     });
-    // Handle client abort - onResponse is NOT called when client disconnects
-    app.addHook('onRequestAbort', (_req, done) => {
+    app.addHook('onRequestAbort', (req, done) => {
         log_js_1.default.debug('Worker #%d: request aborted by client', worker.id);
-        decrementAndMaybeShutdown('onRequestAbort');
+        decrementAndMaybeShutdown(req, 'onRequestAbort');
         done();
     });
-    // Handle request timeout - onResponse is NOT called when request times out
-    app.addHook('onTimeout', (_req, _reply, done) => {
+    app.addHook('onTimeout', (req, _reply, done) => {
         log_js_1.default.debug('Worker #%d: request timed out', worker.id);
-        decrementAndMaybeShutdown('onTimeout');
+        decrementAndMaybeShutdown(req, 'onTimeout');
         done();
     });
 };

package/lib/worker/handleIncrementalRenderRequest.d.ts

@@ -27,6 +27,7 @@ export type FirstIncrementalRenderRequestChunk = {
     onRequestClosedUpdateChunk?: UpdateChunk;
     pullEnabled?: boolean;
     pushProps?: string[];
+    rscStreamObservability?: boolean;
 };
 export type IncrementalRenderResult = {
     response: ResponseResult;

package/lib/worker/handleIncrementalRenderRequest.js

@@ -27,6 +27,7 @@ const utils_1 = require("../shared/utils");
 const tracing_js_1 = require("../shared/tracing.js");
 const streamingUtils_1 = require("./streamingUtils");
 // These keys must match the constants in AsyncPropsManager.ts (react-on-rails-pro package)
+// MIRROR VALUES OF: packages/react-on-rails-pro/src/AsyncPropsManager.ts
 exports.PULL_ENABLED_KEY = 'pullEnabled';
 exports.PUSH_PROPS_KEY = 'pushProps';
 exports.PROP_REQUEST_EMITTER_KEY = 'propRequestEmitter';
@@ -94,6 +95,12 @@ function assertFirstIncrementalRenderRequestChunk(chunk) {
     if ('pullEnabled' in chunk && chunk.pullEnabled !== undefined && typeof chunk.pullEnabled !== 'boolean') {
         throw new Error('Invalid first incremental render request chunk: pullEnabled must be a boolean');
     }
+    if ('rscStreamObservability' in chunk &&
+        chunk.rscStreamObservability !== undefined &&
+        // Incremental NDJSON requests are produced in-process, so keep this strict.
+        typeof chunk.rscStreamObservability !== 'boolean') {
+        throw new Error('Invalid first incremental render request chunk: rscStreamObservability must be a boolean');
+    }
     if ('pushProps' in chunk &&
         chunk.pushProps !== undefined &&
         (!Array.isArray(chunk.pushProps) || chunk.pushProps.some((propName) => typeof propName !== 'string'))) {
@@ -131,7 +138,7 @@ function assertFirstIncrementalRenderRequestChunk(chunk) {
 async function handleIncrementalRenderRequest(initial) {
     const { firstRequestChunk, bundleTimestamp, dependencyBundleTimestamps } = initial;
     assertFirstIncrementalRenderRequestChunk(firstRequestChunk);
-    const { renderingRequest, onRequestClosedUpdateChunk } = firstRequestChunk;
+    const { renderingRequest, onRequestClosedUpdateChunk, rscStreamObservability } = firstRequestChunk;
     try {
         // Call handleRenderRequest internally to handle all validation and VM execution
         // handleRenderRequest is called directly without a TracingContext from worker.ts's
@@ -142,129 +149,161 @@ async function handleIncrementalRenderRequest(initial) {
             dependencyBundleTimestamps,
             providedNewBundles: undefined,
             assetsToCopy: undefined,
+            rscStreamObservability,
         });
         // If we don't get an execution context, it means there was an early error
         // (e.g. bundle not found). In this case, the sink will be a no-op.
         if (!executionContext) {
             return { response };
         }
-        // Set up pull mode if enabled: inject propRequest emitter into sharedExecutionContext
-        // so AsyncPropsManager (inside VM) can emit propRequests to the response stream.
         let finalResponse = response;
-        const { pullEnabled, pushProps } = firstRequestChunk;
-        if (pullEnabled && response.stream) {
-            const sourceStream = response.stream;
-            const { sharedExecutionContext } = executionContext;
-            sharedExecutionContext.set(exports.PULL_ENABLED_KEY, true);
-            sharedExecutionContext.set(exports.PUSH_PROPS_KEY, new Set(pushProps || []));
-            // Create injectable PassThrough — sits after the length-prefixed transform.
-            // Both HTML chunks (from React) and propRequest chunks (from us) flow through it.
-            const injectableStream = new stream_1.PassThrough();
-            const writeRenderCompleteAndEnd = () => {
-                if (injectableStream.destroyed || injectableStream.writableEnded)
-                    return;
-                try {
-                    injectableStream.write((0, streamingUtils_1.formatRenderCompleteChunk)());
-                }
-                catch (err) {
-                    log_1.default.warn({ msg: 'Failed to write renderComplete chunk', err });
-                }
-                injectableStream.end();
-            };
-            // Register event handlers BEFORE pipe() to guarantee we catch 'end'
-            // even if the source stream has already buffered all its data.
-            sourceStream.on('end', () => {
-                if (injectableStream.writableNeedDrain) {
-                    injectableStream.once('drain', writeRenderCompleteAndEnd);
-                    return;
-                }
-                writeRenderCompleteAndEnd();
-            });
-            sourceStream.on('error', (err) => {
-                injectableStream.destroy(err);
-            });
-            // Fastify destroys the returned stream when the browser/Rails client disconnects.
-            // Propagate that premature teardown back through the pull wrapper so upstream
-            // React/RSC work and async prop fetches abort just like the non-pull path.
-            injectableStream.once('close', () => {
-                if (!injectableStream.writableEnded && !sourceStream.destroyed) {
-                    sourceStream.destroy();
-                }
-            });
-            // { end: false } prevents pipe from auto-closing injectableStream when
-            // the source ends — we write renderComplete in the 'end' handler above.
-            sourceStream.pipe(injectableStream, { end: false });
-            // Set the emitter callback — AsyncPropsManager calls this from inside the VM
-            sharedExecutionContext.set(exports.PROP_REQUEST_EMITTER_KEY, (propName) => {
-                if (injectableStream.destroyed || injectableStream.writableEnded) {
-                    log_1.default.warn({ msg: 'Skipping propRequest after stream closed', propName });
-                    return;
-                }
-                if (propName.length > exports.MAX_PULL_PROP_NAME_LENGTH) {
-                    log_1.default.warn({
-                        msg: 'Skipping oversized propRequest',
-                        propNameLength: propName.length,
-                        maxPropNameLength: exports.MAX_PULL_PROP_NAME_LENGTH,
-                    });
-                    return;
-                }
-                try {
-                    injectableStream.write((0, streamingUtils_1.formatPropRequestChunk)(propName));
-                }
-                catch (err) {
-                    log_1.default.error({ msg: 'Failed to write propRequest chunk', propName, err });
-                }
-            });
-            const manager = sharedExecutionContext.get(exports.ASYNC_PROPS_MANAGER_KEY);
-            catchUpAsyncPropsManagerPullBridge(manager);
-            finalResponse = { ...response, stream: injectableStream };
-        }
-        // Return the result with a sink that uses the execution context
-        return {
-            response: finalResponse,
-            sink: {
-                executionContext,
-                add: async (chunk) => {
+        let pullModeSharedExecutionContext;
+        let pullModeStream;
+        try {
+            // Set up pull mode if enabled: inject propRequest emitter into sharedExecutionContext
+            // so AsyncPropsManager (inside VM) can emit propRequests to the response stream.
+            const { pullEnabled, pushProps } = firstRequestChunk;
+            if (pullEnabled && response.stream) {
+                const sourceStream = response.stream;
+                const { sharedExecutionContext } = executionContext;
+                pullModeSharedExecutionContext = sharedExecutionContext;
+                sharedExecutionContext.set(exports.PULL_ENABLED_KEY, true);
+                sharedExecutionContext.set(exports.PUSH_PROPS_KEY, new Set(pushProps || []));
+                // Create injectable PassThrough — sits after the length-prefixed transform.
+                // Both HTML chunks (from React) and propRequest chunks (from us) flow through it.
+                const injectableStream = new stream_1.PassThrough();
+                pullModeStream = injectableStream;
+                const writeRenderCompleteAndEnd = () => {
+                    if (injectableStream.destroyed || injectableStream.writableEnded)
+                        return;
                     try {
-                        assertIsUpdateChunk(chunk);
-                        await (0, tracing_js_1.subSpan)({ name: 'ror.incremental.process_chunk' }, async () => {
-                            const bundlePath = (0, utils_1.getRequestBundleFilePath)(chunk.bundleTimestamp);
-                            const result = await executionContext.runInVM(chunk.updateChunk, bundlePath);
-                            if ((0, utils_1.isErrorRenderResult)(result)) {
-                                throw new Error(result.exceptionMessage);
-                            }
-                        });
+                        injectableStream.write((0, streamingUtils_1.formatRenderCompleteChunk)());
                     }
                     catch (err) {
-                        if (err instanceof InvalidIncrementalRenderChunkError) {
-                            log_1.default.error({ msg: 'Invalid incremental render chunk', err, chunk });
-                        }
-                        else {
-                            log_1.default.error({ msg: 'Error running incremental render chunk', err, chunk });
-                        }
+                        log_1.default.warn({ msg: 'Failed to write renderComplete chunk', err });
                     }
-                },
-                handleRequestClosed: async () => {
-                    if (!onRequestClosedUpdateChunk) {
+                    injectableStream.end();
+                };
+                // Register event handlers BEFORE pipe() to guarantee we catch 'end'
+                // even if the source stream has already buffered all its data.
+                sourceStream.on('end', () => {
+                    if (injectableStream.writableNeedDrain) {
+                        injectableStream.once('drain', writeRenderCompleteAndEnd);
+                        return;
+                    }
+                    writeRenderCompleteAndEnd();
+                });
+                sourceStream.on('error', (err) => {
+                    injectableStream.destroy(err);
+                });
+                // Fastify destroys the returned stream when the browser/Rails client disconnects.
+                // Propagate that premature teardown back through the pull wrapper so upstream
+                // React/RSC work and async prop fetches abort just like the non-pull path.
+                injectableStream.once('close', () => {
+                    if (!injectableStream.writableEnded && !sourceStream.destroyed) {
+                        sourceStream.destroy();
+                    }
+                });
+                // { end: false } prevents pipe from auto-closing injectableStream when
+                // the source ends — we write renderComplete in the 'end' handler above.
+                sourceStream.pipe(injectableStream, { end: false });
+                // Set the emitter callback — AsyncPropsManager calls this from inside the VM
+                sharedExecutionContext.set(exports.PROP_REQUEST_EMITTER_KEY, (propName) => {
+                    if (injectableStream.destroyed || injectableStream.writableEnded) {
+                        log_1.default.warn({ msg: 'Skipping propRequest after stream closed', propName });
+                        return;
+                    }
+                    if (propName.length > exports.MAX_PULL_PROP_NAME_LENGTH) {
+                        log_1.default.warn({
+                            msg: 'Skipping oversized propRequest',
+                            propNameLength: propName.length,
+                            maxPropNameLength: exports.MAX_PULL_PROP_NAME_LENGTH,
+                        });
                         return;
                     }
-                    const bundlePath = (0, utils_1.getRequestBundleFilePath)(onRequestClosedUpdateChunk.bundleTimestamp);
                     try {
-                        const result = await executionContext.runInVM(onRequestClosedUpdateChunk.updateChunk, bundlePath);
-                        if ((0, utils_1.isErrorRenderResult)(result)) {
-                            throw new Error(result.exceptionMessage);
-                        }
+                        injectableStream.write((0, streamingUtils_1.formatPropRequestChunk)(propName));
                     }
                     catch (err) {
-                        log_1.default.error({
-                            msg: 'Error running onRequestClosedUpdateChunk',
-                            err,
-                            onRequestClosedUpdateChunk,
-                        });
+                        log_1.default.error({ msg: 'Failed to write propRequest chunk', propName, err });
                     }
+                });
+                const manager = sharedExecutionContext.get(exports.ASYNC_PROPS_MANAGER_KEY);
+                catchUpAsyncPropsManagerPullBridge(manager);
+                finalResponse = { ...response, stream: injectableStream };
+            }
+            // Return the result with a sink that uses the execution context
+            return {
+                response: finalResponse,
+                sink: {
+                    executionContext,
+                    add: async (chunk) => {
+                        try {
+                            assertIsUpdateChunk(chunk);
+                            await (0, tracing_js_1.subSpan)({ name: 'ror.incremental.process_chunk' }, async () => {
+                                const bundlePath = (0, utils_1.getRequestBundleFilePath)(chunk.bundleTimestamp);
+                                const result = await executionContext.runInVM(chunk.updateChunk, bundlePath);
+                                if ((0, utils_1.isErrorRenderResult)(result)) {
+                                    throw new Error(result.exceptionMessage);
+                                }
+                            });
+                        }
+                        catch (err) {
+                            if (err instanceof InvalidIncrementalRenderChunkError) {
+                                log_1.default.error({ msg: 'Invalid incremental render chunk', err, chunk });
+                            }
+                            else {
+                                log_1.default.error({ msg: 'Error running incremental render chunk', err, chunk });
+                            }
+                        }
+                    },
+                    handleRequestClosed: async () => {
+                        if (!onRequestClosedUpdateChunk) {
+                            return;
+                        }
+                        const bundlePath = (0, utils_1.getRequestBundleFilePath)(onRequestClosedUpdateChunk.bundleTimestamp);
+                        try {
+                            const result = await executionContext.runInVM(onRequestClosedUpdateChunk.updateChunk, bundlePath);
+                            if ((0, utils_1.isErrorRenderResult)(result)) {
+                                throw new Error(result.exceptionMessage);
+                            }
+                        }
+                        catch (err) {
+                            log_1.default.error({
+                                msg: 'Error running onRequestClosedUpdateChunk',
+                                err,
+                                onRequestClosedUpdateChunk,
+                            });
+                        }
+                    },
                 },
-            },
-        };
+            };
+        }
+        catch (error) {
+            if (pullModeSharedExecutionContext) {
+                pullModeSharedExecutionContext.delete(exports.PULL_ENABLED_KEY);
+                pullModeSharedExecutionContext.delete(exports.PUSH_PROPS_KEY);
+                pullModeSharedExecutionContext.delete(exports.PROP_REQUEST_EMITTER_KEY);
+            }
+            try {
+                if (pullModeStream && !pullModeStream.destroyed) {
+                    pullModeStream.destroy();
+                }
+                if (response.stream && response.stream !== pullModeStream && !response.stream.destroyed) {
+                    response.stream.destroy();
+                }
+            }
+            catch (err) {
+                log_1.default.error({ msg: 'Error cleaning up incremental render setup failure', err });
+            }
+            try {
+                executionContext.release();
+            }
+            catch (err) {
+                log_1.default.error({ msg: 'Error releasing execution context after incremental render setup failure', err });
+            }
+            throw error;
+        }
     }
     catch (error) {
         // Handle any unexpected errors

package/lib/worker/handleIncrementalRenderStream.d.ts

@@ -25,6 +25,9 @@ export interface IncrementalRenderStreamHandlerOptions {
     onResponseStart: (response: ResponseResult) => Promise<void> | void;
     onUpdateReceived: (updateData: unknown) => Promise<void> | void;
     onRequestEnded: () => Promise<void> | void;
+    getChunkTimeoutMs?: () => number;
+    shouldStopReading?: () => boolean;
+    waitForStopReading?: () => Promise<void>;
 }
 /**
  * Handles incremental rendering requests with streaming JSON data.

package/lib/worker/handleIncrementalRenderStream.js

@@ -67,11 +67,57 @@ exports.StreamChunkTimeoutError = StreamChunkTimeoutError;
  * Wraps an async iterator with a timeout for each chunk.
  * If no chunk is received within the timeout, throws StreamChunkTimeoutError.
  */
-async function* withChunkTimeout(iterator, timeoutMs) {
+async function* withChunkTimeout(iterator, getTimeoutMs, shouldStopReading, waitForStopReading) {
     const asyncIterator = iterator[Symbol.asyncIterator]();
+    const stopIterator = () => {
+        try {
+            const returnPromise = asyncIterator.return?.();
+            if (returnPromise) {
+                void Promise.resolve(returnPromise).catch(() => undefined);
+            }
+        }
+        catch {
+            // The caller has already decided to stop reading; cleanup failures should not keep the response open.
+        }
+    };
     while (true) {
+        if (shouldStopReading()) {
+            stopIterator();
+            return;
+        }
         let timeoutId;
+        const timeoutMs = getTimeoutMs();
         try {
+            if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+                const nextChunkPromise = asyncIterator.next();
+                const stopReadingPromise = waitForStopReading?.().then(() => 'stop-reading');
+                // eslint-disable-next-line no-await-in-loop
+                const result = await (stopReadingPromise
+                    ? Promise.race([nextChunkPromise, stopReadingPromise])
+                    : nextChunkPromise);
+                if (result === 'stop-reading') {
+                    if (shouldStopReading()) {
+                        stopIterator();
+                        return;
+                    }
+                    // The stop signal was stale. Keep waiting for the in-flight read to settle
+                    // before starting another read on the same async iterator.
+                    // eslint-disable-next-line no-await-in-loop
+                    const nextResult = await nextChunkPromise;
+                    if (nextResult.done) {
+                        return;
+                    }
+                    yield nextResult.value;
+                    // eslint-disable-next-line no-continue
+                    continue;
+                }
+                if (result.done) {
+                    return;
+                }
+                yield result.value;
+                // eslint-disable-next-line no-continue
+                continue;
+            }
             // eslint-disable-next-line no-await-in-loop
             const result = await Promise.race([
                 asyncIterator.next(),
@@ -97,20 +143,29 @@ async function* withChunkTimeout(iterator, timeoutMs) {
         }
     }
 }
+function reportResponseStartError(err) {
+    errorReporter.error(err instanceof Error ? err : new Error(String(err)));
+}
+function observeResponseStartError(promise) {
+    void promise.catch(reportResponseStartError);
+}
+function suppressUnhandledResponseStartError(promise) {
+    void promise.catch(() => { });
+}
 /**
  * Handles incremental rendering requests with streaming JSON data.
  * The first object triggers rendering, subsequent objects provide incremental updates.
  */
 async function handleIncrementalRenderStream(options) {
     return (0, tracing_js_1.subSpan)({ name: 'ror.incremental.stream' }, async () => {
-        const { request, onRenderRequestReceived, onResponseStart, onUpdateReceived, onRequestEnded } = options;
+        const { request, onRenderRequestReceived, onResponseStart, onUpdateReceived, onRequestEnded, getChunkTimeoutMs = () => constants_1.STREAM_CHUNK_TIMEOUT_MS, shouldStopReading = () => false, waitForStopReading, } = options;
         let hasReceivedFirstObject = false;
         const decoder = new string_decoder_1.StringDecoder('utf8');
         let buffer = '';
         let totalBytesReceived = 0;
         let onResponseStartPromise = null;
         try {
-            for await (const chunk of withChunkTimeout(request.raw, constants_1.STREAM_CHUNK_TIMEOUT_MS)) {
+            for await (const chunk of withChunkTimeout(request.raw, getChunkTimeoutMs, shouldStopReading, waitForStopReading)) {
                 const chunkBuffer = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
                 totalBytesReceived += chunkBuffer.length;
                 // Check total request size limit
@@ -158,7 +213,9 @@ async function handleIncrementalRenderStream(options) {
                                 const result = await onRenderRequestReceived(parsed);
                                 const { response, shouldContinue: continueFlag } = result;
                                 onResponseStartPromise = Promise.resolve(onResponseStart(response));
+                                suppressUnhandledResponseStartError(onResponseStartPromise);
                                 if (!continueFlag) {
+                                    observeResponseStartError(onResponseStartPromise);
                                     return;
                                 }
                             }
@@ -206,14 +263,31 @@ async function handleIncrementalRenderStream(options) {
             }
         }
         catch (err) {
+            if (onResponseStartPromise !== null) {
+                observeResponseStartError(onResponseStartPromise);
+            }
             const error = err instanceof Error ? err : new Error(String(err));
             // Update the error message in place to retain the original stack trace, rather than creating a new error object
             error.message = `Error while handling the request stream: ${error.message}`;
             throw error;
         }
         // Stream ended normally
-        await onRequestEnded();
-        await onResponseStartPromise;
+        try {
+            await onRequestEnded();
+        }
+        catch (err) {
+            if (onResponseStartPromise !== null) {
+                observeResponseStartError(onResponseStartPromise);
+            }
+            throw err;
+        }
+        try {
+            await onResponseStartPromise;
+        }
+        catch (err) {
+            reportResponseStartError(err);
+            throw err;
+        }
     });
 }
 //# sourceMappingURL=handleIncrementalRenderStream.js.map

package/lib/worker/handleRenderRequest.d.ts

@@ -6,18 +6,22 @@ export type ProvidedNewBundle = {
     timestamp: string | number;
     bundle: Asset;
 };
+export declare function escapeServerTimingDescription(description: string): string;
+/** Adds renderer prepare Server-Timing to streamed responses when enabled. */
+export declare function addRendererServerTiming(response: ResponseResult, startedAtMs: number, enabled: boolean): void;
 export declare function handleNewBundlesProvided(requestContext: RequestInfo, providedNewBundles: ProvidedNewBundle[], assetsToCopy: Asset[] | null | undefined): Promise<ResponseResult | undefined>;
 /**
  * Creates the result for the Fastify server to use.
  * @returns Promise where the result contains { status, data, headers } to
  * send back to the browser.
  */
-export declare function handleRenderRequest({ renderingRequest, bundleTimestamp, dependencyBundleTimestamps, providedNewBundles, assetsToCopy, tracingContext, }: {
+export declare function handleRenderRequest({ renderingRequest, bundleTimestamp, dependencyBundleTimestamps, providedNewBundles, assetsToCopy, rscStreamObservability, tracingContext, }: {
     renderingRequest: string;
     bundleTimestamp: string | number;
     dependencyBundleTimestamps?: string[] | number[];
     providedNewBundles?: ProvidedNewBundle[] | null;
     assetsToCopy?: Asset[] | null;
+    rscStreamObservability?: boolean;
     tracingContext?: TracingContext;
 }): Promise<{
     response: ResponseResult;

package/lib/worker/handleRenderRequest.js

@@ -18,6 +18,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sumUploadedBytes = sumUploadedBytes;
+exports.escapeServerTimingDescription = escapeServerTimingDescription;
+exports.addRendererServerTiming = addRendererServerTiming;
 exports.handleNewBundlesProvided = handleNewBundlesProvided;
 exports.handleRenderRequest = handleRenderRequest;
 /**
@@ -49,6 +51,20 @@ async function sumUploadedBytes(assets) {
     }));
     return sizes.reduce((total, size) => total + size, 0);
 }
+function escapeServerTimingDescription(description) {
+    return description.replace(/[\r\n\0]/g, '').replace(/["\\]/g, (char) => `\\${char}`);
+}
+/** Adds renderer prepare Server-Timing to streamed responses when enabled. */
+function addRendererServerTiming(response, startedAtMs, enabled) {
+    if (!enabled || !response.stream) {
+        return;
+    }
+    const durMs = (performance.now() - startedAtMs).toFixed(3);
+    const desc = 'Node renderer prepare (bundle sync + exec context build + render start)';
+    const entry = `ror_renderer_prepare;dur=${durMs};desc="${escapeServerTimingDescription(desc)}"`;
+    const existing = response.headers['Server-Timing'];
+    response.headers['Server-Timing'] = existing ? `${existing}, ${entry}` : entry;
+}
 async function prepareResult(renderingRequest, bundleTimestamp, bundleFilePathPerTimestamp, executionContext) {
     return (0, tracing_js_1.subSpan)({ name: 'ror.result.prepare' }, async (resultSpan) => {
         try {
@@ -91,6 +107,11 @@ async function prepareResult(renderingRequest, bundleTimestamp, bundleFilePathPe
         }
     });
 }
+async function prepareResponseWithServerTiming(renderingRequest, bundleTimestamp, bundleFilePathPerTimestamp, executionContext, rendererServerTimingStartedAtMs, rscStreamObservability) {
+    const response = await prepareResult(renderingRequest, bundleTimestamp, bundleFilePathPerTimestamp, executionContext);
+    addRendererServerTiming(response, rendererServerTimingStartedAtMs, rscStreamObservability);
+    return { response, executionContext };
+}
 /**
  * @param bundleFilePathPerTimestamp
  * @param providedNewBundle
@@ -173,7 +194,7 @@ async function handleNewBundlesProvided(requestContext, providedNewBundles, asse
  * @returns Promise where the result contains { status, data, headers } to
  * send back to the browser.
  */
-async function handleRenderRequest({ renderingRequest, bundleTimestamp, dependencyBundleTimestamps, providedNewBundles, assetsToCopy, tracingContext, }) {
+async function handleRenderRequest({ renderingRequest, bundleTimestamp, dependencyBundleTimestamps, providedNewBundles, assetsToCopy, rscStreamObservability = false, tracingContext, }) {
     try {
         // const bundleFilePathPerTimestamp = getRequestBundleFilePath(bundleTimestamp);
         const allBundleFilePaths = Array.from(new Set([...(dependencyBundleTimestamps ?? []), bundleTimestamp].map(utils_js_1.getRequestBundleFilePath)));
@@ -188,6 +209,9 @@ async function handleRenderRequest({ renderingRequest, bundleTimestamp, dependen
                 },
             };
         }
+        // Start before the first VM lookup so cache-hit and cache-miss timings cover
+        // the same request span, including bundle upload on first deploy.
+        const rendererServerTimingStartedAtMs = performance.now();
         try {
             const executionContext = await (0, tracing_js_1.subSpan)({
                 name: 'ror.bundle.build_execution_context',
@@ -197,10 +221,7 @@ async function handleRenderRequest({ renderingRequest, bundleTimestamp, dependen
                     'cache.strategy': 'cache-first',
                 },
             }, () => (0, vm_js_1.buildExecutionContext)(allBundleFilePaths, /* buildVmsIfNeeded */ false));
-            return {
-                response: await prepareResult(renderingRequest, bundleTimestamp, entryBundleFilePath, executionContext),
-                executionContext,
-            };
+            return await prepareResponseWithServerTiming(renderingRequest, bundleTimestamp, entryBundleFilePath, executionContext, rendererServerTimingStartedAtMs, rscStreamObservability);
         }
         catch (e) {
             // Ignore VMContextNotFoundError, it means the bundle does not exist.
@@ -246,10 +267,7 @@ async function handleRenderRequest({ renderingRequest, bundleTimestamp, dependen
                 'cache.strategy': 'cache-miss',
             },
         }, () => (0, vm_js_1.buildExecutionContext)(allBundleFilePaths, /* buildVmsIfNeeded */ true));
-        return {
-            response: await prepareResult(renderingRequest, bundleTimestamp, entryBundleFilePath, executionContext),
-            executionContext,
-        };
+        return await prepareResponseWithServerTiming(renderingRequest, bundleTimestamp, entryBundleFilePath, executionContext, rendererServerTimingStartedAtMs, rscStreamObservability);
     }
     catch (error) {
         const msg = (0, utils_js_1.formatExceptionMessage)({ renderingRequest }, error, 'Caught top level error in handleRenderRequest');

package/lib/worker/shutdownHooks.js

@@ -24,7 +24,7 @@ exports.__resetWorkerShutdownHooksForTest = __resetWorkerShutdownHooksForTest;
  * timeouts (e.g. OpenTelemetry `shutdownTimeoutMs`) must stay below this so
  * the worker doesn't kill an in-flight hook before it finishes flushing.
  */
-exports.WORKER_SHUTDOWN_HOOKS_TIMEOUT_MS = 10000;
+exports.WORKER_SHUTDOWN_HOOKS_TIMEOUT_MS = 10_000;
 const workerShutdownHooks = [];
 function registerWorkerShutdownHook(hook) {
     workerShutdownHooks.push(hook);