@dokebi/template-inertia 0.2.0 → 0.4.1

package/dist/vite-dev.js

@@ -1,15 +1,28 @@
 // Development mode (D-0045): with DOKEBI_VITE_DEV=1 (set by `dokebi dev`) pages load their code
-// from the project's Vite in middleware mode instead of a build, so a .vue edit reaches the
-// browser by hot module replacement. Vite is the project's dev dependency, found from the
-// working directory; this package does not depend on it.
+// from the project's Vite instead of a build, so a .vue edit reaches the browser by hot module
+// replacement. Vite is the project's dev dependency, found from the working directory; this
+// package does not depend on it.
+//
+// One Vite per `dokebi dev` session (D-0045 addendum 3): the Vite host (`startViteHost`, run by
+// `dokebi dev` through `vite-host.ts`) starts Vite in middleware mode behind a loopback HTTP server
+// of its own. Every app process (every cluster worker) is a client (`connectViteDev`): its
+// `<base>*` routes forward to the host, and server rendering asks the host. The browser's HMR
+// socket goes straight to the host's port, so all workers advertise one port and one token, and
+// dependencies are pre-bundled once. Without a host (`DOKEBI_VITE_DEV_URL` unset) the process
+// starts a host of its own, as one process did before.
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { Agent, createServer as createHttpServer, request as httpRequest, } from 'node:http';
 import { createRequire } from 'node:module';
