convex-rust 0.0.0-stage → 0.1.0

package/dist/cli/generate.js

@@ -0,0 +1,82 @@
+// Generator: manifest entries -> TypeScript wrappers (contracts/V8HOST.md).
+import path from "node:path";
+import { groupByModule } from "./manifest.js";
+import { objectFields, validatorToTs } from "./validators.js";
+export const GENERATED_HEADER = "// @generated by convex-rust. Do not edit.";
+/** Relative import specifier with a leading `./` or `../`, `/` separators. */
+function rel(fromDir, to) {
+    const r = path.posix.relative(fromDir, to) || ".";
+    return r.startsWith(".") ? r : `./${r}`;
+}
+function actionExport(e, env = []) {
+    const builder = e.visibility === "internal" ? "internalAction" : "action";
+    const lines = [`export const ${e.name} = ${builder}({`];
+    const args = e.args;
+    if (args !== null && args !== undefined) {
+        if (args.type !== "object") {
+            throw new Error(`${e.modulePath}::${e.name}: args validator must be an object`);
+        }
+        lines.push(`  args: ${objectFields(args.value)},`);
+    }
+    if (e.returns !== null && e.returns !== undefined) {
+        lines.push(`  returns: ${validatorToTs(e.returns)},`);
+    }
+    const argType = args === null || args === undefined ? "args: any" : "args";
+    lines.push(`  handler: (ctx, ${argType}) => runRust(ctx, wasm, ${JSON.stringify(`convex_run:${e.modulePath}:${e.name}`)}, args${env.length ? `, { env: ${JSON.stringify(env)} }` : ""}),`);
+    lines.push("});");
+    return lines.join("\n");
+}
+const isHttp = (e) => e.kind === "http";
+function httpExport(e, env = []) {
+    return `export const ${e.name} = httpAction((ctx, request) => runRustHttp(ctx, wasm, ${JSON.stringify(`convex_run:${e.modulePath}:${e.name}`)}, request${env.length ? `, { env: ${JSON.stringify(env)} }` : ""}));`;
+}
+function usesValidators(entries) {
+    return entries.some((e) => !isHttp(e) && (e.args != null || e.returns != null));
+}
+// Names the generated file itself uses, plus every ECMAScript reserved word (`export const delete` is a syntax error).
+const RESERVED = new Set([
+    "default", "runRust", "runRustHttp", "wasm", "action", "internalAction", "httpAction", "v",
+    "await", "break", "case", "catch", "class", "const", "continue", "debugger", "delete", "do", "else",
+    "enum", "export", "extends", "false", "finally", "for", "function", "if", "import", "in", "instanceof",
+    "new", "null", "return", "super", "switch", "this", "throw", "true", "try", "typeof", "var", "void",
+    "while", "with", "yield", "let", "static", "implements", "interface", "package", "private", "protected",
+    "public", "arguments", "eval", "undefined", "NaN", "Infinity",
+]);
+/** Generated files, keyed by path relative to the out dir. */
+export function generateFiles(opts) {
+    const out = (opts.outRelToFunctions ?? "rust").replace(/\\/g, "/").replace(/\/+$/, "");
+    const files = new Map();
+    for (const [module, entries] of [...groupByModule(opts.entries)].sort(([a], [b]) => a < b ? -1 : 1)) {
+        for (const e of entries) {
+            if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e.name) || RESERVED.has(e.name)) {
+                throw new Error(`Rust function ${e.modulePath}::${e.name} cannot be exported as a Convex function name.`);
+            }
+        }
+        // File directory relative to the functions dir, e.g. `rust/a`.
+        const fileDir = path.posix.join(out, path.posix.dirname(module));
+        const toOut = (p) => rel(fileDir, path.posix.join(out, p));
+        const toFunctions = (p) => rel(fileDir, p);
+        const builders = [
+            ...(entries.some((e) => !isHttp(e) && e.visibility !== "internal") ? ["action"] : []),
+            ...(entries.some((e) => !isHttp(e) && e.visibility === "internal") ? ["internalAction"] : []),
+            ...(entries.some(isHttp) ? ["httpAction"] : []),
+        ];
+        const mw = opts.moduleWasm?.get(module);
+        const wasmFile = mw?.file ?? opts.wasmFile;
+        const wasmHash = mw?.hash ?? opts.wasmHash;
+        const head = [
+            GENERATED_HEADER,
+            ...(wasmHash ? [`// wasm: ${wasmHash}`] : []),
+            `import { ${builders.join(", ")} } from "${toFunctions("_generated/server")}";`,
+        ];
+        if (usesValidators(entries))
+            head.push('import { v } from "convex/values";');
+        const runtime = [...(entries.some((e) => !isHttp(e)) ? ["runRust"] : []), ...(entries.some(isHttp) ? ["runRustHttp"] : [])];
+        head.push(`import { ${runtime.join(", ")} } from "convex-rust/runtime";`);
+        head.push(`import wasm from "${toOut(`_wasm/${wasmFile}`)}";`);
+        const body = [...entries].sort((a, b) => (a.name < b.name ? -1 : 1)).map((e) => (isHttp(e) ? httpExport(e, opts.env) : actionExport(e, opts.env)));
+        files.set(`${module}.ts`, `${head.join("\n")}\n\n${body.join("\n\n")}\n`);
+    }
+    files.set("_wasm.d.ts", `${GENERATED_HEADER}\ndeclare module "*.wasm" {\n  const m: WebAssembly.Module;\n  export default m;\n}\n`);
+    return files;
+}

