convex-rust 0.0.0-stage → 0.1.0

package/dist/cli/symbols.js

@@ -0,0 +1,133 @@
+/**
+ * Function-name map for the deployed wasm. The shipped wasm has its name section stripped (wasm-opt without -g),
+ * so the names are captured at build time and kept next to cargo's target dir, never in the deployed bundle.
+ * `convex-rust symbolize` uses them to rewrite `wasm-function[123]:0x...` frames from Convex logs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { readLeb } from "./size.js";
+import { demangle } from "./demangle.js";
+const dec = new TextDecoder();
+/** Function names (subsection 1) of the "name" custom section, by function index. */
+export function parseNameSection(wasm) {
+    const out = new Map();
+    let pos = 8;
+    while (pos < wasm.length) {
+        const id = wasm[pos++];
+        let size;
+        [size, pos] = readLeb(wasm, pos);
+        const end = pos + size;
+        if (id === 0) {
+            let len;
+            let p;
+            [len, p] = readLeb(wasm, pos);
+            if (dec.decode(wasm.subarray(p, p + len)) === "name") {
+                p += len;
+                while (p < end) {
+                    const sub = wasm[p++];
+                    let subSize;
+                    [subSize, p] = readLeb(wasm, p);
+                    const subEnd = p + subSize;
+                    if (sub === 1) {
+                        let n;
+                        [n, p] = readLeb(wasm, p);
+                        for (let i = 0; i < n; i++) {
+                            let idx;
+                            let l;
+                            [idx, p] = readLeb(wasm, p);
+                            [l, p] = readLeb(wasm, p);
+                            out.set(idx, dec.decode(wasm.subarray(p, p + l)));
+                            p += l;
+                        }
+                    }
+                    p = subEnd;
+                }
+            }
+        }
+        pos = end;
+    }
+    return out;
+}
+/** Parses `wasm-opt --print-function-map` output (`index:name` per line). */
+export function parseFunctionMap(text) {
+    const out = new Map();
+    for (const line of text.split("\n")) {
+        const m = line.match(/^(\d+):(.+)$/);
+        if (m)
+            out.set(Number(m[1]), m[2].trim());
+    }
+    return out;
+}
+export function buildSymbolMap(names, info) {
+    const out = {};
+    for (const [idx, n] of [...names].sort((a, b) => a[0] - b[0]))
+        out[String(idx)] = demangle(n);
+    return { version: 1, wasm: info.wasm, modules: info.modules, names: out };
+}
+export function symbolsDir(targetDir) {
+    return path.join(targetDir, "convex-rust-symbols");
+}
+/** Replaces the maps in `dir` with `maps` (stale ones removed). */
+export function writeSymbolMaps(dir, maps) {
+    fs.mkdirSync(dir, { recursive: true });
+    const keep = new Set(maps.map((m) => `${m.wasm}.json`));
+    for (const f of fs.readdirSync(dir)) {
+        if (f.endsWith(".wasm.json") && !keep.has(f))
+            fs.rmSync(path.join(dir, f), { force: true });
+    }
+    return maps.map((m) => {
+        const file = path.join(dir, `${m.wasm}.json`);
+        fs.writeFileSync(file, JSON.stringify(m));
+        return file;
+    });
+}
+export function readSymbolMaps(dir) {
+    let files = [];
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith(".wasm.json")).sort();
+    }
+    catch {
+        return [];
+    }
+    return files.map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")));
+}
+const FRAME = /wasm-function\[(\d+)\](:0x[0-9a-fA-F]+)?/g;
+/**
+ * Rewrites `wasm-function[N]:0xOFF` into `name (wasm-function[N]:0xOFF)`. With several maps, `module` picks one;
+ * otherwise a module named like `rust/<module>` in the text does, if exactly one does.
+ */
+export function symbolize(text, maps, module) {
+    if (maps.length === 0)
+        return { text, replaced: 0, note: "no symbol maps found (run `convex-rust build` first)" };
+    let map;
+    let note;
+    if (maps.length === 1)
+        map = maps[0];
+    else if (module) {
+        map = maps.find((m) => m.modules.includes(module) || m.wasm.replace(/\.wasm$/, "").endsWith(`.${module.replace(/\//g, "__")}`));
+        if (!map)
+            note = `no symbol map for module "${module}" (have: ${maps.flatMap((m) => m.modules).join(", ")})`;
+    }
+    else {
+        const seen = new Set();
+        for (const m of maps)
+            for (const mod of m.modules)
+                if (text.includes(`rust/${mod}`))
+                    seen.add(m);
+        if (seen.size === 1)
+            map = [...seen][0];
+        else
+            note = `several wasm modules were built; pass --module <name> (one of: ${maps.flatMap((m) => m.modules).join(", ")})`;
+    }
+    if (!map)
+        return { text, replaced: 0, ...(note ? { note } : {}) };
+    let replaced = 0;
+    const out = text.replace(FRAME, (all, idx) => {
+        const n = map.names[idx];
+        if (!n)
+            return all;
+        replaced++;
+        return `${n} (${all})`;
+    });
+    return { text: out, replaced };
+}

