toiljs 0.0.16 → 0.0.19

package/server/runtime/handlers/ToilHandler.ts

@@ -0,0 +1,34 @@
+/**
+ * Base class every toiljs server-side handler extends, analog to
+ * btc-runtime's `OP_NET`. Override `handle(req)` to produce the
+ * response. The framework calls `onRequestStarted` / `onRequestCompleted`
+ * around every call so the user can hook for logging or metrics
+ * without re-implementing `handle`.
+ */
+
+import { Request } from '../request';
+import { Response } from '../response';
+
+export class ToilHandler {
+    /**
+     * Override to declare your routes. The default implementation
+     * returns a generic 404 so a handler that hasn't been wired up
+     * still produces a valid envelope.
+     */
+    public handle(_req: Request): Response {
+        return Response.notFound();
+    }
+
+    /**
+     * Called before each `handle` call. Empty by default; override
+     * for per-request setup (logging, header reads, etc.).
+     */
+    public onRequestStarted(_req: Request): void {}
+
+    /**
+     * Called after each `handle` call returns (also when it throws,
+     * after the runtime has converted the throw into a 500). Empty by
+     * default.
+     */
+    public onRequestCompleted(_req: Request, _resp: Response): void {}
+}

package/server/runtime/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Public surface of the toiljs server runtime, analog to
+ * `@btc-vision/btc-runtime/runtime`. The user does
+ *
+ * ```ts
+ * import { Server, ToilHandler, Response } from './runtime';
+ * ```
+ *
+ * and then assigns `Server.handler = () => new MyHandler()` in their
+ * `main.ts`. The wasm `handle(i32, i32) -> i64` export comes from
+ * `./exports`, which the user re-exports with `export * from
+ * './runtime/exports'`. The `abort` runtime hook comes from
+ * `./abort/abort`, which the user re-exports as a top-level `abort`
+ * function in their `main.ts`.
+ */
+
+export { Header, Method, Request } from './request';
+export { Response } from './response';
+export { ToilHandler } from './handlers/ToilHandler';
+export { Server, ServerEnvironment } from './env/Server';
+
+// HTTP layer (`@rest` / `@route`).
+export { Rest, RestRegistry, RouteFn } from './rest/Rest';
+export { RouteContext } from './rest/RouteContext';
+export { matchRoute } from './rest/match';
+export { RestHandler } from './rest/RestHandler';

package/server/runtime/lang/Potential.ts

@@ -0,0 +1,5 @@
+/**
+ * `Potential<T>` is just `T | null`. Mirrors btc-runtime's
+ * convention so the runtime's optional fields read consistently.
+ */
+export type Potential<T> = T | null;

package/server/runtime/memory.ts

@@ -0,0 +1,81 @@
+/**
+ * Tiny load/store wrappers around AssemblyScript's linear-memory
+ * intrinsics. The envelope codec stays readable when it calls
+ * `readU16(p)` instead of `load<u16>(p)` everywhere.
+ *
+ * All reads are little-endian (matches the wire format produced by
+ * `toil-backend/src/http/envelope.rs`).
+ */
+
+@inline export function readU8(ofs: usize): u8 {
+    return load<u8>(ofs);
+}
+
+@inline export function readU16(ofs: usize): u16 {
+    return load<u16>(ofs);
+}
+
+@inline export function readU32(ofs: usize): u32 {
+    return load<u32>(ofs);
+}
+
+@inline export function writeU8(ofs: usize, v: u8): void {
+    store<u8>(ofs, v);
+}
+
+@inline export function writeU16(ofs: usize, v: u16): void {
+    store<u16>(ofs, v);
+}
+
+@inline export function writeU32(ofs: usize, v: u32): void {
+    store<u32>(ofs, v);
+}
+
+/**
+ * Read `len` bytes starting at `ofs` and return them as a fresh
+ * `Uint8Array` (copying out of linear memory). Used for the request
+ * body so the handler can hold onto it past the call to `dispatch`.
+ */
+export function readBytes(ofs: usize, len: u32): Uint8Array {
+    const out = new Uint8Array(<i32>len);
+    memory.copy(changetype<usize>(out.dataStart), ofs, <usize>len);
+    return out;
+}
+
+/**
+ * Write `bytes` into linear memory starting at `ofs`. Returns the
+ * number of bytes written.
+ */
+export function writeBytes(ofs: usize, bytes: Uint8Array): u32 {
+    const n = <u32>bytes.length;
+    memory.copy(ofs, changetype<usize>(bytes.dataStart), <usize>n);
+    return n;
+}
+
+/**
+ * Decode `len` bytes of UTF-8 at `ofs` into a string. The bytes
+ * remain in linear memory; the returned string is a fresh AS string.
+ */
+export function readUtf8(ofs: usize, len: u32): string {
+    return String.UTF8.decodeUnsafe(ofs, <usize>len);
+}
+
+/**
+ * Encode `s` as UTF-8 into linear memory starting at `ofs`. Returns
+ * the number of bytes written.
+ */
+export function writeUtf8(ofs: usize, s: string): u32 {
+    const buf = String.UTF8.encode(s);
+    const n = <u32>buf.byteLength;
+    memory.copy(ofs, changetype<usize>(buf), <usize>n);
+    return n;
+}
+
+/**
+ * UTF-8 byte length of `s` without actually writing it anywhere.
+ * Used by the response encoder to pre-compute total envelope size
+ * before laying out the bytes.
+ */
+@inline export function utf8Length(s: string): u32 {
+    return <u32>String.UTF8.byteLength(s, false);
+}