package/dist/cli/manifest.d.ts

@@ -0,0 +1,24 @@
+export declare const MANIFEST_SECTION = "convex:manifest";
+export interface RustManifestEntry {
+    abiVersion: number;
+    /** Rust `module_path!()`, e.g. `bench_rust::cpu`. */
+    modulePath: string;
+    name: string;
+    visibility: "public" | "internal";
+    /** `"http"` for `#[http_action]` (an `httpAction`); absent or `"action"` for `#[action]`. */
+    kind?: "action" | "http";
+    args: unknown | null;
+    returns: unknown | null;
+}
+/**
+ * Convex module name for a Rust `module_path!()`: the segments after the crate
+ * name joined by `/` (`bench_rust::cpu` -> `cpu`, `app::a::b` -> `a/b`). The
+ * crate root maps to `lib` (V8HOST.md).
+ */
+export declare function convexModuleName(modulePath: string): string;
+/** Parse manifest text (one JSON entry per line) and validate it. */
+export declare function parseManifestText(text: string): RustManifestEntry[];
+/** Parse the `convex:manifest` custom section(s) out of wasm bytes. */
+export declare function parseManifest(wasm: Uint8Array): RustManifestEntry[];
+/** Group manifest entries by Convex module name (e.g. `cpu`, `a/b`). */
+export declare function groupByModule(entries: RustManifestEntry[]): Map<string, RustManifestEntry[]>;

package/dist/cli/manifest.js

