@dokebi/template-inertia 0.4.1 → 0.4.4

package/dist/options.d.ts

@@ -1,13 +1,40 @@
 import { type OptionsOf } from '@dokebi/core';
+/**
+ * An asset version: empty, or 1 to 128 printable ASCII characters that do not start or end with a
+ * space. The client sends it back in the X-Inertia-Version header, where other characters cannot
+ * travel (a browser refuses them, a line break is refused by Node) and edge spaces are trimmed,
+ * so the version would never match and every visit would reload (409).
+ */
+export declare const VERSION = "^(?:[\\x21-\\x7e](?:[\\x20-\\x7e]{0,126}[\\x21-\\x7e])?)?$";
 export declare const options: import("@dokebi/core").OptionsDeclaration<{
+    readonly assetCacheMaxBytes: number;
+    readonly bootFallback: {
+        readonly enabled: boolean;
+        readonly logo?: string;
+        readonly messages?: Readonly<Record<string, {
+            readonly failed?: string;
+            readonly loading?: string;
+            readonly reload?: string;
+        }>>;
+        readonly stylesheet?: string;
+        readonly timeoutMs: number;
+    };
+    readonly devDepsRepairIntervalMs: number;
+    readonly devHosts: readonly string[];
     readonly encryptHistory: "sealed" | boolean;
     readonly errorPage?: string;
+    readonly logRepeatWindowMs: number;
     readonly rootId?: string;
+    readonly routeIds?: {
+        readonly assets?: string;
+        readonly viteDev?: string;
+    };
     readonly scripts?: readonly string[];
     readonly ssr?: {
         readonly bundle: string;
         readonly entry?: string;
         readonly failure: "error" | "fallback";
+        readonly timeoutMs: number;
     };
     readonly styles?: readonly string[];
     readonly title?: string;
@@ -17,6 +44,7 @@ export declare const options: import("@dokebi/core").OptionsDeclaration<{
         readonly entry: string;
         readonly manifest: string;
     };
+    readonly viteManifestMaxBytes: number;
 }>;
 /** The parsed options of dokebi-template-inertia (`options.dokebi-template-inertia`). */
 export type InertiaPluginOptions = OptionsOf<typeof options>;

package/dist/options.js

@@ -1,4 +1,5 @@
 import { defineOptions, option as o } from '@dokebi/core';
