react-on-rails-pro-node-renderer 17.0.0-rc.5 → 17.0.0-rc.7

package/lib/shared/utils.js

@@ -50,12 +50,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.delay = exports.majorVersion = exports.isErrorRenderResult = exports.handleStreamError = exports.safePipe = exports.isReadableStream = exports.SHUTDOWN_WORKER_MESSAGE = exports.TRUNCATION_FILLER = void 0;
+exports.delay = exports.majorVersion = exports.isErrorRenderResult = exports.handleStreamError = exports.safePipe = exports.isReadableStream = exports.SHUTDOWN_WORKER_ACK_MESSAGE = exports.SHUTDOWN_WORKER_MESSAGE = exports.TRUNCATION_FILLER = void 0;
 exports.workerIdLabel = workerIdLabel;
 exports.smartTrim = smartTrim;
 exports.badRequestResponseResult = badRequestResponseResult;
 exports.errorResponseResult = errorResponseResult;
 exports.formatExceptionMessage = formatExceptionMessage;
+exports.validateAssetFilename = validateAssetFilename;
 exports.saveMultipartFile = saveMultipartFile;
 exports.moveUploadedAsset = moveUploadedAsset;
 exports.copyUploadedAsset = copyUploadedAsset;
@@ -77,6 +78,7 @@ const fileExistsAsync_js_1 = __importDefault(require("./fileExistsAsync.js"));
 const vmSourceMapSupport_js_1 = require("../worker/vmSourceMapSupport.js");
 exports.TRUNCATION_FILLER = '\n... TRUNCATED ...\n';
 exports.SHUTDOWN_WORKER_MESSAGE = 'NODE_RENDERER_SHUTDOWN_WORKER';
+exports.SHUTDOWN_WORKER_ACK_MESSAGE = 'NODE_RENDERER_SHUTDOWN_WORKER_ACK';
 function workerIdLabel() {
     return cluster_1.default?.worker?.id || 'NO WORKER ID';
 }
