@lensmcp/cluster 1.0.0

package/main.devserver.js

@@ -0,0 +1,812 @@
+"use strict";
+// Parent/Child dual-mode runner with multi-child round-robin + hot reload.
+//
+// Parent (default):
+//  - Stable public port (env.PORT or first free >= 8100).
+//  - Spawns N children (env.CHILD_COUNT, default 2), each runs this file with APP_RUNNER=1.
+//  - Round-robin load balancing to healthy children.
+//  - POST /webpack/reload:
+//      * forwards 'reload' to all healthy children (they hot-swap in-process)
+//      * respawns any unhealthy/crashed children
+//  - If a child crashes, it is marked unhealthy; parent keeps serving via others.
+//  - If ALL are down, parent returns 503 with last errors. Parent only dies on user interrupt.
+//
+// Child (APP_RUNNER=1):
+//  - Loads webpack bundle (BUNDLE_PATH, default ./main.js) exporting global.createChildApp().
+//  - createChildApp() bootstraps NestJS+Fastify, returns a raw http.RequestListener handler.
+//  - Child wraps handler in http.createServer on a Unix socket; reports {type:'ready', socketPath} via IPC.
+//  - On 'reload' IPC or POST /webpack/reload, closes old app, re-imports bundle, swaps handler in-place.
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("node:path"));
+const fs = tslib_1.__importStar(require("node:fs"));
+const os = tslib_1.__importStar(require("node:os"));
+const node_child_process_1 = require("node:child_process");
+const http = tslib_1.__importStar(require("node:http"));
+const readline = tslib_1.__importStar(require("node:readline"));
+const inspector = tslib_1.__importStar(require("node:inspector"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const httpProxy = require('http-proxy');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { prettyFactory } = require('pino-pretty');
+// ----------------------------- Shared Config ----------------------------------
+const BUNDLE_PATH = process.env.BUNDLE_PATH?.trim() || './main.js';
+const SERVICE_NAME = process.env.SERVICE_NAME || '';
+const SERVICE_PREFIX = process.env.SERVE_PREFIX ? `/${process.env.SERVE_PREFIX}` : '';
+const GATEWAY_MIDDLEWARE_PATH = process.env.GATEWAY_MIDDLEWARE || '';
+const GATEWAY_CONFIG = (() => {
+    const raw = process.env.GATEWAY_CONFIG;
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+})();
+let gatewayMiddleware = null;
+if (GATEWAY_MIDDLEWARE_PATH) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require(GATEWAY_MIDDLEWARE_PATH);
+        gatewayMiddleware = typeof mod === 'function' ? mod : (typeof mod.default === 'function' ? mod.default : null);
+        if (!gatewayMiddleware) {
+            console.warn(`[gateway] ${GATEWAY_MIDDLEWARE_PATH} does not export a function, gateway disabled`);
+        }
+    }
+    catch (err) {
+        console.error(`[gateway] Failed to load middleware from ${GATEWAY_MIDDLEWARE_PATH}:`, err);
+    }
+}
+function applyGatewayMiddleware(req) {
+    if (!gatewayMiddleware)
+        return;
+    try {
+        gatewayMiddleware(req, GATEWAY_CONFIG);
+    }
+    catch (err) {
+        console.error('[gateway] Middleware error:', err);
+    }
+}
+const GATEWAY_ROUTES = (() => {
+    try {
+        return JSON.parse(process.env.GATEWAY_ROUTES || '[]');
+    }
+    catch {
+        return [];
+    }
+})();
+const GATEWAY_HTTPS = process.env.GATEWAY_HTTPS === '1';
+function hostMatches(pattern, host) {
+    if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(1); // ".tetros.localhost"
+        return host.endsWith(suffix) || host === pattern.slice(2);
+    }
+    return host === pattern;
+}
+function matchGatewayRoute(req) {
+    if (GATEWAY_ROUTES.length === 0)
+        return undefined;
+    const host = (req.headers.host || '').split(':')[0];
+    const url = req.url || '/';
+    for (const route of GATEWAY_ROUTES) {
+        if (route.host && !hostMatches(route.host, host))
+            continue;
+        if (route.prefix && !url.startsWith(route.prefix))
+            continue;
+        return route;
+    }
+    return undefined;
+}
+// ----------------------------- Worker Config ------------------------------------
+const WORKER_NAMES = (() => {
+    try {
+        return JSON.parse(process.env.WORKERS || '[]');
+    }
+    catch {
+        return [];
+    }
+})();
+// ----------------------------- Socket Helpers ---------------------------------
+const SOCK_DIR = path.join(os.tmpdir(), `${SERVICE_NAME || 'lensmcp-cluster'}-devserver`);
+function childSockPath(id) {
+    return path.join(SOCK_DIR, `child-${id}.sock`);
+}
+function cleanupSock(sockPath) {
+    if (!sockPath)
+        return;
+    try {
+        fs.unlinkSync(sockPath);
+    }
+    catch { }
+}
+// delete from CJS cache + require fresh
+async function importFresh(spec) {
+    process.env.DEVSERVER_MODE = '1';
+    const resolved = path.isAbsolute(spec) ? spec : path.join(__dirname, spec);
+    eval(`delete require.cache["${resolved}"]`); // delete from CJS cache
+    return eval(`require("${resolved}")`);
+}
+function debounce(fn, ms) {
+    let t = null;
+    return (...args) => {
+        if (t)
+            clearTimeout(t);
+        t = setTimeout(() => fn(...args), ms);
+    };
+}
+// ===================================================================================
+// CHILD MODE (APP_RUNNER=1) — loads bundle, bootstraps NestJS app, listens on socket
+// ===================================================================================
+if (process.env.APP_RUNNER === '1') {
+    // Zero-touch instrumentation: load BEFORE the app bundle so the require
+    // hook sees pg/ioredis/bullmq/@nestjs/core on their first load, builtins
+    // (fs/net/exec) are tapped, NestFactory.create grafts the lens module, and
+    // the child-app bridge owns global.createChildApp — a completely plain
+    // main.ts (NestFactory.create + app.listen) becomes a pod with no
+    // devserver contract in host source. Legacy dual-mode bundles overwrite
+    // global.createChildApp at import and keep working unchanged.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        require('@lensmcp/node-instrumentation/register');
+    }
+    catch { /* instrumentation package absent — pods run untapped */ }
+    (async () => {
+        let current = null;
+        let swapping = false;
+        let pendingReload = false;
+        // Delegate starts as 503; swapped to the real handler after first boot
+        let delegate = (_req, res) => {
+            res.statusCode = 503;
+            res.end('starting');
+        };
+        async function swapNow() {
+            if (swapping) {
+                pendingReload = true;
+                console.log('[child] Reload deferred — will re-swap after current swap completes');
+                return current;
+            }
+            swapping = true;
+            // ── Stale-handler cleanup ──
+            // @frontegg/nestjs-common/app-builder registers process.on('uncaughtException')
+            // during build() and never removes it on close. After swap, the OLD handler
+            // fires during background teardown and crashes because its AsyncLocalStorage
+            // context is destroyed. Fix: wipe all handlers before re-import, then add
+            // a safe catch-all. The fresh bundle will register its own valid handlers.
+            process.removeAllListeners('uncaughtException');
+            process.removeAllListeners('unhandledRejection');
+            process.on('uncaughtException', (err, origin) => {
+                console.error(`[child] uncaughtException (${origin}):`, err);
+            });
+            process.on('unhandledRejection', (reason) => {
+                // Suppress known stale-context rejections from previous app's background teardown.
+                const msg = reason instanceof Error ? reason.stack || reason.message : String(reason);
+                if (msg.includes('FronteggContextScope') || msg.includes('populateLoggerMetadata')) {
+                    return; // swallow — old app context is gone, nothing to do
+                }
+                console.error('[child] unhandledRejection:', reason);
+            });
+            await importFresh(BUNDLE_PATH);
+            if (typeof global.createChildApp !== 'function') {
+                swapping = false;
+                throw new Error(`Bundle '${BUNDLE_PATH}' does not export createChildApp() and the zero-touch ` +
+                    `bridge is not active. Either install @lensmcp/node-instrumentation (a plain ` +
+                    `NestFactory.create + app.listen main.ts then just works) or set ` +
+                    `global.createChildApp in main.ts when DEVSERVER_MODE === '1'.`);
+            }
+            const next = await global.createChildApp();
+            const prev = current;
+            current = next;
+            delegate = next.handler;
+            console.log(`[child] Swapped to fresh app (previous closing in background)`);
+            if (prev)
+                prev.close().catch(err => console.error('[child] background close error:', err));
+            swapping = false;
+            if (pendingReload) {
+                pendingReload = false;
+                return swapNow();
+            }
+            return next;
+        }
+        // Create ONE debounced swapper that lives across requests
+        const debouncedSwap = debounce(async () => {
+            try {
+                console.log('[child] /webpack/reload');
+                await swapNow();
+            }
+            catch (e) {
+                console.error('[child] reload failed:', e);
+            }
+        }, 250);
+        // Raw HTTP server: admin reload endpoint + delegate all else to NestJS handler
+        const server = http.createServer((req, res) => {
+            if (req.method === 'POST' && req.url === '/webpack/reload') {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true }));
+                debouncedSwap();
+                return;
+            }
+            delegate(req, res);
+        });
+        const sockPath = process.env.CHILD_SOCK_PATH;
+        // ORPHAN GUARD: if the parent devserver dies (idle-kill, crash, tree
+        // SIGTERM that missed us), the IPC channel closes — exit immediately and
+        // remove our socket so no ghost pod (live process + stale sock) survives.
+        process.on('disconnect', () => {
+            try {
+                fs.unlinkSync(sockPath);
+            }
+            catch { /* already gone */ }
+            process.exit(0);
+        });
+        // boot once, then listen on Unix socket
+        try {
+            await swapNow();
+            const resolvedBundle = path.isAbsolute(BUNDLE_PATH) ? BUNDLE_PATH : path.join(__dirname, BUNDLE_PATH);
+            console.log(`[child] Using bundle: ${resolvedBundle}`);
+            cleanupSock(sockPath); // remove stale socket from previous run
+            server.listen(sockPath, () => {
+                console.log(`[child] Listening on ${sockPath}`);
+                if (process.send)
+                    process.send({ type: 'ready', socketPath: sockPath });
+            });
+        }
+        catch (err) {
+            console.error('[child] Startup error:', err);
+            if (process.send)
+                process.send({ type: 'boot-error', error: String(err?.stack || err) });
+            process.exitCode = 1;
+            return;
+        }
+        // IPC reload handler (parent-initiated reloads)
+        process.on('message', async (msg) => {
+            if (!msg || typeof msg !== 'object')
+                return;
+            if (msg.type === 'reload') {
+                try {
+                    await swapNow();
+                    if (process.send)
+                        process.send({ type: 'reloaded', socketPath: sockPath });
+                }
+                catch (e) {
+                    console.error('[child] reload error:', e);
+                    if (process.send)
+                        process.send({ type: 'reload-error', error: String(e?.stack || e) });
+                }
+            }
+        });
+        process.on('beforeExit', () => {
+            try {
+                inspector?.close?.();
+            }
+            catch {
+            }
+        });
+        const shutdown = async (sig) => {
+            console.log(`[child ${sig}] shutting down…`);
+            const closingApp = current?.close().catch(err => console.error('[child] close error:', err));
+            const closingServer = new Promise(resolve => server.close(() => resolve()));
+            cleanupSock(sockPath);
+            setTimeout(() => process.exit(0), 700).unref();
+            await Promise.all([closingApp, closingServer]);
+            process.exit(0);
+        };
+        ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT', 'SIGUSR2'].forEach(sig => {
+            process.on(sig, () => {
+                inspector?.close?.();
+                void shutdown(sig);
+            });
+        });
+    })();
+}
+else {
+    // ---------- Colored prefix helpers (no deps) ----------
+    const COLORS = [
+        '\x1b[36m', // cyan
+        '\x1b[33m', // yellow
+        '\x1b[35m', // magenta
+        '\x1b[32m', // green
+        '\x1b[34m', // blue
+        '\x1b[31m' // red
+    ];
+    const RESET = '\x1b[0m';
+    const CHILD_COUNT = Math.max(1, Number(process.env.CHILD_COUNT || 1));
+    const colorFor = (id) => {
+        return COLORS[(id - 1) % COLORS.length];
+    };
+    const tagFor = (id) => {
+        if (CHILD_COUNT === 1) {
+            return '';
+        }
+        const base = `[child#${id}] `;
+        return `${colorFor(id)}${base}${RESET}`;
+    };
+    const isJsonLog = (log) => {
+        return log.startsWith('{') && log.endsWith('}');
+    };
+    const wireProcLogging = (proc, tag) => {
+        const prettyLog = prettyFactory({
+            sync: true,
+            colorize: true,
+            crlf: true,
+            messageKey: 'message',
+            errorLikeObjectKeys: ['err', 'error'],
+            errorProps: 'type,message,stack',
+            ignore: [
+                'logContext', 'context', 'hostname', 'req', 'res', 'err.driverError',
+                'module', 'cloudEnvironment',
+                'frontegg-application-id', 'frontegg-tenant-id',
+                'frontegg-trace-id', 'frontegg-vendor-id',
+                'host', 'service', 'version',
+                'err', 'error',
+            ].join(','),
+            messageFormat: '{if module}[{module}] {end}{if context}[{context}] {end}{if logContext}[{logContext}] {end}{message}',
+            customPrettifiers: {
+                stack: (value) => '\n' + String(value),
+            },
+        });
+        const write = (kind, line) => {
+            const dest = kind === 'stdout' ? process.stdout : process.stderr;
+            const log = isJsonLog(line) ? prettyLog(line) : `${line}\n`;
+            dest.write(`${tag}${log}`);
+        };
+        const attach = (stream, kind) => {
+            if (!stream)
+                return;
+            const rl = readline.createInterface({ input: stream });
+            rl.on('line', (line) => write(kind, line));
+            rl.on('close', () => { });
+        };
+        attach(proc.stdout, 'stdout');
+        attach(proc.stderr, 'stderr');
+    };
+    const wireChildLogging = (info) => wireProcLogging(info.proc, tagFor(info.id));
+    (async () => {
+        // Ensure socket directory exists
+        fs.mkdirSync(SOCK_DIR, { recursive: true });
+        const proxy = httpProxy.createProxyServer({});
+        let publicPort = Number(process.env.PORT) || 0;
+        if (!publicPort)
+            publicPort = 9090;
+        const children = [];
+        let nextId = 1;
+        let rrIndex = 0;
+        let shuttingDown = false; // set by the parent's signal handler
+        let desiredPods = CHILD_COUNT; // pool target; grown by /webpack/scale
+        let recentCrashRespawns = []; // timestamps — crash-loop backstop
+        function healthyChildren() {
+            return children.filter(c => c.healthy && typeof c.socketPath === 'string');
+        }
+        function pickChild() {
+            const healthy = healthyChildren();
+            if (healthy.length === 0)
+                return null;
+            const idx = rrIndex % healthy.length;
+            rrIndex = (rrIndex + 1) % healthy.length;
+            return healthy[idx];
+        }
+        async function spawnChild() {
+            const id = nextId++;
+            const sockPath = childSockPath(id);
+            cleanupSock(sockPath); // remove stale socket
+            // When running from TS source (local dev), children need @swc-node/register too
+            const childExecArgv = ['--enable-source-maps'];
+            if (__filename.endsWith('.ts')) {
+                childExecArgv.unshift('--require', '@swc-node/register');
+            }
+            const proc = (0, node_child_process_1.fork)(__filename, {
+                env: {
+                    ...process.env,
+                    APP_RUNNER: '1',
+                    CHILD_SOCK_PATH: sockPath,
+                    CHILD_DEBUG_PORT: CHILD_COUNT == 1 ? '1' : '0',
+                },
+                stdio: ['inherit', 'pipe', 'pipe', 'ipc'],
+                execArgv: childExecArgv,
+            });
+            const info = { id, proc, healthy: false, lastError: null };
+            proc.on('message', (msg) => {
+                if (!msg || typeof msg !== 'object')
+                    return;
+                const m = msg;
+                if (m.type === 'ready') {
+                    info.socketPath = String(m.socketPath);
+                    info.healthy = true;
+                    console.log(`[parent] Child#${info.id} ready on socket ${info.socketPath}`);
+                }
+                else if (m.type === 'inspector-url') {
+                    console.log(`[parent] Child#${info.id} inspector: ${m.url}`);
+                }
+                else if (m.type === 'reloaded') {
+                    info.socketPath = String(m.socketPath);
+                    info.healthy = true;
+                    console.log(`[parent] Child#${info.id} hot-swapped on socket ${info.socketPath}`);
+                }
+                else if (m.type === 'reload-error') {
+                    info.lastError = String(m.error || 'unknown reload error');
+                    console.error(`[parent] Child#${info.id} reload error: ${info.lastError}`);
+                    info.healthy = false;
+                }
+                else if (m.type === 'boot-error') {
+                    info.lastError = String(m.error || 'unknown boot error');
+                    console.error(`[parent] Child#${info.id} boot error: ${info.lastError}`);
+                    info.healthy = false;
+                }
+            });
+            proc.on('exit', (code, signal) => {
+                const clean = signal === 'SIGINT' || signal === 'SIGTERM' || code === 0;
+                if (clean) {
+                    console.log(`[parent] Child#${info.id} exited cleanly (code=${code}, signal=${signal ?? 'none'})`);
+                }
+                else {
+                    console.error(`[parent] Child#${info.id} crashed (code=${code}, signal=${signal ?? 'none'})`);
+                    if (!info.lastError)
+                        info.lastError = `Child exited abnormally (code=${code}, signal=${signal ?? 'none'})`;
+                }
+                info.healthy = false;
+                cleanupSock(info.socketPath);
+                info.socketPath = undefined;
+                // Supervise the pool: a CRASHED pod (not a clean shutdown, not a
+                // reload/idle-kill) must be replaced or the pool silently shrinks to
+                // zero (with CHILD_COUNT=1, the service dies until a code edit). Drop
+                // the corpse and respawn after a short backoff — with a crash-loop
+                // backstop so a bundle that dies on boot doesn't busy-spin forever.
+                if (!clean && !shuttingDown) {
+                    const i = children.indexOf(info);
+                    if (i >= 0)
+                        children.splice(i, 1);
+                    const now = Date.now();
+                    recentCrashRespawns = recentCrashRespawns.filter((t) => now - t < 30_000);
+                    if (recentCrashRespawns.length >= 5) {
+                        console.error(`[parent] crash-loop detected (${recentCrashRespawns.length} respawns/30s) — pausing auto-respawn; POST /webpack/reload to retry`);
+                        return;
+                    }
+                    recentCrashRespawns.push(now);
+                    setTimeout(() => {
+                        const live = children.filter((c) => c.proc.killed === false).length;
+                        if (!shuttingDown && live < desiredPods) {
+                            console.log(`[parent] respawning a crashed pod (${live}/${desiredPods} live)`);
+                            void spawnChild().catch(() => undefined); // spawnChild pushes to children + wires logging itself
+                        }
+                    }, 1500).unref?.();
+                }
+            });
+            children.push(info);
+            // connect stdout/stderr now that it's piped
+            wireChildLogging(info);
+            return info;
+        }
+        async function ensurePoolSize(n) {
+            desiredPods = Math.max(desiredPods, n); // remember the target so crash-respawn restores it
+            const live = children.filter(c => c.proc.killed === false);
+            const need = n - live.length;
+            for (let i = 0; i < need; i++) {
+                await spawnChild();
+            }
+        }
+        async function respawnUnhealthy() {
+            // Kill & replace children that are unhealthy or missing socketPaths
+            const toReplace = children.filter(c => !c.healthy || typeof c.socketPath !== 'string');
+            await Promise.all(toReplace.map(async (c) => {
+                try {
+                    c.proc.kill('SIGTERM');
+                }
+                catch { /* ignore */
+                }
+                cleanupSock(c.socketPath);
+                c.socketPath = undefined;
+                // Remove from array
+                const idx = children.indexOf(c);
+                if (idx >= 0)
+                    children.splice(idx, 1);
+                // Spawn a fresh one
+                await spawnChild();
+            }));
+        }
+        const workerProcesses = [];
+        function spawnWorkerProcess(name) {
+            const bundleDir = path.dirname(path.isAbsolute(BUNDLE_PATH) ? BUNDLE_PATH : path.resolve(BUNDLE_PATH));
+            const workerBundle = path.join(bundleDir, `${name}.js`);
+            if (!fs.existsSync(workerBundle)) {
+                console.error(`[parent] Worker "${name}" bundle not found: ${workerBundle}`);
+                return null;
+            }
+            const workerExecArgv = ['--enable-source-maps'];
+            if (__filename.endsWith('.ts')) {
+                workerExecArgv.unshift('--require', '@swc-node/register');
+            }
+            // Workers get the same zero-touch taps as pods (fs/net/exec/db/redis/queue).
+            try {
+                workerExecArgv.push('--require', require.resolve('@lensmcp/node-instrumentation/register'));
+            }
+            catch { /* instrumentation package absent — workers run untapped */ }
+            const proc = (0, node_child_process_1.fork)(workerBundle, {
+                env: process.env,
+                stdio: ['inherit', 'pipe', 'pipe', 'ipc'],
+                execArgv: workerExecArgv,
+            });
+            const info = { name, proc };
+            workerProcesses.push(info);
+            wireProcLogging(proc, `\x1b[35m[worker:${name}] \x1b[0m`);
+            proc.on('exit', (code, signal) => {
+                const clean = signal === 'SIGINT' || signal === 'SIGTERM' || code === 0;
+                if (!clean) {
+                    console.error(`[parent] Worker "${name}" crashed (code=${code}, signal=${signal ?? 'none'})`);
+                }
+                const idx = workerProcesses.indexOf(info);
+                if (idx >= 0)
+                    workerProcesses.splice(idx, 1);
+            });
+            console.log(`[parent] Worker "${name}" started (pid=${proc.pid})`);
+            return info;
+        }
+        function restartWorkers() {
+            for (const w of [...workerProcesses]) {
+                try {
+                    w.proc.kill('SIGTERM');
+                }
+                catch { }
+            }
+            workerProcesses.length = 0;
+            for (const name of WORKER_NAMES) {
+                spawnWorkerProcess(name);
+            }
+        }
+        // Create ONE debounced forwarder that lives across requests
+        const debouncedForwardReload = debounce(async () => {
+            const healthies = healthyChildren();
+            if (healthies.length > 0) {
+                console.log(`[parent] Forwarding reload to ${healthies.length} child(ren)`);
+                for (const c of healthies)
+                    c.proc.send?.({ type: 'reload' });
+            }
+            await respawnUnhealthy();
+            if (WORKER_NAMES.length > 0)
+                restartWorkers();
+        }, 200);
+        // Start parent server (stable port)
+        const requestHandler = async (req, res) => {
+            // Admin endpoint: trigger rolling hot-reload & respawn crashed
+            if (req.method === 'POST' && req.url === '/webpack/reload') {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true }));
+                debouncedForwardReload();
+                return;
+            }
+            // Admin endpoint: grow the pod pool at runtime (gateway autoscaling).
+            if (req.method === 'POST' && req.url === '/webpack/scale') {
+                let body = '';
+                req.on('data', (c) => { body += c; });
+                req.on('end', async () => {
+                    let pods = 0;
+                    try {
+                        pods = Number(JSON.parse(body || '{}').pods) || 0;
+                    }
+                    catch { /* bad json */ }
+                    pods = Math.max(1, Math.min(pods, 16));
+                    await ensurePoolSize(pods);
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, pods }));
+                });
+                return;
+            }
+            // Front-gateway routes: host/prefix match → external target, or fall
+            // through to this service's own children when the route has no target.
+            const route = matchGatewayRoute(req);
+            if (route?.prependPrefix && !req.url?.startsWith(route.prependPrefix)) {
+                req.url = route.prependPrefix + (req.url ?? '/');
+            }
+            if (route?.target) {
+                applyGatewayMiddleware(req);
+                proxy.web(req, res, { target: route.target, autoRewrite: true, changeOrigin: true }, (err) => {
+                    console.error(`[parent] proxy error to ${route.target}:`, err);
+                    res.statusCode = 502;
+                    res.setHeader('content-type', 'text/plain; charset=utf-8');
+                    res.end(`Upstream error from ${route.target}.`);
+                });
+                return;
+            }
+            // Enforce service prefix (mimics production gateway)
+            if (SERVICE_PREFIX) {
+                if (!req.url?.startsWith(SERVICE_PREFIX)) {
+                    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end(`Not found. This service is mounted at ${SERVICE_PREFIX}/`);
+                    return;
+                }
+                req.url = req.url.slice(SERVICE_PREFIX.length) || '/';
+            }
+            // Gateway middleware: user-provided plugin modifies headers before proxying
+            applyGatewayMiddleware(req);
+            // Proxy all other traffic using round-robin among healthy children
+            const targetChild = pickChild();
+            if (!targetChild) {
+                res.statusCode = 503;
+                res.setHeader('content-type', 'text/plain; charset=utf-8');
+                const errs = children.map(c => `#${c.id}: ${c.lastError ?? 'no error recorded'}`).join('\n');
+                res.end(`No healthy children available. POST /webpack/reload to recover.\n\nLast errors:\n${errs}`);
+                return;
+            }
+            proxy.web(req, res, {
+                target: { socketPath: targetChild.socketPath },
+                autoRewrite: true,
+                headers: {
+                    'x-proxy-child-id': String(targetChild.id) // for logging/debugging
+                }
+            }, (err) => {
+                console.error(`[parent] proxy error to Child#${targetChild.id}:`, err);
+                // Mark this child unhealthy so next request won't pick it
+                targetChild.healthy = false;
+                targetChild.lastError = String(err?.stack || err);
+                res.statusCode = 502;
+                res.setHeader('content-type', 'text/plain; charset=utf-8');
+                res.end(`Upstream error from Child#${targetChild.id}. Try /webpack/reload.\n${targetChild.lastError}`);
+            });
+        };
+        // Optional HTTPS, @vitejs/plugin-basic-ssl style: a cached self-signed cert
+        // (SANs: localhost + loopbacks + every configured route hostname) so
+        // https://*.localhost dev "just works" after a one-time browser trust.
+        let server;
+        let gatewayPem;
+        let gatewayCaPath;
+        const extraServers = [];
+        if (GATEWAY_HTTPS) {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const basicSsl = require('./basic-ssl');
+            const certDomains = GATEWAY_ROUTES.map((r) => r.host).filter((h) => !!h);
+            const certCacheDir = path.join(process.cwd(), 'node_modules', '.cache', 'davnx-webpack');
+            gatewayPem = basicSsl.getCertificateSync(certCacheDir, SERVICE_NAME || 'davnx.dev', certDomains);
+            gatewayCaPath = basicSsl.caCertPath(certCacheDir);
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const httpsMod = require('node:https');
+            server = httpsMod.createServer({ key: gatewayPem, cert: gatewayPem }, requestHandler);
+        }
+        else {
+            server = http.createServer(requestHandler);
+        }
+        // WebSocket upgrades (vite HMR, app sockets): same routing as requests —
+        // external target when a route matches, otherwise a healthy child socket.
+        const upgradeHandler = (req, socket, head) => {
+            const route = matchGatewayRoute(req);
+            if (route?.prependPrefix && !req.url?.startsWith(route.prependPrefix)) {
+                req.url = route.prependPrefix + (req.url ?? '/');
+            }
+            if (route?.target) {
+                proxy.ws(req, socket, head, { target: route.target, changeOrigin: true }, () => socket.destroy());
+                return;
+            }
+            const targetChild = pickChild();
+            if (!targetChild) {
+                socket.destroy();
+                return;
+            }
+            proxy.ws(req, socket, head, { target: { socketPath: targetChild.socketPath } }, () => socket.destroy());
+        };
+        server.on('upgrade', upgradeHandler);
+        server.listen(publicPort, async () => {
+            const scheme = GATEWAY_HTTPS ? 'https' : 'http';
+            console.log(`[parent] Listening on ${scheme}://localhost:${publicPort}`);
+            if (SERVICE_PREFIX) {
+                console.log(`[parent] Service prefix: "${SERVICE_PREFIX}" (enforced — requests without it will get 404)`);
+            }
+            if (gatewayMiddleware) {
+                console.log(`[parent] Gateway middleware: ACTIVE (${GATEWAY_MIDDLEWARE_PATH})`);
+            }
+            if (GATEWAY_ROUTES.length > 0) {
+                console.log(`[parent] Gateway routes: ${GATEWAY_ROUTES.map((r) => `${r.host ?? '*'}${r.prefix ?? '/'}→${r.target ?? 'children'}`).join('  ')}`);
+            }
+            if (gatewayCaPath) {
+                console.log(`[parent] HTTPS dev CA (trust ONCE, then rotations/new hostnames stay green):`);
+                console.log(`[parent]   sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ${gatewayCaPath}`);
+            }
+            console.log(`POST ${scheme}://localhost:${publicPort}/webpack/reload to trigger rolling swap/respawn`);
+            await ensurePoolSize(CHILD_COUNT);
+            for (const name of WORKER_NAMES) {
+                spawnWorkerProcess(name);
+            }
+        });
+        // Internal service-to-service port: plain http, straight to the children —
+        // NO gateway routes, NO gateway middleware (JWT etc.). Peers call this
+        // directly (http://localhost:<internalPort>/...) instead of going through
+        // the public front door, mirroring cluster-internal networking in prod.
+        const INTERNAL_PORT = Number(process.env.INTERNAL_PORT || 0);
+        if (INTERNAL_PORT > 0) {
+            const internalHandler = (req, res) => {
+                const targetChild = pickChild();
+                if (!targetChild) {
+                    res.statusCode = 503;
+                    res.setHeader('content-type', 'text/plain; charset=utf-8');
+                    res.end('No healthy children available.');
+                    return;
+                }
+                proxy.web(req, res, {
+                    target: { socketPath: targetChild.socketPath },
+                    autoRewrite: true,
+                }, (err) => {
+                    targetChild.healthy = false;
+                    targetChild.lastError = String(err?.stack || err);
+                    res.statusCode = 502;
+                    res.end(`Upstream error from Child#${targetChild.id}.`);
+                });
+            };
+            const internal = http.createServer(internalHandler);
+            internal.on('upgrade', (req, socket, head) => {
+                const targetChild = pickChild();
+                if (!targetChild) {
+                    socket.destroy();
+                    return;
+                }
+                proxy.ws(req, socket, head, { target: { socketPath: targetChild.socketPath } }, () => socket.destroy());
+            });
+            internal.on('error', (err) => {
+                console.warn(`[parent] internal port ${INTERNAL_PORT} unavailable (${err.code}).`);
+            });
+            internal.listen(INTERNAL_PORT, () => {
+                console.log(`[parent] Internal (service-to-service, no gateway middleware) on http://localhost:${INTERNAL_PORT}`);
+            });
+            extraServers.push(internal);
+        }
+        // Extra listener ports sharing the SAME handler + upgrade routing. The
+        // point is pretty dev domains: with `gateway.https` + extraPorts [443],
+        // https://tetros.ai.local/ works with no :port in the URL (macOS lets
+        // unprivileged processes bind <1024; elsewhere we warn and carry on).
+        const EXTRA_PORTS = (() => {
+            try {
+                return JSON.parse(process.env.GATEWAY_EXTRA_PORTS || '[]');
+            }
+            catch {
+                return [];
+            }
+        })();
+        for (const extraPort of EXTRA_PORTS) {
+            if (!Number.isInteger(extraPort) || extraPort === Number(publicPort))
+                continue;
+            const extra = GATEWAY_HTTPS
+                ? // eslint-disable-next-line @typescript-eslint/no-require-imports
+                    require('node:https').createServer({ key: gatewayPem, cert: gatewayPem }, requestHandler)
+                : http.createServer(requestHandler);
+            extra.on('upgrade', upgradeHandler);
+            extra.on('error', (err) => {
+                console.warn(`[parent] extra port ${extraPort} unavailable (${err.code}) — main port still up.`);
+            });
+            extra.listen(extraPort, () => {
+                const scheme = GATEWAY_HTTPS ? 'https' : 'http';
+                console.log(`[parent] Also listening on ${scheme}://localhost:${extraPort}`);
+            });
+            extraServers.push(extra);
+        }
+        // Graceful shutdown of parent (children get SIGTERM)
+        const shutdown = async (sig) => {
+            shuttingDown = true; // stop crash-respawn from fighting the teardown
+            console.log(`[${sig}] [parent] shutting down…`);
+            for (const extra of extraServers) {
+                try {
+                    extra.close();
+                }
+                catch { /* ignore */ }
+            }
+            for (const w of workerProcesses) {
+                try {
+                    w.proc.kill('SIGTERM');
+                }
+                catch { }
+            }
+            for (const c of children) {
+                try {
+                    c.proc.kill('SIGTERM');
+                }
+                catch { /* ignore */
+                }
+                if (c.socketPath)
+                    cleanupSock(c.socketPath);
+            }
+            // Clean up socket directory
+            try {
+                fs.rmdirSync(SOCK_DIR);
+            }
+            catch { }
+            setTimeout(() => process.exit(0), 700).unref();
+        };
+        ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT', 'SIGUSR2'].forEach(sig => process.on(sig, () => void shutdown(sig)));
+    })();
+}