toiljs 0.0.26 → 0.0.27

package/src/devserver/module.ts

@@ -0,0 +1,167 @@
+/**
+ * Loads the ToilScript-compiled server wasm and dispatches request envelopes
+ * into it, the dev-mode equivalent of the edge's fresh dispatcher
+ * (`toil-backend/src/wasm/dispatcher/fresh.rs`): one fresh instance per
+ * request, so guest state can never leak between requests and a trapped
+ * instance is simply dropped. Instantiation of a compiled module is
+ * microseconds, irrelevant next to dev-mode I/O.
+ *
+ * The compiled module is cached and transparently recompiled when the wasm
+ * file's mtime changes (the `toiljs dev` watcher rebuilds it via toilscript on
+ * server-source edits), which is the server-side hot reload.
+ */
+
+import fs from 'node:fs';
+
+import {
+    decodeResponseEnvelope,
+    encodeRequestEnvelope,
+    unpackHandleResult,
+    type EnvelopeRequest,
+} from './envelope.js';
+import { buildHostImports, freshDispatchState, type MemoryRef } from './host.js';
+
+export { WasmAbortError } from './host.js';
+
+/**
+ * Marker header the server runtime puts on its fallback 404 (no `@rest` route
+ * matched and no custom handler produced a response). The dev server strips it
+ * and falls through to Vite; a deliberate `Response.notFound()` does not carry
+ * it and is sent to the client as-is. Mirrors `TOIL_UNHANDLED_HEADER` in
+ * `server/runtime/response.ts`.
+ */
+export const UNHANDLED_HEADER = 'x-toil-unhandled';
+
+const WASM_PAGE = 65536;
+
+/** The shaped outcome of one guest dispatch. */
+export interface WasmDispatchResult {
+    readonly status: number;
+    readonly headers: readonly (readonly [string, string])[];
+    readonly body: Uint8Array;
+    /** Path from a guest `respond_file` call; when set it replaces `body`. */
+    readonly sendfile: string | null;
+    /** True when the guest reported "no route matched" (the {@link UNHANDLED_HEADER} marker). */
+    readonly unhandled: boolean;
+}
+
+interface HandleExports {
+    readonly memory: WebAssembly.Memory;
+    readonly handle: (reqOfs: number, reqLen: number) => bigint;
+}
+
+/** Host functions the dev server provides under `env` (see `host.ts`). */
+const PROVIDED_IMPORTS = new Set(['abort', 'set_status', 'set_header', 'respond_file', 'thread_spawn']);
+
+export class WasmServerModule {
+    private module: WebAssembly.Module | null = null;
+    private loadedMtimeMs = -1;
+
+    constructor(private readonly wasmPath: string) {}
+
+    /** Whether a compiled module is currently available to dispatch into. */
+    get available(): boolean {
+        return this.module !== null;
+    }
+
+    /**
+     * (Re)compile when the wasm file appeared or changed since the last load.
+     * Returns `true` when a (re)compile happened, `false` when the cached
+     * module is still current or the file is missing (`available` tells the
+     * caller which).
+     */
+    refresh(): boolean {
+        let mtimeMs: number;
+        try {
+            mtimeMs = fs.statSync(this.wasmPath).mtimeMs;
+        } catch {
+            this.module = null;
+            this.loadedMtimeMs = -1;
+            return false;
+        }
+        if (this.module !== null && mtimeMs === this.loadedMtimeMs) return false;
+
+        const bytes = fs.readFileSync(this.wasmPath);
+        const module = new WebAssembly.Module(bytes);
+        this.assertImportSurface(module);
+        this.assertExportSurface(module);
+        this.module = module;
+        this.loadedMtimeMs = mtimeMs;
+        return true;
+    }
+
+    /**
+     * Run one request through a fresh guest instance. Throws on a guest trap
+     * (including ToilScript `abort`), a malformed response envelope, or a
+     * missing module; the caller shapes those into a 500.
+     */
+    dispatch(req: EnvelopeRequest): WasmDispatchResult {
+        if (this.module === null) throw new Error(`server wasm not loaded (${this.wasmPath})`);
+
+        const envelope = encodeRequestEnvelope(req);
+
+        const ref: MemoryRef = { memory: null };
+        const state = freshDispatchState();
+        const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
+        const exports = instance.exports as unknown as HandleExports;
+        ref.memory = exports.memory;
+
+        // The edge writes the envelope at offset 0, which only holds for tiny
+        // requests: ToilScript static data starts at offset 1024, so anything
+        // larger would corrupt the guest. `handle(req_ofs, req_len)` takes the
+        // offset as a parameter, so we stay ABI-compatible and write past the
+        // current end of linear memory instead (grown to fit). The guest heap
+        // grows upward from its data section and copies the envelope into
+        // managed objects on decode, well before it could reach this region.
+        const reqOfs = exports.memory.buffer.byteLength;
+        exports.memory.grow(Math.ceil(envelope.length / WASM_PAGE) || 1);
+        Buffer.from(exports.memory.buffer).set(envelope, reqOfs);
+
+        const packed = exports.handle(reqOfs, envelope.length);
+        const { ptr, len } = unpackHandleResult(packed);
+
+        // Same bounds validation as the edge: never trust the guest's pointer.
+        const memSize = exports.memory.buffer.byteLength;
+        if (len > memSize || ptr + len > memSize)
+            throw new Error(
+                `guest returned an out-of-bounds response: ptr=${String(ptr)} len=${String(len)}`,
+            );
+
+        const resp = decodeResponseEnvelope(new Uint8Array(exports.memory.buffer, ptr, len));
+
+        // Merge the imperative host-import state on top of the envelope (a
+        // toiljs guest answers fully in-band, so this is usually a no-op).
+        const headers: (readonly [string, string])[] = [...resp.headers, ...state.headers];
+        const status = state.status ?? resp.status;
+
+        const unhandled = headers.some(([n]) => n.toLowerCase() === UNHANDLED_HEADER);
+
+        return {
+            status,
+            headers: headers.filter(([n]) => n.toLowerCase() !== UNHANDLED_HEADER),
+            body: resp.body,
+            sendfile: state.sendfile,
+            unhandled,
+        };
+    }
+
+    /** Fail instantiation up front, with names, when the guest needs imports we do not provide. */
+    private assertImportSurface(module: WebAssembly.Module): void {
+        const missing = WebAssembly.Module.imports(module)
+            .filter((i) => i.kind === 'function' && (i.module !== 'env' || !PROVIDED_IMPORTS.has(i.name)))
+            .map((i) => `${i.module}.${i.name}`);
+        if (missing.length > 0)
+            throw new Error(
+                `server wasm imports unsupported host functions: ${missing.join(', ')}`,
+            );
+    }
+
+    /** The dispatcher needs the `handle` entrypoint and the exported linear memory. */
+    private assertExportSurface(module: WebAssembly.Module): void {
+        const names = new Set(WebAssembly.Module.exports(module).map((e) => e.name));
+        for (const required of ['handle', 'memory']) {
+            if (!names.has(required))
+                throw new Error(`server wasm does not export \`${required}\``);
+        }
+    }
+}

