toiljs 0.0.16 → 0.0.19

package/examples/basic/client/routes/rest.tsx

@@ -0,0 +1,74 @@
+// Demo of the generated REST fetch client (see ../../shared/server.ts, emitted by the
+// server build from the `@rest` controllers in server/api.ts). Unlike `Server.<service>`
+// RPC, this is working code: `Server.REST.<controller>.<route>(args)` is a real, typed
+// `fetch`. `args` is `{ params?, body?, query?, headers? }`; a `@data` return is parsed
+// into its typed class, and a route that returns a `Response` hands you the raw fetch
+// `Response` to inspect (status, `.json()`, ...). Needs the server running to respond.
+import { useState } from 'react';
+
+import { NewPlayer, type Player, ScoreDelta } from 'shared/server';
+
+export default function RestDemo() {
+    const [log, setLog] = useState<string[]>([]);
+    const note = (line: string) => setLog((prev) => [line, ...prev].slice(0, 8));
+
+    // POST /players  ->  typed Promise<Player>, body is a @data class.
+    const onCreate = async () => {
+        try {
+            const names = ['Ada', 'Linus', 'Grace', 'Dennis'];
+            const name = names[Math.floor(Math.random() * names.length)];
+            const player = await Server.REST.players.create({ body: new NewPlayer(name) });
+            note(`created #${player.id} ${player.name}`);
+        } catch (err) {
+            note(parseError(err));
+        }
+    };
+
+    // POST /players/:id/score  ->  path param + body; route returns a Response, so we get
+    // the raw fetch Response and parse it ourselves.
+    const onScore = async () => {
+        try {
+            const points = BigInt(1 + Math.floor(Math.random() * 10));
+            const res = await Server.REST.players.addScore({
+                params: { id: 1 },
+                body: new ScoreDelta(points)
+            });
+            if (!res.ok) {
+                note(`addScore -> ${res.status} (create player #1 first)`);
+                return;
+            }
+            const p = (await res.json()) as Player;
+            note(`#${p.id} ${p.name} -> ${p.score}`);
+        } catch (err) {
+            note(parseError(err));
+        }
+    };
+
+    // GET /leaderboard  ->  typed Promise<Standings>, a @data wrapper of Player[].
+    const onBoard = async () => {
+        try {
+            const board = await Server.REST.leaderboard.top();
+            note('leaderboard: ' + board.players.map((p) => `${p.name}(${p.score})`).join(', '));
+        } catch (err) {
+            note(parseError(err));
+        }
+    };
+
+    return (
+        <main>
+            <h1>REST</h1>
+            <p>
+                <code>Server.REST.*</code> is a real, typed <code>fetch</code> client generated from the{' '}
+                <code>@rest</code> controllers. It needs the server running to respond.
+            </p>
+            <button onClick={onCreate}>create player</button> <button onClick={onScore}>award points to #1</button>{' '}
+            <button onClick={onBoard}>leaderboard</button>
+            <ul>
+                {log.map((line, i) => (
+                    <li key={i}>{line}</li>
+                ))}
+            </ul>
+            <Toil.Link href="/">Back home</Toil.Link>
+        </main>
+    );
+}

package/examples/basic/client/routes/rpc.tsx

@@ -0,0 +1,43 @@
+// Demo of the generated, typed `Server` RPC surface (see ../../shared/server.ts, emitted
+// by the server build from `@service`/`@remote`). `Server` is global (no import) and typed
+// from the server: `Server.ping(n)` (free `@remote`) and `Server.admin.reset()` (a
+// `@service` method). Transport is not wired yet, so a real call throws; this page shows
+// the typing and reports the stub error via the global `parseError`.
+import { useState } from 'react';
+
+export default function RpcDemo() {
+    const [result, setResult] = useState('not called');
+
+    // Scalar in / scalar out: Server.ping is typed (n: number) => Promise<number>.
+    const onPing = async () => {
+        try {
+            const next = await Server.ping(10);
+            setResult(`ping -> ${next}`);
+        } catch (err) {
+            setResult(parseError(err));
+        }
+    };
+
+    // A @service method: namespaced under its service key.
+    const onReset = async () => {
+        try {
+            await Server.admin.reset();
+            setResult('admin.reset -> store cleared');
+        } catch (err) {
+            setResult(parseError(err));
+        }
+    };
+
+    return (
+        <main>
+            <h1>RPC</h1>
+            <p>
+                <code>Server</code> (RPC) is typed from the server build, no import. Calling throws until the transport
+                lands. For working server calls today, use the REST client.
+            </p>
+            <button onClick={onPing}>Server.ping(10)</button> <button onClick={onReset}>Server.admin.reset()</button>
+            <p>{result}</p>
+            <Toil.Link href="/rest">See the REST demo</Toil.Link> · <Toil.Link href="/">Back home</Toil.Link>
+        </main>
+    );
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.16",
+    "version": "0.0.19",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -50,9 +50,22 @@
             "import": "./build/io/index.js",
             "default": "./build/io/index.js"
         },
