toiljs 0.0.26 → 0.0.28

package/src/devserver/envelope.ts

@@ -0,0 +1,154 @@
+/**
+ * Node-side wire envelope codec for the WASM dev server, byte-for-byte compatible with
+ * `server/runtime/envelope.ts` (the ToilScript guest decoder/encoder) and
+ * `toil-backend/src/http/envelope.rs` (the production edge).
+ *
+ * Layout (little-endian, no padding):
+ *
+ *   request:
+ *     u8   method     (0=GET, 1=POST, 2=PUT, 3=DELETE, 4=PATCH, 5=HEAD, 6=OPTIONS)
+ *     u16  path_len
+ *     [u8] path
+ *     u16  n_headers
+ *     for each header: u16 name_len, u16 val_len, [u8] name, [u8] val
+ *     u32  body_len
+ *     [u8] body
+ *
+ *   response: same shape but the first u8+u16 (method + path_len + path)
+ *     is replaced by `u16 status`.
+ *
+ * Header names/values and the path must each fit in u16, the body in u32; the
+ * encoder throws instead of silently truncating (mirrors `EncodeError` on the
+ * edge). The decoder bounds-checks every length field so a malformed guest
+ * response can never read past the envelope.
+ */
+
+/** Method discriminant matching the on-wire envelope byte (part of the wasm ABI; do not reorder). */
+export const METHOD_CODES: Readonly<Record<string, number>> = {
+    GET: 0,
+    POST: 1,
+    PUT: 2,
+    DELETE: 3,
+    PATCH: 4,
+    HEAD: 5,
+    OPTIONS: 6,
+};
+
+/** A request to serialize for the guest. `path` includes the query string. */
+export interface EnvelopeRequest {
+    readonly method: string;
+    readonly path: string;
+    /** Full request header list, passed through to the guest. */
+    readonly headers: readonly (readonly [string, string])[];
+    readonly body: Uint8Array;
+}
+
+/** The decoded guest response envelope. */
+export interface EnvelopeResponse {
+    readonly status: number;
+    readonly headers: readonly (readonly [string, string])[];
+    readonly body: Uint8Array;
+}
+
+const U16_MAX = 0xffff;
+const U32_MAX = 0xffffffff;
+
+/**
+ * Encode `req` into a fresh buffer. Throws on an unsupported method or a field
+ * that does not fit its length prefix; callers turn that into a clean 4xx (or
+ * route the request past the guest) instead of handing the guest garbage.
+ */
+export function encodeRequestEnvelope(req: EnvelopeRequest): Buffer {
+    const method = METHOD_CODES[req.method.toUpperCase()];
+    if (method === undefined) throw new Error(`unsupported method: ${req.method}`);
+
+    const path = Buffer.from(req.path, 'utf8');
+    if (path.length > U16_MAX) throw new Error(`path too long: ${String(path.length)} bytes`);
+    if (req.headers.length > U16_MAX)
+        throw new Error(`too many headers: ${String(req.headers.length)}`);
+    if (req.body.length > U32_MAX) throw new Error(`body too long: ${String(req.body.length)} bytes`);
+
+    const headers: { name: Buffer; value: Buffer }[] = [];
+    let headersSize = 0;
+    for (const [name, value] of req.headers) {
+        const n = Buffer.from(name, 'utf8');
+        const v = Buffer.from(value, 'utf8');
+        if (n.length > U16_MAX || v.length > U16_MAX)
+            throw new Error(`header too long: ${name}`);
+        headers.push({ name: n, value: v });
+        headersSize += 4 + n.length + v.length;
+    }
+
+    const total = 1 + 2 + path.length + 2 + headersSize + 4 + req.body.length;
+    const out = Buffer.allocUnsafe(total);
+    let cur = 0;
+
+    out.writeUInt8(method, cur);
+    cur += 1;
+    out.writeUInt16LE(path.length, cur);
+    cur += 2;
+    cur += path.copy(out, cur);
+
+    out.writeUInt16LE(headers.length, cur);
+    cur += 2;
+    for (const h of headers) {
+        out.writeUInt16LE(h.name.length, cur);
+        cur += 2;
+        out.writeUInt16LE(h.value.length, cur);
+        cur += 2;
+        cur += h.name.copy(out, cur);
+        cur += h.value.copy(out, cur);
+    }
+
+    out.writeUInt32LE(req.body.length, cur);
+    cur += 4;
+    cur += Buffer.from(req.body.buffer, req.body.byteOffset, req.body.length).copy(out, cur);
+
+    return out;
+}
+
+/**
+ * Decode the response envelope the guest wrote at `bytes`. Throws on
+ * truncation or a length field that overruns the envelope (a guest bug);
+ * the dispatcher converts that into a 500.
+ */
+export function decodeResponseEnvelope(bytes: Uint8Array): EnvelopeResponse {
+    const view = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let cur = 0;
+
+    const take = (n: number): number => {
+        if (cur + n > view.length)
+            throw new Error(`response envelope truncated at byte ${String(cur)}`);
+        const at = cur;
+        cur += n;
+        return at;
+    };
+
+    const status = view.readUInt16LE(take(2));
+    if (status === 0) throw new Error('response envelope has status 0');
+
+    const nHeaders = view.readUInt16LE(take(2));
+    const headers: (readonly [string, string])[] = [];
+    for (let i = 0; i < nHeaders; i++) {
+        const nameLen = view.readUInt16LE(take(2));
+        const valLen = view.readUInt16LE(take(2));
+        const name = view.toString('utf8', take(nameLen), cur);
+        const value = view.toString('utf8', take(valLen), cur);
+        headers.push([name, value]);
+    }
+
+    const bodyLen = view.readUInt32LE(take(4));
+    const bodyStart = take(bodyLen);
+    // Copy out of the guest's linear memory so the response outlives the instance.
+    const body = Uint8Array.prototype.slice.call(view, bodyStart, cur);
+
+    return { status, headers, body };
+}
+
+/** Unpack the i64 `handle()` returns: high 32 bits = response offset, low 32 bits = byte length. */
+export function unpackHandleResult(packed: bigint): { ptr: number; len: number } {
+    return {
+        ptr: Number((packed >> 32n) & 0xffffffffn),
+        len: Number(packed & 0xffffffffn),
+    };
+}