@@ -0,0 +1,75 @@
+// Manifest v1 (contracts/MANIFEST.md): read from the `convex:manifest` custom section.
+export const MANIFEST_SECTION = "convex:manifest";
+/**
+ * Convex module name for a Rust `module_path!()`: the segments after the crate
+ * name joined by `/` (`bench_rust::cpu` -> `cpu`, `app::a::b` -> `a/b`). The
+ * crate root maps to `lib` (V8HOST.md).
+ */
+export function convexModuleName(modulePath) {
+    const segments = modulePath.split("::");
+    if (segments.length < 2)
+        return "lib";
+    return segments.slice(1).join("/");
+}
+/** Parse manifest text (one JSON entry per line) and validate it. */
+export function parseManifestText(text) {
+    const entries = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        entries.push(JSON.parse(trimmed));
+    }
+    const seen = new Set();
+    for (const e of entries) {
+        if (e.abiVersion !== 1) {
+            throw new Error(`Rust manifest has unsupported abiVersion ${e.abiVersion} (this convex-rust supports 1).`);
+        }
+        if (e.abiVersion !== entries[0].abiVersion) {
+            throw new Error(`Rust manifest has mixed abiVersion values (${entries[0].abiVersion} and ${e.abiVersion}).`);
+        }
+        const key = `${e.modulePath}:${e.name}`;
+        if (seen.has(key))
+            throw new Error(`Rust manifest has duplicate function ${key}.`);
+        seen.add(key);
+    }
+    // Crate-root functions are served as module `lib` on this path (V8HOST.md); a real `crate::lib`
+    // module would be the same Convex module, so the two cannot coexist.
+    const root = entries.find((e) => !e.modulePath.includes("::"));
+    const lib = entries.find((e) => e.modulePath.split("::").length === 2 && e.modulePath.split("::")[1] === "lib");
+    if (root && lib) {
+        throw new Error(`Rust functions in the crate root (${root.modulePath}::${root.name}) and in the module \`lib\` (${lib.modulePath}::${lib.name}) both map to the Convex module \`lib\`; move one of them.`);
+    }
+    return entries;
+}
+/** Parse the `convex:manifest` custom section(s) out of wasm bytes. */
+export function parseManifest(wasm) {
+    let module;
+    try {
+        module = new WebAssembly.Module(wasm);
+    }
+    catch (e) {
+        throw new Error(`Invalid WebAssembly module: ${e?.message ?? e}`);
+    }
+    const decoder = new TextDecoder("utf-8");
+    const texts = [];
+    for (const section of WebAssembly.Module.customSections(module, MANIFEST_SECTION)) {
+        texts.push(decoder.decode(section));
+    }
+    const entries = parseManifestText(texts.join("\n"));
+    if (entries.length === 0) {
+        throw new Error("The wasm has no `convex:manifest` entries: does the crate define any #[action] functions?");
+    }
+    return entries;
+}
+/** Group manifest entries by Convex module name (e.g. `cpu`, `a/b`). */
+export function groupByModule(entries) {
+    const grouped = new Map();
+    for (const e of entries) {
+        const name = convexModuleName(e.modulePath);
+        const list = grouped.get(name) ?? [];
+        list.push(e);
+        grouped.set(name, list);
+    }
+    return grouped;
+}

package/dist/cli/rustApi.d.ts

