Documentation v0.38.3 Concepts Activities

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

Activity Types

Obelisk supports three kinds of activities:

All three types share the same retry, durability, and observability guarantees. The choice depends on your toolchain and use case.

Exec Activities

Exec activities run any executable as a durable activity. The child process receives function parameters as JSON-encoded CLI arguments. The result is read from stdout — exit code 0 means success, non-zero means error. Both stdout and stderr are streamed and persisted, available via the CLI, REST API, and Web UI.

Example deployment.toml:

[[activity_exec]]
ffqn = "myapp:scripts/greet.greet"
location = "${DEPLOYMENT_DIR}/scripts/greet.sh"
params = [{ name = "name", type = "string" }]
return_type = "result<string, string>"
env_vars = ["PATH"]
max_retries = 5

With a corresponding script scripts/greet.sh:

#!/usr/bin/env bash
set -euo pipefail
NAME=$(echo "$1" | jq -r '.')
echo "\"Hello, ${NAME}!\""

The script receives each parameter as a JSON-encoded positional argument and must write a JSON-encoded return value to stdout.

See Configuration for all activity_exec fields including inline content, secrets, environment variables, and output size limits.

Defining activity functions in WIT

As with all components in Obelisk, the WIT interface definition language is used to describe each activity function. Since activities can fail when the function invocation traps (panics), runs out of time or retries, each function must be fallible. This means that the return type must be one of following:

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) -> result<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) -> Result<u64, ()> {
        if n <= 1 {
            Ok(n.into())
        } else {
            Ok(Self::fibo(n - 1).unwrap() + Self::fibo(n - 2).unwrap())
        }
    }
}

The configuration file obelisk.toml already includes the activity:

[[activity_wasm]]
name = "myactivity"
location = "${OBELISK_TOML_DIR}/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 execution submit --follow \
    template-fibo:activity/fibo-activity-ifc.fibo [10]

Follow the template's README for more details.

Subsections