Documentation v0.42.0 WASM (Rust) Rust Activities
Documentation v0.42.0 all versions

Rust Activities

This page shows the WIT and Rust code behind a WASM activity. Read Activities first for the retry and idempotency contract, which is the same in every language.

Return types

A WASM activity declares its functions in WIT. Since an activity can fail when the invocation traps (panics), times out, or runs out of retries, each function must be fallible. The return type must be one of the following:

  • result
  • result<T> where T represents any successful variant like string or list<u32> or even a none type (_)
  • result<T, string>
  • result<T, E> where E is a variant type that contains execution-failed variant.

A minimal activity

In this contrived example the activity does not communicate with an external system. Its purpose is to show the WIT and Rust code needed for an activity. Install Rust and use the demo-tutorial Rust activity as a complete project example. A project with the following structure can host this example:

.
├── Cargo.toml
├── rust-toolchain.toml
├── src
│   └── lib.rs
└── wit
    ├── deps
    │   └── template-fibo_activity
    │       └── fibo.wit
    └── impl.wit

fibo.wit is a WIT interface with a single function:

package template-fibo:activity;

interface fibo-activity-ifc {
    fibo: func(n: u8) -> result<u64, _>;
}

impl.wit exports this interface:

package any:any;

world any {
    export template-fibo:activity/fibo-activity-ifc;
}

Obelisk disregards the namespace, package name, and world name of the world file. It only concerns itself with the exported interfaces. A world can be thought of as an ES module with no code, just imports and exports.

The (naive) implementation in lib.rs:

impl Guest for Component {
    fn fibo(n: u8) -> Result<u64, ()> {
        if n <= 1 {
            Ok(n.into())
        } else {
            Ok(Self::fibo(n - 1).unwrap() + Self::fibo(n - 2).unwrap())
        }
    }
}

Add the activity to deployment.toml. WASM components carry their signatures, so there are no params or return_type fields:

[[activity_wasm]]
name = "myactivity"
location = "target/wasm32-wasip2/release/myactivity.wasm"

Build the component and run Obelisk:

cargo build --release
obelisk server run --app-config app.toml --deployment deployment.toml

Execute the activity using its FFQN:

obelisk execution submit --follow \
    template-fibo:activity/fibo-activity-ifc.fibo [10]

For a complete build and deployment, follow Getting Started (Rust / WASM). For outbound HTTP, see HTTP Client.

Logging

Import the obelisk:log/log@1.0.0 interface in the world:

world any {
    export template-fibo:activity/fibo-activity-ifc;
    import obelisk:log/log@1.0.0;
}
use obelisk::log::log;

log::info("Processing request");
log::debug(&format!("Input: {input:?}"));

Each message is a string, so use format! for dynamic content. Output of println! and eprintln! is captured as well, see Logging.

Testing

Unit and integration testing is possible with Cargo's test harness. The stargazers demo repository contains unit and integration tests for activities.

On this page