Services and gates in Rust

Each call in substrio_wasm::services corresponds to a JavaScript call and runs the same platform code. Its result is the same, so a function can move between the two languages without changing that behavior.

Each call crosses into the platform once. A call returning JSON writes it into a Vec<u8> you retain, so a warm call allocates nothing. A result larger than the vector's capacity is returned whole. The service is not run a second time to fill the buffer.

The caller

Gates apply to the caller of the running call. In JavaScript you pass request.auth. Rust has no auth argument because the platform already has the caller's identity, grants, and verified flag. A gate applies to the person who made the request.

Calls

The caller's grants are evaluated first. When the caller has the requested permission everywhere, the gate passes without a lookup. Otherwise, the caller's membership in the organization is read once. held_permissions returns the caller's grants together with that membership, or every bit when the caller has the catalog's all.

collections and a collection's pipeline, stats and drop go through the platform request for that operation. They are rare calls that set up or inspect a collection, and no call on a hot path reaches them. The operation is known in advance, so the platform parses no method and matches no path.

Write a search or a batch of writes as a Rust chain. Chains run directly against the collection, and a search returns rows. The calls are described under Chains.

call runs the other function on the same thread, and that function uses what is left of this call's CPU and wall time. When it runs out of either, this call ends with it, as a chain of JavaScript calls does.

smtp runs the transfer to its end inside the call, because a Rust call has no promise to settle later. The transfer goes through the same outbound fence as JavaScript's and counts against the same cf_fetch_limit.

once stores the reply's JSON text as supplied. When f returns an error, the claim is released and the error is returned, so a retry runs f again. When f panics, the call ends and the platform releases the claim.

Every secret read is written to the audit trail before the value is returned. The value is cleared from the platform buffer after it reaches yours.

Refusals

A failed call returns an Error whose code matches the platform code in the JavaScript error. db::last_error_message() returns its message.

A server's refusal of an SMTP message is a reply with ok false, never an error.

Example

A route that lets a person edit an event when they host it or hold EDIT_EVENTS in its organization, at most 10 times a minute, and queues a notice of the edit:

#![no_std]
extern crate alloc;

use alloc::format;
use alloc::string::ToString;
use substrio_wasm::{db, services, Ctx, Env, Request, Response};

fn fetch(req: &Request, _env: &Env, _ctx: &Ctx) -> Response {
    let run = || -> Result<Response, db::Error> {
        let edit = services::permission("EDIT_EVENTS")?;
        let events = db::collection("events")?;
        let id = req.path().trim_start_matches("/events/");
        let (host, org) = match events.find_by_id(id, |r| {
            let host = r.get("host_user").and_then(|v| v.as_i64()).unwrap_or(0) as u64;
            let org = r.get("org").and_then(|v| v.as_str()).unwrap_or("").to_string();
            (host, org)
        })? {
            Some(found) => found,
            None => return Ok(Response::text(404, "no such event")),
        };
        services::require_person_or_permission(host, edit, &org)?;
        let hit = services::limit(id, 10, 60_000, services::LimitOptions::default())?;
        if !hit.allowed {
            return Ok(Response::text(429, "too many edits"));
        }
        events.set(id, req.text().unwrap_or("{}"))?;
        services::queue("notices")?.send(&format!("{{\"event\":\"{}\"}}", id))?;
        Ok(Response::text(200, "saved"))
    };
    run().unwrap_or_else(|e| Response::json(500, format!("{{\"code\":{}}}", e.code)))
}

substrio_wasm::export!(fetch);

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