toiljs 0.0.15 → 0.0.19

package/server/runtime/rest/RouteContext.ts

@@ -0,0 +1,82 @@
+/**
+ * Per-request context handed to a `@route` method. Carries the captured path
+ * params (`/todos/:id`), the parsed query string, and the raw `Request`. The
+ * compiler builds one of these for you and injects it into any route method
+ * that declares a `RouteContext` parameter.
+ */
+
+import { Request } from '../request';
+
+export class RouteContext {
+    /** The raw incoming request (method, path, headers, body). */
+    request: Request;
+
+    // Parallel arrays rather than a Map: a route has a handful of params, the
+    // linear scan is cheaper than hashing, and it keeps the codec-free runtime small.
+    private paramKeys: Array<string>;
+    private paramVals: Array<string>;
+    private queryKeys: Array<string> | null = null;
+    private queryVals: Array<string> | null = null;
+
+    constructor(request: Request, paramKeys: Array<string>, paramVals: Array<string>) {
+        this.request = request;
+        this.paramKeys = paramKeys;
+        this.paramVals = paramVals;
+    }
+
+    /** A captured path parameter (`/todos/:id` gives `param("id")`), or "" if absent. */
+    param(name: string): string {
+        for (let i = 0; i < this.paramKeys.length; i++) {
+            if (this.paramKeys[i] == name) return this.paramVals[i];
+        }
+        return '';
+    }
+
+    /** A query-string value (`?q=hi` gives `query("q")`), or "" if absent. Not URL-decoded in v1. */
+    query(name: string): string {
+        this.ensureQuery();
+        const keys = this.queryKeys!;
+        const vals = this.queryVals!;
+        for (let i = 0; i < keys.length; i++) {
+            if (keys[i] == name) return vals[i];
+        }
+        return '';
+    }
+
+    /** Case-insensitive request header, or null. Delegates to `Request.header`. */
+    header(name: string): string | null {
+        return this.request.header(name);
+    }
+
+    /** The raw request body decoded as UTF-8 text (used by the JSON stream codec). */
+    text(): string {
+        const body = this.request.body;
+        if (body.length == 0) return '';
+        return String.UTF8.decodeUnsafe(body.dataStart, body.byteLength);
+    }
+
+    private ensureQuery(): void {
+        if (this.queryKeys != null) return;
+        const keys = new Array<string>();
+        const vals = new Array<string>();
+        const path = this.request.path;
+        const q = path.indexOf('?');
+        if (q >= 0 && q + 1 < path.length) {
+            const pairs = path.substring(q + 1).split('&');
+            for (let i = 0; i < pairs.length; i++) {
+                const pair = pairs[i];
+                if (pair.length == 0) continue;
+                const eq = pair.indexOf('=');
+                if (eq < 0) {
+                    keys.push(pair);
+                    vals.push('');
+                } else {
+                    keys.push(pair.substring(0, eq));
+                    vals.push(pair.substring(eq + 1));
+                }
+            }
+        }
+        this.queryKeys = keys;
+        this.queryVals = vals;
+    }
+}

package/server/runtime/rest/match.ts

@@ -0,0 +1,48 @@
+/**
+ * Compile-time route patterns (`/api/todos/:id`) matched against a request path
+ * at runtime, capturing `:params`. The compiler emits one `matchRoute(...)` call
+ * per route inside a controller's injected `__tryRoute`.
+ */
+
+import { Request } from '../request';
+import { RouteContext } from './RouteContext';
+
+const COLON: i32 = 0x3a; // ':'
+
+/**
+ * Match `pattern` against `req.path`. Static segments must be equal; a `:name`
+ * segment captures the corresponding path segment. The query string is ignored
+ * for matching. Returns a populated `RouteContext` on a match, `null` on a miss.
+ */
+export function matchRoute(pattern: string, req: Request): RouteContext | null {
+    let path = req.path;
+    const q = path.indexOf('?');
+    if (q >= 0) path = path.substring(0, q);
+
+    const pat = splitSegments(pattern);
+    const act = splitSegments(path);
+    if (pat.length != act.length) return null;
+
+    const keys = new Array<string>();
+    const vals = new Array<string>();
+    for (let i = 0; i < pat.length; i++) {
+        const seg = pat[i];
+        if (seg.length > 0 && seg.charCodeAt(0) == COLON) {
+            keys.push(seg.substring(1));
+            vals.push(act[i]);
+        } else if (seg != act[i]) {
+            return null;
+        }
+    }
+    return new RouteContext(req, keys, vals);
+}
+
+/** Split a path on `/`, dropping empty segments (so leading/trailing slashes don't matter). */
+function splitSegments(path: string): Array<string> {
+    const out = new Array<string>();
+    const parts = path.split('/');
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i].length > 0) out.push(parts[i]);
+    }
+    return out;
+}

