The ledger and files in Rust

The Rust ledger is substrio_wasm::db::ledger(), corresponding to db.ledger. File operations are in substrio_wasm::files, corresponding to substrio.files. Calls go directly to the platform ledger and file store, without an HTTP request or JSON between the function and the store. The results and error names match the JavaScript calls.

The ledger's entries, its accounts, and its catalog of kinds and categories are described in The ledger. The Rust function itself, its deploy, and its limits are described in Wasm functions (Rust).

The ledger

db::ledger() opens the app's ledger. It returns LEDGER_UNAVAILABLE when the app has no ledger. Kinds and categories are named in the catalog and used by index. Look up an index once with kind(name) or category(name).

An argument JavaScript lets you leave out is an Option in Rust. None is the same as leaving it out, and Some("") is an empty string. A by of None is By::Scope. A limit of None is 50.

A list is read in place from the call's result. Its rows borrow party text from the list, so it uses one buffer and makes no allocation per row. get and entries pass each row to your read closure while it is still in the store's memory. Retain only the fields you read.

Entries

An Entry is built with Entry::new(kind, party, currency, amount, entry_type). Its other members are public fields, and .key(key) sets the idempotency key. The text members are borrowed from your strings, and post sends them to the ledger without a copy. data is JSON text, and it must be an object.

use substrio_wasm::db::{self, ledger::{Entry, EntryType}};

let l = db::ledger()?;
let cash = l.kind("cash")?;
let mut sale = Entry::new(cash, "alice", "USD", 500, EntryType::Credit).key("order-1");
sale.reference = "order-1";
sale.data = r#"{"sku":"A1"}"#;
let posted = l.post(&[sale])?;
let balance = l.balance(cash, "alice", "USD", None)?;

Repeating the same post returns Outcome::Existing with the same ids and does not write the entries twice.

Refusals

A ledger refusal is ledger::Error::Refused { reason, entry }. Its reason.name() matches the JavaScript LedgerRefused error's error, and entry matches its index, identifying the refused entry in a post. A write the store could not finish returns ledger::Error::WriteFailed, corresponding to LedgerWriteFailed. Other refusals return ledger::Error::Platform with the platform code. db::last_error_message() contains the same message as the JavaScript error. A wrong argument type throws TypeError in JavaScript. Rust's types rule out most such arguments; the rest return INVALID_ARGUMENT.

The platform codes these calls reach are LEDGER_UNAVAILABLE (the tenant has no ledger), INVALID_ARGUMENT (an unknown kind or category name, or a value past 2^53 - 1), and NO_CALL_CONTEXT (a call made outside a request).

Files

Meta has size(), created_at(), updated_at(), public(), content_type(), cache_control(), and hash(). get reads the file straight into your function's memory in one read. get_into reuses a buffer you keep, so a function that reads many files allocates once.

response and slice return a Response that serves the file. Its bytes go from the file to the client without passing through your function. A range header such as bytes=0-4 returns 206 with Content-Range, and a range past the end returns 416, as in JavaScript. You may add headers to the response before you return it.

use substrio_wasm::{files, Ctx, Env, Request, Response};

fn fetch(req: &Request, _env: &Env, _ctx: &Ctx) -> Response {
    match files::response("docs/report.pdf", 200, req.header("range")) {
        Ok(Some(res)) => res,
        Ok(None) => Response::text(404, "not found"),
        Err(_) => Response::text(500, "unavailable"),
    }
}

A refused file call returns a db::Error with the platform code, and db::last_error_message() contains its message. An invalid file path returns INVALID_ARGUMENT. fetch returns GRANT_REQUIRED unless the app has the fetch_to_file grant, and QUEUE_NOT_DECLARED when its queue is not declared. A header containing a line break returns INVALID_ARGUMENT.

Cost

Each call is one import into the platform. A list call is two imports when its answer does not fit the buffer it starts with, and a buffer that grew is kept for the next call. A refusal's reason is read with one more import, only when a call is refused. Nothing a call reads is copied into an intermediate form on its way to you.

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