+import { routeIdsOption } from '@dokebi/web/points';
 /*
  * Options of dokebi-template-inertia (D-0063 §3): one declaration is the parser and, at build
  * time, options.schema.json. The rules are the hand parser's before wave B; the asset URL rule
@@ -14,9 +15,18 @@ const localAsset = o.string({
         },
     ],
 });
+/**
+ * An asset version: empty, or 1 to 128 printable ASCII characters that do not start or end with a
+ * space. The client sends it back in the X-Inertia-Version header, where other characters cannot
+ * travel (a browser refuses them, a line break is refused by Node) and edge spaces are trimmed,
+ * so the version would never match and every visit would reload (409).
+ */
+export const VERSION = '^(?:[\\x21-\\x7e](?:[\\x20-\\x7e]{0,126}[\\x21-\\x7e])?)?$';
 export const options = defineOptions({
     version: o.string({
-        description: 'Asset version sent with every page; a client with another one reloads (409). Unset: development (and a warning).',
+        // It travels back in the X-Inertia-Version header: printable ASCII, no edge spaces.
+        pattern: VERSION,
+        description: 'Asset version sent with every page; a client with another one reloads (409). Unset: development (and a warning). Up to 128 printable ASCII characters without leading or trailing spaces: the client sends it back in the X-Inertia-Version header.',
     }),
     rootId: o.string({
         pattern: '^[A-Za-z][A-Za-z0-9_-]*$',
@@ -59,17 +69,103 @@ export const options = defineOptions({
             pattern: '^(?!.*\\.\\.)',
             description: 'Development (D-0045): source module of the bundle rendered through Vite, e.g. src/apps/admin/views/ssr.js. Default: ssr.js beside vite.entry',
         }),
+        timeoutMs: o.integer({
+            minimum: 1,
+            maximum: 600_000,
+            default: 5000,
+            description: 'How long one render(page) may take in ms; past it the render fails with SSR_TIMEOUT, handled as failure says (fallback: the client-rendered page). Size it above your slowest page render (D-0107)',
+        }),
     }, {
         description: 'Render the first HTML of each page on the server (D-0039) with the SSR build output, imported once at start. A missing bundle stops the start.',
     }),
+    devHosts: o.array(o.string({
+        maxLength: 254,
+        pattern: '^\\.?[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$',
+    }), {
+        maxItems: 256,
+        default: [],
+        description: 'Development (DOKEBI_VITE_DEV=1): host names besides loopback names, IP addresses and @dokebi/app domains that may load the Vite dev routes, such as a tunnel host; .example.com also allows its subdomains (D-0107)',
+    }),
+    devDepsRepairIntervalMs: o.integer({
+        minimum: 1000,
+        maximum: 3_600_000,
+        default: 10_000,
+        description: 'Development (dokebi dev): the Vite dev host re-optimizes the pre-bundled dependencies (node_modules/.vite/deps) when they changed on disk under it, at most once per this many ms; a cache that keeps changing faster is reported with INERTIA_VITE_DEPS_CHANGING (D-0128). Read by the host when dokebi dev starts.',
+    }),
     encryptHistory: o.union([o.boolean(), o.literal('sealed')], {
         default: 'sealed',
         description: 'Inertia history encryption (D-0062): true, false, or sealed (default) = on for requests of seal hosts',
     }),
+    viteManifestMaxBytes: o.integer({
+        minimum: 1024,
+        maximum: 67_108_864,
+        default: 4_194_304,
+        description: 'Largest Vite build manifest read at start; a larger one stops the start with VITE_MANIFEST_INVALID (D-0114). An app with thousands of chunks may need more.',
+    }),
+    assetCacheMaxBytes: o.integer({
+        minimum: 0,
+        maximum: 67_108_864,
+        default: 4_194_304,
+        description: 'Built files up to this size are kept in memory after their first request; larger ones are streamed from disk on every request (D-0114). 0 streams every file. Memory is at most the sum of the built files at or below it.',
+    }),
+    logRepeatWindowMs: o.integer({
+        minimum: 1000,
+        maximum: 3_600_000,
+        default: 10_000,
+        description: 'Window of the repeated per-request failure logs (an SSR render that failed, a shared-data or flash hook that threw) in ms: the first is logged in full, the rest of the window are counted (D-0114).',
+    }),
+    bootFallback: o.object({
+        enabled: o.boolean({
+            default: true,
+            description: 'Show the text in the root of the first HTML (false: an empty root, as before)',
+        }),
+        timeoutMs: o.integer({
+            minimum: 1000,
+            maximum: 120_000,
+            default: 10_000,
+            description: 'How long "loading" shows before "could not load — reload" (ms)',
+        }),
+        messages: o.record(o.object({
+            loading: o.string({ minLength: 1, maxLength: 200 }),
+            failed: o.string({ minLength: 1, maxLength: 200 }),
+            reload: o.string({ minLength: 1, maxLength: 200 }),
+        }), {
+            description: 'Texts by language tag of <html lang> (ko, en, pt-BR) over the built-in Korean and English ones',
+        }),
+        stylesheet: o.string({
+            pattern: '^/[^/]',
+            maxLength: 2048,
+            refine: [
+                {
+                    test: (value) => ![...value].some((char) => '\\"\'<>'.includes(char) || char.charCodeAt(0) <= 32),
+                    message: 'must be a local absolute URL without backslash, quote, angle bracket, space or control characters',
+                },
+            ],
+            description: "A local stylesheet (/assets/boot.css) linked right after the built-in style: the app's own look of the box ([data-dokebi-boot] selectors), shown before any script of the app runs, also under dokebi dev",
+        }),
+        logo: o.string({
+            pattern: '^/[^/]',
+            maxLength: 2048,
+            refine: [
+                {
+                    test: (value) => ![...value].some((char) => '\\"\'<>'.includes(char) || char.charCodeAt(0) <= 32),
+                    message: 'must be a local absolute URL without backslash, quote, angle bracket, space or control characters',
+                },
+            ],
+            description: 'A local image (/assets/logo.svg) above the spinner and the could-not-load text of the box, decorative (alt is empty)',
+        }),
+    }, {
+        default: { enabled: true, timeoutMs: 10_000 },
+        description: 'The first HTML while the app loads (Studio v2): a centered spinner ("loading" for screen readers), then "could not load" with a reload button after timeoutMs (by CSS, also under a CSP without inline scripts) or at once when the entry script fails to load; stylesheet restyles it. Not on a server-rendered page.',
+    }),
     errorPage: o.string({
         pattern: '^[A-Za-z0-9][A-Za-z0-9_-]*(?:/[A-Za-z0-9][A-Za-z0-9_-]*)*$',
         description: 'Page component (for example Error) rendered with { status, error, message, hint } for error answers of Inertia visits and full page loads (D-0074). Unset: JSON for visits, a small HTML page for page loads.',
     }),
+    routeIds: routeIdsOption('dokebi-template-inertia', {
+        assets: 'the GET routes of the built files of vite.manifest (one per file)',
+        viteDev: 'the GET <vite base>* routes of the Vite dev server (dokebi dev, one per base)',
+    }),
 }, {
     checks: [
         {

package/dist/prune.d.ts

@@ -0,0 +1,30 @@
+export interface PruneBuildOptions {
+    /** The current build's manifest, as `inertia.vite.manifest` names it (`dist/.vite/manifest.json`). */
+    readonly manifest: string;
+    /** Only files unchanged this long are removed, in ms (default 7 days; 0: every unnamed one). */
+    readonly olderThanMs?: number;
+    /** List what would be removed, remove nothing. */
+    readonly dryRun?: boolean;
+    /** A larger manifest is refused (default 4 MiB, the plugin's `viteManifestMaxBytes`). */
+    readonly maxManifestBytes?: number;
+    /** The time to count ages from, in ms since the epoch (default now). */
+    readonly now?: number;
+}
+export interface PruneBuildResult {
+    /** The build folders looked at: those of the manifest's files (`dist/assets`), as served. */
+    readonly folders: readonly string[];
+    /** The files removed (with `dryRun`: that would be). */
+    readonly removed: readonly string[];
+    /** How many files of those folders stay. */
+    readonly kept: number;
+}
+/**
+ * Removes the old build files from the folders a Vite manifest's files sit in — the folders
+ * @dokebi/template-inertia serves for rolling deploys (`dist/assets`). A file stays when the
+ * manifest names it (or it is the source map of one), when its name is not content-hashed (not a
+ * build output: `app-3fa8c1d2.js` is one, `robots.txt` is not), when it is hidden, a link or
+ * changed within `olderThanMs`. Files directly in the output folder (the manifest's `.vite/`, the
+ * SSR build's `ssr/`) are never looked at. A manifest that cannot be read, is not an object of
+ * chunks or names no file is an error and nothing is removed.
+ */
+export declare function pruneBuildFiles(options: PruneBuildOptions): Promise<PruneBuildResult>;

package/dist/prune.js

@@ -0,0 +1,159 @@
+import { lstat, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { HASHED } from './built-files.js';
+import { InertiaError, InertiaUsageError } from './errors.js';
+/*
+ * Removing the chunks of builds that no page uses any more (audit r5 review). A rolling deploy
+ * keeps the previous builds' files (vite `build.emptyOutDir: false`, D-0160 §5), so the build
+ * folders grow with every deploy. A cleanup by age alone (`find -mtime +7 -delete`) also removed
+ * the current build's files when no deploy came for a week. Here the current manifest decides:
+ * every file it names stays whatever its age; only content-hashed files it does not name, unchanged
+ * for `olderThanMs`, go.
+ */
+/** A week: the pages of a previous build are long gone by then (a tab left open for days). */
+const DEFAULT_OLDER_THAN_MS = 7 * 86_400_000;
+/** The default of the plugin's `viteManifestMaxBytes`. */
+const DEFAULT_MAX_MANIFEST_BYTES = 4_194_304;
+/**
+ * Removes the old build files from the folders a Vite manifest's files sit in — the folders
+ * @dokebi/template-inertia serves for rolling deploys (`dist/assets`). A file stays when the
+ * manifest names it (or it is the source map of one), when its name is not content-hashed (not a
+ * build output: `app-3fa8c1d2.js` is one, `robots.txt` is not), when it is hidden, a link or
+ * changed within `olderThanMs`. Files directly in the output folder (the manifest's `.vite/`, the
+ * SSR build's `ssr/`) are never looked at. A manifest that cannot be read, is not an object of
+ * chunks or names no file is an error and nothing is removed.
+ */
+export async function pruneBuildFiles(options) {
+    const olderThanMs = options.olderThanMs ?? DEFAULT_OLDER_THAN_MS;
+    const maxBytes = options.maxManifestBytes ?? DEFAULT_MAX_MANIFEST_BYTES;
+    const now = options.now ?? Date.now();
+    if (typeof options.manifest !== 'string' || !options.manifest)
+        throw new InertiaUsageError('INVALID_PRUNE', 'pruneBuildFiles: manifest must be a file path');
+    for (const [name, value] of [
+        ['olderThanMs', olderThanMs],
+        ['maxManifestBytes', maxBytes],
+        ['now', now],
+    ])
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new InertiaUsageError('INVALID_PRUNE', `pruneBuildFiles: ${name} must be whole milliseconds or bytes from 0, not ${String(value)}`);
+    const path = resolve(options.manifest);
+    const named = await namedFiles(path, maxBytes);
+    // Vite writes <outDir>/.vite/manifest.json; a custom manifest name sits in outDir itself.
+    const outDir = basename(dirname(path)) === '.vite' ? dirname(dirname(path)) : dirname(path);
+    const folders = buildFolders(outDir, named);
+    const cutoff = now - olderThanMs;
+    const removed = [];
+    let kept = 0;
+    const walk = async (folder) => {
+        let entries;
+        try {
+            entries = await readdir(folder, { withFileTypes: true });
+        }
+        catch (error) {
+            // A folder the manifest names but the build did not write (or removed meanwhile).
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const file = join(folder, entry.name);
+            if (entry.name.startsWith('.')) {
+                kept++;
+                continue;
+            }
+            // A link (to a file or folder) is never followed or removed: a Dirent of a link is neither.
+            if (entry.isDirectory()) {
+                await walk(file);
+                continue;
+            }
+            if (!entry.isFile() || current(file, named) || !built(entry.name)) {
+                kept++;
+                continue;
+            }
+            if ((await lstat(file)).mtimeMs > cutoff) {
+                kept++;
+                continue;
+            }
+            removed.push(file);
+            // force: another cleanup that removed it first is no failure.
+            if (options.dryRun !== true)
+                await rm(file, { force: true });
+        }
+    };
+    for (const folder of folders)
+        await walk(folder);
+    return { folders, removed, kept };
+}
+/** The files the manifest names (every chunk's file, CSS and assets), as absolute paths. */
+async function namedFiles(path, maxBytes) {
+    let size;
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            throw new InertiaError('VITE_MANIFEST_INVALID', `Vite manifest ${path} is not a file`);
+        size = info.size;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new InertiaError('VITE_MANIFEST_MISSING', `Vite manifest not found: ${path}`, {
+                cause: error,
+            });
+        throw error;
+    }
+    if (size > maxBytes)
+        throw new InertiaError('VITE_MANIFEST_INVALID', `Vite manifest ${path} is larger than maxManifestBytes (${maxBytes})`);
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        throw new InertiaError('VITE_MANIFEST_INVALID', `Vite manifest ${path} is not JSON`, {
+            cause: error,
+        });
+    }
+    if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest))
+        throw new InertiaError('VITE_MANIFEST_INVALID', `Vite manifest ${path} is not an object of chunks`);
+    const outDir = basename(dirname(path)) === '.vite' ? dirname(dirname(path)) : dirname(path);
+    const named = new Set();
+    const add = (file) => {
+        if (typeof file !== 'string' || file.split('/').some((part) => part === '..' || !part))
+            return;
+        named.add(join(outDir, ...file.split('/')));
+    };
+    for (const chunk of Object.values(manifest)) {
+        if (chunk === null || typeof chunk !== 'object')
+            continue;
+        const { file, css, assets } = chunk;
+        add(file);
+        for (const item of Array.isArray(css) ? css : [])
+            add(item);
+        for (const item of Array.isArray(assets) ? assets : [])
+            add(item);
+    }
+    if (named.size === 0)
+        throw new InertiaError('VITE_MANIFEST_INVALID', `Vite manifest ${path} names no file: nothing is removed`);
+    return named;
+}
+/** The folders of the named files under outDir (not outDir itself, no hidden one), outermost. */
+function buildFolders(outDir, named) {
+    const folders = new Set();
+    for (const file of named) {
+        const folder = dirname(file);
+        const inside = folder.slice(outDir.length + 1);
+        if (!folder.startsWith(outDir + sep) || inside.split(sep).some((part) => part.startsWith('.')))
+            continue;
+        folders.add(folder);
+    }
+    // A folder inside another is walked with it.
+    return [...folders]
+        .sort()
+        .filter((folder, _index, all) => !all.some((other) => folder.startsWith(other + sep)));
+}
+/** A file the manifest names, or the source map of one (`build.sourcemap: 'hidden'`). */
+function current(file, named) {
+    return named.has(file) || (/\.map$/i.test(file) && named.has(file.slice(0, -4)));
+}
+/** A build output by its name: content-hashed (`app-3fa8c1d2.js`), or the source map of one. */
+function built(name) {
+    return HASHED.test(/\.map$/i.test(name) ? name.slice(0, -4) : name);
+}

package/dist/responder.d.ts

@@ -1,7 +1,8 @@
 import type { Awaitable, Logger } from '@dokebi/core';
 import { diagnostics } from '@dokebi/core/libraries';
-import type { WebErrorResponse } from '@dokebi/web';
+import { type WebErrorResponse } from '@dokebi/web';
 import type { FastifyReply, FastifyRequest } from 'fastify';
+import { type InertiaBootFallback, type NormalizedBootFallback } from './boot-fallback.js';
 import { type InertiaProp } from './props.js';
 export type Json = null | boolean | number | string | readonly Json[] | {
     readonly [key: string]: Json;
@@ -25,6 +26,12 @@ export interface InertiaOptions {
      * unset: JSON for visits, dokebi-web's small HTML page for page loads.
      */
     errorPage?: string | false;
+    /**
+     * Text in the root of the first HTML while the app loads, then "could not load — reload" after
+     * `timeoutMs` or at once when the entry script fails to load (Studio v2); `false` turns it off.
+     * Not on a server-rendered page.
+     */
+    bootFallback?: InertiaBootFallback | NormalizedBootFallback | false;
 }
 /** What `answerError` reads of a dokebi-web error answer (`WebErrorResponse`). */
 export type InertiaErrorResponse = Pick<WebErrorResponse, 'request' | 'reply' | 'status' | 'body' | 'format' | 'sealed'>;
@@ -116,7 +123,9 @@ export interface InertiaApi {
     answerError(response: InertiaErrorResponse): Promise<boolean>;
 }
 export declare function vary(reply: FastifyReply): void;
-export type NormalizedInertiaOptions = Readonly<Required<InertiaOptions>>;
+export type NormalizedInertiaOptions = Readonly<Required<Omit<InertiaOptions, 'bootFallback'>> & {
+    bootFallback: NormalizedBootFallback;
+}>;
 /** Validates and fills defaults; the result is accepted again unchanged. */
 export declare function normalizeInertiaOptions(options?: InertiaOptions): NormalizedInertiaOptions;
 export declare class InertiaResponder implements InertiaApi {
@@ -133,8 +142,9 @@ export declare class InertiaResponder implements InertiaApi {
     /**
      * The error answer of an Inertia request or page load (D-0074 §3), for dokebi-web's error
      * responders: the validation redirect (an Inertia request refused with 422 VALIDATION_FAILED,
-     * with a session), then the `errorPage` component. False leaves the answer to dokebi-web (JSON
-     * for visits, a small HTML page for page loads).
+     * or with another 4xx whose `data.formErrors` asks for it — D-0076 §2.5, dokebi-csrf's expired
+     * token — with a session), then the `errorPage` component. False leaves the answer to
+     * dokebi-web (JSON for visits, a small HTML page for page loads).
      */
     answerError(response: InertiaErrorResponse): Promise<boolean>;
     redirect(request: FastifyRequest, reply: FastifyReply, url: string): FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;