Activities

Activities are the fundamental building blocks of work within an Obelisk workflow . They represent individual, idempotent operations that perform a specific task, typically a network activity. Think of them as the "verbs" of your workflow - the interactions with real world that get things done. Activities are executed at least once for resiliency.

Defining Features of Activities

• Idempotency: This is the most crucial aspect of an activity. An activity must be idempotent, meaning it can be executed multiple times with the same input and produce the same result without unintended side effects. This is essential for retries and ensuring the integrity of your workflow, even in the face of failures. The responsibility for fulfilling this contract lies with the activity's implementation.

• WASM Sandboxing: Activities are executed within a WebAssembly (WASM) sandbox. This provides a secure, isolated environment, preventing activities from having unrestricted access to the system.

• Resilience: Obelisk automatically handles retries for activities that fail due to errors, timeouts, or panics(traps). This retry mechanism makes activities highly reliable. The input parameters and execution results of activities are persistently stored. Keep in mind that an activity can be retried even after it succeeded - in a rare case when persisting the result fails, e.g. during a server restart.

Developing an Activity in Rust

In this contrived example we will create an activity that does not communicate with an external system. Its purpose is to show all the basic steps needed to execute an activity. Install Rust, cargo-generate and run:

cargo generate obeli-sk/obelisk-templates fibo/activity --name myactivity
cd myactivity

This will generate a directory with the following structure:

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

First let's look at the fibo.wit - a WIT interface with a single function.

package template-fibo:activity;

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

The other WIT file - impl.wit - exports this interface:

package any:any;

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

Obelisk disregards namespace, package name and the world name - it only concerns itself with the exported interface(s). The world can be though of as an ESModule with no code - just imports and exports.

Let's look at the (naive) implementation found in lib.rs:

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

The configuration file obelisk.toml already includes the activity:

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

Let's build the WASM Component and run Obelisk.

cargo build --release
obelisk server run --config ./obelisk.toml

In order to execute the activity, we can use the CLI or the Web UI. In either case, we need the FFQN and the function parameters:

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

Follow the template's README for more details.