package/src/devserver/proxy.ts

@@ -0,0 +1,155 @@
+/**
+ * Transparent proxy from the uWebSockets.js front server to the internal Vite
+ * dev server, so every Vite dev feature (module transforms, HMR websocket,
+ * `/__toil/*` toolbar endpoints, public assets, SPA fallback) keeps working
+ * unchanged behind the WASM dispatcher. HTTP goes through `fetch`, the HMR
+ * websocket through Node's built-in `WebSocket` client, both loopback-only.
+ */
+
+import { Readable } from 'node:stream';
+
+import {
+    type Request,
+    type Response,
+    type Server,
+    type Websocket,
+} from '@btc-vision/hyper-express';
+
+/** Where the internal Vite dev server listens (always loopback). */
+export interface ViteTarget {
+    readonly host: string;
+    readonly port: number;
+}
+
+/**
+ * Hop-by-hop request headers (RFC 9110 §7.6.1) plus headers `fetch` manages
+ * itself; everything else is forwarded verbatim. `accept-encoding` is dropped
+ * so Vite answers identity-encoded and bytes can be piped through untouched.
+ */
+const SKIP_REQUEST_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'content-length',
+    'accept-encoding',
+]);
+
+/** Response headers owned by the front server's own HTTP framing. */
+const SKIP_RESPONSE_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'content-length',
+    'content-encoding',
+    'transfer-encoding',
+]);
+
+/** Forwards one HTTP request to Vite and streams the answer back. */
+export async function proxyToVite(
+    request: Request,
+    response: Response,
+    target: ViteTarget,
+): Promise<void> {
+    const url = `http://${target.host}:${String(target.port)}${request.url}`;
+
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (!SKIP_REQUEST_HEADERS.has(name.toLowerCase())) headers.set(name, value);
+    }
+
+    const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+    const body = hasBody ? await request.buffer() : undefined;
+
+    const upstream = await fetch(url, {
+        method: request.method,
+        headers,
+        body: body && body.length > 0 ? new Uint8Array(body) : undefined,
+        // The browser follows redirects itself; pass them through untouched.
+        redirect: 'manual',
+    });
+
+    response.status(upstream.status);
+    upstream.headers.forEach((value, name) => {
+        if (!SKIP_RESPONSE_HEADERS.has(name)) response.header(name, value);
+    });
+
+    if (upstream.body === null) {
+        response.send();
+        return;
+    }
+    await response.stream(Readable.fromWeb(upstream.body));
+}
+
+/**
+ * A uWS message as something `WebSocket.send` accepts: text stays a string,
+ * binary is copied into a plain `ArrayBuffer`-backed view (a `Buffer` may sit
+ * on a shared pool slab, which the WebSocket types reject).
+ */
+function toUpstreamMessage(data: Buffer, binary: boolean): string | Uint8Array<ArrayBuffer> {
+    if (!binary) return data.toString('utf8');
+    const copy = new Uint8Array(data.length);
+    copy.set(data);
+    return copy;
+}
+
+/**
+ * Wires a catch-all websocket route that pipes every upgrade (Vite's HMR
+ * socket connects to the page origin at `/`, subprotocol `vite-hmr`) to the
+ * internal Vite server. Messages are queued until the upstream socket opens,
+ * closes propagate in both directions.
+ */
+export function wireWebsocketProxy(app: Server, target: ViteTarget): void {
+    app.upgrade('/*', (request: Request, response: Response) => {
+        response.upgrade({
+            url: request.url,
+            protocol: request.headers['sec-websocket-protocol'] ?? '',
+        });
+    });
+
+    app.ws(
+        '/*',
+        { message_type: 'Buffer', idle_timeout: 120, max_payload_length: 16 * 1024 * 1024 },
+        (ws: Websocket) => {
+            const { url, protocol } = ws.context as { url: string; protocol: string };
+            const upstream = new WebSocket(
+                `ws://${target.host}:${String(target.port)}${url}`,
+                protocol ? protocol.split(',').map((p) => p.trim()) : [],
+            );
+            upstream.binaryType = 'arraybuffer';
+
+            const pending: (string | Uint8Array<ArrayBuffer>)[] = [];
+            let open = false;
+
+            upstream.onopen = (): void => {
+                open = true;
+                for (const m of pending) upstream.send(m);
+                pending.length = 0;
+            };
+            upstream.onmessage = (event: MessageEvent): void => {
+                if (typeof event.data === 'string') ws.send(event.data);
+                else ws.send(Buffer.from(event.data as ArrayBuffer), true);
+            };
+            upstream.onclose = (event: CloseEvent): void => {
+                ws.close(event.code, event.reason);
+            };
+            upstream.onerror = (): void => {
+                ws.close();
+            };
+
+            ws.on('message', (message: Buffer, isBinary: boolean) => {
+                const m = toUpstreamMessage(message, isBinary);
+                if (open) upstream.send(m);
+                else pending.push(m);
+            });
+            ws.on('close', () => {
+                if (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING) {
+                    upstream.close();
+                }
+            });
+        },
+    );
+}