@@ -0,0 +1,78 @@
+import type { RustManifestEntry } from "./manifest.js";
+type ConvexValidator = any;
+export interface AnalyzedFunction {
+    name: string;
+    udfType: string;
+    visibility: {
+        kind: "public" | "internal";
+    };
+    args: string | null;
+    returns: string | null;
+}
+export interface AnalyzedModule {
+    functions: AnalyzedFunction[];
+}
+export declare const RUST_API_HEADER = "// @generated by `convex-rust`. Do not edit; changes are overwritten.\n//\n// Typed references to your Convex functions for `ctx.run_query`,\n// `ctx.run_mutation` and `ctx.run_action`. Include it from `lib.rs` with\n//\n//     #[path = \"_generated/api.rs\"]\n//     pub mod api;\n#![allow(\n    non_upper_case_globals,\n    non_snake_case,\n    non_camel_case_types,\n    dead_code,\n    unused_imports,\n    clippy::all\n)]\n";
+/** Placeholder `api.rs` until the first codegen fills it in. */
+export declare const RUST_API_STUB = "// @generated by `convex-rust`. Do not edit; changes are overwritten.\n//\n// Typed references to your Convex functions for `ctx.run_query`,\n// `ctx.run_mutation` and `ctx.run_action`. Include it from `lib.rs` with\n//\n//     #[path = \"_generated/api.rs\"]\n//     pub mod api;\n#![allow(\n    non_upper_case_globals,\n    non_snake_case,\n    non_camel_case_types,\n    dead_code,\n    unused_imports,\n    clippy::all\n)]\n\n// No functions yet: this file is filled in by the next `convex-rust build` or `convex-rust codegen`.\n";
+/** A Rust identifier for `name` (a Convex module, function or field name). */
+export declare function rustIdent(name: string): string;
+/** `list_messages` / `listMessages` -> `ListMessages`. */
+export declare function pascalCase(name: string): string;
+interface Generator {
+    /** Struct definitions emitted next to the function reference. */
+    structs: string[];
+}
+/**
+ * Rust type for a validator. Objects become structs named after `hint`
+ * (pushed to `gen.structs`); anything the Rust types can't express exactly
+ * (general unions, mixed literals) becomes `serde_json::Value`.
+ */
+export declare function rustType(v: ConvexValidator, hint: string, gen: Generator): string;
+/** Contents of `api.rs` for the analyzed modules (`messages.js`, ...). */
+export declare function rustApiCodegen(modules: Record<string, AnalyzedModule>): string;
+/** Runs in the subprocess: prints one JSON line `{ [module]: fn[] }`. */
+export declare const ANALYZE_SCRIPT = "\nimport { pathToFileURL } from \"node:url\";\nconst [dir, ...mods] = process.argv.slice(1);\nconst out = {};\nfor (const m of mods) {\n  let ns;\n  try {\n    ns = await import(pathToFileURL(dir + \"/\" + m).href);\n  } catch (e) {\n    process.stderr.write(\"convex-rust: could not load \" + m + \": \" + (e && e.message || e) + \"\\n\");\n    continue;\n  }\n  const fns = [];\n  for (const [name, f] of Object.entries(ns)) {\n    if (typeof f !== \"function\") continue;\n    const udfType = f.isQuery ? \"Query\" : f.isMutation ? \"Mutation\" : f.isAction ? \"Action\" : null;\n    if (udfType === null) continue;\n    const kind = f.isPublic ? \"public\" : f.isInternal ? \"internal\" : null;\n    if (kind === null) continue;\n    let args = null, returns = null;\n    try { args = f.exportArgs(); returns = f.exportReturns(); } catch {}\n    fns.push({ name, udfType, visibility: { kind }, args, returns });\n  }\n  out[m] = fns;\n}\nprocess.stdout.write(\"\\n@@convex-analysis@@\" + JSON.stringify(out) + \"\\n\");\n";
+export declare function parseAnalysisOutput(stdout: string): Record<string, AnalyzedModule> | null;
+/**
+ * TS/JS entry points of the functions directory, following the stock bundler's rules
+ * (skips `_generated`, dotfiles, `schema.*`, files with several dots, component directories).
+ * `skipDirs` are absolute directories to leave out (e.g. the Rust output directory).
+ */
+export declare function findEntryPoints(functionsDir: string, skipDirs?: string[]): string[];
+export interface AnalyzeResult {
+    modules: Record<string, AnalyzedModule>;
+    warnings: string[];
+}
+/**
+ * Analyzes the TS functions under `functionsDir` without a backend: bundles each module with
+ * esbuild (npm packages external, so `convex/server` is the project's), imports the bundles in a
+ * Node subprocess and reads each registered function's visibility and validators. Returns null
+ * when analysis is not possible (callers keep the existing api.rs).
+ */
+export declare function analyzeTsFunctions(projectRoot: string, functionsDir: string, skipDirs?: string[], timeoutMs?: number, log?: (m: string) => void): Promise<AnalyzeResult | null>;
+/** Rust functions (from the wasm manifest) as analysed modules under `<outRel>/<module>.js`. */
+export declare function rustEntriesAsModules(entries: RustManifestEntry[], outRel: string): Record<string, AnalyzedModule>;
+export declare function apiRsPath(crateDir: string): string;
+/** Function paths (`messages:list`) present in an `api.rs`. */
+export declare function functionPathsInApiRs(contents: string): Set<string>;
+export declare function rustSourcesReferenceApi(crateDir: string): boolean;
+export interface ApiRsOptions {
+    projectRoot: string;
+    functionsDir: string;
+    crateDir: string;
+    outDir: string;
+    /** Rust functions from a previous build (cache) or the fresh manifest. */
+    rustEntries?: RustManifestEntry[];
+    log?: (m: string) => void;
+}
+/**
+ * Regenerates `<crate>/src/_generated/api.rs` from the TS functions plus the Rust ones. Only
+ * runs when the file exists or the Rust sources use `api::`. A failed analysis leaves the file
+ * alone. Returns true when the file changed.
+ */
+export declare function updateApiRs(o: ApiRsOptions): Promise<boolean>;
+/** Rust functions of the last build, kept in the cargo target dir so the first compile sees them. */
+export declare function readRustCache(cacheFile: string): RustManifestEntry[];
+export declare function writeRustCache(cacheFile: string, entries: RustManifestEntry[]): void;
+export {};