package/src/devserver/host.ts

@@ -0,0 +1,145 @@
+/**
+ * The host import surface the dev server exposes to the guest, mirroring the
+ * functions the production edge (`toil-backend/src/wasm/host/imports.rs`)
+ * registers under the `env` namespace:
+ *
+ *   - `abort(msg, file, line, col)`   ToilScript panic hook; raises a trap
+ *   - `set_status(code)`              imperative status (clamped to [100, 599])
+ *   - `set_header(nPtr, nLen, vPtr, vLen)`  imperative response header
+ *   - `respond_file(pathPtr, pathLen)`      stream a file as the response body
+ *   - `thread_spawn(startArg)`        fail-closed stub, always -1 (no threading in dev)
+ *
+ * The ToilScript runtime returns status + headers in-band via the response
+ * envelope, so a toiljs guest today only imports `abort`; the imperative
+ * functions are provided for parity with the edge and apply on top of the
+ * envelope (a `set_status` wins over the envelope status, `set_header` values
+ * are appended). Extra keys in the import object are ignored by
+ * `WebAssembly.Instance`, so offering the full surface costs nothing.
+ */
+
+import { buildCryptoImports, freshCryptoState, type CryptoState } from './crypto.js';
+
+/** Limits identical to the edge's `set_header` / `respond_file` bounds. */
+const MAX_TOTAL_HEADERS_BYTES = 64 * 1024;
+const MAX_HEADER_NAME_LEN = 256;
+const MAX_HEADER_VALUE_LEN = 8192;
+const MAX_PATH_LEN = 4096;
+
+/** RFC 9110 tchar token, the only bytes allowed in a header name. */
+const TCHAR = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+/** A guest `abort()` (ToilScript assert/bounds-check failure), surfaced as a trap. */
+export class WasmAbortError extends Error {
+    constructor(message: string, fileName: string, line: number, column: number) {
+        super(
+            `wasm aborted: ${message || '<no message>'}` +
+                (fileName ? ` at ${fileName}:${String(line)}:${String(column)}` : ''),
+        );
+        this.name = 'WasmAbortError';
+    }
+}
+
+/** Per-dispatch state the imperative host imports write into. */
+export interface DispatchState {
+    /** Status from `set_status`, or `null` when the guest never called it. */
+    status: number | null;
+    /** Headers accumulated by `set_header`, in call order. */
+    headers: [string, string][];
+    /** Total header bytes so far (cap: {@link MAX_TOTAL_HEADERS_BYTES}). */
+    headerBytes: number;
+    /** File path from `respond_file`, or `null`; when set, the envelope body is ignored. */
+    sendfile: string | null;
+    /** Per-dispatch Web Crypto keystore + result scratch (mirrors the edge). */
+    crypto: CryptoState;
+}
+
+/** A fresh, zeroed per-dispatch state (the edge resets the same way before each request). */
+export function freshDispatchState(): DispatchState {
+    return { status: null, headers: [], headerBytes: 0, sendfile: null, crypto: freshCryptoState() };
+}
+
+/**
+ * Late-bound memory holder: the import object must exist before the instance
+ * (and therefore its exported memory) does, so the host functions read through
+ * this indirection. The module loader fills it in right after instantiation.
+ */
+export interface MemoryRef {
+    memory: WebAssembly.Memory | null;
+}
+
+function mem(ref: MemoryRef): Buffer {
+    if (!ref.memory) throw new Error('host import called before memory was bound');
+    return Buffer.from(ref.memory.buffer);
+}
+
+/** Bounds-checked byte read out of guest linear memory. */
+function readBytes(ref: MemoryRef, ptr: number, len: number): Buffer {
+    const m = mem(ref);
+    if (ptr < 0 || len < 0 || ptr + len > m.length)
+        throw new Error(`host import read out of bounds: ptr=${String(ptr)} len=${String(len)}`);
+    return m.subarray(ptr, ptr + len);
+}
+
+/**
+ * Read a ToilScript string (UTF-16LE payload, byte length in the u32 at
+ * `ptr - 4`). Used by `abort`, whose pointers reference string objects rather
+ * than raw byte ranges. A null pointer yields ''.
+ */
+function readGuestString(ref: MemoryRef, ptr: number): string {
+    if (ptr === 0) return '';
+    const m = mem(ref);
+    if (ptr < 4 || ptr > m.length) return '';
+    const byteLen = m.readUInt32LE(ptr - 4);
+    if (ptr + byteLen > m.length) return '';
+    return m.toString('utf16le', ptr, ptr + byteLen);
+}
+
+/**
+ * Build the `env` import object for one instance. `state` collects what the
+ * imperative imports produce during a dispatch; bind a fresh state per request.
+ */
+export function buildHostImports(ref: MemoryRef, state: DispatchState): WebAssembly.Imports {
+    return {
+        env: {
+            abort: (msgPtr: number, filePtr: number, line: number, col: number): void => {
+                throw new WasmAbortError(
+                    readGuestString(ref, msgPtr),
+                    readGuestString(ref, filePtr),
+                    line,
+                    col,
+                );
+            },
+
+            set_status: (code: number): void => {
+                state.status = code >= 100 && code <= 599 ? code : 500;
+            },
+
+            set_header: (namePtr: number, nameLen: number, valPtr: number, valLen: number): void => {
+                if (nameLen > MAX_HEADER_NAME_LEN)
+                    throw new Error(`header name too long: ${String(nameLen)} bytes`);
+                if (valLen > MAX_HEADER_VALUE_LEN)
+                    throw new Error(`header value too long: ${String(valLen)} bytes`);
+                if (state.headerBytes + nameLen + valLen > MAX_TOTAL_HEADERS_BYTES)
+                    throw new Error('total response headers exceed 64 KiB');
+                const name = readBytes(ref, namePtr, nameLen).toString('utf8');
+                const value = readBytes(ref, valPtr, valLen).toString('utf8');
+                if (!TCHAR.test(name)) throw new Error(`invalid header name: ${name}`);
+                if (/[\r\n]/.test(value)) throw new Error('header value contains CR/LF');
+                state.headers.push([name, value]);
+                state.headerBytes += nameLen + valLen;
+            },
+
+            respond_file: (pathPtr: number, pathLen: number): void => {
+                if (pathLen > MAX_PATH_LEN)
+                    throw new Error(`respond_file path too long: ${String(pathLen)} bytes`);
+                state.sendfile = readBytes(ref, pathPtr, pathLen).toString('utf8');
+            },
+
+            thread_spawn: (_startArg: number): number => -1,
+
+            // Web Crypto host functions (`env.crypto.*`), backed by Node's
+            // `crypto`. The dev server skips metering, so these charge nothing.
+            ...buildCryptoImports(ref, state.crypto),
+        },
+    };
+}

