Skip to content
Tenura docs

Recipe 44: The Smallest Working Tasklet

What You Build

The smallest tasklet that does something. Reads input bytes, returns a JSON document with a greeting and the byte count. Useful as the starting point for any new tasklet you write — copy this and replace compute() with whatever you actually want to compute.

Source

The full crate lives at cookbook/recipe-44-hello-tasklet/ in the source tree. It’s a real workspace member; CI checks it compiles on every change.

// src/lib.rs (excerpt — see the source tree for the full file)
use serde::{Deserialize, Serialize};


#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct HelloOutput {
    pub greeting: String,
    pub input_bytes: usize,
}


pub fn compute(input: &[u8]) -> HelloOutput {
    HelloOutput {
        greeting: "hello from grafOS".to_string(),
        input_bytes: input.len(),
    }
}

What’s interesting

  1. compute() is pure. Same code runs in unit tests on your laptop and inside the WASM tasklet on a cell. No #[cfg(target_arch)] branches in the logic.
  2. The tasklet ABI is one function. tasklet_run(in_ptr, in_len, out_ptr, out_cap) -> i32. The -> i32 is the byte length written; negative is a typed error. See Tasklet ABI for the full v0 contract.
  3. JSON in, JSON out. serde_json does the serialization; the runtime persists the bytes as output.b64 in the run’s artifact directory.

Build + run

Terminal window
cargo new --lib my-hello && cd my-hello
# copy cookbook/recipe-44-hello-tasklet/{Cargo.toml, src/lib.rs} into here
# add a grafos.toml declaring the tasklet (copy from a `grafos new` scaffold)


grafos tasklet build
grafos validate
grafos deploy run --provider aws --tasklet hello-tasklet --mem 32768 --json

Expected:

Built 1 tasklet(s):
  hello-tasklet <sha256> <bytes> .grafos/tasklets/hello-tasklet/<sha256>.wasm

After the deploy finalizes, grafos artifacts <run-id> shows response.json carrying the JSON the tasklet wrote.

Failure Behavior

  • Negative ABI pointers or lengths return -1.
  • Output larger than the caller-provided buffer returns -2.
  • Serialization failure returns -3; HelloOutput is serializable, so this is a fail-closed guard.
  • The tasklet has no external resources, so retries are safe and deterministic.

Run And Verify

Terminal window
cargo test -p cookbook-recipe-44-hello-tasklet

Expected: the tests cover empty input and arbitrary byte input.

Adapt It

Keep the compute(input: &[u8]) boundary and replace the body with your actual tasklet logic. Add typed input and typed error values once the tasklet needs caller-supplied structure.

Where to next

  • The same pattern, with state across calls: Recipe 45 (uses grafos-sync).
  • The same pattern, with shared data structures: Recipe 46 (uses grafos-collections::FabricVec).
  • The same pattern, but composed into a pipeline: Recipe 48 (uses grafos-collections::FabricQueue).