toiljs 0.0.15 → 0.0.19

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);
+}

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();
+    }
+}