react-on-rails-pro-node-renderer 17.0.0-rc.2 → 17.0.0-rc.4

package/lib/master.js

@@ -66,6 +66,8 @@ const errorReporter = __importStar(require("./shared/errorReporter.js"));
 const licenseValidator_js_1 = require("./shared/licenseValidator.js");
 const runRscPeerCompatibilityCheck_js_1 = require("./shared/runRscPeerCompatibilityCheck.js");
 const workerMessages_js_1 = require("./shared/workerMessages.js");
+const utils_js_1 = require("./shared/utils.js");
+const shutdownHooks_js_1 = require("./worker/shutdownHooks.js");
 const MILLISECONDS_IN_MINUTE = 60000;
 // How often to scan for orphaned upload directories.
 const ORPHAN_CLEANUP_INTERVAL_MS = 5 * MILLISECONDS_IN_MINUTE;
@@ -73,6 +75,26 @@ const ORPHAN_CLEANUP_INTERVAL_MS = 5 * MILLISECONDS_IN_MINUTE;
 // Set well above the longest realistic upload duration so that large bundle
 // uploads in progress are never deleted by the cleanup timer.
 const ORPHAN_AGE_THRESHOLD_MS = 30 * MILLISECONDS_IN_MINUTE;
+// Give workers a short window to receive SHUTDOWN_WORKER_MESSAGE and enter
+// their own graceful shutdown path before the master falls back to disconnect().
+const MASTER_WORKER_SHUTDOWN_MESSAGE_GRACE_MS = 1000;
+// Hard deadline for the master to exit after it begins draining workers. It
+// starts before workers receive SHUTDOWN_WORKER_MESSAGE, so it must include the
+// message grace window plus the worker hook budget. If a worker is stuck after
+// that point, this guarantees the master still exits.
+const MASTER_SHUTDOWN_TIMEOUT_MS = MASTER_WORKER_SHUTDOWN_MESSAGE_GRACE_MS + shutdownHooks_js_1.WORKER_SHUTDOWN_HOOKS_TIMEOUT_MS;
+// When a worker's event loop is blocked (synchronous render) it can process
+// neither SHUTDOWN_WORKER_MESSAGE nor a disconnect, so only SIGKILL can stop
+// it — and the master must send that SIGKILL while it is still alive itself.
+// Process supervisors kill the master well before MASTER_SHUTDOWN_TIMEOUT_MS
+// (Foreman's default SIGTERM-to-SIGKILL window is 5s), so survivors are
+// force-killed early: after the message grace window has given draining a
+// chance, but safely inside the supervisor's window.
+const SHUTDOWN_WORKER_FORCE_KILL_TIMEOUT_MS = 2000;
+const SIGNAL_EXIT_CODES = {
+    SIGINT: 130,
+    SIGTERM: 143,
+};
 function masterRun(runningConfig) {
     // This is memoized after the wrapper path runs, but still protects direct `./master` entrypoint users.
     (0, runRscPeerCompatibilityCheck_js_1.runRscPeerCompatibilityCheck)({ proVersion: packageJson_js_1.default.version });
@@ -124,34 +146,130 @@ function masterRun(runningConfig) {
         })();
     }, ORPHAN_CLEANUP_INTERVAL_MS);
     let isAbortingForStartupFailure = false;
+    let hasReportedStartupFailure = false;
     let fatalStartupFailure = null;