package/dist/cli/toolchain.d.ts

@@ -0,0 +1,53 @@
+export declare const RUST_TARGET = "wasm32-wasip1";
+export interface ExecResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: {
+        code?: string;
+    } | Error | undefined;
+}
+export type Exec = (cmd: string, args: string[], opts: {
+    cwd: string;
+    inherit?: boolean;
+}) => ExecResult;
+export declare const defaultExec: Exec;
+export type ToolchainStatus = {
+    ok: true;
+} | {
+    ok: false;
+    kind: "no-cargo" | "no-rustup" | "no-toolchain" | "no-target";
+    message: string;
+    /** Command that fixes it (for no-target / no-toolchain). */
+    fix?: string[];
+};
+/** `channel` from `<rustDir>/rust-toolchain.toml`, if any. */
+export declare function readToolchainChannel(rustDir: string): string | null;
+export declare function checkRustToolchain(rustDir: string, exec?: Exec, target?: string): ToolchainStatus;
+/** Install hint for binaryen's `wasm-opt` for the current platform. */
+export declare function wasmOptInstallHint(platform?: string): string;
+/**
+ * When the toolchain check failed with a fixable cause (`status.fix`) and a person is at the terminal,
+ * offers to run the fix (`Run ... now? (Y/n)`), then re-checks. Never installs anything without an
+ * answer: without a TTY (CI) or when declined the original failing status is returned.
+ */
+export declare function offerToolchainFix(rustDir: string, status: ToolchainStatus, o?: {
+    interactive?: boolean;
+    ask?: (question: string) => Promise<string>;
+    exec?: Exec;
+    log?: (m: string) => void;
+}): Promise<ToolchainStatus>;
+export interface DoctorLine {
+    ok: boolean;
+    /** Missing but not fatal (wasm-opt). */
+    optional?: boolean;
+    text: string;
+}
+/** Environment report for `convex-rust doctor`. `ok` is false when a required piece is missing. */
+export declare function doctorReport(rustDir: string | null, exec?: Exec, extra?: {
+    convexFnPath?: string | undefined;
+    functionsDirExists?: boolean;
+}): {
+    ok: boolean;
+    lines: DoctorLine[];
+};

package/dist/cli/toolchain.js

