@dokebi/template-inertia 0.4.2 → 0.4.5

package/dist/vite-deps.d.ts

@@ -0,0 +1,76 @@
+import type { Logger } from '@dokebi/core';
+/** One optimized dependency or chunk as Vite's optimizer holds it (absolute `file`). */
+interface DepInfoShape {
+    readonly file: string;
+    readonly fileHash?: string;
+}
+/** The part of Vite's dependency optimizer read here. */
+interface DepsOptimizerShape {
+    readonly metadata: {
+        readonly hash: string;
+        readonly optimized: Readonly<Record<string, DepInfoShape>>;
+        readonly chunks: Readonly<Record<string, DepInfoShape>>;
+    };
+}
+/** The part of Vite's dev server the cache check uses. */
+export interface DepsServerShape {
+    readonly config: {
+        readonly cacheDir: string;
+    };
+    readonly environments?: {
+        readonly client?: {
+            readonly depsOptimizer?: DepsOptimizerShape;
+        };
+    };
+    restart(forceOptimize?: boolean): Promise<void>;
+}
+/** Why the folder no longer holds what the optimizer serves. */
+export type DepsDrift = 'missing' | 'rewritten';
+export interface DepsState {
+    /** Undefined when the folder holds every file the optimizer serves, as it wrote them. */
+    readonly drift: DepsDrift | undefined;
+    /** Files the optimizer serves (optimized dependencies and their chunks). */
+    readonly files: number;
+    /** Served files that are not on disk (absolute paths). */
+    readonly missing: readonly string[];
+    /** The optimizer metadata that was compared (Vite replaces the object on every commit). */
+    readonly metadata?: object;
+}
+/** What asked for the check (logged). */
+export type DepsTrigger = 'start' | 'client' | 'outdated';
+export interface DependencyCacheOptions {
+    /** Least time between two repairs in ms (`devDepsRepairIntervalMs`). */
+    readonly repairIntervalMs: number;
+    /** The clock (tests). */
+    readonly now?: () => number;
+}
+/**
+ * The host's check of its dependency cache. `ensure` re-optimizes when the folder no longer holds
+ * what the optimizer serves; one check or repair runs at a time (callers share it).
+ */
+export declare class DependencyCache {
+    #private;
+    constructor(logger: Logger, server: DepsServerShape, options: DependencyCacheOptions);
+    /** Repairs so far. */
+    get repairs(): number;
+    /** The deps folder of the browser environment (`<cacheDir>/deps`, Vite's default name). */
+    get folder(): string;
+    /**
+     * Compares the optimizer's state with the folder: every served file is there, and the
+     * metadata on disk is the one this optimizer wrote or loaded (same hash and file hashes).
+     */
+    inspect(): Promise<DepsState>;
+    /**
+     * Checks the cache and re-optimizes when it drifted; resolves true after a repair. A check or
+     * repair already running is shared. Failures reject (the caller logs them).
+     */
+    ensure(trigger: DepsTrigger): Promise<boolean>;
+    /**
+     * Records this host in the cache folder and warns when another live host of `dokebi dev`
+     * recorded itself there: two optimizers on one folder can break each other's files.
+     */
+    claim(pid?: number): Promise<void>;
+    /** Removes the marker when it is still this host's. */
+    release(pid?: number): Promise<void>;
+}
+export {};

package/dist/vite-deps.js