-    let hasInitiatedShutdown = false;
+    // Set as soon as any shutdown path (external signal or startup-failure abort)
+    // begins. Read by the `cluster.on('exit')` handler to suppress re-forking
+    // workers that exit because we are intentionally tearing the cluster down.
+    let isShuttingDown = false;
+    // Drain every live worker, then exit with `exitCode`. Idempotent: only the
+    // first call performs the disconnect + exit; later calls are no-ops so that
+    // an external signal and a near-simultaneous startup-failure abort can't both
+    // disconnect or schedule duplicate exits.
+    //
+    // cluster.disconnect() is async, but its callback only proves workers have
+    // disconnected from IPC. Workers may still be draining in-flight requests, so
+    // external signal shutdown also waits for their exit events before the master
+    // exits. A hard-deadline timer guarantees the master still exits if a worker
+    // is stuck.
+    const currentWorkers = () => Object.values(cluster_1.default.workers ?? {}).filter((worker) => Boolean(worker));
+    const forceKillSurvivingWorkers = (workers) => {
+        workers.forEach((worker) => {
+            const workerProcess = worker.process;
+            // isDead() only: ChildProcess.killed means a signal was sent, not that
+            // the process died — e.g. a blocked worker surviving destroy()'s SIGTERM.
+            if (worker.isDead())
+                return;
+            try {
+                workerProcess.kill('SIGKILL');
+            }
+            catch (err) {
+                log_js_1.default.warn({ msg: 'Error sending SIGKILL to worker during node renderer master shutdown', err });
+            }
+        });
+    };
+    const sendGracefulShutdownMessageToWorkers = (workers) => {
+        workers.forEach((worker) => {
+            try {
+                worker.send(utils_js_1.SHUTDOWN_WORKER_MESSAGE);
+            }
+            catch (err) {
+                log_js_1.default.warn({ msg: 'Error sending graceful shutdown message to worker', err });
+            }
+        });
+    };
+    const waitForWorkerExits = (workers, onAllWorkersExited) => {
+        let remainingWorkers = 0;
+        let hasFinished = false;
+        const finishIfComplete = () => {
+            if (hasFinished || remainingWorkers > 0)
+                return;
+            hasFinished = true;
+            onAllWorkersExited();
+        };
+        workers.forEach((worker) => {
+            if (worker.isDead())
+                return;
+            remainingWorkers += 1;
+            const markWorkerExited = () => {
+                remainingWorkers -= 1;
+                finishIfComplete();
+            };
+            worker.once('exit', markWorkerExited);
+            if (worker.isDead()) {
+                worker.off('exit', markWorkerExited);
+                markWorkerExited();
+            }
+        });
+        finishIfComplete();
+    };
+    const shutdownGracefully = (exitCode, notifyWorkersBeforeDisconnect = false) => {
+        if (isShuttingDown)
+            return;
+        isShuttingDown = true;
+        const workersAtShutdown = currentWorkers();
+        const shutdownTimer = setTimeout(() => {
+            forceKillSurvivingWorkers(workersAtShutdown);
+            process.exit(exitCode);
+        }, MASTER_SHUTDOWN_TIMEOUT_MS);
+        if (typeof shutdownTimer.unref === 'function')
+            shutdownTimer.unref();
+        // Early force-kill of workers that cannot drain (blocked event loop).
+        // Their SIGKILL-induced exits complete the disconnect, which lets the
+        // normal waitForWorkerExits path below finish the shutdown promptly.
+        const forceKillTimer = setTimeout(() => {
+            forceKillSurvivingWorkers(workersAtShutdown);
+        }, SHUTDOWN_WORKER_FORCE_KILL_TIMEOUT_MS);
+        if (typeof forceKillTimer.unref === 'function')
+            forceKillTimer.unref();
+        const finishShutdown = () => {
+            clearTimeout(shutdownTimer);
+            clearTimeout(forceKillTimer);
+            process.exit(exitCode);
+        };
+        const disconnectCluster = () => {
+            cluster_1.default.disconnect(() => {
+                if (notifyWorkersBeforeDisconnect) {
+                    waitForWorkerExits(workersAtShutdown, finishShutdown);
+                    return;
+                }
+                finishShutdown();
+            });
+        };
+        if (notifyWorkersBeforeDisconnect) {
+            sendGracefulShutdownMessageToWorkers(workersAtShutdown);
+            setTimeout(disconnectCluster, MASTER_WORKER_SHUTDOWN_MESSAGE_GRACE_MS);
+            return;
+        }
+        disconnectCluster();
+    };
     const abortForStartupFailure = () => {
         if (!(isAbortingForStartupFailure && fatalStartupFailure))
             return false;
-        if (!hasInitiatedShutdown) {
-            hasInitiatedShutdown = true;
-            // Note: the exiting worker may differ from the one that sent the
-            // failure message if multiple workers exit in rapid succession.
-            // We always report the first failure received.
-            const { failure, workerId: failedWorkerId } = fatalStartupFailure;
-            const msg = failure.code === 'EADDRINUSE'
-                ? `Node renderer startup failed: ${failure.host}:${failure.port} is already in use`
-                : `Node renderer startup failed in worker ${failedWorkerId}: ${failure.message}`;
-            errorReporter.message(msg);
-            // Disconnect all live workers so they release their ports before the
-            // master exits. cluster.disconnect() is async — the callback fires
-            // once every worker has disconnected. A hard-deadline timer guarantees
-            // the master still exits if a worker is stuck (leaked handle, blocking
-            // syscall, etc.), following the same pattern as restartWorkers.ts.
-            const MASTER_SHUTDOWN_TIMEOUT_MS = 5000;
-            const shutdownTimer = setTimeout(() => process.exit(1), MASTER_SHUTDOWN_TIMEOUT_MS);
-            if (typeof shutdownTimer.unref === 'function')
-                shutdownTimer.unref();
-            cluster_1.default.disconnect(() => {
-                clearTimeout(shutdownTimer);
-                process.exit(1);
-            });
+        if (hasReportedStartupFailure)
+            return true;
+        // Note: the exiting worker may differ from the one that sent the
+        // failure message if multiple workers exit in rapid succession.
+        // We always report the first failure received.
+        const { failure, workerId: failedWorkerId } = fatalStartupFailure;
+        const msg = failure.code === 'EADDRINUSE'
+            ? `Node renderer startup failed: ${failure.host}:${failure.port} is already in use`
+            : `Node renderer startup failed in worker ${failedWorkerId}: ${failure.message}`;
+        errorReporter.message(msg);
+        hasReportedStartupFailure = true;
+        if (!isShuttingDown) {
+            // Exit non-zero so supervisors (Foreman/systemd/k8s) see the failed start.
+            shutdownGracefully(1);
         }
         return true;
     };
@@ -163,17 +281,23 @@ function masterRun(runningConfig) {
         isAbortingForStartupFailure = true;
         fatalStartupFailure = { workerId: worker.id, failure: message };
     });