package/src/devserver/index.ts

@@ -0,0 +1,242 @@
+/**
+ * The toiljs WASM dev server: a uWebSockets.js front (via @btc-vision/hyper-express,
+ * the same stack as `toiljs/backend`) that dispatches HTTP requests into the
+ * ToilScript-compiled server wasm exactly like the production edge does, and
+ * proxies everything the server does not claim to an internal Vite dev server,
+ * so dev keeps 100% of Vite's behavior (HMR, transforms, toolbar endpoints,
+ * public assets, SPA fallback).
+ *
+ * Request flow:
+ *
+ *   browser ── uWS :port ──► wasm `handle()` (fresh instance, envelope ABI)
+ *                 │                │
+ *                 │                └─ "unhandled" marker (no route matched)
+ *                 ▼                                   │
+ *           Vite dev server (loopback) ◄──────────────┘
+ *
+ * Dev intentionally skips the edge's metering, gas, pooling and snapshot-reset
+ * machinery; the ABI (envelope layout, `handle(ofs, len) -> i64`, host import
+ * surface, trap isolation) is identical so a server that runs here runs there.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Server, type Request, type Response } from '@btc-vision/hyper-express';
+import pc from 'picocolors';
+
+import { METHOD_CODES, type EnvelopeRequest } from './envelope.js';
+import { WasmServerModule } from './module.js';
+import { proxyToVite, wireWebsocketProxy, type ViteTarget } from './proxy.js';
+
+export { METHOD_CODES, encodeRequestEnvelope, decodeResponseEnvelope, unpackHandleResult } from './envelope.js';
+export type { EnvelopeRequest, EnvelopeResponse } from './envelope.js';
+export { WasmServerModule, WasmAbortError, UNHANDLED_HEADER } from './module.js';
+export type { WasmDispatchResult } from './module.js';
+export { buildHostImports, freshDispatchState } from './host.js';
+export type { DispatchState, MemoryRef } from './host.js';
+export type { ViteTarget } from './proxy.js';
+
+const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
+
+/**
+ * Paths that are Vite's own by construction; skipping the wasm round-trip for
+ * them keeps the hot path of module serving untouched. Everything else is
+ * offered to the server first (it answers or yields via the unhandled marker).
+ */
+const VITE_PREFIXES = ['/@', '/node_modules/', '/__toil/'];
+
+/** Minimal type map for `respond_file` bodies when the guest set no content-type. */
+const MIME: Readonly<Record<string, string>> = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.wasm': 'application/wasm',
+    '.woff2': 'font/woff2',
+};
+
+/** Options for {@link startDevServer}. */
+export interface DevServerOptions {
+    /** Project root; `respond_file` paths resolve against it (and may not escape it). */
+    readonly root: string;
+    /** Public listening port (the one the browser opens). */
+    readonly port: number;
+    /** Bind host. Default `127.0.0.1`. */
+    readonly host?: string;
+    /** Absolute path to the ToilScript server wasm (toilconfig `targets.release.outFile`). */
+    readonly wasmFile: string;
+    /** The internal Vite dev server to proxy unclaimed traffic to. */
+    readonly vite: ViteTarget;
+    /** Max request body bytes. Default 8 MB. */
+    readonly maxBodyLength?: number;
+}
+
+/** A running dev server. */
+export interface RunningDevServer {
+    readonly port: number;
+    readonly host: string;
+    /** Gracefully shuts the front server down (the Vite server is owned by the caller). */
+    close(): Promise<void>;
+}
+
+/** True for requests that belong to Vite by construction (never offered to the wasm). */
+function isViteInternal(url: string): boolean {
+    return VITE_PREFIXES.some((p) => url.startsWith(p));
+}
+
+/** Resolves a guest `respond_file` path inside `root`, refusing traversal outside it. */
+function resolveSendfile(root: string, file: string): string | null {
+    const resolved = path.resolve(root, file);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) return null;
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) return null;
+    return resolved;
+}
+
+/** Builds the envelope request for one incoming HTTP request. */
+async function toEnvelopeRequest(request: Request): Promise<EnvelopeRequest> {
+    const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+    const body = hasBody ? new Uint8Array(await request.buffer()) : new Uint8Array(0);
+    return {
+        method: request.method,
+        // `url` keeps the query string; the guest's RouteContext parses it off the path.
+        path: request.url,
+        headers: Object.entries(request.headers),
+        body,
+    };
+}
+
+/** Sends a shaped wasm response, mirroring the edge's response defaults. */
+function sendWasmResponse(
+    response: Response,
+    root: string,
+    result: {
+        status: number;
+        headers: readonly (readonly [string, string])[];
+        body: Uint8Array;
+        sendfile: string | null;
+    },
+): void {
+    response.status(result.status);
+    let hasContentType = false;
+    for (const [name, value] of result.headers) {
+        if (name.toLowerCase() === 'content-type') hasContentType = true;
+        response.header(name, value);
+    }
+    response.header('server', 'toil-dev');
+
+    if (result.sendfile !== null) {
+        const file = resolveSendfile(root, result.sendfile);
+        if (file === null) {
+            response.status(404).send('not found\n');
+            return;
+        }
+        if (!hasContentType) {
+            // The edge defaults file bodies to application/octet-stream; in dev we
+            // guess from the extension so a guest-served asset renders in the browser.
+            response.header('content-type', MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream');
+        }
+        response.sendFile(file);
+        return;
+    }
+
+    if (!hasContentType) response.header('content-type', 'text/plain; charset=utf-8');
+    response.send(Buffer.from(result.body.buffer, result.body.byteOffset, result.body.length));
+}
+
+/**
+ * Starts the front server. The caller owns the Vite dev server (start it on a
+ * loopback port first) and the toilscript rebuild watcher; this watches only
+ * the wasm artifact and hot-swaps the compiled module when it changes.
+ */
+export async function startDevServer(options: DevServerOptions): Promise<RunningDevServer> {
+    const host = options.host ?? '127.0.0.1';
+    const root = path.resolve(options.root);
+    const module = new WasmServerModule(options.wasmFile);
+
+    let warnedMissing = false;
+    let loadedOnce = false;
+    const refresh = (): void => {
+        try {
+            if (module.refresh() && loadedOnce) {
+                process.stdout.write(pc.green('  ✓ ') + pc.dim('server module reloaded') + '\n');
+            }
+            loadedOnce ||= module.available;
+        } catch (e) {
+            process.stdout.write(pc.red(`  ✗ server wasm failed to load: ${String(e)}`) + '\n');
+        }
+        if (!module.available && !warnedMissing) {
+            warnedMissing = true;
+            process.stdout.write(
+                pc.yellow('  ! ') +
+                    pc.dim(`server wasm not found at ${options.wasmFile}; serving client only`) +
+                    '\n',
+            );
+        }
+    };
+    refresh();
+
+    const app = new Server({
+        max_body_length: options.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH,
+        max_body_buffer: 1024 * 32,
+        fast_abort: true,
+    });
+
+    app.set_error_handler((_request: Request, response: Response, error: Error) => {
+        if (response.completed) return;
+        response.atomic(() => {
+            response.status(500).send(`internal error: ${error.message}\n`);
+        });
+    });
+
+    wireWebsocketProxy(app, options.vite);
+
+    app.any('/*', async (request: Request, response: Response) => {
+        response.removeHeader('uWebSockets');
+
+        const dispatchable =
+            !isViteInternal(request.url) && METHOD_CODES[request.method] !== undefined;
+        if (dispatchable) refresh();
+
+        if (dispatchable && module.available) {
+            const envelopeReq = await toEnvelopeRequest(request);
+            try {
+                const result = module.dispatch(envelopeReq);
+                if (!result.unhandled) {
+                    sendWasmResponse(response, root, result);
+                    return;
+                }
+            } catch (e) {
+                // A trap (ToilScript abort, OOB, malformed envelope) is isolated to
+                // this request, exactly like the edge poisoning one instance.
+                process.stdout.write(
+                    pc.red(`  ✗ ${request.method} ${request.path} server error: ${String(e)}`) + '\n',
+                );
+                response.status(500).send('internal error\n');
+                return;
+            }
+        }
+
+        await proxyToVite(request, response, options.vite);
+    });
+
+    await app.listen(options.port, host);
+
+    return {
+        port: options.port,
+        host,
+        close: async (): Promise<void> => {
+            await app.shutdown();
+        },
+    };
+}