convex-rust 0.0.0-stage → 0.1.0

package/dist/runtime/http.d.ts

@@ -0,0 +1,40 @@
+/** Convex limits an HTTP action's request and response body to 20 MiB. */
+export declare const MAX_HTTP_BODY_BYTES: number;
+export interface HttpHead {
+    method: string;
+    url: string;
+    headers: [string, string][];
+}
+/** The head the guest receives as its call args (the body follows as a host stream). */
+export declare function requestHead(request: Request): HttpHead;
+/** The Response for a buffered guest answer `{status, headers, body}` (`body` base64 or null). */
+export declare function bufferedResponse(ok: any): Response;
+/**
+ * Receives the guest's response writes. `start` builds the Response (its body is a ReadableStream
+ * fed by `write`); `write` waits while the client lags more than ~1 MiB behind, and fails once the
+ * client cancelled the response, so the guest stops producing.
+ */
+export declare class HttpSink {
+    readonly head: HttpHead;
+    readonly requestBody: ReadableStream<Uint8Array> | null;
+    /** Resolves when the guest sent `httpStart`. */
+    readonly started: Promise<void>;
+    /** Set by `start`. */
+    response: Response | null;
+    cancelled: boolean;
+    private resolveStarted;
+    private controller;
+    private waiting;
+    private written;
+    private ended;
+    constructor(head: HttpHead, requestBody: ReadableStream<Uint8Array> | null);
+    private release;
+    /** `httpStart`: validates the head and creates the streaming Response. */
+    start(status: unknown, headers: unknown): void;
+    /** `httpWrite`: queues bytes for the client; resolves once the queue has room again. */
+    write(bytes: Uint8Array): Promise<void>;
+    /** `httpEnd` (and the guest returning): closes the body. */
+    end(): void;
+    /** The guest failed after `httpStart`: error the body so the client sees a truncated response. */
+    fail(e: unknown): void;
+}

package/dist/runtime/http.js