@@ -0,0 +1,167 @@
+import path from "path";
+import nodeFs from "fs";
+import { spawnSync } from "child_process";
+export const RUST_TARGET = "wasm32-wasip1";
+export const defaultExec = (cmd, args, opts) => {
+    const r = spawnSync(cmd, args, {
+        cwd: opts.cwd,
+        encoding: "utf8",
+        stdio: opts.inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    return {
+        status: r.status,
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? "",
+        error: r.error,
+    };
+};
+/** `channel` from `<rustDir>/rust-toolchain.toml`, if any. */
+export function readToolchainChannel(rustDir) {
+    for (const f of ["rust-toolchain.toml", "rust-toolchain"]) {
+        try {
+            const text = nodeFs.readFileSync(path.join(rustDir, f), "utf8");
+            const m = text.match(/^\s*channel\s*=\s*"([^"]+)"/m);
+            if (m)
+                return m[1];
+            const bare = text.trim();
+            if (f === "rust-toolchain" && bare && !bare.includes("\n"))
+                return bare;
+        }
+        catch {
+            // not present
+        }
+    }
+    return null;
+}
+const RUSTUP_URL = "https://rustup.rs";
+export function checkRustToolchain(rustDir, exec = defaultExec, target = RUST_TARGET) {
+    const notFound = (r) => r.error?.code === "ENOENT";
+    const cargo = exec("cargo", ["--version"], { cwd: rustDir });
+    const rustup = exec("rustup", ["--version"], { cwd: rustDir });
+    if (notFound(rustup)) {
+        if (notFound(cargo)) {
+            return {
+                ok: false,
+                kind: "no-cargo",
+                message: `Neither \`cargo\` nor \`rustup\` was found. Install Rust with rustup: ${RUSTUP_URL}\nThen re-run this command (the ${target} target will be set up for you).`,
+            };
+        }
+        return {
+            ok: false,
+            kind: "no-rustup",
+            message: `\`rustup\` was not found, so the ${target} target can't be verified. Install rustup: ${RUSTUP_URL}\n(If you manage Rust another way, make sure the ${target} target is installed.)`,
+        };
+    }
+    if (notFound(cargo)) {
+        return {
+            ok: false,
+            kind: "no-cargo",
+            message: `\`cargo\` was not found. Install Rust with rustup: ${RUSTUP_URL}`,
+        };
+    }
+    const channel = readToolchainChannel(rustDir);
+    const toolchainArgs = channel ? ["--toolchain", channel] : [];
+    const list = exec("rustup", ["target", "list", "--installed", ...toolchainArgs], { cwd: rustDir });
+    if (list.status !== 0) {
+        const fix = [
+            "rustup",
+            "toolchain",
+            "install",
+            channel ?? "stable",
+            "--profile",
+            "minimal",
+            "--target",
+            target,
+        ];
+        if (/not installed|no such toolchain|is not installed/i.test(list.stderr)) {
+            return {
+                ok: false,
+                kind: "no-toolchain",
+                message: `The Rust toolchain \`${channel ?? "stable"}\` is not installed. Run:\n  ${fix.join(" ")}`,
+                fix,
+            };
+        }
+        // Unknown rustup failure: don't block the build, cargo will report it.
+        return { ok: true };
+    }
+    const installed = list.stdout.split("\n").map((l) => l.trim());
+    if (installed.includes(target))
+        return { ok: true };
+    const fix = ["rustup", "target", "add", target, ...toolchainArgs];
+    return {
+        ok: false,
+        kind: "no-target",
+        message: `The ${target} Rust target is not installed${channel ? ` for toolchain ${channel}` : ""}. Run:\n  ${fix.join(" ")}`,
+        fix,
+    };
+}
+/** Install hint for binaryen's `wasm-opt` for the current platform. */
+export function wasmOptInstallHint(platform = process.platform) {
+    if (platform === "darwin")
+        return "brew install binaryen";
+    if (platform === "win32")
+        return "npm install --save-dev binaryen (or scoop install binaryen)";
+    return "apt install binaryen / dnf install binaryen / npm install --save-dev binaryen";
+}
+/**
+ * When the toolchain check failed with a fixable cause (`status.fix`) and a person is at the terminal,
+ * offers to run the fix (`Run ... now? (Y/n)`), then re-checks. Never installs anything without an
+ * answer: without a TTY (CI) or when declined the original failing status is returned.
+ */
+export async function offerToolchainFix(rustDir, status, o = {}) {
+    if (status.ok || !status.fix)
+        return status;
+    const exec = o.exec ?? defaultExec;
+    const interactive = o.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!interactive)
+        return status;
+    const ask = o.ask ??
+        (async (q) => {
+            const rl = (await import("node:readline/promises")).createInterface({ input: process.stdin, output: process.stderr });
+            try {
+                return await rl.question(q);
+            }
+            finally {
+                rl.close();
+            }
+        });
+    const cmd = status.fix.join(" ");
+    const answer = (await ask(`${status.message.split("\n")[0]}\nRun \`${cmd}\` now? (Y/n) `)).trim().toLowerCase();
+    if (answer !== "" && answer !== "y" && answer !== "yes")
+        return status;
+    const r = exec(status.fix[0], status.fix.slice(1), { cwd: rustDir, inherit: true });
+    if (r.status !== 0)
+        return status;
+    return checkRustToolchain(rustDir, exec);
+}
+/** Environment report for `convex-rust doctor`. `ok` is false when a required piece is missing. */
+export function doctorReport(rustDir, exec = defaultExec, extra = {}) {
+    const lines = [];
+    const ver = (cmd, args = ["--version"]) => {
+        const r = exec(cmd, args, { cwd: rustDir ?? process.cwd() });
+        return r.status === 0 ? r.stdout.trim().split("\n")[0] : null;
+    };
+    const cargo = ver("cargo");
+    lines.push({ ok: cargo !== null, text: cargo ? `cargo: ${cargo}` : "cargo not found. Install Rust with rustup: https://rustup.rs" });
+    const rustup = ver("rustup");
+    lines.push({ ok: rustup !== null, text: rustup ? `rustup: ${rustup.split(" (")[0]}` : "rustup not found. Install it from https://rustup.rs" });
+    if (rustDir && cargo && rustup) {
+        const st = checkRustToolchain(rustDir, exec);
+        const channel = readToolchainChannel(rustDir);
+        lines.push({
+            ok: st.ok,
+            text: st.ok ? `toolchain ${channel ?? "default"} with ${RUST_TARGET}` : st.message,
+        });
+    }
+    if (extra.convexFnPath !== undefined) {
+        const has = nodeFs.existsSync(path.join(extra.convexFnPath, "Cargo.toml"));
+        lines.push({ ok: has, text: has ? `convex_fn: ${extra.convexFnPath}` : `convex_fn not found at ${extra.convexFnPath}. Reinstall convex-rust (npm install convex-rust).` });
+    }
+    const wo = ver("wasm-opt");
+    lines.push({
+        ok: wo !== null,
+        optional: true,
+        text: wo ? `wasm-opt: ${wo}` : `wasm-opt not found (optional: smaller wasm). Install: ${wasmOptInstallHint()}`,
+    });
+    return { ok: lines.every((l) => l.ok || l.optional), lines };
+}