package/src/io/codec.ts

@@ -22,7 +22,9 @@ const utf8Decoder = new TextDecoder();
  * {@link toBytes} for an exact-length copy of what was written.
  */
 export class DataWriter {
-    private buf: Uint8Array;
+    // `ArrayBuffer`-backed (not the `ArrayBufferLike` default) so `toBytes()` yields a
+    // `Uint8Array<ArrayBuffer>`, which `fetch`/`Blob`/`Response` accept as a `BodyInit`.
+    private buf: Uint8Array<ArrayBuffer>;
     private view: DataView;
     private off = 0;
 
@@ -120,7 +122,7 @@ export class DataWriter {
     length(): number { return this.off; }
 
     /** A fresh copy of exactly the bytes written. */
-    toBytes(): Uint8Array { return this.buf.slice(0, this.off); }
+    toBytes(): Uint8Array<ArrayBuffer> { return this.buf.slice(0, this.off); }
 }
 
 /**

package/test/devserver.test.ts

@@ -0,0 +1,199 @@
+/**
+ * WASM dev server: envelope codec (byte-for-byte against the ABI shared with
+ * `server/runtime/envelope.ts` and the edge's `envelope.rs`) and real dispatch
+ * into the example project's ToilScript-compiled server wasm.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+    decodeResponseEnvelope,
+    encodeRequestEnvelope,
+    unpackHandleResult,
+    WasmServerModule,
+} from '../src/devserver/index.js';
+
+const EXAMPLE_WASM = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '../examples/basic/build/server/release.wasm',
+);
+
+describe('request envelope encoding', () => {
+    it('encodes a minimal GET / exactly like the edge', () => {
+        const out = encodeRequestEnvelope({
+            method: 'GET',
+            path: '/',
+            headers: [],
+            body: new Uint8Array(0),
+        });
+        // Mirrors envelope.rs `encode_minimal_get`.
+        expect(out.length).toBe(10);
+        expect(out[0]).toBe(0); // method GET
+        expect(out.readUInt16LE(1)).toBe(1); // path_len
+        expect(out.toString('utf8', 3, 4)).toBe('/');
+        expect(out.readUInt16LE(4)).toBe(0); // n_headers
+        expect(out.readUInt32LE(6)).toBe(0); // body_len
+    });
+
+    it('encodes a POST with a header and body exactly like the edge', () => {
+        const out = encodeRequestEnvelope({
+            method: 'POST',
+            path: '/api',
+            headers: [['host', 'example.com']],
+            body: new TextEncoder().encode('hi'),
+        });
+        // Mirrors envelope.rs `encode_post_with_body_and_host`.
+        expect(out[0]).toBe(1); // method POST
+        expect(out.readUInt16LE(1)).toBe(4);
+        expect(out.toString('utf8', 3, 7)).toBe('/api');
+        expect(out.readUInt16LE(7)).toBe(1); // n_headers
+        expect(out.readUInt16LE(9)).toBe(4); // name_len
+        expect(out.readUInt16LE(11)).toBe(11); // val_len
+        expect(out.toString('utf8', 13, 17)).toBe('host');
+        expect(out.toString('utf8', 17, 28)).toBe('example.com');
+        expect(out.readUInt32LE(28)).toBe(2); // body_len
+        expect(out.toString('utf8', 32, 34)).toBe('hi');
+    });
+
+    it('rejects an unsupported method and oversized fields', () => {
+        const base = { path: '/', headers: [], body: new Uint8Array(0) } as const;
+        expect(() => encodeRequestEnvelope({ ...base, method: 'TRACE' })).toThrow(/unsupported/);
+        expect(() =>
+            encodeRequestEnvelope({ ...base, method: 'GET', path: '/'.repeat(0x10000) }),
+        ).toThrow(/path too long/);
+        expect(() =>
+            encodeRequestEnvelope({
+                ...base,
+                method: 'GET',
+                headers: [['x', 'y'.repeat(0x10000)]],
+            }),
+        ).toThrow(/header too long/);
+    });
+});
+
+/** Hand-builds a response envelope (the layout the guest writes). */
+function buildResponse(status: number, headers: [string, string][], body: Uint8Array): Buffer {
+    const parts: Buffer[] = [];
+    const u16 = (v: number): Buffer => {
+        const b = Buffer.allocUnsafe(2);
+        b.writeUInt16LE(v);
+        return b;
+    };
+    const u32 = (v: number): Buffer => {
+        const b = Buffer.allocUnsafe(4);
+        b.writeUInt32LE(v);
+        return b;
+    };
+    parts.push(u16(status), u16(headers.length));
+    for (const [n, v] of headers) {
+        parts.push(u16(Buffer.byteLength(n)), u16(Buffer.byteLength(v)));
+        parts.push(Buffer.from(n), Buffer.from(v));
+    }
+    parts.push(u32(body.length), Buffer.from(body));
+    return Buffer.concat(parts);
+}
+
+describe('response envelope decoding', () => {
+    it('round-trips status, headers and body', () => {
+        const buf = buildResponse(
+            201,
+            [
+                ['content-type', 'application/json'],
+                ['x-trace', 'abc'],
+            ],
+            new TextEncoder().encode('{"ok":true}'),
+        );
+        const resp = decodeResponseEnvelope(buf);
+        expect(resp.status).toBe(201);
+        expect(resp.headers).toEqual([
+            ['content-type', 'application/json'],
+            ['x-trace', 'abc'],
+        ]);
+        expect(Buffer.from(resp.body).toString()).toBe('{"ok":true}');
+    });
+
+    it('rejects truncation, zero status, and overflowing lengths', () => {
+        expect(() => decodeResponseEnvelope(new Uint8Array([1]))).toThrow(/truncated/);
+        expect(() => decodeResponseEnvelope(buildResponse(0, [], new Uint8Array(0)))).toThrow(
+            /status 0/,
+        );
+        // Claim a huge header name with too few bytes behind it.
+        const bad = Buffer.concat([
+            Buffer.from([200, 0, 1, 0, 255, 255, 0, 0]),
+            Buffer.from('hi'),
+        ]);
+        expect(() => decodeResponseEnvelope(bad)).toThrow(/truncated/);
+    });
+});
+
+describe('handle() result unpacking', () => {
+    it('splits the packed i64 into pointer and length', () => {
+        expect(unpackHandleResult((65536n << 32n) | 8n)).toEqual({ ptr: 65536, len: 8 });
+        expect(unpackHandleResult(0n)).toEqual({ ptr: 0, len: 0 });
+        expect(unpackHandleResult(0xffffffff_ffffffffn)).toEqual({
+            ptr: 0xffffffff,
+            len: 0xffffffff,
+        });
+    });
+});
+
+describe.skipIf(!fs.existsSync(EXAMPLE_WASM))('dispatch into the example server wasm', () => {
+    const load = (): WasmServerModule => {
+        const m = new WasmServerModule(EXAMPLE_WASM);
+        m.refresh();
+        return m;
+    };
+    const get = (m: WasmServerModule, p: string) =>
+        m.dispatch({
+            method: 'GET',
+            path: p,
+            headers: [['host', 'localhost:3000']],
+            body: new Uint8Array(0),
+        });
+
+    it('serves a plain route', () => {
+        const r = get(load(), '/');
+        expect(r.status).toBe(200);
+        expect(r.unhandled).toBe(false);
+        expect(Buffer.from(r.body).toString()).toBe('hello from toiljs\n');
+    });
+
+    it('serves a @rest route with its content-type', () => {
+        const r = get(load(), '/leaderboard');
+        expect(r.status).toBe(200);
+        expect(r.headers.some(([n, v]) => n === 'content-type' && v.includes('json'))).toBe(true);
+    });
+
+    it('marks a route miss as unhandled and strips the marker header', () => {
+        const r = get(load(), '/definitely-missing');
+        expect(r.status).toBe(404);
+        expect(r.unhandled).toBe(true);
+        expect(r.headers.some(([n]) => n === 'x-toil-unhandled')).toBe(false);
+    });
+
+    it('dispatches a POST body through the envelope', () => {
+        const m = load();
+        const r = m.dispatch({
+            method: 'POST',
+            path: '/players',
+            headers: [
+                ['host', 'localhost:3000'],
+                ['content-type', 'application/json'],
+            ],
+            body: new TextEncoder().encode('{"name":"ada"}'),
+        });
+        expect(r.unhandled).toBe(false);
+        expect(r.status).toBeGreaterThanOrEqual(200);
+        expect(r.status).toBeLessThan(500);
+    });
+
+    it('keeps requests isolated across instances (fresh state per dispatch)', () => {
+        const m = load();
+        const a = get(m, '/json');
+        const b = get(m, '/json');
+        expect(Buffer.from(a.body).toString()).toBe(Buffer.from(b.body).toString());
+    });
+});

package/tsconfig.devserver.json

@@ -0,0 +1,13 @@
+{
+    "extends": "./tsconfig.base.json",
+    "compilerOptions": {
+        "module": "ESNext",
+        "target": "ESNext",
+        "moduleResolution": "bundler",
+        "rootDir": "src/devserver",
+        "outDir": "build/devserver",
+        "types": ["node"],
+        "tsBuildInfoFile": "build/devserver/.tsbuildinfo"
+    },
+    "include": ["src/devserver/**/*"]
+}