@dokebi/template-inertia 0.4.2 → 0.4.4

package/dist/vite-dev.js

@@ -13,11 +13,14 @@
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { Agent, createServer as createHttpServer, request as httpRequest, } from 'node:http';
 import { createRequire } from 'node:module';
-import { createServer as createNetServer, } from 'node:net';
+import { connect as connectNet, 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';
+import { DependencyCache } from './vite-deps.js';
+import { DEV_CLIENT_HEADER, dokebiDevFiles } from './vite-files.js';
+import { ServedFiles, staleEventFilter } from './vite-watch.js';
 const { describeError } = diagnostics;
 export const viteDevRequested = () => process.env.DOKEBI_VITE_DEV === '1';
 /**
@@ -47,6 +50,11 @@ const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
 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']);
+/** Whether an upgrade request is Vite's client (its HMR or ping socket), by its subprotocol. */
+export function isViteUpgrade(request) {
+    const protocol = request.headers['sec-websocket-protocol'];
+    return typeof protocol === 'string' && VITE_PROTOCOLS.has(protocol.trim());
+}
 /** Hop-by-hop headers (RFC 9110 §7.6.1) that a forwarder does not pass on. */
 const HOP_BY_HOP = [
     'connection',
@@ -59,6 +67,8 @@ const HOP_BY_HOP = [
     'transfer-encoding',
     'upgrade',
 ];
+/** Default of `devDepsRepairIntervalMs` (D-0128). */
+export const DEFAULT_DEPS_REPAIR_INTERVAL_MS = 10_000;
 function listenExclusive(host, port) {
     return new Promise((resolve, reject) => {
         const listener = createNetServer();
@@ -206,14 +216,22 @@ function findVite(root) {
  * - 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.
+ *
+ * Watcher events for files whose state did not change since Vite read them (FSEvents delivering
+ * writes from before the start, late) are dropped before Vite sees them (`vite-watch.ts`).
+ *
+ * The pre-bundled dependencies (node_modules/.vite/deps) are compared with what Vite serves at
+ * the start, whenever an app process connects (every app restart) and after a 504; when the
+ * folder changed under Vite, the host re-optimizes (`vite-deps.ts`, D-0128).
  */
-export async function startViteHost(logger, root = process.cwd()) {
+export async function startViteHost(logger, root = process.cwd(), settings = {}) {
     const begin = performance.now();
     const entry = findVite(root);
     const vite = (await import(pathToFileURL(entry).href));
     const key = randomBytes(24).toString('base64url');
     const expected = Buffer.from(key);
     let started;
+    let deps;
     const report = (operation) => (error) => logger.log('error', 'Vite dev host request failed', {
         code: 'INERTIA_VITE_HOST_FAILED',
         operation,
@@ -259,25 +277,48 @@ export async function startViteHost(logger, root = process.cwd()) {
             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')
+        // D-0129: a browser request the app forwarded (it carries DEV_CLIENT_HEADER) never reaches
+        // the host-only paths: with the Vite base `/` they sit under the dev route, and the ping
+        // names the project root.
+        const browser = request.headers[DEV_CLIENT_HEADER] !== undefined;
+        const cache = deps;
+        if (path === HOST_PATH && !browser) {
+            // An app process connects (it started or restarted): it is answered once the pre-bundled
+            // dependencies match what Vite serves, so its pages get hashes that load (D-0128).
+            void (cache ? cache.ensure('client').catch(report('deps')) : Promise.resolve()).then(() => sendJson(response, 200, { root, pid: process.pid }));
+        }
+        else if (path === SSR_PATH && request.method === 'POST' && !browser)
             void ssr(request, response, server);
-        else
+        else {
+            // Vite answers 504 for a pre-bundled file it cannot serve: if the folder changed under it,
+            // re-optimize so the next page load gets files that exist (D-0128).
+            if (cache)
+                response.once('finish', () => {
+                    if (response.statusCode === 504)
+                        void cache.ensure('outdated').catch(report('deps'));
+                });
             server.middlewares(request, response, (error) => viteFallthrough(response, error, report('vite')));
+        }
     });
+    // Events FSEvents still holds from before the start are no edits (D-0045 addendum 4).
+    const served = new ServedFiles(logger);
+    served.recordConfig(root);
     try {
         started = await vite.createServer({
             root,
             appType: 'custom',
+            // D-0129: the dev file policy for a vite.config without dokebiInertia() (which carries it).
+            plugins: [staleEventFilter(served, logger), dokebiDevFiles(logger)],
             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 },
+                // Vite 8 `server.ws`: Vite answers upgrades on `server`. No `port`: its client then
+                // connects to the page's own origin and `<base>` (the port the page came from, a tunnel's
+                // 443 included), and the app forwards that upgrade here (ViteDev.upgrade). With a port
+                // it went to `<page host>:<this loopback port>`, which no tunnel or other device reaches.
+                ws: { server: endpoint.server },
             },
         });
     }
@@ -287,6 +328,24 @@ export async function startViteHost(logger, root = process.cwd()) {
         throw error;
     }
     const server = started;
+    const cache = new DependencyCache(logger, server, {
+        repairIntervalMs: settings.depsRepairIntervalMs ?? DEFAULT_DEPS_REPAIR_INTERVAL_MS,
+    });
+    try {
+        await cache.claim();
+        // A cache left broken by an earlier session would answer every dependency 504 (D-0128).
+        await cache.ensure('start');
+    }
+    catch (error) {
+        try {
+            await server.close();
+        }
+        finally {
+            await endpoint.close();
+        }
+        throw error;
+    }
+    deps = cache;
     logger.log('debug', 'Vite dev host started', {
         port: endpoint.port,
         hosts: endpoint.hosts,
@@ -304,7 +363,12 @@ export async function startViteHost(logger, root = process.cwd()) {
                 await server.close();
             }
             finally {
-                await endpoint.close();
+                try {
+                    await cache.release();
+                }
+                finally {
+                    await endpoint.close();
+                }
             }
         })()),
     };
@@ -339,6 +403,21 @@ function hostUrl(url) {
         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;
 }
+/**
+ * Destroys a request to the host without leaving a listener on a pooled connection. Node 24.15
+ * (`_http_client` onSocket, onSocketNT) adds the connection's 'error' listener when the agent
+ * hands it to a request and, when that request was destroyed while it waited in the agent's
+ * queue, puts the connection back in the pool with the listener still on it: one more per such
+ * request for as long as the keep-alive connection lives (audit r6: MaxListenersExceededWarning
+ * after renders cut at their deadline). A request without its connection yet is destroyed once
+ * it has one, which closes that connection instead.
+ */
+export function destroyRequest(outgoing, error) {
+    if (outgoing.socket || outgoing.destroyed)
+        outgoing.destroy(error);
+    else
+        outgoing.once('socket', () => outgoing.destroy(error));
+}
 /**
  * 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).
@@ -348,13 +427,16 @@ export async function connectViteDev(logger, url, key) {
     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) => {
+    // Server renders on connections of their own: renders that wait (a slow or hung page) never
+    // hold the connections the browser's module requests are forwarded on.
+    const renders = new Agent({ keepAlive: true, maxSockets: 64 });
+    const call = (method, path, body, through = agent, timeoutMs) => new Promise((resolve, reject) => {
         const outgoing = httpRequest({
             host,
             port,
             method,
             path,
-            agent,
+            agent: through,
             headers: {
                 [VITE_HOST_KEY_HEADER]: key,
                 ...(body === undefined
@@ -374,6 +456,15 @@ export async function connectViteDev(logger, url, key) {
             answer.once('error', reject);
         });
         outgoing.once('error', reject);
+        if (timeoutMs !== undefined) {
+            const timer = setTimeout(() => {
+                const error = new InertiaError('SSR_TIMEOUT', `The Vite dev host did not finish a server render within ${timeoutMs} ms (ssr.timeoutMs)`, { data: { timeoutMs } });
+                // Settled now, also for a request still waiting for a connection (destroyRequest).
+                reject(error);
+                destroyRequest(outgoing, error);
+            }, timeoutMs);
+            outgoing.once('close', () => clearTimeout(timer));
+        }
         outgoing.end(body);
     });
     try {
@@ -383,12 +474,57 @@ export async function connectViteDev(logger, url, key) {
     }
     catch (cause) {
         agent.destroy();
+        renders.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 });
+    /** HMR sockets joined to the host, ended by close(). */
+    const joined = new Set();
     return {
+        upgrade(request, socket, head, report) {
+            const upstream = connectNet({ host, port });
+            joined.add(socket);
+            joined.add(upstream);
+            let ended = false;
+            const end = () => {
+                if (ended)
+                    return;
+                ended = true;
+                joined.delete(socket);
+                joined.delete(upstream);
+                socket.destroy();
+                upstream.destroy();
+            };
+            upstream.once('connect', () => {
+                // The handshake as the browser sent it (rawHeaders keeps names, order and repeats; Node
+                // refused any line break in them): Vite checks the token and the subprotocol itself.
+                const lines = [`${request.method ?? 'GET'} ${request.url ?? '/'} HTTP/1.1`];
+                const raw = request.rawHeaders;
+                for (let index = 0; index + 1 < raw.length; index += 2)
+                    lines.push(`${raw[index]}: ${raw[index + 1]}`);
+                upstream.write(`${lines.join('\r\n')}\r\n\r\n`);
+                if (head.length)
+                    upstream.write(head);
+                socket.pipe(upstream);
+                upstream.pipe(socket);
+            });
+            upstream.once('error', (error) => {
+                // The host is gone or refused: the browser's socket ends (its client retries).
+                if (!ended)
+                    report(error);
+                end();
+            });
+            socket.once('error', (error) => {
+                // The browser or tunnel closed the connection: no fault.
+                if (logger.isEnabled('debug'))
+                    logger.log('debug', 'Vite HMR socket ended by the browser', { code: error.code });
+                end();
+            });
+            socket.once('close', end);
+            upstream.once('close', end);
+        },
         forward(request, response, report) {
             const headers = { ...request.headers };
             for (const name of HOP_BY_HOP)
@@ -399,7 +535,11 @@ export async function connectViteDev(logger, url, key) {
                 const out = { ...answer.headers };
                 for (const name of HOP_BY_HOP)
                     delete out[name];
-                response.writeHead(answer.statusCode ?? 502, out);
+                // The reason too: Vite's 504s say which (`Outdated Optimize Dep`, D-0128).
+                if (answer.statusMessage)
+                    response.writeHead(answer.statusCode ?? 502, answer.statusMessage, out);
+                else
+                    response.writeHead(answer.statusCode ?? 502, out);
                 answer.pipe(response);
                 answer.once('error', (error) => {
                     if (!aborted)
@@ -428,12 +568,12 @@ export async function connectViteDev(logger, url, key) {
                 if (response.writableFinished)
                     return;
                 aborted = true;
-                outgoing.destroy();
+                destroyRequest(outgoing);
             });
             outgoing.end();
         },
-        async render(entry, page) {
-            const { status, text } = await call('POST', SSR_PATH, JSON.stringify({ entry, page }));
+        async render(entry, page, timeoutMs) {
+            const { status, text } = await call('POST', SSR_PATH, JSON.stringify({ entry, page }), renders, timeoutMs);
             let answer;
             try {
                 answer = JSON.parse(text);
@@ -447,6 +587,11 @@ export async function connectViteDev(logger, url, key) {
         },
         close: async () => {
             agent.destroy();
+            renders.destroy();
+            // Open HMR sockets would keep the process (and a draining worker) alive.
+            for (const socket of [...joined])
+                socket.destroy();
+            joined.clear();
             logger.log('debug', 'Vite dev host disconnected', { url: target.origin });
         },
     };
@@ -478,6 +623,7 @@ export async function openViteDev(logger, environment = process.env, root = proc
     return {
         forward: client.forward,
         render: client.render,
+        upgrade: client.upgrade,
         close: async () => {
             try {
                 await client.close();

package/dist/vite-files.d.ts

@@ -0,0 +1,129 @@
+import type { Logger } from '@dokebi/core';
+/**
+ * Files the dev server never serves, whatever the app's config says (Vite globs: a pattern
+ * without `/` matches the name in every folder; letter case is ignored). Vite's own defaults are
+ * included, because a deny list replaces them.
+ */
+export declare const DEV_FILES_DENY: readonly string[];
+/**
+ * Header the app process sets on every request it forwards to the Vite host: `loopback` or
+ * `remote`, from the browser's socket peer, the forwarding headers and the host name it judged
+ * (isRemoteRequest, §12). Any value the browser sent is replaced. Without it (Vite run on its
+ * own) the Vite host judges its own socket, the forwarding headers and the Host header.
+ */
+export declare const DEV_CLIENT_HEADER = "x-dokebi-dev-client";
+/** The whole 403 a remote host gets: no path, no allow list. */
+export declare const FORBIDDEN_SHORT = "403 Forbidden\n";
+/** Whether a host name (no port, no brackets) is this machine: a remote one gets no details. */
+export declare function isLoopbackHost(name: string): boolean;
+/**
+ * Headers a proxy or tunnel adds (D-0129 §12). Any of them makes a request remote: a tunnel
+ * client runs on this machine (its socket is loopback) and may rewrite Host to localhost, so
+ * neither the socket nor the Host header alone tells a local browser from a forwarded one.
+ */
+export declare const FORWARDING_HEADERS: readonly string[];
+/** Whether a socket peer address is this machine (127.0.0.0/8, ::1, ::ffff:127.x). */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * Whether a request comes from another machine (a `devHosts` tunnel, a proxy, a LAN address).
+ * Local, and so shown details, only when the socket peer is loopback, no forwarding header is
+ * present, the Host is a loopback name and the app process (DEV_CLIENT_HEADER, when set) said
+ * loopback too. An unknown peer counts as remote.
+ */
+export declare function isRemoteRequest(headers: Readonly<Record<string, string | string[] | undefined>>, peer: string | undefined): boolean;
+/**
+ * A Vite deny glob as a regular expression on an absolute `/` path, matched like Vite matches it
+ * (picomatch with `dot` and `nocase`; a pattern without `/` matches in every folder). Supports
+ * `*`, `**`, `?` and `{a,b}`, which is all DEV_FILES_DENY and ordinary app entries use.
+ */
+export declare function denyPattern(glob: string): RegExp;
+/** The part of Vite's resolved config this policy reads (and repairs). */
+export interface ResolvedFilesShape {
+    readonly command: 'build' | 'serve';
+    readonly base: string;
+    readonly root?: string;
+    readonly cacheDir?: string;
+    readonly plugins?: readonly {
+        readonly name?: string;
+    }[];
+    readonly server?: {
+        readonly fs?: {
+            strict: boolean;
+            allow: string[];
+            deny: string[];
+        };
+    };
+    /** Vite's set of files the served modules import (internal, read when present). */
+    readonly safeModulePaths?: ReadonlySet<string>;
+}
+/** The request and response of a connect middleware, as far as the policy needs them. */
+export interface DevRequestShape {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    /** The socket: its peer address is part of the loopback judgement (§12). */
+    readonly socket?: {
+        readonly remoteAddress?: string;
+    };
+}
+export interface DevResponseShape {
+    statusCode: number;
+    readonly headersSent?: boolean;
+    setHeader(name: string, value: string): unknown;
+    removeHeader?(name: string): unknown;
+    write?(chunk: unknown, ...rest: unknown[]): boolean;
+    end(body?: string): unknown;
+}
+export type DevMiddleware = (request: DevRequestShape, response: DevResponseShape, next: (error?: unknown) => void) => void;
+/** What the `config` hook adds for the policy (Vite merges it into the app's config). */
+export interface DevFilesPatch {
+    readonly server: {
+        readonly fs: {
+            readonly strict: true;
+            readonly allow: string[];
+            readonly deny: string[];
+        };
+    };
+}
+export interface DevFilesOptions {
+    /** Further files or folders the browser loads (relative to the Vite root, or absolute). */
+    readonly allow?: readonly string[];
+    /** Further Vite globs the dev server never serves (added to DEV_FILES_DENY). */
+    readonly deny?: readonly string[];
+}
+/**
+ * The dev file policy of one Vite config (one plugin instance). `owner` `dev-host` is the copy the
+ * Vite host of `dokebi dev` adds: it stays inactive when the app's config has `dokebiInertia()`.
+ */
+export declare class DevFilesPolicy {
+    #private;
+    constructor(logger: Logger, options: DevFilesOptions, owner: 'dokebi-inertia' | 'dev-host');
+    /** The deny entries this policy always keeps (DEV_FILES_DENY and the plugin's `deny`). */
+    get required(): string[];
+    /** The `config` hook (dev server only): the policy as a patch, and warnings for a weaker config. */
+    config(raw: unknown, command: 'build' | 'serve'): DevFilesPatch | null;
+    /** The `configResolved` hook: repairs what a later plugin loosened and keeps the live config. */
+    configResolved(config: ResolvedFilesShape): void;
+    /** The middleware to add before Vite's own (undefined when this copy is inactive). */
+    middleware(): DevMiddleware | undefined;
+}
+/** The Vite plugin of the policy alone (what the Vite host of `dokebi dev` adds). */
+export interface DokebiDevFilesPlugin {
+    readonly name: 'dokebi-inertia:dev-files';
+    readonly enforce: 'pre';
+    config(config: unknown, env: {
+        command: 'build' | 'serve';
+    }): DevFilesPatch | null;
+    configResolved(config: ResolvedFilesShape): void;
+    configureServer(server: {
+        readonly middlewares: {
+            use(handler: DevMiddleware): unknown;
+        };
+    }): void;
+}
+/**
+ * The dev file policy as a plugin of its own, for a vite.config without `dokebiInertia()` (which
+ * carries the same policy): the Vite host of `dokebi dev` adds it; it stays inactive next to
+ * `dokebiInertia()`.
+ */
+export declare function dokebiDevFiles(logger: Logger, options?: DevFilesOptions): DokebiDevFilesPlugin;