package/dist/cli/validators.d.ts

@@ -0,0 +1,6 @@
+export declare function validatorToTs(j: any): string;
+/** `{ a: v.string(), b: v.optional(v.number()) }` */
+export declare function objectFields(fields: Record<string, {
+    fieldType: any;
+    optional: boolean;
+}>): string;

package/dist/cli/validators.js

@@ -0,0 +1,66 @@
+// ValidatorJson (the shape `v.*().json` produces) -> TypeScript source using `v`.
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function key(k) {
+    return IDENT.test(k) ? k : JSON.stringify(k);
+}
+function int64FromJson(b64) {
+    const bytes = Buffer.from(b64, "base64");
+    if (bytes.length !== 8)
+        throw new Error(`bad $integer literal ${b64}`);
+    return bytes.readBigInt64LE(0);
+}
+function literal(value) {
+    if (value === null)
+        return "v.null()";
+    if (value && typeof value === "object" && typeof value.$integer === "string") {
+        return `v.literal(${int64FromJson(value.$integer)}n)`;
+    }
+    if (typeof value === "string" || typeof value === "boolean") {
+        return `v.literal(${JSON.stringify(value)})`;
+    }
+    if (typeof value === "number")
+        return `v.literal(${JSON.stringify(value)})`;
+    throw new Error(`unsupported literal validator ${JSON.stringify(value)}`);
+}
+export function validatorToTs(j) {
+    switch (j?.type) {
+        case "null":
+            return "v.null()";
+        case "number":
+            return "v.number()";
+        case "bigint":
+            return "v.int64()";
+        case "boolean":
+            return "v.boolean()";
+        case "string":
+            return "v.string()";
+        case "bytes":
+            return "v.bytes()";
+        case "any":
+            return "v.any()";
+        case "literal":
+            return literal(j.value);
+        case "id":
+            return `v.id(${JSON.stringify(j.tableName)})`;
+        case "array":
+            return `v.array(${validatorToTs(j.value)})`;
+        case "record":
+            return `v.record(${validatorToTs(j.keys)}, ${validatorToTs(j.values.fieldType)})`;
+        case "union":
+            if (j.value.length === 1)
+                return validatorToTs(j.value[0]);
+            return `v.union(${j.value.map(validatorToTs).join(", ")})`;
+        case "object":
+            return `v.object(${objectFields(j.value)})`;
+        default:
+            throw new Error(`unsupported validator type ${JSON.stringify(j?.type)}`);
+    }
+}
+/** `{ a: v.string(), b: v.optional(v.number()) }` */
+export function objectFields(fields) {
+    const parts = Object.entries(fields).map(([name, f]) => {
+        const t = validatorToTs(f.fieldType);
+        return `${key(name)}: ${f.optional ? `v.optional(${t})` : t}`;
+    });
+    return parts.length === 0 ? "{}" : `{ ${parts.join(", ")} }`;
+}