package/server/runtime/request.ts

@@ -0,0 +1,55 @@
+/**
+ * The incoming HTTP request handed to the user's handler. Decoded
+ * from the wire envelope the host wrote at offset 0 of linear
+ * memory. See `envelope.ts`.
+ */
+
+export enum Method {
+    GET = 0,
+    POST = 1,
+    PUT = 2,
+    DELETE = 3,
+    PATCH = 4,
+    HEAD = 5,
+    OPTIONS = 6,
+    UNKNOWN = 255,
+}
+
+export class Header {
+    name: string;
+    value: string;
+
+    constructor(name: string, value: string) {
+        this.name = name;
+        this.value = value;
+    }
+}
+
+export class Request {
+    method: Method;
+    path: string;
+    headers: Array<Header>;
+    body: Uint8Array;
+
+    constructor(method: Method, path: string, headers: Array<Header>, body: Uint8Array) {
+        this.method = method;
+        this.path = path;
+        this.headers = headers;
+        this.body = body;
+    }
+
+    /**
+     * Case-insensitive header lookup. Returns `null` if not present.
+     * O(n) over the header list; the request typically carries fewer
+     * than a dozen, so the linear scan is the right call.
+     */
+    header(name: string): string | null {
+        const lower = name.toLowerCase();
+        for (let i = 0; i < this.headers.length; i++) {
+            if (this.headers[i].name.toLowerCase() == lower) {
+                return this.headers[i].value;
+            }
+        }
+        return null;
+    }
+}

package/server/runtime/response.ts

@@ -0,0 +1,86 @@
+/**
+ * The response the user's handler builds. Serialised into a wire
+ * envelope at a fixed offset before `handle()` returns. See
+ * `envelope.ts` and `dispatch.ts`.
+ */
+
+import { Header } from './request';
+
+export class Response {
+    status: u16;
+    headers: Array<Header>;
+    body: Uint8Array;
+
+    constructor(status: u16, body: Uint8Array, headers: Array<Header> | null = null) {
+        this.status = status;
+        this.body = body;
+        this.headers = headers != null ? headers : new Array<Header>();
+    }
+
+    public static text(body: string, status: u16 = 200): Response {
+        const buf = String.UTF8.encode(body);
+        const bytes = Uint8Array.wrap(buf);
+        const r = new Response(status, bytes);
+
+        r.setHeader('content-type', 'text/plain; charset=utf-8');
+
+        return r;
+    }
+
+    public static html(body: string, status: u16 = 200): Response {
+        const buf = String.UTF8.encode(body);
+        const bytes = Uint8Array.wrap(buf);
+        const r = new Response(status, bytes);
+
+        r.setHeader('content-type', 'text/html; charset=utf-8');
+
+        return r;
+    }
+
+    public static json(body: string, status: u16 = 200): Response {
+        const buf = String.UTF8.encode(body);
+        const bytes = Uint8Array.wrap(buf);
+        const r = new Response(status, bytes);
+
+        r.setHeader('content-type', 'application/json; charset=utf-8');
+
+        return r;
+    }
+
+    /**
+     * A raw binary body, tagged `application/octet-stream`. Used by `@route`
+     * methods with `stream: DataStream.Binary` to ship a `@data` `encode()`.
+     */
+    public static bytes(body: Uint8Array, status: u16 = 200): Response {
+        const r = new Response(status, body);
+
+        r.setHeader('content-type', 'application/octet-stream');
+
+        return r;
+    }
+
+    public static notFound(): Response {
+        return Response.text('not found\n', 404);
+    }
+
+    public static badRequest(msg: string = 'bad request'): Response {
+        return Response.text(msg + '\n', 400);
+    }
+
+    public static internalError(msg: string = 'internal error'): Response {
+        return Response.text(msg + '\n', 500);
+    }
+
+    public static empty(status: u16): Response {
+        return new Response(status, new Uint8Array(0));
+    }
+
+    /**
+     * Builder-style: returns `this` so calls can chain.
+     */
+    public setHeader(name: string, value: string): Response {
+        this.headers.push(new Header(name, value));
+
+        return this;
+    }
+}

