Rust: objects, fetch, timers, crypto and the clock

These calls are in substrio_wasm::platform and have the same behavior and errors as their JavaScript counterparts. An error is an Error whose code is the platform error code, matching the code thrown by the JavaScript call. Read its message with substrio_wasm::db::last_error_message().

Waiting

A Rust call runs on its thread from start to finish. Where JavaScript awaits a promise, Rust waits on a handle. Fetch::wait() waits for one response, sleep(ms) waits for a duration, and run_until_idle() waits until every timer has fired and every fetch has ended. Timers that become due still fire while the call waits.

Timers belong to the function. Setting or clearing one makes no platform call. Waiting does not consume CPU time or count against the CPU limit. The call's wall-time limit still applies and ends the wait with 504 CF_WALL_TIMEOUT, as it does for a JavaScript call.

A fetch still in progress when the call returns is ended, and a pending object reply is dropped. Timers that have not fired are also dropped. JavaScript clears a call's timers the same way.

The calls

A storage value is JSON text, the same form used by JavaScript storage. Either language can read values written by the other. A string is stored with its quotes, so put("name", "\"Ada\"") reads in JavaScript as "Ada".

A request is built with FetchRequest::get(url), FetchRequest::post(url) or FetchRequest::new(method, url), then .header(name, value), .text(body) or .bytes(body). A text body without a Content-Type header is sent as text/plain;charset=UTF-8, as JavaScript sends a string body. A bytes body gets no type. The method is sent in capitals, as JavaScript sends every method, and a request without one is a GET.

A response provides status(), ok(), status_text(), url(), headers(), header(name), body(), and text(). status_text() is the reason phrase the server sent on its status line, such as "Created" for a 201, and JS's statusText is the same text. A server that sends no phrase gives an empty string. Header names are lower case, and a repeated name's values are joined with ", ".

A fetch uses the same platform implementation as JavaScript, including the private-address restrictions, allowances, and limits (cf_fetch_limit, cf_fetch_bytes_mb, and the response size limit). A fenced sandbox keeps the request in its outbox, and a test tenant's stubs respond as they do for JavaScript.

Object classes in Rust

A Rust function can export durable object classes, as a JavaScript module exports a class. Each class has a fetch handler, an alarm handler, or both. They are exported once, with export_object!, beside export!.

use substrio_wasm::platform::{self as p, AlarmInfo, ObjectState};

fn room_fetch(state: &ObjectState, req: &Request, _env: &Env) -> Response {
    let storage = state.storage().unwrap();
    let n = storage.get("n").unwrap().and_then(|v| v.parse::<u64>().ok()).unwrap_or(0) + 1;
    storage.put("n", &n.to_string()).unwrap();
    Response::text(200, &format!("{} {}", req.method(), n))
}
fn room_alarm(state: &ObjectState, _info: &AlarmInfo, _env: &Env) -> Result<(), db::Error> {
    state.storage()?.delete_all()
}
substrio_wasm::export_object!(Room { fetch: room_fetch, alarm: room_alarm });

The class name is its identifier, as with a JavaScript class. Any function in the app can access it through objects("Room") in Rust or substrio.objects.Room in JavaScript. Both address the same object for the same id.

A Rust class turn runs like a JavaScript turn. The object has one home thread, its turns run one at a time, and storage writes are applied before its reply. state.storage() gives the object's storage, state.id() its id, and state.class_name() its class. fetch receives the stub's request and returns a response. alarm receives AlarmInfo (retry_count and is_retry), and an Err is retried like a thrown JavaScript alarm. A class without fetch or alarm refuses the corresponding turn with the same message as JavaScript.

A turn that calls the stub of the object it runs for is refused with INVALID_ARGUMENT, because the call would wait for the turn that made it. JavaScript refuses it too.

A function whose code fetches, sleeps or calls an object is always run on the server's function threads. A thread that serves connections never runs it, so a slow upstream never holds other requests. An object's home thread is one of the function threads too, so a turn that waits never holds a connection thread.

The classes are read from the compiled module when the function is deployed. A module that names a class without exporting its turns, or exports turns without naming a class, is refused, and so is a class name that is not an identifier (letters, digits, _ and $, not starting with a digit). export_object! writes both parts, so a function that uses it is never refused for this.

Refusals

Example

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

fn fetch(_req: &Request, _env: &Env, _ctx: &Ctx) -> Response {
    let rooms = match p::objects("Room") {
        Ok(ns) => ns,
        Err(e) => return Response::json(500, format!("{{\"code\":{}}}", e.code)),
    };
    let id = rooms.id_from_name("lobby").unwrap();
    let pending = rooms.get(&id).unwrap().fetch(&FetchRequest::post("https://room/join").text("ada")).unwrap();
    let started = p::performance_now();
    match pending.wait() {
        Ok(r) => Response::json(200, format!("{{\"status\":{},\"ms\":{}}}", r.status(), p::performance_now() - started)),
        Err(e) => Response::json(500, format!("{{\"code\":{}}}", e.code)),
    }
}
substrio_wasm::export!(fetch);

The Room class is exported by a JavaScript function of the same app. The Rust function calls its fetch and reads the reply as it reads any response.

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