package/dist/cli/wasisdk.d.ts

@@ -0,0 +1,82 @@
+export declare const WASI_SDK_VERSION = "34.0";
+/** Pinned release archives (sha256 as published by GitHub for the release assets). */
+export declare const WASI_SDK_ASSETS: Record<string, {
+    file: string;
+    sha256: string;
+    size: number;
+}>;
+type Env = Record<string, string | undefined>;
+/** `~/.cache/convex-rust` (override: `CONVEX_RUST_CACHE_DIR`; honours `XDG_CACHE_HOME`). */
+export declare function cacheRoot(env?: Env): string;
+export declare function cachedSdkDir(env?: Env): string;
+/** True when `dir` looks like a wasi-sdk (clang + sysroot). */
+export declare function isWasiSdk(dir: string): boolean;
+export type SdkSource = "env" | "cache";
+/** `WASI_SDK_PATH` first, then the cache dir. Null when neither holds a usable SDK. */
+export declare function findWasiSdk(env?: Env): {
+    dir: string;
+    source: SdkSource;
+} | null;
+/**
+ * Environment that points cc-rs at the SDK. Variables the user already set are left alone.
+ * `clang` is used as `ar` fallback only when `llvm-ar` is missing.
+ */
+export declare function wasiSdkEnv(sdkDir: string, env?: Env): Record<string, string>;
+/** Subset of `cargo metadata` used to spot C build scripts. */
+export interface MetadataLite {
+    packages: {
+        id: string;
+        name: string;
+    }[];
+    resolve?: {
+        nodes: {
+            id: string;
+            deps: {
+                name: string;
+                pkg: string;
+                dep_kinds?: {
+                    kind: string | null;
+                }[];
+            }[];
+        }[];
+    } | null;
+}
+/**
+ * Crates in the resolved (target-filtered) graph whose build script uses a C compiler driver
+ * (`cc`, `cmake`, `bindgen` is not counted). Their names, sorted.
+ */
+export declare function crateNamesWithCBuild(meta: MetadataLite): string[];
+export declare function assetForPlatform(platform?: string, arch?: string): {
+    file: string;
+    sha256: string;
+    size: number;
+} | null;
+export interface InstallOptions {
+    env?: Env;
+    log?: (m: string) => void;
+    /** Test hook: replaces `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Downloads the pinned wasi-sdk into the cache dir (sha256 checked) and returns its directory.
+ * An archive already present in `<cache>/dl` with the right hash is reused.
+ */
+export declare function installWasiSdk(opts?: InstallOptions): Promise<string>;
+export type WasiSdkMode = "auto" | "always" | "never";
+/** `--wasi-sdk` / `--no-wasi-sdk` / `CONVEX_RUST_WASI_SDK=1|0`. Default: auto (download only if a C build is detected). */
+export declare function wasiSdkMode(flags: {
+    wasiSdk?: boolean;
+    noWasiSdk?: boolean;
+}, env?: Env): WasiSdkMode;
+/**
+ * Decides the cargo environment for C compilation. Uses an SDK that is already there (always, it is free);
+ * downloads one only when `mode` is "always", or "auto" and `cNames` (crates with a C build script) is non-empty.
+ */
+export declare function prepareWasiSdk(args: {
+    mode: WasiSdkMode;
+    cNames: () => Promise<string[]> | string[];
+    env?: Env;
+    log: (m: string) => void;
+    install?: typeof installWasiSdk;
+}): Promise<Record<string, string>>;
+export {};