Wasm functions (Rust)

You send its source and nothing else: the server compiles it to WebAssembly and then to native code when you deploy it. No toolchain is needed where you write it, so a function can be written and deployed from a phone through MCP. It is routed, gated, limited, counted and logged exactly as a JavaScript function is, and it gets the same request and gives back the same kind of response. It is written against the substrio_wasm crate (packages/substrio-wasm), which the server provides.

Wasm functions suit computational work such as parsing, encoding, hashing, scoring, and processing images or text. JavaScript is a choice for code that mostly calls the platform.

A function

#![no_std]
extern crate alloc;
use alloc::format;
use substrio_wasm::{Ctx, Env, Request, Response};

fn fetch(req: &Request, env: &Env, _ctx: &Ctx) -> Response {
    let name = req.param("name").unwrap_or("world");
    let greeting = env.get("GREETING").unwrap_or("Hello");
    Response::text(200, &format!("{greeting}, {name}!"))
}

substrio_wasm::export!(fetch);

fetch(request, env, ctx) is the JavaScript entry's shape. export! writes the module's three exports (substrio_in, substrio_alloc, substrio_fetch). The crate has no dependencies and brings its own allocator (blocks up to 64 KiB in power-of-two classes, larger ones as exact runs of 64 KiB pages, so a 70 MiB body takes about 70 MiB of the function's memory limit) and panic handler. A function is one source file (#![no_std], with alloc); it can use the crate, core and alloc, and no other crate.

Deploy

Send the source. Over MCP or the API, function.deploy (POST /v1/deploy) takes it as text in rust in place of script:

{ "name": "hello", "rust": "#![no_std]\nextern crate alloc;\n...\nsubstrio_wasm::export!(fetch);\n",
  "routes": ["GET /hello/:name"], "vars": { "GREETING": "Hi" } }

With the CLI, put the source in functions/ with its routes beside it, as for a JavaScript function, and run substrio deploy. The file functions/hello.json holds routes and tools only. The vars of the function are declared in substrio.toml:

functions/hello.rs
functions/hello.json    { "routes": ["GET /hello/:name"] }
substrio.toml           [functions.hello]  vars = { GREETING = "Hi" }

The answer's function.kind is "wasm". A function keeps its name and its routes when it moves between JavaScript and Rust. function.update takes rust the same way.

At deploy the server compiles the source in two steps, each confined in the tools jail (one process, no network, nothing of the host's but what the step needs, read-only):

1. rustc (from the release, rust/) compiles it with the crate into WebAssembly. Its flags are the platform (rust/ARGS, the same the crate was built with): --edition 2021, -C opt-level=3, -C codegen-units=1, -C panic=abort. It has 120 s of time and CPU and 4 GiB of memory.
2. substrio_wasmc links it, validates the module against the platform ABI, translates it to C and compiles that to native code for the server's CPU.

The compiled code is kept by the source's content address (GxHash-128) and the toolchain's version, so a source already compiled on a node is never compiled again: deploying it again, or to another app, answers from the cache. A new release with another toolchain compiles each function once more, on its first call.

substrio_wasmc and rust/ ship in the release beside the server; the server links neither. A release is built on a host with LLVM 19's static libraries (Debian llvm-19-dev, libclang-19-dev, liblld-19-dev and libpolly-19-dev) and the one Rust toolchain the release pins, a dated nightly with its rust-src component (SUBSTRIO_RUST_TOOLCHAIN in scripts/release/keys.sh: rustup toolchain install nightly-2026-10-20 --component rust-src). A function is compiled for wasm64-unknown-unknown, which has no prebuilt standard library, so scripts/release/rust.sh builds core and alloc for it from that source and bundles them with the compiler and the C library it runs on, once per toolchain version.

A function's memory is 64-bit (memory64), so the app's store fits in its address space (below). Each instance reserves an address space of 2^41 bytes (SUBSTRIO_WASM_SPACE_BITS, set when the release is built), which is virtual and not memory: a 5-level-paging host holds about 32,000 of them. The store is mapped from 64 GiB upward in that space, so about 1.94 TiB of an app's store can be read directly. A module compiled for another space, or for the 32-bit ABI before it, is refused when it is loaded and compiled again from its source before it runs.

Edit in place

An agent edits a Rust function as it edits a JavaScript one: function.source.read to read it, function.source.preview then function.source.edit for a range of lines or bytes, function.source.replace for the whole source (in rust: a replace keeps the function's language, and script on a Rust function is refused with 400). Every one compiles the edited source exactly as a deploy does, before anything is stored: an edit that does not compile is refused with RUST_COMPILE_FAILED and rustc's diagnostics (a preview already refuses it), and the function keeps serving its last source. An edit that compiles serves from the next call:

POST  /v1/functions/hello/source/preview   { "start_line": 4, "end_line": 5, "replacement": "    Response::text(200, \"hi\")\n" }
PATCH /v1/functions/hello/source           { "start_line": 4, "end_line": 5, "replacement": "...", "approval_token": "<the preview's>" }

The request

Request is read in place: nothing in it is parsed or copied on a call.

No header that carries a key and no Substrio-Caller header reaches a function, as for JavaScript.

The response

Response::new(status), Response::text(status, &str) (Content-Type text/plain;charset=UTF-8, the Fetch standard's type for text; a JavaScript function answering new Response(text) with no Content-Type of its own is sent as application/json on this platform, so its twin of Response::text names the type), Response::json(status, bytes) (Content-Type application/json, as Response.json), then .header(name, value), .content_type(value), .body(Vec<u8>) or body_mut(). The platform sends it from the module's own memory.

env, ctx and the platform

ctx is the call's context. In this release it carries nothing more than the request does.

The database

substrio_wasm::db provides the JavaScript function db API with Rust names such as find_by_id for findById. Reads access storage directly without HTTP, JSON, or a copy. The app's store is mapped read-only into the function's address space, and values are read where they are stored.

use substrio_wasm::db;

let people = db::collection("people")?;
match people.find_by_id(id, |row| row.to_json())? {
    Some(json) => Response::json(200, json),
    None => Response::json(404, "null"),
}

A read takes a closure and returns its result. Another call can change a row while it is being read. When the closure returns, the read verifies that each row is unchanged and runs the closure again on the current row if it changed. JavaScript reads perform the same check. A row and its values are valid within the closure, so copy out anything you need to keep with String::from or to_json. A read inside another read's closure returns INVALID_ARGUMENT.

row.get("name") and row.field(f) return a Value: Null, Bool, Int, Double, Date (milliseconds), Str, Decimal and BigInt (their text), Binary, ObjectId, Vector (a vector field's floats), Object and Array. A text or binary value is a slice of the stored bytes and a number is read where it is stored. Object(o).fields() and Array(a).elements() read a nested value the same way. row.fields() walks the fields in their stored order, row.id() is the _id, and row.to_json() writes the row in the platform JSON format (a date as its milliseconds, binary as base64).

A row contains the same fields as a JavaScript row. Fields declared secret are excluded from both. Read a secret with db.secret from JavaScript.

Writes

A write takes a document as JSON object text and reads it from the function's memory. Each write uses the same code as its JavaScript equivalent. Indexing, realtime publication, quota accounting, and errors therefore follow the same rules. As with JavaScript, a write blocks while another call has a db.transaction open.

let people = db::collection("people")?;
let id = people.insert(r#"{"name":"Ada","visits":1}"#)?;
people.set(id.as_str(), r#"{"visits":2}"#)?;
people.delete(id.as_str())?;

An expired document is absent to set and delete, as it is to JavaScript. Rust also supports update operators through update(id, &ops) and Update. See writing records from Rust.

Chains

A chain starts at the collection with any chain method and ends at a terminal, as in JavaScript. The crate encodes the steps in a program in the module's memory. The terminal sends that program in one call, where it is decoded into the same plan used by JavaScript. The chain stays usable for another terminal until it is dropped.

use substrio_wasm::db::{self, Order};

let orders = db::collection("orders")?;
let page = orders.eq("status", "paid").gte("total", 100).sort("total", Order::Desc).skip(20).limit(10)
    .all(|row| row.to_json())?;
let paid = orders.eq("status", "paid").count()?;
let revenue = orders.eq("status", "paid").sum("total")?;

A value is a bool, an integer, an f64, a &str, a &[u8] (compared by its bytes) or an Arg (Arg::Null, Arg::Date(ms)). The chain refuses what JavaScript's refuses, with the same code: a filter, sort or fold that names a secret field or an operator given the wrong kind of value. A substring under 3 bytes has no trigram key and can require a record scan; see text conditions. all and first read their rows as find_by_id does, closure and check included: if a writer changed a row while your closure read it, the chain runs again and the closure reads every row again.

KV

db::kv(name) opens the app's KV store name, made at its first write, as db.kv(name) is in JavaScript. A key and a value are bytes, so a &str, a String, a &[u8] or a Vec<u8> can be passed. A value is copied once, straight into a buffer your function holds. No other copy is made, and no buffer is allocated once yours has grown to the largest value it reads.

let views = db::kv("views")?;
views.put("home", "1")?;
let hits = views.increment("hits", 1)?;     // Some(n) once the key holds a number
let home = views.with("home", |v| v.len())?; // reads the value with no Vec of your own

KV cursors

kv.cursor() opens a cursor over the store in key order. Each seek or step is one call that answers the entry it lands on, its key and value together, where JavaScript makes three calls (the step, key() and value()). The cursor is closed when it is dropped, and every cursor still open is closed when the call returns.

let mut cur = db::kv("sessions")?.cursor()?;
let mut entry = cur.seek_prefix("user:7:")?;
while let Some(e) = entry {
    // e.key and e.value are the entry's bytes
    entry = cur.next()?;
}

Each answers Some(Entry { key, value }), or None past either end.

Pages of entries

A page reads many entries in one call. It makes one move and then steps on in that move's direction, and it writes up to n entries back to back into the cursor's buffer. JavaScript has no page, so the same entries there are a seek and its steps, three calls an entry. You read a page's entries in place, and nothing is copied or allocated for them.

let mut cur = db::kv("sessions")?.cursor()?;
let mut page = cur.page_prefix("user:7:", 100)?;
loop {
    let end = page.end();
    for e in page {
        // e.key and e.value are the entry's bytes
    }
    if end {
        break;
    }
    page = cur.page(100)?;
}

A move backwards (page_last, page_prefix_last, page_le, page_lt, page_back, or a seek backwards before page) answers its entries last first. A page under a prefix stays under it. end() is true when the range ended in the page, so the next page is empty. A page can hold fewer than n entries without end() when the buffer ran out of room. The next page(n) carries on from the first entry it left out. An entry too large for the buffer grows it, and the page is read again. An n of 0 is refused with INVALID_ARGUMENT.

SQL

db::sql(text, params) runs one statement over the app's tables, as db.sql(text, params) does, through the same engine and the same plan cache. db::prepare(text) keeps a statement for many runs. A parameter is a Param (Null, Bool, I64, U64, F64, Text or Bytes), and From turns plain values into one. The answer is written straight into your function's memory, one 16-byte cell a value, and the text and bytes of a row are read there with no copy.

use substrio_wasm::db::{self, Param};

db::sql("INSERT INTO orders (item, qty) VALUES (?, ?)", &["book".into(), 2i64.into()])?;
let top = db::prepare("SELECT item, qty FROM orders WHERE qty >= ? ORDER BY qty DESC")?;
for row in top.all(&[Param::I64(2)])?.iter() {
    let item = row.by_name("item").as_str();
}

A value maps as JavaScript maps it: an unsigned column is U64, a binary column is Bytes, and a number, text or null is what the engine holds.

Transactions

db::transaction(|| { ... }) runs the closure as one SQL transaction, as db.transaction(fn) does. A closure that returns Ok commits. A closure that returns Err rolls back and propagates the error. A transaction inside another is a savepoint of the one around it. A collection write inside a transaction is undone with it, as in JavaScript. A KV or graph write inside one is refused with UNSUPPORTED_OPERATION, as JavaScript's is. A transaction your function leaves open when it returns is rolled back.

db::transaction(|| -> Result<(), db::Error> {
    db::sql("UPDATE stock SET qty = qty - 1 WHERE item = ?", &["book".into()])?;
    db::sql("INSERT INTO sales (item) VALUES (?)", &["book".into()])?;
    Ok(())
})?;

The graph

db::graph(label) opens the app's graph label, made at its first edge, as db.graph(label) does. A node is a u32. db::graph_labels() lists the labels the app has.

JavaScript returns an object for the first three operations, such as { label, src, dst, added }. Rust returns the boolean.

Refusals

A failed call returns Err(db::Error { code }). The numeric code corresponds to an error that JavaScript throws by name:

A write rejected for its content returns the code JavaScript throws for the same document: UNIQUE, SCHEMA_REFUSED, TOO_DEEP, RECORD_TOO_LARGE and the other document limits in the function errors table.

What a data call costs

The same reads JavaScript makes come from the same code: src/substrio/runtime/ owns them, and each language only turns its arguments into typed ones and its answers into its own values.

The ABI the crate implements

A module is wasm64 (memory64): it imports from substrio and exports three functions, and every address and length is a u64 in the module's address space (a handle or a flag is a u32).

An invalid step is reported when the terminal runs the encoded chain.

A row carries its record's address once, and each value carries the 32-bit offset and length of its bytes from it in the record-relative representation introduced in ABI 3. A stored value always lies inside its record, and a record is at most 4 GiB less one byte, so the offset is exact. A converted value has the kValueOwn flag, and its offset counts from the row's own head instead. A nested object's or array's entries count from the nested value's own address, which is the at that nested was given. nested refuses a value longer than a record with INVALID_ARGUMENT.

A data import's answer at or above 0xFFFF0000 (a u64 answer: 0xFFFFFFFFFFFF0000) is a refusal, its low 16 bits the error code.

The request head, the answer record and the pair blob (u32 key length, u32 value length, key, value) are laid out in src/substrio/wasm/wasm_abi.h.

Entries

A Rust function answers every entry a JavaScript function does. Each entry is a handler of the shape of fetch, fn(&Request, &Env, &Ctx) -> Response, and you name the ones you write in export!:

substrio_wasm::export!(fetch: fetch, scheduled: scheduled, queue: queue, trigger: trigger, call: call);

export!(handler) is the route-only form and stays as it was. For every entry other than a route, req.text() is the event's JSON, exactly the bytes a JavaScript handler is given as its event, and req.method() is POST.

A cron run, a trigger run and a queue delivery fail, and are retried by that entry's own policy, when the handler traps, hits a limit or answers a status of 400 or more, and a JavaScript handler's does the same when it throws or returns a Response of 400 or more. The answer's body is the run's error. A direct call keeps its status as its answer in both runtimes. Response::with_status(code) changes the status of a response you already built, such as an Outcome's.

A queue has no fallback, because only a consumer written for a batch can settle one. The crate has no JSON reader, so a cron, trigger or call handler reads its event as text. The fixture tests/wasm/fixtures/entries.rs shows each entry.

A queue consumer

A consumer reads its batch with Batch::of(req) and answers an Outcome. Neither costs an allocation beyond the outcome's own, and the guest writes no JSON.

fn queue(req: &Request, _env: &Env, _ctx: &Ctx) -> Response {
    let batch = Batch::of(req);
    let mut outcome = Outcome::with_capacity(batch.len());
    for message in batch.messages() {
        if message.attempts < 3 && !process(message.body) {
            outcome.retry_after(1000);
        } else {
            outcome.ack();
        }
    }
    outcome.into_response()
}

Each call to ack, retry or retry_after is the verdict of the next message, in the order messages() lists them. The answer is 8 bytes a message (one verdict byte and a delay in milliseconds, QueueVerdict in src/substrio/wasm/wasm_abi.h), and the queue reads the bytes where they lie: no JSON is parsed and nothing is allocated. A message the outcome has no word for is retried, as a JavaScript message its consumer did not settle is. A message retried more times than the queue allows is dead-lettered as it is for JavaScript.

An entry the function has no handler for ends as a JavaScript call that throws. The run fails with the message substrio-wasm: this function exports no scheduled or call entry (export!(scheduled: handler)), and its kind's words name what to export. A cron run made by hand returns it as {"outcome":"error","error":...}.

Calls between functions

substrio_wasm::services::call(name, args_json, &mut out) is substrio.functions.<name>(args), and it reaches a Rust function and a JavaScript one alike. A JavaScript function calls a Rust one with substrio.functions.<name>(arg) as it calls a JavaScript one. The arguments are at most one value, sent as JSON, and the answer is the JSON the callee answered, or its text when it is not JSON. The callee runs nested on the caller's thread, for the caller's tenant, as the caller's user, and under the caller's remaining CPU. A callee that runs out of the caller's limit ends the caller too. The depth is limited by jsc.limit_call_depth, and a call inside db.transaction is refused. A name that is not a function of the app is refused with FUNCTION_NOT_FOUND.

Calling a Rust function from JavaScript gives the callee the tenant's CPU and memory limits afresh, because a JavaScript call's own budget belongs to its engine. The caller's wall deadline still ends the call. Calling a JavaScript function from Rust gives the callee a fresh wall timeout of the tenant's, and the caller's deadline is checked when the callee returns.

What an entry costs

In a tenant's cell

A server started with --cells runs a tenant's code in the tenant's own cell, a process the supervisor owns. A Rust function deploys and runs there as it does anywhere else. The server compiles it when it is deployed. Its first call in a cell sends the cell the compiled module and the tenant's CPU, memory and wall limits, and the cell opens the module once. A call then costs the cell's ring and nothing else beyond a Rust call on the server: the request head the server wrote is copied into the module once, and the answer is sent from the module's memory. A change to a limit sends the function to the cell again, and the next call runs under it. The CPU and wall limits end a call in a cell with the same status, code and counter as anywhere else.

A cell holds the tenant's database as a read-only mapping and has no System over it yet. A function in a cell computes with no data calls until the cell's read-only System lands, in Rust and in JavaScript alike. It cannot call the platform. Its first call of db, services, the ledger or any other import of the platform answers WASM_CELL_IMPORT_UNSUPPORTED in the form every refusal of the data surface has (substrio_wasm::db::Error, code 0xC59D), and the function decides what to answer. The code 0xC592, WASM_CELLS_UNSUPPORTED, is retired: no server answers it, and it stays named because published clients map it. A function that computes from its request runs in a cell without change. Until the cell supports platform calls:

• env.get and env.pairs are empty.
• substrio_wasm::api answers that the call has no context.
• auth::check_permission ends the call with the message that it does not run in a cell yet.
• auth::current_user and the request's own auth_json work, because the caller's JSON is in the request.
• A cron run, a queue delivery, a document trigger and a call by another function run on the server, not in a cell.

Limits

Every limit is the JavaScript function's, with the same status, code and counter.

A trap (a panic, unreachable, a memory access out of bounds, a stack overflow) answers 500 CF_EXECUTION_FAILED with the function error a JavaScript throw gives. A panic's message is the error's message. Every call adds to invocations, wall_ns, its status class and its latency bucket; a call under a CPU limit also adds its CPU to cpu_us, as a JavaScript call does (an app with no CPU limit is not metered). The CPU limit is checked every 10 ms: a call ends within 10 ms of CPU past it.

The module keeps its memory between calls, as a JavaScript isolate keeps its globals, and is made again after a trap or a limit ended a call. A function holds one instance for each call it runs at once, on whichever thread runs it, so an instance can serve any thread. There is no limit on how many functions a server holds, and the operating system pages out what is not in use. An instance that has had no calls for 10 minutes is freed, and the next call makes a new one. The jsc.idle_drop_ms platform setting changes that time, and 0 keeps every instance.

A function is compiled once, when it is deployed, and its record stores the address of the compiled module. After the deploy, nothing reads or hashes its source to run it. A release with a new compiler has no compiled file yet, so each function compiles once, at its first call on that release.

Refusals at deploy and edit

Nothing is stored when a deploy is refused.

For example, a type error on line 4:

{ "error": "The Rust source did not compile; the detail is the compiler's own diagnostics, ...",
  "code": "RUST_COMPILE_FAILED", "status": 422, "retryable": false, "next_action": "correct_request",
  "detail": "error[E0308]: mismatched types\n --> src/lib.rs:4:18\n  |\n4 |     let n: u32 = req.path();\n  |            ---   ^^^^^^^^^^ expected `u32`, found `&str`\n ..." }

detail holds the compiler's diagnostics as it printed them. Fix the line and deploy again.

What a call costs

Not in this release

pages() is not available; loop on page with its next token. Live rows, outbound fetch, and timers are not available. See writing records from Rust, platform services from Rust, and ledger from Rust for the supported data and service calls and their limits. A Wasm function can also call registry operations through substrio_wasm::api.

A Wasm function answers every entry (see Entries), but a Rust function and a JavaScript function share one name in an app: a queue is declared by a version, and a version holds JavaScript functions only, so a Rust function consumes a queue after a version names the queue and /v1/deploy replaces its consumer with the Rust source. Its stored source is its Rust, the size the tenant's functions_code_bytes_limit counts. More than one source file, and crates beyond substrio_wasm, come in a later release.

See also Rust functions, the entry page: when to pick Rust, every call exposed to it, deploy and testing.