@@ -0,0 +1,157 @@
+// HTTP actions written in Rust (contracts/V8HOST.md "HTTP actions"): the Request -> guest head
+// conversion, and the sink that turns a guest's `httpStart` / `httpWrite` / `httpEnd` tasks into a
+// streamed Response. The wasm instance itself is driven by host.ts.
+import { decodeBase64 } from "./base64.js";
+/** Convex limits an HTTP action's request and response body to 20 MiB. */
+export const MAX_HTTP_BODY_BYTES = 20 * 1024 * 1024;
+/** Bytes buffered for a streamed response before `httpWrite` waits for the client to catch up. */
+const STREAM_HIGH_WATER_BYTES = 1024 * 1024;
+/** Statuses a `Response` cannot carry a body with. */
+const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
+/** The head the guest receives as its call args (the body follows as a host stream). */
+export function requestHead(request) {
+    const headers = [];
+    request.headers.forEach((value, key) => headers.push([key, value]));
+    return { method: request.method, url: request.url, headers };
+}
+function toHeaders(pairs, what) {
+    const headers = new Headers();
+    if (pairs === undefined || pairs === null)
+        return headers;
+    if (!Array.isArray(pairs))
+        throw new Error(`${what}: headers must be a list of [name, value] pairs`);
+    for (const pair of pairs) {
+        if (!Array.isArray(pair) || typeof pair[0] !== "string" || typeof pair[1] !== "string") {
+            throw new Error(`${what}: headers must be [name, value] pairs`);
+        }
+        headers.append(pair[0], pair[1]);
+    }
+    return headers;
+}
+function checkStatus(status, what) {
+    if (typeof status !== "number" || !Number.isInteger(status) || status < 200 || status > 599) {
+        throw new Error(`${what}: invalid HTTP status ${String(status)} (expected 200..599)`);
+    }
+    return status;
+}
+/** The Response for a buffered guest answer `{status, headers, body}` (`body` base64 or null). */
+export function bufferedResponse(ok) {
+    if (ok === null || typeof ok !== "object") {
+        throw new Error('The "use rust" HTTP action returned something other than an HttpResponse');
+    }
+    const status = checkStatus(ok.status, "HTTP response");
+    const headers = toHeaders(ok.headers, "HTTP response");
+    let body = null;
+    if (typeof ok.body === "string")
+        body = decodeBase64(ok.body);
+    else if (ok.body !== null && ok.body !== undefined) {
+        throw new Error("HTTP response: `body` must be a base64 string or null");
+    }
+    if (body !== null && body.length > MAX_HTTP_BODY_BYTES) {
+        throw new Error(`HTTP response of ${body.length} bytes exceeds the ${MAX_HTTP_BODY_BYTES} byte limit`);
+    }
+    if (NULL_BODY_STATUS.has(status))
+        body = null;
+    return new Response(body, { status, headers });
+}
+/**
+ * Receives the guest's response writes. `start` builds the Response (its body is a ReadableStream
+ * fed by `write`); `write` waits while the client lags more than ~1 MiB behind, and fails once the
+ * client cancelled the response, so the guest stops producing.
+ */
+export class HttpSink {
+    head;
+    requestBody;
+    /** Resolves when the guest sent `httpStart`. */
+    started;
+    /** Set by `start`. */
+    response = null;
+    cancelled = false;
+    resolveStarted;
+    controller;
+    waiting = [];
+    written = 0;
+    ended = false;
+    constructor(head, requestBody) {
+        this.head = head;
+        this.requestBody = requestBody;
+        this.started = new Promise((resolve) => {
+            this.resolveStarted = resolve;
+        });
+    }
+    release() {
+        const w = this.waiting;
+        this.waiting = [];
+        for (const f of w)
+            f();
+    }
+    /** `httpStart`: validates the head and creates the streaming Response. */
+    start(status, headers) {
+        if (this.response)
+            throw new Error("httpStart: the response was already started");
+        const code = checkStatus(status, "httpStart");
+        if (NULL_BODY_STATUS.has(code)) {
+            throw new Error(`httpStart: status ${code} cannot have a streamed body`);
+        }
+        const h = toHeaders(headers, "httpStart");
+        const stream = new ReadableStream({
+            start: (c) => {
+                this.controller = c;
+            },
+            pull: () => this.release(),
+            cancel: () => {
+                this.cancelled = true;
+                this.release();
+            },
+        }, { highWaterMark: STREAM_HIGH_WATER_BYTES, size: (chunk) => chunk?.byteLength ?? 0 });
+        this.response = new Response(stream, { status: code, headers: h });
+        this.resolveStarted();
+    }
+    /** `httpWrite`: queues bytes for the client; resolves once the queue has room again. */
+    write(bytes) {
+        if (!this.response)
+            throw new Error("httpWrite before httpStart");
+        if (this.ended)
+            throw new Error("httpWrite after the response ended");
+        if (this.cancelled)
+            throw new Error("the client closed the response");
+        this.written += bytes.length;
+        if (this.written > MAX_HTTP_BODY_BYTES) {
+            const e = new Error(`HTTP response exceeds the ${MAX_HTTP_BODY_BYTES} byte limit`);
+            this.fail(e);
+            throw e;
+        }
+        this.controller.enqueue(bytes);
+        const room = this.controller.desiredSize;
+        if (room !== null && room <= 0) {
+            return new Promise((resolve) => this.waiting.push(resolve));
+        }
+        return Promise.resolve();
+    }
+    /** `httpEnd` (and the guest returning): closes the body. */
+    end() {
+        if (!this.response || this.ended)
+            return;
+        this.ended = true;
+        try {
+            this.controller.close();
+        }
+        catch {
+            // already cancelled / errored
+        }
+        this.release();
+    }
+    /** The guest failed after `httpStart`: error the body so the client sees a truncated response. */
+    fail(e) {
+        if (!this.response || this.ended)
+            return;
+        this.ended = true;
+        try {
+            this.controller.error(e);
+        }
+        catch {
+            // already cancelled / errored
+        }
+        this.release();
+    }
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export { runRust, runRustHttp, collectEnviron, PANIC_LOG_PREFIX } from "./host.js";
+export type { HostCtx, RunRustOptions } from "./host.js";

package/dist/runtime/index.js

@@ -0,0 +1 @@
+export { runRust, runRustHttp, collectEnviron, PANIC_LOG_PREFIX } from "./host.js";

package/dist/runtime/intl.d.ts

@@ -0,0 +1,5 @@
+type Json = any;
+/** Offset of `tz` from UTC at `epochMs`, in seconds (east positive). */
+export declare function tzOffsetSeconds(tz: string, epochMs: number): number;
+export declare function intlOp(op: string, args: Json): Json;
+export {};

package/dist/runtime/intl.js

@@ -0,0 +1,69 @@
+// Optional sync ops `intl/*` (contracts/ABI.md): time zones and locale formatting backed by the
+// runtime's `Intl`. A wasm32 guest has no tz database; these never fall back to UTC.
+const dtfCache = new Map();
+function zoneFormat(tz) {
+    let f = dtfCache.get(tz);
+    if (!f) {
+        // Throws RangeError for an unknown zone.
+        f = new Intl.DateTimeFormat("en-US", {
+            timeZone: tz,
+            hourCycle: "h23",
+            year: "numeric",
+            month: "numeric",
+            day: "numeric",
+            hour: "numeric",
+            minute: "numeric",
+            second: "numeric",
+            era: "short",
+        });
+        dtfCache.set(tz, f);
+    }
+    return f;
+}
+/** Offset of `tz` from UTC at `epochMs`, in seconds (east positive). */
+export function tzOffsetSeconds(tz, epochMs) {
+    if (typeof tz !== "string" || tz === "")
+        throw new Error("intl/tzOffset: `tz` must be a non-empty string");
+    if (typeof epochMs !== "number" || !Number.isFinite(epochMs)) {
+        throw new Error("intl/tzOffset: `epochMs` must be a finite number");
+    }
+    const secs = Math.floor(epochMs / 1000);
+    const parts = zoneFormat(tz).formatToParts(new Date(secs * 1000));
+    const get = (t) => parts.find((p) => p.type === t)?.value;
+    let year = Number(get("year"));
+    if ((get("era") ?? "").startsWith("B"))
+        year = 1 - year; // BC: astronomical year numbering
+    // The wall clock read as if it were UTC (setUTCFullYear, since Date.UTC maps years 0..99 to 1900..1999).
+    const d = new Date(0);
+    d.setUTCFullYear(year, Number(get("month")) - 1, Number(get("day")));
+    d.setUTCHours(Number(get("hour")), Number(get("minute")), Number(get("second")), 0);
+    return Math.round((d.getTime() - secs * 1000) / 1000);
+}
+export function intlOp(op, args) {
+    try {
+        if (op === "intl/tzOffset") {
+            return { ok: tzOffsetSeconds(args?.tz, args?.epochMs) };
+        }
+        if (op === "intl/format") {
+            const locale = args?.locale === undefined || args.locale === "" ? undefined : args.locale;
+            const options = args?.options ?? undefined;
+            if (args?.kind === "date") {
+                if (typeof args.value !== "number" || !Number.isFinite(args.value)) {
+                    throw new Error("intl/format: date `value` must be a finite number of epoch milliseconds");
+                }
+                return { ok: new Intl.DateTimeFormat(locale, options).format(new Date(args.value)) };
+            }
+            if (args?.kind === "number") {
+                if (typeof args.value !== "number")
+                    throw new Error("intl/format: number `value` must be a number");
+                return { ok: new Intl.NumberFormat(locale, options).format(args.value) };
+            }
+            throw new Error(`intl/format: unknown kind ${JSON.stringify(args?.kind)}`);
+        }
+        return { error: { message: `unknown sync op ${op}` } };
+    }
+    catch (e) {
+        const m = String(e?.message ?? e);
+        return { error: { message: m.startsWith("intl/") ? m : `${op}: ${m}` } };
+    }
+}

package/dist/runtime/tmpfs.d.ts

@@ -0,0 +1,129 @@
+export declare const TMP_DIR = "/tmp";
+/** Default cap on the allocated bytes of all files. */
+export declare const DEFAULT_TMP_BYTES: number;
+interface Seg {
+    /** Guest address, or -1 when `arr` holds the bytes. */
+    ptr: number;
+    arr?: Uint8Array;
+    cap: number;
+}
+interface Base {
+    ino: number;
+    parent: DirNode | null;
+    atim: bigint;
+    mtim: bigint;
+    ctim: bigint;
+    /** Open descriptors; an unlinked node is released when the last one closes. */
+    open: number;
+    unlinked: boolean;
+}
+interface FileNode extends Base {
+    kind: "file";
+    segs: Seg[];
+    size: number;
+}
+interface DirNode extends Base {
+    kind: "dir";
+    entries: Map<string, Node>;
+}
+type Node = FileNode | DirNode;
+export interface TmpFsOptions {
+    maxBytes?: number;
+    memory: () => WebAssembly.Memory;
+    /** Guest allocator (`convex_alloc`); absent => JS-backed segments. */
+    alloc?: (len: number) => number;
+    /** `convex_free(ptr, len)`; absent => guest segments are only forgotten on reset. */
+    free?: (ptr: number, len: number) => void;
+}
+export declare class TmpFs {
+    maxBytes: number;
+    private opts;
+    private root;
+    private fds;
+    private nextFd;
+    private nextIno;
+    /** Sum of the allocated segment capacities. */
+    used: number;
+    constructor(opts: TmpFsOptions);
+    /** Empties the file system. `release` hands the guest segments back to the guest allocator. */
+    reset(release: boolean): void;
+    private freeTree;
+    private newBase;
+    private mkdir;
+    private mkfile;
+    private segCap;
+    private view;
+    private freeSegs;
+    /** Makes sure the file has segments for `size` bytes; throws ENOSPC beyond the cap or when the guest cannot allocate. */
+    private reserve;
+    /** Copies between the file and `buf`; callers have reserved the range for writes. */
+    private xfer;
+    private zero;
+    private setSize;
+    private release;
+    private dirOf;
+    /** Resolves `path` relative to `dir`. Returns the parent directory, the last name and the node (if it exists). */
+    private walk;
+    private unlinkNode;
+    open(dirfd: number, path: string, oflags: number, rightsBase: bigint, fdflags: number): number;
+    close(fd: number): void;
+    has(fd: number): boolean;
+    private file;
+    read(fd: number, bufs: Uint8Array[], at?: number): number;
+    /** `chunks` are copied before any allocation (an allocation can grow, and so detach, the guest memory). */
+    write(fd: number, chunks: Uint8Array[], at?: number): number;
+    seek(fd: number, offset: bigint, whence: number): number;
+    tell(fd: number): number;
+    truncate(fd: number, size: bigint): void;
+    allocate(fd: number, offset: bigint, len: bigint): void;
+    node(fd: number): Node;
+    stat(dirfd: number, path: string): Node;
+    createDir(dirfd: number, path: string): void;
+    removeDir(dirfd: number, path: string): void;
+    unlink(dirfd: number, path: string): void;
+    rename(oldfd: number, oldPath: string, newfd: number, newPath: string): void;
+    /** Directory listing for `fd_readdir`: `.`, `..`, then the entries in creation order. */
+    list(fd: number): {
+        name: string;
+        node: Node;
+    }[];
+    setTimes(n: Node, atim: bigint | null, mtim: bigint | null): void;
+    fdInfo(fd: number): {
+        filetype: number;
+        append: boolean;
+    };
+}
+/** The `wasi_snapshot_preview1` file-system functions backed by `fs`. Merged into the table of `makeWasi`. */
+export declare function tmpFsImports(fs: TmpFs, memory: () => WebAssembly.Memory): {
+    fd_prestat_get: (fd: number, ptr: number) => number;
+    fd_prestat_dir_name: (fd: number, ptr: number, len: number) => number;
+    path_open: (dirfd: number, _dirflags: number, pathPtr: number, pathLen: number, oflags: number, rightsBase: bigint, _rightsInh: bigint, fdflags: number, outPtr: number) => number;
+    fd_close: (fd: number) => number;
+    fd_read: (fd: number, iov: number, n: number, outPtr: number) => number;
+    fd_pread: (fd: number, iov: number, n: number, off: bigint, outPtr: number) => number;
+    fd_pwrite: (fd: number, iov: number, n: number, off: bigint, outPtr: number) => number;
+    fd_seek: (fd: number, off: bigint, whence: number, outPtr: number) => number;
+    fd_tell: (fd: number, outPtr: number) => number;
+    fd_sync: (fd: number) => number;
+    fd_datasync: (fd: number) => number;
+    fd_advise: (fd: number) => number;
+    fd_allocate: (fd: number, off: bigint, len: bigint) => number;
+    fd_fdstat_get: (fd: number, ptr: number) => number;
+    fd_fdstat_set_flags: (fd: number) => number;
+    fd_filestat_get: (fd: number, ptr: number) => number;
+    fd_filestat_set_size: (fd: number, size: bigint) => number;
+    fd_filestat_set_times: (fd: number, a: bigint, m: bigint, flags: number) => number;
+    path_filestat_get: (fd: number, _flags: number, p: number, l: number, out: number) => number;
+    path_filestat_set_times: (fd: number, _fl: number, p: number, l: number, a: bigint, m: bigint, flags: number) => number;
+    path_create_directory: (fd: number, p: number, l: number) => number;
+    path_remove_directory: (fd: number, p: number, l: number) => number;
+    path_unlink_file: (fd: number, p: number, l: number) => number;
+    path_rename: (ofd: number, op: number, ol: number, nfd: number, np: number, nl: number) => number;
+    path_readlink: () => 28;
+    path_symlink: () => 63;
+    path_link: () => 63;
+    fd_readdir: (fd: number, buf: number, bufLen: number, cookie: bigint, usedPtr: number) => number;
+    /** fd_write for descriptors of this file system (stdout/stderr stay with the caller). */
+    write: (fd: number, iov: number, n: number, outPtr: number) => number;
+};
+export {};