package/server/runtime/rest/Rest.ts

@@ -0,0 +1,39 @@
+/**
+ * The auto-populated REST router. Every `@rest` controller self-registers a
+ * dispatcher here at module init (compiler-injected); your handler calls
+ * `Rest.dispatch(req)` to try them all. The first controller that matches the
+ * method + path wins; `null` means no route matched (fall through to your own
+ * logic / static files / 404).
+ */
+
+import { Request } from '../request';
+import { Response } from '../response';
+
+/** A controller dispatcher: returns a Response on a route hit, null on a miss. */
+export type RouteFn = (req: Request) => Response | null;
+
+export class RestRegistry {
+    private fns: Array<RouteFn> = new Array<RouteFn>();
+
+    /** Compiler-injected: registers a controller's dispatcher. Not for direct use. */
+    register(fn: RouteFn): void {
+        this.fns.push(fn);
+    }
+
+    /** Try every registered controller in registration order; first match wins. */
+    dispatch(req: Request): Response | null {
+        for (let i = 0; i < this.fns.length; i++) {
+            const hit = this.fns[i](req);
+            if (hit != null) return hit;
+        }
+        return null;
+    }
+
+    /** Number of registered controllers (diagnostics / tests). */
+    get size(): i32 {
+        return this.fns.length;
+    }
+}
+
+/** The process-wide REST router singleton. */
+export const Rest: RestRegistry = new RestRegistry();

package/server/runtime/rest/RestHandler.ts

@@ -0,0 +1,20 @@
+/**
+ * A drop-in handler for REST-only projects: dispatches to every `@rest`
+ * controller and 404s on a miss. Wire it with
+ * `Server.handler = () => new RestHandler()`. If you need custom logic, skip
+ * this and call `Rest.dispatch(req)` from your own `ToilHandler` instead.
+ */
+
+import { Request } from '../request';
+import { Response } from '../response';
+import { ToilHandler } from '../handlers/ToilHandler';
+import { Rest } from './Rest';
+
+export class RestHandler extends ToilHandler {
+    /** Dispatches to the registered `@rest` controllers; returns 404 when none match. */
+    handle(req: Request): Response {
+        const hit = Rest.dispatch(req);
+        if (hit != null) return hit;
+        return Response.notFound();
+    }
+}

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

@@ -4,7 +4,7 @@
  * 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`.
+ * toilscript WASM runtime in `server/runtime` (the `toiljs/server/runtime` library export).
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -35,8 +35,18 @@ export interface BackendOptions {
     readonly root: string;
     /** Listening port. Default `3000`. */
     readonly port?: number;
-    /** Bind host. Default `0.0.0.0`. */
+    /**
+     * 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`. */
@@ -58,6 +68,26 @@ export interface RunningBackend {
     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);
@@ -74,7 +104,7 @@ function resolveStaticFile(root: string, requestPath: string): string | null {
  */
 export async function startBackend(options: BackendOptions): Promise<RunningBackend> {
     const port = options.port ?? 3000;
-    const host = options.host ?? '0.0.0.0';
+    const host = options.host ?? '127.0.0.1';
     const wsPath = options.wsPath ?? '/_toil';
     const cors = options.cors ?? true;
     const root = path.resolve(options.root);
@@ -137,6 +167,18 @@ export async function startBackend(options: BackendOptions): Promise<RunningBack
         },
     );
 
+    // 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);

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',