@@ -0,0 +1,249 @@
+// The pre-bundled dependencies of the Vite dev host (D-0128). Vite keeps what its dependency
+// optimizer produced in memory (each dependency's file under node_modules/.vite/deps and the
+// `?v=` hash the browser is given) and trusts node_modules/.vite/deps/_metadata.json at start when
+// its lockfile and config hashes match; it never looks at the files again. A cache changed under
+// it (another Vite or `dokebi dev` on the same folder re-optimizing at the same time, a reinstall)
+// leaves metadata that names files that are gone. Vite answers a gone file requested with `?v=` as
+// 504 "Outdated Optimize Dep", and nothing ever heals that: the host outlives app restarts (D-0045
+// addendum 3) and the next host trusts the same metadata.
+//
+// So the host compares its optimizer's state with the folder when it starts, whenever an app
+// process connects (every app or worker restart) and after a 504, and re-optimizes when they
+// differ: it removes the deps folder and restarts its Vite (a new optimizer, a new module graph;
+// open pages reconnect HMR and reload, a new page load gets the new hashes). A repair at most once
+// per `devDepsRepairIntervalMs`; a cache that keeps changing faster is reported instead.
+import { constants } from 'node:fs';
+import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { diagnostics } from '@dokebi/core/libraries';
+const { describeError } = diagnostics;
+/** Vite's metadata file in the deps folder. */
+const METADATA_FILE = '_metadata.json';
+/**
+ * The marker of the host that uses a cache folder (its pid), in Vite's cacheDir: under `.dokebi/`,
+ * which the dev server never serves (the `.dokebi` rule of DEV_FILES_DENY, D-0129).
+ */
+const HOST_MARKER = join('.dokebi', 'vite-host.json');
+/** Missing files named in a log record at most. */
+const SAMPLE = 5;
+async function present(file) {
+    try {
+        await access(file, constants.F_OK);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** `process.kill(pid, 0)`: whether the process exists (EPERM: it exists, owned by another user). */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * The host's check of its dependency cache. `ensure` re-optimizes when the folder no longer holds
+ * what the optimizer serves; one check or repair runs at a time (callers share it).
+ */
+export class DependencyCache {
+    #logger;
+    #server;
+    #intervalMs;
+    #now;
+    #running;
+    #repairedAt = Number.NEGATIVE_INFINITY;
+    #repairs = 0;
+    #skippedWarnedAt = Number.NEGATIVE_INFINITY;
+    #skipped = 0;
+    constructor(logger, server, options) {
+        this.#logger = logger;
+        this.#server = server;
+        this.#intervalMs = options.repairIntervalMs;
+        this.#now = options.now ?? Date.now;
+    }
+    /** Repairs so far. */
+    get repairs() {
+        return this.#repairs;
+    }
+    /** The deps folder of the browser environment (`<cacheDir>/deps`, Vite's default name). */
+    get folder() {
+        return join(this.#server.config.cacheDir, 'deps');
+    }
+    /**
+     * Compares the optimizer's state with the folder: every served file is there, and the
+     * metadata on disk is the one this optimizer wrote or loaded (same hash and file hashes).
+     */
+    async inspect() {
+        const optimizer = this.#server.environments?.client?.depsOptimizer;
+        if (!optimizer)
+            return { drift: undefined, files: 0, missing: [] };
+        const { metadata } = optimizer;
+        const served = [...Object.values(metadata.optimized), ...Object.values(metadata.chunks)];
+        // Nothing served from the folder yet (a first optimization still running): nothing to lose.
+        if (served.length === 0)
+            return { drift: undefined, files: 0, missing: [], metadata };
+        const found = await Promise.all(served.map((info) => present(info.file)));
+        const missing = served.filter((_, index) => !found[index]).map((info) => info.file);
+        if (missing.length)
+            return { drift: 'missing', files: served.length, missing, metadata };
+        const folder = dirname(served[0]?.file ?? join(this.folder, METADATA_FILE));
+        let text;
+        try {
+            text = await readFile(join(folder, METADATA_FILE), 'utf8');
+        }
+        catch (error) {
+            // The files are there and Vite never reads the metadata again while it runs; the next
+            // host start finds no metadata and optimizes afresh.
+            if (error.code === 'ENOENT')
+                return { drift: undefined, files: served.length, missing, metadata };
+            throw error;
+        }
+        let disk;
+        try {
+            disk = JSON.parse(text);
+        }
+        catch (error) {
+            if (this.#logger.isEnabled('debug'))
+                this.#logger.log('debug', 'Vite dev host found unreadable dependency metadata', {
+                    folder,
+                    error: describeError(error),
+                });
+            return { drift: 'rewritten', files: served.length, missing, metadata };
+        }
+        const same = disk.hash === metadata.hash &&
+            Object.entries(metadata.optimized).every(([id, info]) => disk.optimized?.[id]?.fileHash === info.fileHash);
+        return { drift: same ? undefined : 'rewritten', files: served.length, missing, metadata };
+    }
+    /**
+     * Checks the cache and re-optimizes when it drifted; resolves true after a repair. A check or
+     * repair already running is shared. Failures reject (the caller logs them).
+     */
+    ensure(trigger) {
+        this.#running ??= this.#ensure(trigger).finally(() => {
+            this.#running = undefined;
+        });
+        return this.#running;
+    }
+    async #ensure(trigger) {
+        let state = await this.inspect();
+        // Vite commits a new optimization by renaming folders and then replacing its metadata; a
+        // check between the two saw the old metadata against the new files. Compare again.
+        if (state.drift !== undefined &&
+            state.metadata !== this.#server.environments?.client?.depsOptimizer?.metadata) {
+            if (this.#logger.isEnabled('debug'))
+                this.#logger.log('debug', 'Vite dev host compares its dependency cache again', {
+                    trigger,
+                    drift: state.drift,
+                });
+            state = await this.inspect();
+        }
+        if (state.drift === undefined) {
+            if (this.#logger.isEnabled('debug'))
+                this.#logger.log('debug', 'Vite dev host dependency cache matches', {
+                    trigger,
+                    files: state.files,
+                });
+            return false;
+        }
+        const now = this.#now();
+        if (now - this.#repairedAt < this.#intervalMs) {
+            // Something rewrites the folder faster than the host repairs it: say so, once a window.
+            this.#skipped++;
+            if (now - this.#skippedWarnedAt >= this.#intervalMs) {
+                this.#logger.log('warn', 'Vite dev host dependency cache keeps changing; is another dokebi dev or Vite using this project?', {
+                    code: 'INERTIA_VITE_DEPS_CHANGING',
+                    trigger,
+                    drift: state.drift,
+                    folder: this.folder,
+                    repairIntervalMs: this.#intervalMs,
+                    repeated: this.#skipped,
+                });
+                this.#skippedWarnedAt = now;
+                this.#skipped = 0;
+            }
+            return false;
+        }
+        this.#repairedAt = now;
+        this.#repairs++;
+        this.#logger.log('warn', 'Vite dev host found its pre-bundled dependencies changed on disk; re-optimizing', {
+            code: 'INERTIA_VITE_DEPS_STALE',
+            trigger,
+            drift: state.drift,
+            folder: this.folder,
+            files: state.files,
+            missing: state.missing.length,
+            sample: state.missing.slice(0, SAMPLE),
+        });
+        const begin = performance.now();
+        // Vite reads no metadata from a folder that is not there: the restarted optimizer starts
+        // afresh (the folder is rewritten, the browser gets new `?v=` hashes). restart(true) would
+        // do the same but keep forcing a re-optimization on every later restart of this Vite.
+        await rm(this.folder, { recursive: true, force: true });
+        await this.#server.restart();
+        this.#logger.log('debug', 'Vite dev host re-optimized its dependencies', {
+            trigger,
+            ms: Math.round(performance.now() - begin),
+            repairs: this.#repairs,
+        });
+        return true;
+    }
+    /**
+     * Records this host in the cache folder and warns when another live host of `dokebi dev`
+     * recorded itself there: two optimizers on one folder can break each other's files.
+     */
+    async claim(pid = process.pid) {
+        const marker = join(this.#server.config.cacheDir, HOST_MARKER);
+        let other;
+        try {
+            const recorded = JSON.parse(await readFile(marker, 'utf8')).pid;
+            if (typeof recorded === 'number' && recorded !== pid && alive(recorded))
+                other = recorded;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && !(error instanceof SyntaxError))
+                throw error;
+            if (this.#logger.isEnabled('debug'))
+                this.#logger.log('debug', 'Vite dev host found no live host marker', {
+                    marker,
+                    reason: code ?? 'unreadable',
+                });
+        }
+        if (other !== undefined)
+            this.#logger.log('warn', 'Another dokebi dev Vite host uses this project; stop one, or their pre-bundled dependencies can break each other', { code: 'INERTIA_VITE_HOST_SHARED', pid: other, folder: this.#server.config.cacheDir });
+        await mkdir(dirname(marker), { recursive: true });
+        await writeFile(marker, `${JSON.stringify({ pid })}\n`);
+        this.#logger.log('debug', 'Vite dev host recorded itself in the cache folder', {
+            marker,
+            shared: other !== undefined,
+        });
+    }
+    /** Removes the marker when it is still this host's. */
+    async release(pid = process.pid) {
+        const marker = join(this.#server.config.cacheDir, HOST_MARKER);
+        let recorded;
+        try {
+            recorded = JSON.parse(await readFile(marker, 'utf8')).pid;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && !(error instanceof SyntaxError))
+                throw error;
+            // Gone or not a marker this host wrote: nothing of this host's to remove.
+            if (this.#logger.isEnabled('debug'))
+                this.#logger.log('debug', 'Vite dev host has no marker to remove', {
+                    marker,
+                    reason: code ?? 'unreadable',
+                });
+            return;
+        }
+        if (recorded === pid)
+            await rm(marker, { force: true });
+    }
+}