-    for (let i = 0; i < workersCount; i += 1) {
-        cluster_1.default.fork();
-    }
     // Listen for dying workers:
     cluster_1.default.on('exit', (worker) => {
         // Once a startup failure has been detected, abort regardless of whether
         // this particular exit was from the failing worker, a scheduled restart,
-        // or an unrelated crash. Don't fork any more workers.
+        // or an unrelated crash. Don't fork any more workers. If an external signal
+        // already started shutdown, still report the recorded failure once while
+        // preserving the signal-style exit code and avoiding duplicate disconnects.
         if (abortForStartupFailure()) {
             return;
         }
+        // If we are intentionally tearing the cluster down (external SIGTERM/SIGINT
+        // or a startup-failure abort), workers are expected to exit — never re-fork
+        // them, or we would resurrect the processes we are trying to drain and leave
+        // them orphaned after the master exits.
+        if (isShuttingDown) {
+            return;
+        }
         if (worker.isScheduledRestart) {
             log_js_1.default.info('Restarting worker #%d on schedule', worker.id);
             cluster_1.default.fork();
@@ -182,7 +306,9 @@ function masterRun(runningConfig) {
         // Give in-flight startup-failure IPC messages one event-loop turn to be
         // processed before classifying this as an ordinary runtime crash.
         setImmediate(() => {
-            if (abortForStartupFailure())
+            // A startup failure may have arrived during this event-loop turn; report
+            // it before any signal-shutdown bail-out suppresses crash classification.
+            if (abortForStartupFailure() || isShuttingDown)
                 return;
             // TODO: Track last rendering request per worker.id
             // TODO: Consider blocking a given rendering request if it kills a worker more than X times
@@ -191,6 +317,20 @@ function masterRun(runningConfig) {
             cluster_1.default.fork();
         });
     });
+    // Drain workers on external shutdown signals. Process managers (Foreman,
+    // systemd, Kubernetes, Docker) send SIGTERM (and SIGINT on Ctrl-C in a
+    // foreground terminal) to the master. Without these handlers the master is
+    // killed immediately and its forked workers are left orphaned, holding their
+    // ports.
+    const handleShutdownSignal = (signal) => {
+        log_js_1.default.info('Received %s, draining workers before shutting down the node renderer master', signal);
+        shutdownGracefully(SIGNAL_EXIT_CODES[signal] ?? 0, true);
+    };
+    process.on('SIGTERM', () => handleShutdownSignal('SIGTERM'));
+    process.on('SIGINT', () => handleShutdownSignal('SIGINT'));
+    for (let i = 0; i < workersCount; i += 1) {
+        cluster_1.default.fork();
+    }
     // Schedule regular restarts of workers
     if (allWorkersRestartInterval && delayBetweenIndividualWorkerRestarts) {
         log_js_1.default.info('Scheduled workers restarts every %d minutes (%d minutes btw each)', allWorkersRestartInterval, delayBetweenIndividualWorkerRestarts);

package/lib/shared/checkRscPeerCompatibility.js

@@ -41,8 +41,20 @@ const isAtLeast = (actual, floor) => {
     return true;
 };
 const sameTuple = (left, right) => left.every((value, index) => value === right[index]);
-const supportedReactRange = ({ supportedMajor, supportedMinor, minPatch, }) => `${supportedMajor}.${supportedMinor}.x with patch >= ${supportedMajor}.${supportedMinor}.${minPatch}`;
-const isSupportedReactTuple = ([major, minor, patch], { supportedMajor, supportedMinor, minPatch }) => major === supportedMajor && minor === supportedMinor && patch >= minPatch;
+const supportedRscRange = ({ supportedMajor }, { supportedRanges }) => {
+    const supportedMinors = [...new Set(supportedRanges.map((range) => range.rscMinor))].sort((left, right) => left - right);
+    return supportedMinors.map((minor) => `${supportedMajor}.${minor}.x`).join(' or ');
+};
+const supportedReactRange = (rscTuple, { supportedMajor, supportedRanges }) => {
+    const rscMinor = rscTuple[1];
+    const matchingRanges = supportedRanges.filter((range) => range.rscMinor === rscMinor);
+    return matchingRanges
+        .map(({ minor, minPatch }) => `${supportedMajor}.${minor}.x with patch >= ${supportedMajor}.${minor}.${minPatch}`)
+        .join(' or ');
+};
+const isSupportedReactTuple = ([major, minor, patch], rscTuple, { supportedMajor, supportedRanges }) => major === supportedMajor &&
+    supportedRanges.some((range) => rscTuple[1] === range.rscMinor && minor === range.minor && patch >= range.minPatch);
+const isSupportedRscMinor = (rscTuple, { supportedRanges }) => supportedRanges.some((range) => rscTuple[1] === range.rscMinor);
 const proLabel = (proVersion) => proVersion ? `React on Rails Pro (${proVersion})` : 'React on Rails Pro';
 const errorMessage = (pkg, found, want, proVersion) => [
     `[ReactOnRails] Incompatible ${pkg} version.`,
@@ -70,24 +82,30 @@ function checkRscPeerCompatibility(input) {
             message: errorMessage('react-on-rails-rsc', rscVersion, `${reactOnRailsRsc.supportedMajor}.x`, proVersion),
         };
     }
+    if (!isSupportedRscMinor(rscTuple, react)) {
+        return {
+            level: 'error',
+            message: errorMessage('react-on-rails-rsc', rscVersion, supportedRscRange(reactOnRailsRsc, react), proVersion),
+        };
+    }
     // If React is not resolvable (unusual, since RSC requires React), skip this check;
     // an app with React truly absent will fail during normal module loading.
     let reactTuple = null;
     if (reactVersion) {
         reactTuple = parseTuple(reactVersion);
-        if (!isSupportedReactTuple(reactTuple, react)) {
+        if (!isSupportedReactTuple(reactTuple, rscTuple, react)) {
             return {
                 level: 'error',
-                message: errorMessage('react', reactVersion, supportedReactRange(react), proVersion),
+                message: errorMessage('react', reactVersion, supportedReactRange(rscTuple, react), proVersion),
             };
         }
     }
     if (reactDomVersion) {
         const reactDomTuple = parseTuple(reactDomVersion);
-        if (!isSupportedReactTuple(reactDomTuple, react)) {
+        if (!isSupportedReactTuple(reactDomTuple, rscTuple, react)) {
             return {
                 level: 'error',
-                message: errorMessage('react-dom', reactDomVersion, supportedReactRange(react), proVersion),
+                message: errorMessage('react-dom', reactDomVersion, supportedReactRange(rscTuple, react), proVersion),
             };
         }
         if (reactTuple && !sameTuple(reactTuple, reactDomTuple)) {

package/lib/shared/configBuilder.d.ts

@@ -25,6 +25,7 @@ export interface Config {
     includeTimerPolyfills?: boolean;
     replayServerAsyncOperationLogs: boolean;
     maxVMPoolSize: number;
+    enableHealthEndpoints: boolean;
 }
 export declare function getConfig(): Config;
 export declare function logSanitizedConfig(): void;

package/lib/shared/configBuilder.js

@@ -109,6 +109,9 @@ function defaultReplayServerAsyncOperationLogs() {
     }
     return env.NODE_ENV?.toLowerCase() === 'development';
 }
+function truthyHealthEndpointFlag(value) {
+    return value === '1' || (0, truthy_js_1.default)(value);
+}
 const defaultConfig = {
     // Use env port if we run on Heroku
     port: Number(env.RENDERER_PORT) || DEFAULT_PORT,
@@ -142,6 +145,8 @@ const defaultConfig = {
     // Maximum number of VM contexts to keep in memory. Defaults to 2 since typically only two contexts
     // are needed - one for the server bundle and one for React Server Components (RSC) if enabled.
     maxVMPoolSize: (env.MAX_VM_POOL_SIZE && parseInt(env.MAX_VM_POOL_SIZE, 10)) || 2,
+    // Built-in /health and /ready probe endpoints are opt-in.
+    enableHealthEndpoints: truthyHealthEndpointFlag(env.RENDERER_ENABLE_HEALTH_ENDPOINTS),
 };
 function envValuesUsed() {
     return {
@@ -163,6 +168,7 @@ function envValuesUsed() {
         INCLUDE_TIMER_POLYFILLS: !('includeTimerPolyfills' in userConfig) && env.INCLUDE_TIMER_POLYFILLS,
         REPLAY_SERVER_ASYNC_OPERATION_LOGS: !userConfig.replayServerAsyncOperationLogs && env.REPLAY_SERVER_ASYNC_OPERATION_LOGS,
         MAX_VM_POOL_SIZE: !userConfig.maxVMPoolSize && env.MAX_VM_POOL_SIZE,
+        RENDERER_ENABLE_HEALTH_ENDPOINTS: !('enableHealthEndpoints' in userConfig) && env.RENDERER_ENABLE_HEALTH_ENDPOINTS,
     };
 }
 function sanitizedSettings(aConfig, defaultValue) {
@@ -248,6 +254,7 @@ function buildConfig(providedUserConfig) {
         password: env.RENDERER_PASSWORD,
         // Re-evaluate env-derived defaults at build time in case env vars are set post-import.
         replayServerAsyncOperationLogs: defaultReplayServerAsyncOperationLogs(),
+        enableHealthEndpoints: truthyHealthEndpointFlag(env.RENDERER_ENABLE_HEALTH_ENDPOINTS),
     };
     config = { ...runtimeDefaultConfig, ...userConfig };
     if (explicitUndefinedPassword) {
@@ -269,6 +276,8 @@ function buildConfig(providedUserConfig) {
             'Use RENDERER_SERVER_BUNDLE_CACHE_PATH instead.');
     }
     config.supportModules = (0, truthy_js_1.default)(config.supportModules);
+    // Coerce in case a user config passes an env-derived string (e.g. "true").
+    config.enableHealthEndpoints = truthyHealthEndpointFlag(config.enableHealthEndpoints);
     if (config.maxVMPoolSize <= 0 || !Number.isInteger(config.maxVMPoolSize)) {
         throw new Error('maxVMPoolSize must be a positive integer');
     }

package/lib/shared/rscPeerSupport.d.ts

@@ -5,8 +5,15 @@ export declare const RSC_PEER_SUPPORT: {
     };
     readonly react: {
         readonly supportedMajor: 19;
-        readonly supportedMinor: 0;
-        readonly minPatch: 4;
+        readonly supportedRanges: readonly [{
+            readonly rscMinor: 0;
+            readonly minor: 0;
+            readonly minPatch: 4;
+        }, {
+            readonly rscMinor: 2;
+            readonly minor: 2;
+            readonly minPatch: 7;
+        }];
     };
 };
 //# sourceMappingURL=rscPeerSupport.d.ts.map

package/lib/shared/rscPeerSupport.js

@@ -26,6 +26,13 @@ exports.RSC_PEER_SUPPORT = void 0;
 // (the stable 19.0.5 ship/pin is tracked by issue #3634).
 exports.RSC_PEER_SUPPORT = {
     reactOnRailsRsc: { recommendedMin: '19.0.2', supportedMajor: 19 },
-    react: { supportedMajor: 19, supportedMinor: 0, minPatch: 4 },
+    react: {
+        supportedMajor: 19,
+        supportedRanges: [
+            { rscMinor: 0, minor: 0, minPatch: 4 },
+            // React 19.2.7 is the coordinated floor for react-on-rails-rsc 19.2.x.
+            { rscMinor: 2, minor: 2, minPatch: 7 },
+        ],
+    },
 };
 //# sourceMappingURL=rscPeerSupport.js.map

package/lib/shared/utils.d.ts

@@ -3,6 +3,7 @@ import { MoveOptions, CopyOptions } from 'fs-extra';
 import { Readable, Writable, PassThrough } from 'stream';
 import type { TracingContext } from './tracing.js';
 import type { RenderResult } from '../worker/vm.js';
+import { remapStackTrace } from '../worker/vmSourceMapSupport.js';
 export declare const TRUNCATION_FILLER = "\n... TRUNCATED ...\n";
 export declare const SHUTDOWN_WORKER_MESSAGE = "NODE_RENDERER_SHUTDOWN_WORKER";
 export declare function workerIdLabel(): number | "NO WORKER ID";
@@ -10,6 +11,9 @@ export declare function smartTrim(value: unknown, maxLength?: number): string |
 export interface ResponseResult {
     headers: {
         'Cache-Control'?: string;
+        'Content-Type'?: string;
+        'X-Content-Type-Options'?: string;
+        [key: string]: string | undefined;
     };
     status: number;
     data?: unknown;
@@ -27,8 +31,10 @@ export type RequestInfo = {
  * @param request Either a rendering request (auto-labeled) or a { label, content } pair
  * @param error The error that was thrown (typed as `unknown` to minimize casts in `catch`)
  * @param context Optional context to include in the error message
+ * @param stackRemapper Defaults to scanning registered source-map bundles. VM request paths pass a
+ * registration-scoped remapper to avoid rewriting unrelated bundle paths.
  */
-export declare function formatExceptionMessage(request: RequestInfo, error: unknown, context?: string): string;
+export declare function formatExceptionMessage(request: RequestInfo, error: unknown, context?: string, stackRemapper?: typeof remapStackTrace): string;
 export declare function saveMultipartFile(multipartFile: MultipartFile, destinationPath: string): Promise<void>;
 export interface Asset {
     type: 'asset';

package/lib/shared/utils.js

@@ -74,6 +74,7 @@ const errorReporter = __importStar(require("./errorReporter.js"));
 const configBuilder_js_1 = require("./configBuilder.js");
 const log_js_1 = __importDefault(require("./log.js"));
 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';
 function workerIdLabel() {
@@ -121,10 +122,14 @@ function errorResponseResult(msg, tracingContext) {
  * @param request Either a rendering request (auto-labeled) or a { label, content } pair
  * @param error The error that was thrown (typed as `unknown` to minimize casts in `catch`)
  * @param context Optional context to include in the error message
+ * @param stackRemapper Defaults to scanning registered source-map bundles. VM request paths pass a
+ * registration-scoped remapper to avoid rewriting unrelated bundle paths.
  */
-function formatExceptionMessage(request, error, context) {
+function formatExceptionMessage(request, error, context, stackRemapper = vmSourceMapSupport_js_1.remapStackTrace) {
     const label = 'renderingRequest' in request ? 'JS code for rendering request was:' : request.label;
     const content = 'renderingRequest' in request ? request.renderingRequest : request.content;
+    const rawStack = error.stack;
+    const stack = stackRemapper(rawStack) ?? rawStack;
     return `${context ? `\nContext:\n${context}\n` : ''}
 ${label}
 ${smartTrim(content)}
@@ -133,7 +138,7 @@ EXCEPTION MESSAGE:
 ${error.message || error}
 
 STACK:
-${error.stack}`;
+${stack}`;
 }
 // https://github.com/fastify/fastify-multipart?tab=readme-ov-file#usage
 const pump = (0, util_1.promisify)(stream_1.pipeline);
@@ -205,13 +210,24 @@ const delay = (milliseconds) => new Promise((resolve) => {
     setTimeout(resolve, milliseconds);
 });
 exports.delay = delay;
+// Keep aligned with ReactOnRailsPro::RollingDeploy::SAFE_HASH_PATTERN.
+const BUNDLE_TIMESTAMP_PATH_COMPONENT_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+function bundleTimestampPathComponent(bundleTimestamp) {
+    const pathComponent = String(bundleTimestamp);
+    if (!BUNDLE_TIMESTAMP_PATH_COMPONENT_PATTERN.test(pathComponent)) {
+        throw new Error(`Invalid bundle timestamp path component: ${pathComponent}. ` +
+            'Expected only letters, digits, dots, underscores, and hyphens.');
+    }
+    return pathComponent;
+}
 function getBundleDirectory(bundleTimestamp) {
     const { serverBundleCachePath } = (0, configBuilder_js_1.getConfig)();
-    return path_1.default.join(serverBundleCachePath, `${bundleTimestamp}`);
+    return path_1.default.resolve(serverBundleCachePath, bundleTimestampPathComponent(bundleTimestamp));
 }
 function getRequestBundleFilePath(bundleTimestamp) {
-    const bundleDirectory = getBundleDirectory(bundleTimestamp);
-    return path_1.default.join(bundleDirectory, `${bundleTimestamp}.js`);
+    const pathComponent = bundleTimestampPathComponent(bundleTimestamp);
+    const bundleDirectory = getBundleDirectory(pathComponent);
+    return path_1.default.join(bundleDirectory, `${pathComponent}.js`);
 }
 function getAssetPath(bundleTimestamp, filename) {
     const bundleDirectory = getBundleDirectory(bundleTimestamp);

package/lib/worker/handleIncrementalRenderRequest.d.ts

@@ -1,8 +1,10 @@
 import type { ResponseResult } from '../shared/utils';
+import type { ExecutionContext } from './vm';
 export type IncrementalRenderSink = {
     /** Called for every subsequent NDJSON object after the first one */
     add: (chunk: unknown) => Promise<void>;
-    handleRequestClosed: () => void;
+    handleRequestClosed: () => Promise<void>;
+    executionContext: ExecutionContext;
 };
 export type UpdateChunk = {
     bundleTimestamp: string | number;

package/lib/worker/handleIncrementalRenderRequest.js

@@ -102,6 +102,7 @@ async function handleIncrementalRenderRequest(initial) {
         return {
             response,
             sink: {
+                executionContext,
                 add: async (chunk) => {
                     try {
                         assertIsUpdateChunk(chunk);
@@ -122,20 +123,24 @@ async function handleIncrementalRenderRequest(initial) {
                         }
                     }
                 },
-                handleRequestClosed: () => {
+                handleRequestClosed: async () => {
                     if (!onRequestClosedUpdateChunk) {
                         return;
                     }
                     const bundlePath = (0, utils_1.getRequestBundleFilePath)(onRequestClosedUpdateChunk.bundleTimestamp);
-                    executionContext
-                        .runInVM(onRequestClosedUpdateChunk.updateChunk, bundlePath)
-                        .catch((err) => {
+                    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,
                         });
-                    });
+                    }
                 },
             },
         };

package/lib/worker/vm.d.ts

@@ -3,9 +3,11 @@ import type { Readable } from 'stream';
 import type { ReactOnRails as ROR } from 'react-on-rails' with { 'resolution-mode': 'import' };
 import type { Context } from 'vm';
 import SharedConsoleHistory from '../shared/sharedConsoleHistory.js';
+import { type BundleSourceMapRegistration } from './vmSourceMapSupport.js';
 export interface VMContext {
     context: Context;
     sharedConsoleHistory: SharedConsoleHistory;
+    sourceMapRegistration: BundleSourceMapRegistration;
     lastUsed: number;
 }
 /**
@@ -17,6 +19,19 @@ export declare function hasVMContextForBundle(bundlePath: string): boolean;
  * Get a specific VM context by bundle path
  */
 export declare function getVMContext(bundlePath: string): VMContext | undefined;
+/**
+ * Whether this worker has at least one bundle compiled into a VM context.
+ * Used by the built-in /ready readiness endpoint: a worker with zero loaded
+ * bundles cannot serve render requests until a bundle is uploaded.
+ *
+ * This intentionally stays false while a bundle is still compiling in
+ * vmCreationPromises; /ready flips to 200 only after compilation finishes and
+ * the compiled context is stored in vmContexts.
+ *
+ * Pool eviction can remove older bundle contexts, but readiness remains true as
+ * long as at least one compiled bundle remains in the pool.
+ */
+export declare function hasAnyVMContext(): boolean;
 /**
  * The type of the result returned by executing the code payload sent in the rendering request.
  */
@@ -39,6 +54,7 @@ export declare class VMContextNotFoundError extends Error {
 export type ExecutionContext = {
     runInVM: (renderingRequest: string, bundleFilePath: string, vmCluster?: typeof cluster) => Promise<RenderResult>;
     getVMContext: (bundleFilePath: string) => VMContext | undefined;
+    release: () => void;
 };
 /**
  * Builds an ExecutionContext that manages VM execution for a set of bundles.