+        "./server/runtime": {
+            "types": "./server/runtime/index.ts",
+            "default": "./server/runtime/index.ts"
+        },
+        "./server/runtime/exports": {
+            "types": "./server/runtime/exports/index.ts",
+            "default": "./server/runtime/exports/index.ts"
+        },
+        "./server/runtime/*": {
+            "types": "./server/runtime/*.ts",
+            "default": "./server/runtime/*.ts"
+        },
         "./tsconfig": "./presets/tsconfig.json",
         "./eslint": "./presets/eslint.js",
-        "./prettier": "./presets/prettier.json"
+        "./prettier": "./presets/prettier.json",
+        "./prettier-plugin": "./presets/prettier-plugin.js"
     },
     "bin": {
         "toiljs": "./build/cli/index.js"
@@ -77,7 +90,7 @@
     },
     "scripts": {
         "watch": "tsc -p tsconfig.json --watch",
-        "build": "npm run build:shared && npm run build:logger && npm run build:client && npm run build:io && npm run build:backend && npm run build:compiler && npm run build:cli && npm run build:server",
+        "build": "npm run build:shared && npm run build:logger && npm run build:client && npm run build:io && npm run build:backend && npm run build:compiler && npm run build:cli",
         "build:shared": "tsc -p tsconfig.shared.json",
         "build:logger": "tsc -p tsconfig.logger.json",
         "build:client": "tsc -p tsconfig.client.json",
@@ -85,7 +98,6 @@
         "build:backend": "tsc -p tsconfig.backend.json",
         "build:compiler": "tsc -p tsconfig.compiler.json",
         "build:cli": "tsc -p tsconfig.cli.json --noEmit && esbuild src/cli/index.ts --bundle --platform=node --format=esm --outfile=build/cli/index.js --external:toiljs/*",
-        "build:server": "toilscript --target release",
         "test": "vitest run --coverage",
         "test:watch": "vitest",
         "test:ui": "vitest --ui",
@@ -94,7 +106,7 @@
         "test:server:ci": "asp --config as-pect.config.js --summary --no-logo",
         "test:all": "npm run test && npm run test:server",
         "lint": "eslint src",
-        "docs": "typedoc --out docs --tsconfig tsconfig.json --readme README.md --name TOILJS --plugin typedoc-material-theme --themeColor '#cb9820' --exclude src/server src",
+        "docs": "typedoc --out docs --tsconfig tsconfig.json --readme README.md --name TOILJS --plugin typedoc-material-theme --themeColor '#cb9820' src",
         "setup": "npm i && npm run build"
     },
     "dependencies": {
@@ -109,7 +121,7 @@
         "eslint-plugin-react-refresh": "^0.5.2",
         "picocolors": "^1.1.1",
         "sharp": "^0.34.5",
-        "toilscript": "^0.1.4",
+        "toilscript": "^0.1.11",
         "typescript-eslint": "^8.60.0",
         "vite": "^8.0.14",
         "vite-imagetools": "^10.0.0",
@@ -124,7 +136,6 @@
     },
     "devDependencies": {
         "@babel/core": "^7.29.7",
-        "@clack/prompts": "^1.5.0",
         "@babel/preset-env": "^7.29.7",
         "@babel/preset-typescript": "^7.29.7",
         "@btc-vision/as-covers-assembly": "^0.4.5",
@@ -132,6 +143,7 @@
         "@btc-vision/as-pect-assembly": "^8.3.0",
         "@btc-vision/as-pect-cli": "^8.3.0",
         "@btc-vision/as-pect-transform": "^8.3.0",
+        "@clack/prompts": "^1.5.0",
         "@microsoft/api-extractor": "7.58.7",
         "@testing-library/dom": "^10.4.1",
         "@testing-library/react": "^16.3.2",

package/presets/prettier-plugin.js

@@ -0,0 +1,51 @@
+/**
+ * Prettier plugin that lets prettier format toilscript server code, which uses native
+ * decorators on free functions (`@main`, `@remote function ...`). Those are valid
+ * toilscript but not valid ECMAScript/TypeScript grammar, so prettier's parser rejects
+ * them outright.
+ *
+ * The fix is a parse-time/print-time round-trip: in `preprocess` each function decorator
+ * is rewritten to a marker block comment (which the TS parser accepts), and the estree
+ * printer's `printComment` renders that marker back as the original `@decorator`. Class
+ * and method decorators are already valid grammar and pass through untouched.
+ */
+import * as tsPlugin from 'prettier/plugins/typescript';
+import * as estreePlugin from 'prettier/plugins/estree';
+
+const baseTs = tsPlugin.parsers.typescript;
+const baseEstree = estreePlugin.printers.estree;
+
+const MARKER = '::toil-decorator ';
+// One-or-more bare decorators (`@name`, no args) immediately before a function declaration.
+const FN_DECORATORS =
+    /((?:@[A-Za-z_$][\w$]*[ \t]*\r?\n[ \t]*)+)((?:export[ \t]+)?(?:default[ \t]+)?(?:async[ \t]+)?function\b)/g;
+const ONE_DECORATOR = /@([A-Za-z_$][\w$]*)([ \t]*\r?\n[ \t]*)/g;
+
+function preprocess(text, options) {
+    const pre = baseTs.preprocess ? baseTs.preprocess(text, options) : text;
+    return pre.replace(FN_DECORATORS, (_match, decorators, fn) => {
+        const masked = decorators.replace(
+            ONE_DECORATOR,
+            (_d, name, gap) => `/*${MARKER}${name}*/${gap}`,
+        );
+        return masked + fn;
+    });
+}
+
+export const parsers = {
+    typescript: { ...baseTs, preprocess },
+};
+
+export const printers = {
+    estree: {
+        ...baseEstree,
+        printComment(path, options) {
+            const comment = path.node ?? path.getValue();
+            const value = comment?.value;
+            if (typeof value === 'string' && value.startsWith(MARKER)) {
+                return '@' + value.slice(MARKER.length).trim();
+            }
+            return baseEstree.printComment(path, options);
+        },
+    },
+};

package/presets/prettier.json

@@ -1,4 +1,5 @@
 {
+    "plugins": ["toiljs/prettier-plugin"],
     "printWidth": 120,
     "tabWidth": 4,
     "useTabs": false,

package/server/runtime/README.md

@@ -0,0 +1,97 @@
+# toiljs server runtime
+
+In-tree SDK that bridges a toilscript handler to the toil-backend
+edge's wasm ABI.
+
+## What it does
+
+The edge calls `handle(req_ofs: i32, req_len: i32) -> i64` on every
+request. This runtime gives you:
+
+- `Request` / `Response` AssemblyScript types
+- A byte-for-byte envelope codec matching
+  `toil-backend/src/http/envelope.rs`
+- A `ToilHandler` base class you extend, plus a `Server` singleton you
+  assign `Server.handler = () => new MyHandler()`. The `handle` wasm
+  export (re-exported from `toiljs/server/runtime/exports`) decodes the
+  request, runs your handler, encodes the response, and returns the
+  packed i64 the host expects.
+
+## Wire contract
+
+Source of truth: `toil-backend/src/http/envelope.rs`.
+
+```
+request envelope (LE, no padding):
+  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
+```
+
+The response envelope is the same shape with the first `u8 method +
+u16 path_len + path` replaced by `u16 status`.
+
+The handler must return a packed `i64`:
+
+```
+(resp_ofs << 32) | resp_len
+```
+
+The host reads `resp_len` bytes starting at `resp_ofs` in linear
+memory and decodes them as a response envelope.
+
+## Memory layout
+
+- `[0, req_len)` — request envelope, written by the host before
+  `handle` is called.
+- `[65536, 65536 + resp_len)` — response envelope, written by
+  `dispatch` (the response base is the second 64 KiB page so the
+  request and response never overlap).
+
+The edge enforces a 1024-page (64 MiB) linear memory cap via
+`LimitingTunables`, so leaving the first page for the request is
+fine.
+
+## Example
+
+A user app extends `ToilHandler` and wires it up in `server/main.ts`.
+The runtime is consumed as the `toiljs/server/runtime` library export:
+
+```ts
+// server/HelloHandler.ts
+import { ToilHandler, Request, Response } from 'toiljs/server/runtime';
+
+export class HelloHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        if (req.path == '/') return Response.text('hello\n');
+        if (req.path == '/json') return Response.json('{"ok":true}');
+        return Response.notFound();
+    }
+}
+```
+
+```ts
+// server/main.ts
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { HelloHandler } from './HelloHandler';
+
+Server.handler = () => new HelloHandler();
+
+// Surface the wasm `handle(i32, i32) -> i64` entry the edge calls.
+export * from 'toiljs/server/runtime/exports';
+
+// Forward AS runtime panics to the host's env::abort import.
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}
+```
+
+Compile with `toilscript --target release`, drop the resulting
+`build/server/release.wasm` at `<toil-backend>/hosts/<hostname>.wasm`,
+and the edge will route requests with that `Host:` header to it. A
+complete app lives in `examples/basic`.

package/server/runtime/abort/abort.ts

@@ -0,0 +1,27 @@
+/**
+ * AssemblyScript runtime panic hook.
+ *
+ * Any unhandled `assert()`, out-of-bounds array access, or other
+ * runtime failure in the compiled wasm reaches the host's `env::abort`
+ * import (see toil-backend's `AbortImport`). For that import to be
+ * satisfied at link time the compiled module needs an exported
+ * `abort` function with the AS-standard signature; the user's
+ * `main.ts` re-exports it as:
+ *
+ * ```ts
+ * export function abort(message: string, fileName: string, line: u32, column: u32): void {
+ *     revertOnError(message, fileName, line, column);
+ * }
+ * ```
+ *
+ * We just call `unreachable()` after recording the location: wasmer
+ * traps the call, the edge's pump catches the trap, marks the
+ * instance poisoned, and returns 502 to the client. The location
+ * fields are deliberately left untouched in case a future host
+ * import wants to read them off the message/fileName strings; today
+ * the edge's `AbortImport::execute` only logs `line`/`column`.
+ */
+
+export function revertOnError(_message: string, _fileName: string, _line: u32, _column: u32): void {
+    unreachable();
+}

package/server/runtime/env/Server.ts

@@ -0,0 +1,61 @@
+/**
+ * Server — the runtime singleton, analog to btc-runtime's
+ * `Blockchain`.
+ *
+ * The user's `main.ts` assigns `Server.handler = () => new MyHandler()`.
+ * The `handle(req_ofs, req_len)` wasm export in `runtime/exports`
+ * calls that factory once per request.
+ */
+
+import { Potential } from '../lang/Potential';
+import { ToilHandler } from '../handlers/ToilHandler';
+
+@final
+export class ServerEnvironment {
+    /**
+     * The user-supplied handler factory. Assigned at module init by
+     * the contract's `main.ts`. We use a factory rather than a
+     * pre-built instance so the user gets fresh state per request
+     * (the alternative would be threading reset logic through every
+     * handler class).
+     */
+    public handler: () => ToilHandler = defaultHandler;
+
+    /**
+     * Cached handler instance for the current request. Cleared at the
+     * end of every dispatch so the next request runs the factory
+     * again. Exposed for tests; user code should not touch it.
+     */
+    public _current: Potential<ToilHandler> = null;
+
+    /**
+     * Build (or reuse) the handler for this request. Called once per
+     * dispatch from `runtime/exports::handle`.
+     */
+    public currentHandler(): ToilHandler {
+        if (this._current == null) {
+            this._current = this.handler();
+        }
+        return <ToilHandler>this._current;
+    }
+
+    /**
+     * Drop the cached handler so the next request gets a fresh one.
+     * Called at the tail of `runtime/exports::handle`.
+     */
+    public resetCurrentHandler(): void {
+        this._current = null;
+    }
+}
+
+/**
+ * Default factory used until the user's `main.ts` assigns
+ * `Server.handler`. Returns a base handler whose `handle` produces a
+ * 404 — useful as a no-op state during early bring-up and as a
+ * fallback if the user forgot to wire one up.
+ */
+function defaultHandler(): ToilHandler {
+    return new ToilHandler();
+}
+
+export const Server: ServerEnvironment = new ServerEnvironment();

package/server/runtime/envelope.ts

@@ -0,0 +1,191 @@
+/**
+ * Wire envelope codec, byte-for-byte compatible with
+ * `toil-backend/src/http/envelope.rs`.
+ *
+ * Layout (LE, 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)
+ *     is replaced by `u16 status`.
+ */
+
+import {
+    readBytes,
+    readU16,
+    readU32,
+    readU8,
+    readUtf8,
+    utf8Length,
+    writeBytes,
+    writeU16,
+    writeU32,
+    writeUtf8
+} from './memory';
+import { Header, Method, Request } from './request';
+import { Response } from './response';
+
+class DecodeCursor {
+    base: usize;
+    end: usize;
+    cur: usize;
+    ok: bool;
+
+    constructor(base: usize, len: usize) {
+        this.base = base;
+        this.end = base + len;
+        this.cur = base;
+        this.ok = true;
+    }
+
+    @inline canTake(n: usize): bool {
+        return this.cur + n <= this.end;
+    }
+
+    takeU8(): u8 {
+        if (!this.canTake(1)) { this.ok = false; return 0; }
+        const v = readU8(this.cur);
+        this.cur += 1;
+        return v;
+    }
+
+    takeU16(): u16 {
+        if (!this.canTake(2)) { this.ok = false; return 0; }
+        const v = readU16(this.cur);
+        this.cur += 2;
+        return v;
+    }
+
+    takeU32(): u32 {
+        if (!this.canTake(4)) { this.ok = false; return 0; }
+        const v = readU32(this.cur);
+        this.cur += 4;
+        return v;
+    }
+
+    takeBytes(n: u32): Uint8Array {
+        if (!this.canTake(<usize>n)) { this.ok = false; return new Uint8Array(0); }
+        const out = readBytes(this.cur, n);
+        this.cur += <usize>n;
+        return out;
+    }
+
+    takeUtf8(n: u32): string {
+        if (!this.canTake(<usize>n)) { this.ok = false; return ''; }
+        const s = readUtf8(this.cur, n);
+        this.cur += <usize>n;
+        return s;
+    }
+}
+
+/**
+ * Decode the request envelope the host wrote at `req_ofs`. Returns
+ * a populated `Request` on success or `null` on truncation /
+ * malformed bytes.
+ */
+export function decodeRequest(req_ofs: usize, req_len: usize): Request | null {
+    const c = new DecodeCursor(req_ofs, req_len);
+    const methodByte = c.takeU8();
+    if (!c.ok) return null;
+    const method = methodFromByte(methodByte);
+
+    const pathLen = c.takeU16();
+    const path = c.takeUtf8(<u32>pathLen);
+    if (!c.ok) return null;
+
+    const nHeaders = c.takeU16();
+    const headers = new Array<Header>();
+    for (let i: u32 = 0; i < <u32>nHeaders; i++) {
+        const nameLen = c.takeU16();
+        const valLen = c.takeU16();
+        const name = c.takeUtf8(<u32>nameLen);
+        const val = c.takeUtf8(<u32>valLen);
+        if (!c.ok) return null;
+        headers.push(new Header(name, val));
+    }
+
+    const bodyLen = c.takeU32();
+    const body = c.takeBytes(bodyLen);
+    if (!c.ok) return null;
+
+    return new Request(method, path, headers, body);
+}
+
+@inline function methodFromByte(b: u8): Method {
+    if (b == 0) return Method.GET;
+    if (b == 1) return Method.POST;
+    if (b == 2) return Method.PUT;
+    if (b == 3) return Method.DELETE;
+    if (b == 4) return Method.PATCH;
+    if (b == 5) return Method.HEAD;
+    if (b == 6) return Method.OPTIONS;
+    return Method.UNKNOWN;
+}
+
+/**
+ * Serialise `resp` into linear memory starting at `dst_ofs`.
+ * Returns the total byte length written. Status, header count and
+ * body length are bounds-checked: header names and values must each
+ * fit in u16, the body must fit in u32, the header count must fit in
+ * u16. A handler returning an unrepresentable response gets a
+ * minimal 500 envelope written instead so the host never sees an
+ * encoder fault.
+ */
+export function encodeResponse(resp: Response, dst_ofs: usize): u32 {
+    // Validate fits-in-u16/u32 limits up front so we never half-write.
+    if (resp.headers.length > 0xffff) {
+        return encodeFallback500(dst_ofs);
+    }
+    for (let i = 0; i < resp.headers.length; i++) {
+        const h = resp.headers[i];
+        if (utf8Length(h.name) > 0xffff || utf8Length(h.value) > 0xffff) {
+            return encodeFallback500(dst_ofs);
+        }
+    }
+    if (<u64>resp.body.length > <u64>0xffffffff) {
+        return encodeFallback500(dst_ofs);
+    }
+
+    let cur: usize = dst_ofs;
+
+    writeU16(cur, resp.status);
+    cur += 2;
+
+    writeU16(cur, <u16>resp.headers.length);
+    cur += 2;
+
+    for (let i = 0; i < resp.headers.length; i++) {
+        const h = resp.headers[i];
+        const nameLen = utf8Length(h.name);
+        const valLen = utf8Length(h.value);
+        writeU16(cur, <u16>nameLen);
+        cur += 2;
+        writeU16(cur, <u16>valLen);
+        cur += 2;
+        cur += writeUtf8(cur, h.name);
+        cur += writeUtf8(cur, h.value);
+    }
+
+    const bodyLen = <u32>resp.body.length;
+    writeU32(cur, bodyLen);
+    cur += 4;
+    cur += writeBytes(cur, resp.body);
+
+    return <u32>(cur - dst_ofs);
+}
+
+function encodeFallback500(dst_ofs: usize): u32 {
+    // Minimal valid 500 envelope: status + 0 headers + 0-length body.
+    writeU16(dst_ofs, 500);
+    writeU16(dst_ofs + 2, 0);
+    writeU32(dst_ofs + 4, 0);
+    return 8;
+}

package/server/runtime/exports/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Wasm exports the edge calls.
+ *
+ * The user's `main.ts` does
+ *
+ * ```ts
+ * export * from './runtime/exports';
+ * ```
+ *
+ * to surface `handle(i32, i32) -> i64` (and any future entry points)
+ * as wasm exports. The actual work — decode the envelope, run the
+ * user's handler via `Server.currentHandler()`, encode the response —
+ * lives here.
+ */
+
+import { Server } from '../env/Server';
+import { decodeRequest, encodeResponse } from '../envelope';
+import { Response } from '../response';
+
+/**
+ * Linear-memory offset where we lay out the response envelope.
+ *
+ * The host writes the request envelope starting at offset 0. We pick
+ * `65536` (one wasm page in) so the response never overlaps with the
+ * request, no matter how big the request grew. The edge's
+ * LimitingTunables caps the linear memory at 1024 pages (64 MiB), so
+ * we still have 63 MiB of room past `RESPONSE_BASE` for the response
+ * envelope.
+ */
+const RESPONSE_BASE: usize = 65536;
+
+@main
+export function handle(req_ofs: i32, req_len: i32): i64 {
+    let resp: Response;
+
+    const req = decodeRequest(<usize>req_ofs, <usize>req_len);
+    if (req == null) {
+        // Truncated or malformed envelope — host shouldn't send these
+        // but produce a clean 400 so the dispatcher doesn't see a
+        // garbage return value.
+        resp = Response.badRequest('malformed request envelope');
+    } else {
+        const handler = Server.currentHandler();
+        handler.onRequestStarted(req);
+        resp = handler.handle(req);
+        handler.onRequestCompleted(req, resp);
+    }
+
+    const total = encodeResponse(resp, RESPONSE_BASE);
+    Server.resetCurrentHandler();
+    return ((<i64>RESPONSE_BASE) << 32) | (<i64>total);
+}