package/dist/vite-dev.d.ts

@@ -1,4 +1,5 @@
-import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type ClientRequest, type IncomingMessage, type ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
 import type { Logger } from '@dokebi/core';
 export declare const viteDevRequested: () => boolean;
 /** The part of a Node response the dev route finishes. */
@@ -14,6 +15,15 @@ export interface DevResponse {
 export declare function viteFallthrough(response: DevResponse, error: unknown, report: (error: unknown) => void): void;
 /** Header that carries the host key; the host answers no HTTP request without it. */
 export declare const VITE_HOST_KEY_HEADER = "x-dokebi-vite-key";
+/** Whether an upgrade request is Vite's client (its HMR or ping socket), by its subprotocol. */
+export declare function isViteUpgrade(request: Pick<IncomingMessage, 'headers'>): boolean;
+/** Default of `devDepsRepairIntervalMs` (D-0128). */
+export declare const DEFAULT_DEPS_REPAIR_INTERVAL_MS = 10000;
+/** Settings of the host from dokebi.yaml (`options.dokebi-template-inertia`). */
+export interface ViteHostSettings {
+    /** Least time between two repairs of the pre-bundled dependencies in ms (D-0128). */
+    readonly depsRepairIntervalMs?: number;
+}
 /** The one Vite of a development session and the loopback port it answers on. */
 export interface ViteHost {
     /** Where clients reach the host: `http://127.0.0.1:<port>`. */
@@ -31,8 +41,19 @@ export interface ViteHost {
 export interface ViteDev {
     /** Answers a dev route request from the host (status, headers and body as Vite sent them). */
     forward(request: IncomingMessage, response: ServerResponse, report: (error: unknown) => void): void;
-    /** Loads `entry` (relative to the project root) through Vite and calls its `render(page)`. */
-    render(entry: string, page: unknown): Promise<unknown>;
+    /**
+     * Loads `entry` (relative to the project root) through Vite and calls its `render(page)`. With
+     * `timeoutMs` (the scope's `ssr.timeoutMs`) the request to the host is cut at that deadline
+     * (`SSR_TIMEOUT`), so a render that never finishes does not keep a connection to the host.
+     */
+    render(entry: string, page: unknown, timeoutMs?: number): Promise<unknown>;
+    /**
+     * Joins an HMR WebSocket upgrade that reached the app's port (`<base>` with subprotocol
+     * `vite-hmr`) to the host: the browser's handshake goes on as it came, Vite checks its token
+     * and answers, then bytes flow both ways until either side closes. So the browser needs only
+     * the page's own origin (a tunnel, a proxy), never the host's loopback port.
+     */
+    upgrade(request: IncomingMessage, socket: Duplex, head: Buffer, report: (error: unknown) => void): void;
     /** Releases this process's connections (and its own host, when it started one). */
     close(): Promise<void>;
 }
@@ -47,8 +68,25 @@ export interface ViteDev {
  * - 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 declare function startViteHost(logger: Logger, root?: string, settings?: ViteHostSettings): Promise<ViteHost>;
+/**
+ * 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 declare function startViteHost(logger: Logger, root?: string): Promise<ViteHost>;
+export declare function destroyRequest(outgoing: ClientRequest, error?: Error): void;
 /**
  * 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).