-import { createServer } from 'node:net';
+import { createServer as createNetServer, } from 'node:net';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { diagnostics } from '@dokebi/core/libraries';
+import { InertiaError } from './errors.js';
+const { describeError } = diagnostics;
 export const viteDevRequested = () => process.env.DOKEBI_VITE_DEV === '1';
 /**
- * The `next` of Vite's middlewares on a dev route: no error means Vite has nothing for the URL
- * (404); an error is reported (logged by the caller) and answered 500, never dropped (D-0047).
+ * The `next` of Vite's middlewares: no error means Vite has nothing for the URL (404); an error is
+ * reported (logged by the caller) and answered 500, never dropped (D-0047).
  */
 export function viteFallthrough(response, error, report) {
     if (error !== undefined && error !== null) {
@@ -21,37 +34,457 @@ export function viteFallthrough(response, error, report) {
         response.statusCode = 404;
     response.end();
 }
-function freePort() {
+/** Header that carries the host key; the host answers no HTTP request without it. */
+export const VITE_HOST_KEY_HEADER = 'x-dokebi-vite-key';
+/** Host-only paths (outside every Vite base): a ping and server rendering. */
+const HOST_PATH = '/__dokebi/vite-host';
+const SSR_PATH = `${HOST_PATH}/ssr`;
+/** Largest server-render request (the page JSON) the host reads. */
+const SSR_BODY_MAX_BYTES = 32 * 1024 * 1024;
+/** Loopback addresses of the host (a browser resolves `*.localhost` to either); never all. */
+const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
+/** Tries for a port that is free on both loopback addresses. */
+const PORT_ATTEMPTS = 8;
+/** WebSocket subprotocols of Vite's client; other upgrades on the host port are closed. */
+const VITE_PROTOCOLS = new Set(['vite-hmr', 'vite-ping']);
+/** Hop-by-hop headers (RFC 9110 §7.6.1) that a forwarder does not pass on. */
+const HOP_BY_HOP = [
+    'connection',
+    'keep-alive',
+    'proxy-connection',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+];
+function listenExclusive(host, port) {
     return new Promise((resolve, reject) => {
-        const server = createServer();
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            const address = server.address();
-            server.close(() => typeof address === 'object' && address ? resolve(address.port) : reject(new Error('port')));
+        const listener = createNetServer();
+        listener.once('error', reject);
+        // exclusive: the process binds the port itself. Under node:cluster a shared listen goes
+        // through the primary, which would spread HMR sockets over workers (D-0045 addendum 2).
+        listener.listen({ host, port, exclusive: true }, () => {
+            listener.off('error', reject);
+            resolve(listener);
         });
     });
 }
-/**
- * Starts the project's Vite (its vite.config.*) in middleware mode. The HMR socket gets a free
- * port of its own: @dokebi/websocket answers every upgrade on the app's HTTP server and closes
- * the ones that are not its routes, so HMR cannot share that server.
- */
-export async function startViteDev(root = process.cwd()) {
-    let entry;
+function closeListener(listener) {
+    return new Promise((resolve, reject) => listener.close((error) => (error ? reject(error) : resolve())));
+}
+async function openLoopback(logger, handler) {
+    const listeners = [];
+    let port = 0;
+    for (let attempt = 1; listeners.length === 0; attempt++) {
+        const first = await listenExclusive(LOOPBACK_HOSTS[0], 0);
+        port = first.address().port;
+        try {
+            listeners.push(first, await listenExclusive(LOOPBACK_HOSTS[1], port));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'EADDRNOTAVAIL' || code === 'EAFNOSUPPORT') {
+                // No IPv6 loopback here: names that resolve to loopback reach 127.0.0.1.
+                logger.log('debug', 'Vite dev host listens on IPv4 loopback only', { port, code });
+                listeners.push(first);
+            }
+            else {
+                await closeListener(first);
+                if (code !== 'EADDRINUSE' || attempt >= PORT_ATTEMPTS)
+                    throw error;
+                logger.log('debug', 'Vite dev host port is taken on ::1, trying another', {
+                    port,
+                    attempt,
+                });
+            }
+        }
+    }
+    const hosts = listeners.map((listener) => listener.address().address);
+    const server = createHttpServer(handler);
+    // Vite answers its own subprotocols on this server; another upgrade would stay open.
+    server.on('upgrade', (request, socket) => {
+        const protocol = request.headers['sec-websocket-protocol'];
+        if (protocol !== undefined && VITE_PROTOCOLS.has(protocol))
+            return;
+        if (logger.isEnabled('debug'))
+            logger.log('debug', 'Vite dev host closed an upgrade that is not Vite', {
+                protocol: String(protocol ?? '').slice(0, 64),
+            });
+        socket.destroy();
+    });
+    const sockets = new Set();
+    for (const listener of listeners) {
+        listener.on('connection', (socket) => {
+            sockets.add(socket);
+            socket.once('close', () => sockets.delete(socket));
+            server.emit('connection', socket);
+        });
+        listener.on('error', (error) => logger.log('error', 'Vite dev host listener failed', {
+            code: 'INERTIA_VITE_HOST_FAILED',
+            port,
+            error: describeError(error),
+        }));
+    }
+    logger.log('debug', 'Vite dev host listening', { port, hosts });
+    let closing;
+    return {
+        server,
+        port,
+        hosts,
+        close: () => (closing ??= (async () => {
+            const open = sockets.size;
+            for (const socket of sockets)
+                socket.destroy();
+            await Promise.all(listeners.map(closeListener));
+            logger.log('debug', 'Vite dev host closed', { port, connections: open });
+        })()),
+    };
+}
+function keyMatches(expected, presented) {
+    if (typeof presented !== 'string')
+        return false;
+    const given = Buffer.from(presented);
+    return given.length === expected.length && timingSafeEqual(given, expected);
+}
+function sendJson(response, status, value) {
+    const body = JSON.stringify(value);
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(body),
+        'cache-control': 'no-store',
+    });
+    response.end(body);
+}
+/** An error as JSON for the client process (it rebuilds and reports it, D-0047). */
+function errorJson(error) {
+    if (!(error instanceof Error))
+        return { name: 'Error', message: String(error) };
+    const code = error.code;
+    return {
+        name: error.name,
+        message: error.message,
+        ...(error.stack ? { stack: error.stack } : {}),
+        ...(typeof code === 'string' ? { code } : {}),
+    };
+}
+function readBody(request, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        request.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new RangeError(`Server-render request is larger than ${limit} bytes`));
+                request.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.once('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        request.once('error', reject);
+    });
+}
+function findVite(root) {
     try {
         const require = createRequire(join(root, 'package.json'));
-        entry = join(dirname(require.resolve('vite/package.json')), 'dist/node/index.js');
+        return join(dirname(require.resolve('vite/package.json')), 'dist/node/index.js');
     }
     catch (cause) {
-        throw new Error('DOKEBI_VITE_DEV=1 needs Vite in the project (npm install --save-dev vite)', {
-            cause,
-        });
+        throw new InertiaError('VITE_DEV_MISSING', 'DOKEBI_VITE_DEV=1 needs Vite in the project (npm install --save-dev vite)', { cause });
     }
+}
+/**
+ * Starts the project's Vite (its vite.config.*) in middleware mode behind a loopback HTTP server
+ * of its own (127.0.0.1 and ::1 on one free port, `exclusive` so a cluster worker binds it
+ * itself). On that port:
+ * - HTTP requests with the key: Vite's middlewares (modules, pre-bundled dependencies,
+ *   `@vite/client`), a ping (`/__dokebi/vite-host`) and server rendering
+ *   (`POST /__dokebi/vite-host/ssr`). Without the key: 403 (a page cannot read sources through
+ *   DNS rebinding; app processes check page hosts before forwarding).
+ * - WebSocket upgrades of Vite's client (HMR): Vite answers them and keeps its token check
+ *   (cross-site WebSocket hijacking). @dokebi/websocket answers every upgrade on the app's port,
+ *   so HMR cannot share that one.
+ */
+export async function startViteHost(logger, root = process.cwd()) {
+    const begin = performance.now();
+    const entry = findVite(root);
     const vite = (await import(pathToFileURL(entry).href));
-    return vite.createServer({
+    const key = randomBytes(24).toString('base64url');
+    const expected = Buffer.from(key);
+    let started;
+    const report = (operation) => (error) => logger.log('error', 'Vite dev host request failed', {
+        code: 'INERTIA_VITE_HOST_FAILED',
+        operation,
+        error: describeError(error),
+    });
+    const ssr = async (request, response, server) => {
+        try {
+            const { entry: source, page } = JSON.parse(await readBody(request, SSR_BODY_MAX_BYTES));
+            if (typeof source !== 'string' || !source || source.includes('..') || source.startsWith('/'))
+                throw new TypeError('Server-render entry must be a path relative to the project root');
+            const module = await server.ssrLoadModule(`/${source}`);
+            if (typeof module.render !== 'function')
+                throw new InertiaError('SSR_BUNDLE_INVALID', `Inertia SSR entry ${source} does not export render(page)`);
+            sendJson(response, 200, { result: await module.render(page) });
+        }
+        catch (error) {
+            // Returned to the app process, which counts and logs it (`Inertia SSR render failed`).
+            if (logger.isEnabled('debug'))
+                logger.log('debug', 'Vite dev host returned a server-render failure', {
+                    error: describeError(error),
+                });
+            if (response.headersSent)
+                response.destroy(error);
+            else
+                sendJson(response, 500, { error: errorJson(error) });
+        }
+    };
+    const endpoint = await openLoopback(logger, (request, response) => {
+        if (!keyMatches(expected, request.headers[VITE_HOST_KEY_HEADER])) {
+            if (logger.isEnabled('debug'))
+                logger.log('debug', 'Vite dev host refused a request without its key', {
+                    method: request.method,
+                    path: String(request.url ?? '').slice(0, 200),
+                });
+            response.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+            response.end('The Vite dev host answers the app processes of dokebi dev only.');
+            return;
+        }
+        const server = started;
+        if (!server) {
+            response.writeHead(503, { 'content-type': 'text/plain; charset=utf-8' });
+            response.end('Vite is starting.');
+            return;
+        }
+        const path = String(request.url ?? '').split('?', 1)[0];
+        if (path === HOST_PATH)
+            sendJson(response, 200, { root, pid: process.pid });
+        else if (path === SSR_PATH && request.method === 'POST')
+            void ssr(request, response, server);
+        else
+            server.middlewares(request, response, (error) => viteFallthrough(response, error, report('vite')));
+    });
+    try {
+        started = await vite.createServer({
+            root,
+            appType: 'custom',
+            server: {
+                middlewareMode: true,
+                // Hosts are checked by the dev routes of the plugin (see index.ts) and HTTP needs the key,
+                // so Vite's host check is off. The HMR socket keeps Vite's token check.
+                allowedHosts: true,
+                // Vite 8 `server.ws`: Vite answers upgrades on `server`; its client connects to `port`
+                // on the page's host name.
+                ws: { server: endpoint.server, port: endpoint.port },
+            },
+        });
+    }
+    catch (error) {
+        // The start failure goes to the caller; the port opened for it must not outlive it.
+        await endpoint.close();
+        throw error;
+    }
+    const server = started;
+    logger.log('debug', 'Vite dev host started', {
+        port: endpoint.port,
+        hosts: endpoint.hosts,
         root,
-        appType: 'custom',
-        // Hosts are checked by the dev routes of the plugin (see index.ts), not by Vite.
-        server: { middlewareMode: true, allowedHosts: true, hmr: { port: await freePort() } },
+        ms: Math.round(performance.now() - begin),
+    });
+    let closing;
+    return {
+        url: `http://127.0.0.1:${endpoint.port}`,
+        key,
+        port: endpoint.port,
+        hosts: endpoint.hosts,
+        close: () => (closing ??= (async () => {
+            try {
+                await server.close();
+            }
+            finally {
+                await endpoint.close();
+            }
+        })()),
+    };
+}
+/** Rebuilds an error the host returned, keeping its name, message, stack and known code. */
+function remoteError(info) {
+    const message = typeof info.message === 'string' ? info.message : 'Vite dev host failed';
+    if (info.code === 'SSR_BUNDLE_INVALID')
+        return new InertiaError('SSR_BUNDLE_INVALID', message);
+    const error = new Error(message);
+    if (typeof info.name === 'string')
+        error.name = info.name;
+    if (typeof info.stack === 'string')
+        error.stack = info.stack;
+    if (typeof info.code === 'string')
+        Object.assign(error, { code: info.code });
+    return error;
+}
+function hostUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (cause) {
+        throw new InertiaError('VITE_DEV_UNAVAILABLE', 'DOKEBI_VITE_DEV_URL is not a URL', { cause });
+    }
+    // The key goes along with every request: only to this machine, never over a network.
+    if (parsed.protocol !== 'http:' ||
+        !['127.0.0.1', '[::1]', 'localhost'].includes(parsed.hostname) ||
+        !parsed.port ||
+        parsed.pathname !== '/')
+        throw new InertiaError('VITE_DEV_UNAVAILABLE', 'DOKEBI_VITE_DEV_URL must be http://127.0.0.1:<port> (a loopback address and port)');
+    return parsed;
+}
+/**
+ * Connects this process to a Vite host and checks that it answers with the key. Requests share
+ * keep-alive connections; `close` ends them (the host keeps running).
+ */
+export async function connectViteDev(logger, url, key) {
+    const target = hostUrl(url);
+    const host = target.hostname.replace(/^\[(.*)\]$/, '$1');
+    const port = Number(target.port);
+    const agent = new Agent({ keepAlive: true, maxSockets: 64 });
+    const call = (method, path, body) => new Promise((resolve, reject) => {
+        const outgoing = httpRequest({
+            host,
+            port,
+            method,
+            path,
+            agent,
+            headers: {
+                [VITE_HOST_KEY_HEADER]: key,
+                ...(body === undefined
+                    ? {}
+                    : {
+                        'content-type': 'application/json',
+                        'content-length': Buffer.byteLength(body),
+                    }),
+            },
+        }, (answer) => {
+            const chunks = [];
+            answer.on('data', (chunk) => chunks.push(chunk));
+            answer.once('end', () => resolve({
+                status: answer.statusCode ?? 0,
+                text: Buffer.concat(chunks).toString('utf8'),
+            }));
+            answer.once('error', reject);
+        });
+        outgoing.once('error', reject);
+        outgoing.end(body);
     });
+    try {
+        const { status } = await call('GET', HOST_PATH);
+        if (status !== 200)
+            throw new InertiaError('VITE_DEV_UNAVAILABLE', `The Vite dev host at ${target.origin} answered ${status} (wrong DOKEBI_VITE_DEV_KEY?)`);
+    }
+    catch (cause) {
+        agent.destroy();
+        if (cause instanceof InertiaError)
+            throw cause;
+        throw new InertiaError('VITE_DEV_UNAVAILABLE', `The Vite dev host at ${target.origin} cannot be reached`, { cause });
+    }
+    logger.log('debug', 'Vite dev host connected', { url: target.origin });
+    return {
+        forward(request, response, report) {
+            const headers = { ...request.headers };
+            for (const name of HOP_BY_HOP)
+                delete headers[name];
+            headers[VITE_HOST_KEY_HEADER] = key;
+            let aborted = false;
+            const outgoing = httpRequest({ host, port, method: request.method, path: request.url, headers, agent }, (answer) => {
+                const out = { ...answer.headers };
+                for (const name of HOP_BY_HOP)
+                    delete out[name];
+                response.writeHead(answer.statusCode ?? 502, out);
+                answer.pipe(response);
+                answer.once('error', (error) => {
+                    if (!aborted)
+                        report(error);
+                    response.destroy();
+                });
+            });
+            outgoing.once('error', (error) => {
+                if (aborted) {
+                    // The browser went away first; the request to the host was cut on purpose.
+                    if (logger.isEnabled('debug'))
+                        logger.log('debug', 'Vite dev request ended by the browser', {
+                            path: String(request.url ?? '').slice(0, 200),
+                        });
+                    return;
+                }
+                report(error);
+                if (response.headersSent)
+                    response.destroy();
+                else {
+                    response.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+                    response.end('The Vite dev host did not answer; see the dokebi dev output.');
+                }
+            });
+            response.once('close', () => {
+                if (response.writableFinished)
+                    return;
+                aborted = true;
+                outgoing.destroy();
+            });
+            outgoing.end();
+        },
+        async render(entry, page) {
+            const { status, text } = await call('POST', SSR_PATH, JSON.stringify({ entry, page }));
+            let answer;
+            try {
+                answer = JSON.parse(text);
+            }
+            catch (cause) {
+                throw new InertiaError('VITE_DEV_UNAVAILABLE', `The Vite dev host answered a server render with ${status} and no JSON`, { cause });
+            }
+            if (status === 200 && 'result' in answer)
+                return answer.result;
+            throw remoteError(answer.error ?? { message: `Vite dev host answered ${status}` });
+        },
+        close: async () => {
+            agent.destroy();
+            logger.log('debug', 'Vite dev host disconnected', { url: target.origin });
+        },
+    };
+}
+/**
+ * The Vite of this process: the host of `dokebi dev` when `DOKEBI_VITE_DEV_URL` and
+ * `DOKEBI_VITE_DEV_KEY` name one, otherwise a host started here (then each process, each cluster
+ * worker, has its own Vite: run cluster apps through `dokebi dev`).
+ */
+export async function openViteDev(logger, environment = process.env, root = process.cwd()) {
+    const url = environment.DOKEBI_VITE_DEV_URL;
+    if (url) {
+        const key = environment.DOKEBI_VITE_DEV_KEY;
+        if (!key)
+            throw new InertiaError('VITE_DEV_UNAVAILABLE', 'DOKEBI_VITE_DEV_URL is set without DOKEBI_VITE_DEV_KEY');
+        logger.log('debug', 'Vite dev uses the host of dokebi dev', { url });
+        return connectViteDev(logger, url, key);
+    }
+    logger.log('debug', 'Vite dev starts a host in this process', { pid: process.pid });
+    const host = await startViteHost(logger, root);
+    let client;
+    try {
+        client = await connectViteDev(logger, host.url, host.key);
+    }
+    catch (error) {
+        await host.close();
+        throw error;
+    }
+    return {
+        forward: client.forward,
+        render: client.render,
+        close: async () => {
+            try {
+                await client.close();
+            }
+            finally {
+                await host.close();
+            }
+        },
+    };
 }

package/dist/vite-host.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vite-host.js

@@ -0,0 +1,62 @@
+// The Vite dev host process (D-0045 addendum 3): `dokebi dev` runs this once per session, in the
+// project folder, before the app. It starts the project's Vite (`startViteHost`) and reports
+// `{ type: 'dokebi-vite-host', state: 'ready', url, key }` over the IPC channel; dev passes them to
+// the app as DOKEBI_VITE_DEV_URL and DOKEBI_VITE_DEV_KEY. The host outlives app restarts.
+// A start failure is reported as `state: 'failed'` and the process exits 1.
+import { ConsoleLogger } from '@dokebi/core';
+import { diagnostics } from '@dokebi/core/libraries';
+import { startViteHost } from './vite-dev.js';
+const { describeError } = diagnostics;
+const LEVELS = new Set(['debug', 'info', 'warn', 'error', 'silent']);
+const asked = process.env.DOKEBI_LOG_LEVEL?.trim().toLowerCase() ?? '';
+const logger = new ConsoleLogger({ level: LEVELS.has(asked) ? asked : 'info' }, { plugin: 'dokebi-template-inertia', process: 'vite-host' });
+const send = (message) => process.send?.(message);
+let host;
+try {
+    host = await startViteHost(logger, process.cwd());
+}
+catch (error) {
+    logger.log('error', 'Vite dev host failed to start', {
+        code: 'INERTIA_VITE_HOST_FAILED',
+        error: describeError(error),
+    });
+    send({
+        type: 'dokebi-vite-host',
+        state: 'failed',
+        message: error instanceof Error ? error.message : String(error),
+    });
+    process.exitCode = 1;
+}
+if (host) {
+    const started = host;
+    let stopping = false;
+    const stop = (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        // Rejections become an error log and exit code 1 here (D-0047).
+        void started.close().then(() => logger.log('debug', 'Vite dev host stopped', { signal }), (error) => {
+            process.exitCode = 1;
+            logger.log('error', 'Vite dev host failed to stop', {
+                code: 'INERTIA_VITE_HOST_FAILED',
+                signal,
+                error: describeError(error),
+            });
+        });
+    };
+    process.on('SIGTERM', () => stop('SIGTERM'));
+    // Under dokebi dev (an IPC channel) a terminal Ctrl+C reaches the whole process group: the app
+    // drains first and dev stops the host after it (SIGTERM). Alone, Ctrl+C stops the host.
+    process.on('SIGINT', () => {
+        if (process.connected)
+            logger.log('debug', 'Vite dev host waits for dokebi dev to stop it');
+        else
+            stop('SIGINT');
+    });
+    logger.log('info', 'Vite dev host ready', {
+        code: 'INERTIA_VITE_HOST',
+        url: started.url,
+        hosts: started.hosts,
+    });
+    send({ type: 'dokebi-vite-host', state: 'ready', url: started.url, key: started.key });
+}