package/server/runtime/tsconfig.json

@@ -0,0 +1,7 @@
+{
+    "extends": "toilscript/std/assembly.json",
+    "compilerOptions": {
+        "plugins": [{ "name": "toilscript/std/ts-plugin.cjs" }]
+    },
+    "include": ["./**/*.ts"]
+}

package/src/backend/index.ts

@@ -1,160 +1,202 @@
-/**
- * toiljs backend, the self-host / dev server, built on @btc-vision/hyper-express (uWebSockets.js)
- * for very high throughput. It serves the built client (static assets + SPA fallback) and exposes
- * a WebSocket channel for realtime / live updates.
- *
- * This is the Node "server" that hosts the app on a local machine; it is distinct from the
- * toilscript WASM target in `src/server`.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-
-import {
-    Server,
-    type MiddlewareNext,
-    type Request,
-    type Response,
-    type Websocket,
-} from '@btc-vision/hyper-express';
-
-const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
-const MAX_BODY_BUFFER = 1024 * 32;
-const HTTP_IDLE_TIMEOUT = 60;
-const HTTP_RESPONSE_TIMEOUT = 120;
-
-const WS_MAX_PAYLOAD_LENGTH = 1024 * 1024;
-const WS_IDLE_TIMEOUT = 120;
-const WS_MAX_BACKPRESSURE = 1024 * 1024 * 2;
-
-const CORS_METHODS = 'GET, POST, OPTIONS, PUT, PATCH, DELETE';
-const CORS_HEADERS = 'X-Requested-With, content-type';
-
-/** Options for {@link startBackend}. */
-export interface BackendOptions {
-    /** Directory to serve (the built client `outDir`, e.g. `dist`). */
-    readonly root: string;
-    /** Listening port. Default `3000`. */
-    readonly port?: number;
-    /** Bind host. Default `0.0.0.0`. */
-    readonly host?: string;
-    /** WebSocket channel path. Default `/_toil`. */
-    readonly wsPath?: string;
-    /** Send permissive CORS headers + handle preflight. Default `true`. */
-    readonly cors?: boolean;
-    /** Max request body length in bytes. Default 8 MB. */
-    readonly maxBodyLength?: number;
-}
-
-/** A running backend instance. */
-export interface RunningBackend {
-    readonly port: number;
-    readonly host: string;
-    readonly wsPath: string;
-    /** Sends a message to every connected WebSocket client. */
-    broadcast(message: string): void;
-    /** Number of currently-connected WebSocket clients. */
-    clientCount(): number;
-    /** Gracefully shuts the server down. */
-    close(): Promise<void>;
-}
-
-/** Resolves a request path to a file inside `root`, guarding against path traversal. */
-function resolveStaticFile(root: string, requestPath: string): string | null {
-    const decoded = decodeURIComponent(requestPath);
-    const resolved = path.join(root, decoded);
-    if (resolved !== root && !resolved.startsWith(root + path.sep)) return null;
-    if (decoded === '/' || decoded === '') return null;
-    if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved;
-    return null;
-}
-
-/**
- * Starts the hyper-express server serving `root` with an SPA fallback to `index.html`,
- * plus a WebSocket channel at `wsPath`. Resolves once the server is listening.
- */
-export async function startBackend(options: BackendOptions): Promise<RunningBackend> {
-    const port = options.port ?? 3000;
-    const host = options.host ?? '0.0.0.0';
-    const wsPath = options.wsPath ?? '/_toil';
-    const cors = options.cors ?? true;
-    const root = path.resolve(options.root);
-    const indexHtml = path.join(root, 'index.html');
-
-    const app = new Server({
-        max_body_length: options.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH,
-        max_body_buffer: MAX_BODY_BUFFER,
-        fast_abort: true,
-        idle_timeout: HTTP_IDLE_TIMEOUT,
-        response_timeout: HTTP_RESPONSE_TIMEOUT,
-    });
-
-    const clients = new Set<Websocket>();
-
-    app.set_error_handler((_request: Request, response: Response, _error: Error) => {
-        if (response.completed) return;
-        response.atomic(() => {
-            response.status(500).json({ error: 'Internal server error.' });
-        });
-    });
-
-    if (cors) {
-        app.use((request: Request, response: Response, next: MiddlewareNext) => {
-            if (request.method !== 'OPTIONS') {
-                response.setHeader('Access-Control-Allow-Origin', '*');
-                response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
-                response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
-            }
-            response.removeHeader('uWebSockets');
-            next();
-        });
-        app.options('/*', (_request: Request, response: Response) => {
-            response.setHeader('Access-Control-Allow-Origin', '*');
-            response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
-            response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
-            response.setHeader('Access-Control-Max-Age', '86400');
-            response.status(204).send();
-        });
-    }
-
-    app.ws(
-        wsPath,
-        {
-            message_type: 'String',
-            max_payload_length: WS_MAX_PAYLOAD_LENGTH,
-            idle_timeout: WS_IDLE_TIMEOUT,
-            max_backpressure: WS_MAX_BACKPRESSURE,
-        },
-        (ws) => {
-            clients.add(ws);
-            ws.send(JSON.stringify({ type: 'connected', clients: clients.size }));
-            ws.on('message', (message: string) => {
-                for (const client of clients) client.send(message);
-            });
-            ws.on('drain', () => {});
-            ws.on('close', () => {
-                clients.delete(ws);
-            });
-        },
-    );
-
-    app.get('/*', (request: Request, response: Response) => {
-        if (response.completed) return;
-        const file = resolveStaticFile(root, request.path);
-        response.sendFile(file ?? indexHtml);
-    });
-
-    await app.listen(port, host);
-
-    return {
-        port,
-        host,
-        wsPath,
-        broadcast: (message: string): void => {
-            for (const client of clients) client.send(message);
-        },
-        clientCount: (): number => clients.size,
-        close: async (): Promise<void> => {
-            await app.shutdown();
-        },
-    };
-}
+/**
+ * toiljs backend, the self-host / dev server, built on @btc-vision/hyper-express (uWebSockets.js)
+ * for very high throughput. It serves the built client (static assets + SPA fallback) and exposes
+ * a WebSocket channel for realtime / live updates.
+ *
+ * This is the Node "server" that hosts the app on a local machine; it is distinct from the
+ * toilscript WASM runtime in `server/runtime` (the `toiljs/server/runtime` library export).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+    Server,
+    type MiddlewareNext,
+    type Request,
+    type Response,
+    type Websocket,
+} from '@btc-vision/hyper-express';
+
+const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
+const MAX_BODY_BUFFER = 1024 * 32;
+const HTTP_IDLE_TIMEOUT = 60;
+const HTTP_RESPONSE_TIMEOUT = 120;
+
+const WS_MAX_PAYLOAD_LENGTH = 1024 * 1024;
+const WS_IDLE_TIMEOUT = 120;
+const WS_MAX_BACKPRESSURE = 1024 * 1024 * 2;
+
+const CORS_METHODS = 'GET, POST, OPTIONS, PUT, PATCH, DELETE';
+const CORS_HEADERS = 'X-Requested-With, content-type';
+
+/** Options for {@link startBackend}. */
+export interface BackendOptions {
+    /** Directory to serve (the built client `outDir`, e.g. `dist`). */
+    readonly root: string;
+    /** Listening port. Default `3000`. */
+    readonly port?: number;
+    /**
+     * Bind host. Default `127.0.0.1` (loopback only). Pass `0.0.0.0` (or a specific interface) to
+     * expose the server on the network; do so deliberately, since the WebSocket channel relays
+     * messages between all connected clients.
+     */
+    readonly host?: string;
+    /**
+     * Extra origins allowed to open the WebSocket channel, in addition to the server's own origin.
+     * Cross-origin WebSocket handshakes from other origins are rejected (prevents cross-site
+     * WebSocket hijacking). Example: `['https://app.example.com']`.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /** WebSocket channel path. Default `/_toil`. */
+    readonly wsPath?: string;
+    /** Send permissive CORS headers + handle preflight. Default `true`. */
+    readonly cors?: boolean;
+    /** Max request body length in bytes. Default 8 MB. */
+    readonly maxBodyLength?: number;
+}
+
+/** A running backend instance. */
+export interface RunningBackend {
+    readonly port: number;
+    readonly host: string;
+    readonly wsPath: string;
+    /** Sends a message to every connected WebSocket client. */
+    broadcast(message: string): void;
+    /** Number of currently-connected WebSocket clients. */
+    clientCount(): number;
+    /** Gracefully shuts the server down. */
+    close(): Promise<void>;
+}
+
+/**
+ * Whether a WebSocket upgrade from `origin` may connect. A missing `Origin` (non-browser clients
+ * like curl or server-to-server) is allowed; a browser `Origin` must match the host the server was
+ * reached at (same-origin) or be in the explicit allowlist. This blocks cross-site WebSocket
+ * hijacking, where a page the victim visits opens a socket to this server from their browser.
+ */
+function isWsOriginAllowed(
+    origin: string | undefined,
+    hostHeader: string | undefined,
+    allowed: readonly string[] | undefined,
+): boolean {
+    if (!origin) return true;
+    if (allowed?.includes(origin)) return true;
+    try {
+        return new URL(origin).host === hostHeader;
+    } catch {
+        return false;
+    }
+}
+
+/** Resolves a request path to a file inside `root`, guarding against path traversal. */
+function resolveStaticFile(root: string, requestPath: string): string | null {
+    const decoded = decodeURIComponent(requestPath);
+    const resolved = path.join(root, decoded);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) return null;
+    if (decoded === '/' || decoded === '') return null;
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved;
+    return null;
+}
+
+/**
+ * Starts the hyper-express server serving `root` with an SPA fallback to `index.html`,
+ * plus a WebSocket channel at `wsPath`. Resolves once the server is listening.
+ */
+export async function startBackend(options: BackendOptions): Promise<RunningBackend> {
+    const port = options.port ?? 3000;
+    const host = options.host ?? '127.0.0.1';
+    const wsPath = options.wsPath ?? '/_toil';
+    const cors = options.cors ?? true;
+    const root = path.resolve(options.root);
+    const indexHtml = path.join(root, 'index.html');
+
+    const app = new Server({
+        max_body_length: options.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH,
+        max_body_buffer: MAX_BODY_BUFFER,
+        fast_abort: true,
+        idle_timeout: HTTP_IDLE_TIMEOUT,
+        response_timeout: HTTP_RESPONSE_TIMEOUT,
+    });
+
+    const clients = new Set<Websocket>();
+
+    app.set_error_handler((_request: Request, response: Response, _error: Error) => {
+        if (response.completed) return;
+        response.atomic(() => {
+            response.status(500).json({ error: 'Internal server error.' });
+        });
+    });
+
+    if (cors) {
+        app.use((request: Request, response: Response, next: MiddlewareNext) => {
+            if (request.method !== 'OPTIONS') {
+                response.setHeader('Access-Control-Allow-Origin', '*');
+                response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
+                response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
+            }
+            response.removeHeader('uWebSockets');
+            next();
+        });
+        app.options('/*', (_request: Request, response: Response) => {
+            response.setHeader('Access-Control-Allow-Origin', '*');
+            response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
+            response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
+            response.setHeader('Access-Control-Max-Age', '86400');
+            response.status(204).send();
+        });
+    }
+
+    app.ws(
+        wsPath,
+        {
+            message_type: 'String',
+            max_payload_length: WS_MAX_PAYLOAD_LENGTH,
+            idle_timeout: WS_IDLE_TIMEOUT,
+            max_backpressure: WS_MAX_BACKPRESSURE,
+        },
+        (ws) => {
+            clients.add(ws);
+            ws.send(JSON.stringify({ type: 'connected', clients: clients.size }));
+            ws.on('message', (message: string) => {
+                for (const client of clients) client.send(message);
+            });
+            ws.on('drain', () => {});
+            ws.on('close', () => {
+                clients.delete(ws);
+            });
+        },
+    );
+
+    // Gate the WebSocket upgrade on the request Origin, so a cross-origin page in a victim's browser
+    // cannot hijack the channel (CSWSH). Registered AFTER `app.ws` so it overrides that route's
+    // default upgrade handler (hyper-express links it to the companion ws route). Same-origin and
+    // non-browser clients pass; others get 403.
+    app.upgrade(wsPath, (request: Request, response: Response) => {
+        if (!isWsOriginAllowed(request.headers.origin, request.headers.host, options.allowedOrigins)) {
+            response.status(403).send();
+            return;
+        }
+        response.upgrade({});
+    });
+
+    app.get('/*', (request: Request, response: Response) => {
+        if (response.completed) return;
+        const file = resolveStaticFile(root, request.path);
+        response.sendFile(file ?? indexHtml);
+    });
+
+    await app.listen(port, host);
+
+    return {
+        port,
+        host,
+        wsPath,
+        broadcast: (message: string): void => {
+            for (const client of clients) client.send(message);
+        },
+        clientCount: (): number => clients.size,
+        close: async (): Promise<void> => {
+            await app.shutdown();
+        },
+    };
+}