@@ -142,6 +144,30 @@ ${stack}`;
 }
 // https://github.com/fastify/fastify-multipart?tab=readme-ov-file#usage
 const pump = (0, util_1.promisify)(stream_1.pipeline);
+const hasAsciiControlCharacter = (value) => {
+    for (let index = 0; index < value.length; index += 1) {
+        const characterCode = value.charCodeAt(index);
+        if (characterCode <= 0x1f || characterCode === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+};
+function validateAssetFilename(filename) {
+    if (typeof filename !== 'string' ||
+        !filename ||
+        filename === '.' ||
+        filename === '..' ||
+        filename.includes('/') ||
+        filename.includes('\\') ||
+        filename.includes(':') ||
+        hasAsciiControlCharacter(filename) ||
+        // Catches Windows drive-relative values such as "C:file" that have no separator.
+        path_1.default.win32.basename(filename) !== filename) {
+        throw new Error(`Invalid asset filename: ${JSON.stringify(filename)}. Expected a single filename, not a path.`);
+    }
+    return filename;
+}
 async function saveMultipartFile(multipartFile, destinationPath) {
     await (0, fs_extra_1.ensureDir)(path_1.default.dirname(destinationPath));
     return pump(multipartFile.file, (0, fs_extra_1.createWriteStream)(destinationPath));
@@ -154,7 +180,7 @@ function copyUploadedAsset(asset, destinationPath, options = {}) {
 }
 async function copyUploadedAssets(uploadedAssets, targetDirectory) {
     const copyMultipleAssets = uploadedAssets.map((asset) => {
-        const destinationAssetFilePath = path_1.default.join(targetDirectory, asset.filename);
+        const destinationAssetFilePath = path_1.default.join(targetDirectory, validateAssetFilename(asset.filename));
         return copyUploadedAsset(asset, destinationAssetFilePath, { overwrite: true });
     });
     await Promise.all(copyMultipleAssets);
@@ -198,7 +224,21 @@ const safePipe = (source, destination, onError) => {
     return destination;
 };
 exports.safePipe = safePipe;
-const handleStreamError = (stream, onError) => (0, exports.safePipe)(stream, new stream_1.PassThrough(), onError);
+const handleStreamError = (stream, onError) => {
+    const wrapper = new stream_1.PassThrough();
+    // `safePipe` propagates source → destination teardown, but not the reverse. The worker hands this
+    // wrapper to Fastify and destroys it when the HTTP client disconnects (issue #3885); plain pipe()
+    // would leave the source (and the in-flight render upstream of it) running. Propagate a premature
+    // wrapper teardown back to the source so the render is aborted. `writableEnded` is true only after a
+    // normal end (source finished → safePipe ended the wrapper), so this is a no-op on normal
+    // completion and fires only when the wrapper is destroyed before it ends.
+    wrapper.once('close', () => {
+        if (!wrapper.writableEnded && !stream.destroyed) {
+            stream.destroy();
+        }
+    });
+    return (0, exports.safePipe)(stream, wrapper, onError);
+};
 exports.handleStreamError = handleStreamError;
 const isErrorRenderResult = (result) => typeof result === 'object' && !(0, exports.isReadableStream)(result) && 'exceptionMessage' in result;
 exports.isErrorRenderResult = isErrorRenderResult;
@@ -231,7 +271,7 @@ function getRequestBundleFilePath(bundleTimestamp) {
 }
 function getAssetPath(bundleTimestamp, filename) {
     const bundleDirectory = getBundleDirectory(bundleTimestamp);
-    return path_1.default.join(bundleDirectory, filename);
+    return path_1.default.join(bundleDirectory, validateAssetFilename(filename));
 }
 async function validateBundlesExist(bundleTimestamp, dependencyBundleTimestamps) {
     const missingBundles = (await Promise.all([...(dependencyBundleTimestamps ?? []), bundleTimestamp].map(async (timestamp) => {

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

@@ -1,5 +1,10 @@
 import type { ResponseResult } from '../shared/utils';
 import type { ExecutionContext } from './vm';
+export declare const PULL_ENABLED_KEY = "pullEnabled";
+export declare const PUSH_PROPS_KEY = "pushProps";
+export declare const PROP_REQUEST_EMITTER_KEY = "propRequestEmitter";
+export declare const ASYNC_PROPS_MANAGER_KEY = "asyncPropsManager";
+export declare const MAX_PULL_PROP_NAME_LENGTH = 256;
 export type IncrementalRenderSink = {
     /** Called for every subsequent NDJSON object after the first one */
     add: (chunk: unknown) => Promise<void>;
@@ -10,6 +15,8 @@ export type UpdateChunk = {
     bundleTimestamp: string | number;
     updateChunk: string;
 };
+/** @internal Used by protocol regression tests. */
+export declare function catchUpAsyncPropsManagerPullBridge(value: unknown): boolean;
 export type IncrementalRenderInitialRequest = {
     firstRequestChunk: unknown;
     bundleTimestamp: string | number;
@@ -18,6 +25,9 @@ export type IncrementalRenderInitialRequest = {
 export type FirstIncrementalRenderRequestChunk = {
     renderingRequest: string;
     onRequestClosedUpdateChunk?: UpdateChunk;
+    pullEnabled?: boolean;
+    pushProps?: string[];
+    rscStreamObservability?: boolean;
 };
 export type IncrementalRenderResult = {
     response: ResponseResult;

package/lib/worker/handleIncrementalRenderRequest.js

@@ -17,11 +17,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PULL_PROP_NAME_LENGTH = exports.ASYNC_PROPS_MANAGER_KEY = exports.PROP_REQUEST_EMITTER_KEY = exports.PUSH_PROPS_KEY = exports.PULL_ENABLED_KEY = void 0;
+exports.catchUpAsyncPropsManagerPullBridge = catchUpAsyncPropsManagerPullBridge;
 exports.handleIncrementalRenderRequest = handleIncrementalRenderRequest;
+const stream_1 = require("stream");
 const handleRenderRequest_1 = require("./handleRenderRequest");
 const log_1 = __importDefault(require("../shared/log"));
 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';
+exports.ASYNC_PROPS_MANAGER_KEY = 'asyncPropsManager';
+exports.MAX_PULL_PROP_NAME_LENGTH = 256;
 class InvalidIncrementalRenderChunkError extends Error {
     constructor() {
         super('Invalid incremental render chunk received, missing properties');
@@ -38,6 +49,38 @@ function assertIsUpdateChunk(value) {
         throw new InvalidIncrementalRenderChunkError();
     }
 }
+function isAsyncPropsManagerPullBridge(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.catchUpPropRequests === 'function';
+}
+function isLegacyAsyncPropsManagerPullBridge(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.flushPendingPullRequests === 'function' &&
+        typeof candidate.emitPendingPullRequests === 'function');
+}
+/** @internal Used by protocol regression tests. */
+function catchUpAsyncPropsManagerPullBridge(value) {
+    if (isAsyncPropsManagerPullBridge(value)) {
+        value.catchUpPropRequests();
+        return true;
+    }
+    if (isLegacyAsyncPropsManagerPullBridge(value)) {
+        // Current AsyncPropsManager keeps both methods as aliases of
+        // catchUpPropRequests() for older node renderers. Calling both is
+        // intentionally harmless: buffered requests drain on the first call and
+        // pullRequested flags prevent duplicate emissions on the second.
+        value.flushPendingPullRequests();
+        value.emitPendingPullRequests();
+        return true;
+    }
+    return false;
+}
 function assertFirstIncrementalRenderRequestChunk(chunk) {
     if (typeof chunk !== 'object' ||
         chunk === null ||
@@ -49,6 +92,20 @@ function assertFirstIncrementalRenderRequestChunk(chunk) {
     if ('onRequestClosedUpdateChunk' in chunk && chunk.onRequestClosedUpdateChunk) {
         assertIsUpdateChunk(chunk.onRequestClosedUpdateChunk);
     }
+    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'))) {
+        throw new Error('Invalid first incremental render request chunk: pushProps must be a string array');
+    }
 }
 /**
  * Handles the initial request for incremental rendering and returns a "sink" for updates.
@@ -81,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
@@ -92,58 +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 };
         }
-        // Return the result with a sink that uses the execution context
-        return {
-            response,
-            sink: {
-                executionContext,
-                add: async (chunk) => {
+        let finalResponse = response;
+        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;