package/src/cli/create.ts

@@ -114,7 +114,7 @@ function scaffold(
         '@types/react-dom': '^19.2.3',
         eslint: '^10.2.0',
         prettier: '^3.8.1',
-        toilscript: '^0.1.2',
+        toilscript: '^0.1.11',
         typescript: '^6.0.3',
     };
     for (const dep of requiredPackages(features).sort()) {
@@ -126,9 +126,9 @@ function scaffold(
         type: 'module',
         scripts: {
             dev: 'toiljs dev',
-            build: 'toiljs build && toilscript --target release',
+            build: 'toilscript --target release --rpcModule shared/server.ts && toiljs build',
             'build:client': 'toiljs build',
-            'build:server': 'toilscript --target release',
+            'build:server': 'toilscript --target release --rpcModule shared/server.ts',
             lint: 'eslint client',
             typecheck: 'tsc --noEmit',
             format: 'prettier --write "client/**/*.{ts,tsx,css,scss,less}" "client/public/**/*.html"',
@@ -152,10 +152,20 @@ function scaffold(
             '    },\n' +
             '});\n',
         'tsconfig.json':
-            '{\n    "extends": "toiljs/tsconfig",\n    "include": ["client", "toil-env.d.ts", "toil-routes.d.ts"]\n}\n',
+            '{\n' +
+            '    "extends": "toiljs/tsconfig",\n' +
+            '    "compilerOptions": {\n' +
+            '        "paths": { "shared/*": ["./shared/*"] }\n' +
+            '    },\n' +
+            '    "include": ["client", "shared", "toil-env.d.ts", "toil-routes.d.ts"]\n' +
+            '}\n',
         'eslint.config.js': "import toiljs from 'toiljs/eslint';\n\nexport default toiljs;\n",
         '.prettierrc': '"toiljs/prettier"\n',
-        '.gitignore': 'node_modules\nbuild\n.toil\ntoil-env.d.ts\ntoil-routes.d.ts\n',
+        // Generated files don't need formatting. (toilscript server decorators like @main /
+        // @remote-on-functions are handled by the toiljs/prettier-plugin, so server/ is not ignored.)
+        '.prettierignore':
+            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\n',
+        '.gitignore': 'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\n',
         // Use the project's pinned TypeScript (node_modules) instead of VS Code's bundled version.
         '.vscode/settings.json':
             JSON.stringify({ 'typescript.tsdk': 'node_modules/typescript/lib' }, null, 4) + '\n',

package/src/cli/diagnostics.ts

@@ -400,6 +400,87 @@ export function checkWasmBuilt(exists: boolean): Check {
           };
 }
 
+// --- Typed RPC (@data / @remote / @service) -------------------------------------------------------
+
+/** Minimum toilscript: the @rest/@route HTTP layer + RPC codegen + hardened decoders + editor decls. */
+export const RPC_TOILSCRIPT_MIN = '0.1.11';
+
+/** Whether each piece of the typed-RPC wiring is in place (computed in `doctor.ts`). */
+export interface RpcFacts {
+    /** `build:server` runs toilscript with `--rpcModule`. */
+    readonly buildServerWired: boolean;
+    /** tsconfig includes `shared` and has the `shared/*` path alias. */
+    readonly tsconfigWired: boolean;
+    /** `.gitignore` ignores the generated `shared/server.ts`. */
+    readonly gitignoreWired: boolean;
+    /** The declared toilscript range is at least {@link RPC_TOILSCRIPT_MIN}. */
+    readonly toilscriptOk: boolean;
+}
+
+/**
+ * One check for the typed-RPC setup (`@data`/`@remote` -> generated `Server`). Warns (does not fail)
+ * when an existing project predates the feature, and points at the one-command upgrade.
+ */
+export function checkRpcWiring(f: RpcFacts): Check {
+    const missing: string[] = [];
+    if (!f.toilscriptOk) missing.push(`toilscript >=${RPC_TOILSCRIPT_MIN}`);
+    if (!f.buildServerWired) missing.push('build:server --rpcModule');
+    if (!f.tsconfigWired) missing.push('tsconfig shared/ + alias');
+    if (!f.gitignoreWired) missing.push('.gitignore shared/server.ts');
+    if (missing.length === 0) {
+        return { id: 'rpc-wiring', label: 'typed RPC wiring', status: 'pass' };
+    }
+    return {
+        id: 'rpc-wiring',
+        label: 'typed RPC wiring',
+        status: 'warn',
+        detail: `missing: ${missing.join(', ')}`,
+        fix: 'Run `toiljs doctor --fix` to wire @data/@remote RPC (build:server, tsconfig, .gitignore, toilscript).',
+    };
+}
+
+/**
+ * Whether the project's prettier setup pulls in the toilscript plugin (`toiljs/prettier-plugin`,
+ * or the `toiljs/prettier` shareable that bundles it). Without it, prettier throws on the server's
+ * native function decorators (`@main`, `@remote function ...`).
+ */
+export function checkPrettierPlugin(present: boolean): Check {
+    return present
+        ? { id: 'prettier-plugin', label: 'prettier toilscript plugin', status: 'pass' }
+        : {
+              id: 'prettier-plugin',
+              label: 'prettier toilscript plugin',
+              status: 'warn',
+              detail: 'prettier will fail on @main / @remote-on-function in server code',
+              fix: 'Run `toiljs doctor --fix` to add toiljs/prettier-plugin to your prettier config.',
+          };
+}
+
+export interface RestFacts {
+    /** The server declares at least one `@rest` controller. */
+    readonly hasControllers: boolean;
+    /** Some server file dispatches them: a `Rest.dispatch(` call, or a `RestHandler`. */
+    readonly dispatched: boolean;
+}
+
+/**
+ * Guards the easy-to-miss wiring step for the HTTP layer: a `@rest` controller self-registers,
+ * but its routes are only served if a handler calls `Rest.dispatch(req)` (or the project uses
+ * `RestHandler`). Without that, the routes silently 404 - a confusing footgun, so we warn.
+ */
+export function checkRestDispatch(f: RestFacts): Check {
+    if (!f.hasControllers || f.dispatched) {
+        return { id: 'rest-dispatch', label: 'REST dispatch wiring', status: 'pass' };
+    }
+    return {
+        id: 'rest-dispatch',
+        label: 'REST dispatch wiring',
+        status: 'warn',
+        detail: '@rest controllers found, but nothing calls Rest.dispatch(req) - their routes will not be served',
+        fix: 'In your handler add `const hit = Rest.dispatch(req); if (hit != null) return hit;`, or set `Server.handler = () => new RestHandler()`.',
+    };
+}
+
 // --- Summary --------------------------------------------------------------------------------------
 
 export function summarize(groups: readonly CheckGroup[]): DoctorSummary {