resonatehq/resonate-skills / resonate-basic-durable-world-usage-rust
resonate-basic-durable-world-usage-rust
VerifiedCore patterns for writing Resonate durable functions in Rust using the
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.3 KB |
SKILL.md
View on GitHub---
name: resonate-basic-durable-world-usage-rust
description: Core patterns for writing Resonate durable functions in Rust using the #[resonate::function] attribute — function kinds (Workflow, Leaf with Info, Pure leaf), Context APIs (ctx.run, ctx.rpc, ctx.sleep with Duration, .spawn() for parallelism, builder options), and the Result<T> return convention. Use when writing any Rust function decorated with #[resonate::function]. SDK in active development; APIs may change between releases.
license: Apache-2.0
---
# Resonate Basic Durable World Usage — Rust
> **SDK note.** The Resonate Rust SDK (`resonate-sdk` v0.6.0, published on crates.io) is in active development; APIs may change between releases. Verify against the current SDK source before relying on any specific shape.
## Overview
Durable functions in Rust are async functions decorated with `#[resonate::function]`. The macro wraps your function in Resonate's durable-execution machinery — every successful `ctx.run` / `ctx.rpc` / `ctx.sleep` is a checkpoint, and the function resumes from the last checkpoint on process restart.
This skill covers the Context API surface used inside those functions. The ephemeral-world counterpart (registration, top-level invocation, promises) lives in `resonate-basic-ephemeral-world-usage-rust`.
## The contract
- **Attribute macro:** `#[resonate::function]` (or `#[resonate::function(name = "alias")]`)
- **Async function:** `async fn` — tokio is the default runtime
- **Return type:** `Result<T>` (aliased from `resonate::error::Result`) — use `?` for propagation
- **First parameter inferred kind:**
| First param | Kind | Capabilities |
|---|---|---|
| `&Context` | Workflow | `ctx.run`, `ctx.rpc`, `ctx.sleep`, `.spawn()` parallelism, context accessors |
| `&Info` | Leaf with metadata | Read-only access to `info.id()`, `info.parent_id()`, etc. |
| value types (`String`, `MyStruct`) | Pure leaf | No context; stateless computation |
Minimal workflow shape:
```rust
use resonate::prelude::*;
#[resonate::function]
async fn process_order(ctx: &Context, order_id: String) -> Result<String> {
let order = ctx.run(load_order, order_id.clone()).await?;
let charge = ctx.rpc::<String>("charge_card", order.clone()).await?;
Ok(format!("order={} charge={}", order, charge))
}
#[resonate::function]
async fn load_order(order_id: String) -> Result<String> {
Ok(format!("order-{}", order_id))
}
```
If this workflow crashes after `load_order` but before `rpc("charge_card")`, it resumes at the `rpc` call on restart — `load_order` is NOT re-executed; its stored result is returned.
## `ctx.run` — same-process invocation
### Sequential (await directly)
```rust
#[resonate::function]
async fn foo(ctx: &Context, input: String) -> Result<String> {
let a = ctx.run(step_a, input.clone()).await?;
let b = ctx.run(step_b, a).await?;
Ok(b)
}
```
### Parallel (`.spawn()` returns a DurableFuture)
```rust
#[resonate::function]
async fn foo(ctx: &Context, input: String) -> Result<(String, String)> {
let fut_a = ctx.run(step_a, input.clone()).spawn()?;
let fut_b = ctx.run(step_b, input).spawn()?;
let a = fut_a.await?;
let b = fut_b.await?;
Ok((a, b))
}
```
`.spawn()` starts the sub-task without blocking; the returned `DurableFuture` is awaited later. This is the Rust analog of TS's `begin_run` / Python's `begin_run` — different shape, same semantics.
## `ctx.rpc` — remote-process invocation
The registered name is a string; the result type needs a turbofish:
```rust
#[resonate::function]
async fn orchestrator(ctx: &Context, batch_id: String) -> Result<()> {
let _result = ctx.rpc::<String>("worker_fn", batch_id).await?;
Ok(())
}
```
With target group + parallelism:
```rust
#[resonate::function]
async fn parallel_remote(ctx: &Context) -> Result<()> {
let f1 = ctx.rpc::<String>("worker-a", "data")
.target("poll://any@group-a")
.spawn()?;
let f2 = ctx.rpc::<String>("worker-b", "data")
.target("poll://any@group-b")
.spawn()?;
f1.await?;
f2.await?;
Ok(())
}
```
## `ctx.sleep` — durable sleep
`ctx.sleep` takes a `std::time::Duration`. There is no upper limit; sleeps survive process restarts because the continuation lives in the Resonate server:
```rust
use std::time::Duration;
#[resonate::function]
async fn daily_digest(ctx: &Context, user_id: String) -> Result<()> {
loop {
ctx.sleep(Duration::from_secs(24 * 60 * 60)).await?;
ctx.rpc::<()>("send_digest", user_id.clone()).await?;
}
}
```
## Builder options
All Context execution methods return a builder that accepts options before `.await` or `.spawn()`:
```rust
use std::time::Duration;
#[resonate::function]
async fn foo(ctx: &Context) -> Result<String> {
let result: String = ctx.run(expensive_leaf, "input".into())
.timeout(Duration::from_secs(30))
.await?;
Ok(result)
}
```
Documented Context builder options:
| Method | Applies to | Purpose |
|---|---|---|
| `.timeout(Duration)` | `ctx.run`, `ctx.rpc` | Execution timeout |
| `.target(&str)` | `ctx.rpc` only | Worker group routing (`poll://any@group-name`) |
Note: `.version(u32)` and `.tags(HashMap<String, String>)` are **ephemeral-world only** (on `resonate.run()` / `resonate.rpc()`) — they are NOT available on Context builders.
## Context accessors
Inside a workflow, `&Context` provides read-only metadata:
```rust
#[resonate::function]
async fn foo(ctx: &Context) -> Result<()> {
println!("id={}", ctx.id());
println!("parent={}", ctx.parent_id());
println!("origin={}", ctx.origin_id());
println!("func={}", ctx.func_name());
println!("timeout_at={}", ctx.timeout_at());
Ok(())
}
```
`origin_id` is the top-level invocation that kicked off this call graph; useful for tracing across RPC hops.
`ctx.info()` returns a snapshot `Info` struct with a superset of these accessors, including `branch_id()` and `tags()` (a `&HashMap<String, String>` of tags set at invocation time). Useful when you want to hand execution metadata to a helper function without passing the whole `Context`.
## Dependency access: `ctx.get_dependency::<T>()`
Dependencies set on the `Resonate` instance with `.with_dependency<T>(value)` (see `resonate-basic-ephemeral-world-usage-rust`) are retrieved inside a durable function by type:
```rust
use std::sync::Arc;
use sqlx::PgPool;
#[resonate::function]
async fn write_order(ctx: &Context, order_id: String) -> Result<()> {
let pool: Arc<PgPool> = ctx.get_dependency::<PgPool>();
// wrap I/O in a leaf so the effect is checkpointed
ctx.run(insert_order_row, (pool.clone(), order_id)).await?;
Ok(())
}
async fn insert_order_row((pool, order_id): (Arc<PgPool>, String)) -> Result<()> {
sqlx::query("INSERT INTO orders (id) VALUES ($1) ON CONFLICT DO NOTHING")
.bind(&order_id)
.execute(&*pool)
.await?;
Ok(())
}
```
Type-dispatched: there is one dependency per type per `Resonate` instance. For multiple values of the same logical type (e.g. two Postgres pools pointing at different databases), wrap them in newtypes and register each separately. `ctx.get_dependency::<T>()` panics if no dependency of that type was registered — wire your DI at startup and keep it static, not conditional.
`&Info` also exposes `get_dependency::<T>()`, so a leaf that takes `info: &Info` as its first parameter can access dependencies without needing the full Context.
> **Note:** `ctx.get_dependency` + `Info::get_dependency` are in the v0.6.0 SDK source (`resonate-sdk-rs:resonate/src/context.rs:120`, `info.rs:43`) but not yet covered in `docs/develop/rust.mdx`. Rust-skill review discovered the docs lag; the API is real.
## Human-in-the-loop: `ctx.promise::<T>()`
Context-side promises let a durable function block until an external actor (webhook, UI, CLI, operator) resolves or rejects. The returned `PromiseTask<T>` is a lazy builder: you can attach `.timeout(Duration)` and `.data(&impl Serialize)`, fetch the generated ID via `.id().await?`, eagerly `create()` a handle for later awaiting, or `.await` it directly to block.
```rust
use serde::{Serialize, Deserialize};
use std::time::Duration;
#[derive(Serialize, Deserialize)]
struct Decision {
approved: bool,
reviewer: String,
}
#[resonate::function]
async fn expense_approval(ctx: &Context, expense_id: String) -> Result<String> {
// create a promise the reviewer will resolve from outside
let decision: Decision = ctx
.promise::<Decision>()
.timeout(Duration::from_secs(24 * 60 * 60)) // 24-hour SLA
.data(&serde_json::json!({ "expense_id": expense_id }))?
.await?; // blocks until resolved
if decision.approved {
ctx.run(process_reimbursement, expense_id.clone()).await?;
Ok(format!("approved by {}", decision.reviewer))
} else {
Ok(format!("rejected by {}", decision.reviewer))
}
}
```
From outside the worker, resolve it with the ephemeral-world `resonate.promises.resolve(...)` API using the same ID. Since the ID is SDK-generated per-invocation, the typical pattern is: fetch `task.id().await?` before awaiting, stash it somewhere the reviewer can read (DB, webhook payload, UI), then `await` the promise.
For the deep HITL pattern (multi-approver, webhooks, SLAs), see `resonate-human-in-the-loop-pattern-rust`.
> **Note:** `ctx.promise::<T>()` is in the v0.6.0 SDK source (`resonate-sdk-rs:resonate/src/context.rs:335`) with a full `PromiseTask<T>` builder (`.timeout`, `.data`, `.create`) but not yet covered in `docs/develop/rust.mdx`.
## Leaf with `&Info`
A pure leaf that still needs execution metadata uses `&Info` as its first parameter:
```rust
#[resonate::function]
async fn stamped_log(info: &Info, message: String) -> Result<()> {
println!("[{}] {}", info.id(), message);
Ok(())
}
```
`&Info` is read-only — no sub-task invocation, no sleep — which lets the SDK optimize its execution differently from workflows.
## Common shapes
**Sequential pipeline with typed `?` propagation:**
```rust
#[resonate::function]
async fn ingest(ctx: &Context, url: String) -> Result<usize> {
let raw = ctx.run(fetch, url).await?;
let parsed = ctx.run(parse, raw).await?;
let count = ctx.run(persist, parsed).await?;
Ok(count)
}
```
**Parallel fan-out over a known set:**
```rust
#[resonate::function]
async fn enrich_batch(ctx: &Context, ids: Vec<String>) -> Result<Vec<String>> {
let mut futures = Vec::with_capacity(ids.len());
for id in ids {
futures.push(ctx.run(enrich_one, id).spawn()?);
}
let mut results = Vec::with_capacity(futures.len());
for f in futures {
results.push(f.await?);
}
Ok(results)
}
```
**Error mapping at a step boundary:**
```rust
#[resonate::function]
async fn resilient(ctx: &Context, input: String) -> Result<String> {
match ctx.rpc::<String>("flaky_worker", input.clone()).await {
Ok(v) => Ok(v),
Err(_) => ctx.run(fallback, input).await,
}
}
```
## Distinct Rust idioms
- **`#[resonate::function]` attribute macro** — not a higher-order function call like TS's `resonate.register`. Registration still happens ephemeral-side; the attribute just transforms the function's signature for the SDK to pick up
- **Turbofish on `ctx.rpc::<T>`** — Rust needs the result type when it can't be inferred from the call site
- **`.spawn()?`** is synchronous — it returns a `DurableFuture` (wrapped in `Result`, hence `?`) immediately, WITHOUT awaiting. You await that `DurableFuture` later (once) to get the `T`. There is a single await now, on the returned future — not two.
- **`Duration::from_secs` / `from_millis` / `from_millis` / `from_micros`** — never raw numeric literals for time
- **`Result<T>` + `?` everywhere** — idiomatic Rust propagation; matches the SDK's uniform return shape
- **`tokio::main` runtime** — async without it requires boilerplate; every Resonate Rust app uses `#[tokio::main]` on its entry point
- **Dependencies via type-dispatched `ctx.get_dependency::<T>()`** — attach at `Resonate::new(...).with_dependency(value)` time; retrieve in any durable function by type. Newtype if you need multiple values of the same logical type
## Rust SDK API coverage status
Honest reading of v0.6.0, verified against `resonate-sdk-rs` source (not just docs):
### In the SDK source + documented in `rust.mdx`
- `ctx.run` / `ctx.rpc` / `ctx.sleep` with builders + `.spawn()` parallelism
- Context accessors `ctx.id/parent_id/origin_id/func_name/timeout_at`
- `Info` accessors on leaf-with-info functions
### In the SDK source BUT not in `rust.mdx` (safe to use; docs lag)
- **`ctx.promise::<T>()`** — Context-side HITL primitive with `PromiseTask<T>` builder (`.timeout`, `.data`, `.id`, `.create`, `.await`). Fully featured; discovered in post-session audit against `resonate/src/context.rs:335`
- **`ctx.get_dependency::<T>()`** — type-dispatched DI. Panics if not registered. `Info::get_dependency` is the same shape on leaves
- **`ctx.info()`** — returns an `Info` snapshot with extra accessors (`branch_id()`, `tags()`)
- **`ctx.detached(func, args)`** — fire-and-forget remote execution (`context.rs:405`). `.spawn()?` returns a `DetachedHandle`; call `handle.id().await?` for the durable promise ID. Does not return the callee's result
Each has been verified as `pub fn` with source-level docstrings; they appear intended for users. Treat them as "supported but not yet in rust.mdx; verify signatures against `resonate-sdk-rs` at the commit you depend on."
### NOT in the SDK source at v0.6.0
- **`ctx.random.random()` / `ctx.time.time()`** — no deterministic randomness/time helpers. Standard Rust `SystemTime::now()` and `rand` will cause replay inconsistency. Workaround: do non-deterministic work inside a leaf so the value is checkpointed
- **`ctx.panic()` / `ctx.assert()`** — use standard `panic!` / `assert!` (non-recoverable; retry policy sees them). For recoverable invariant checks, propagate via `Result`
Each of these may land in a later v0.x; write your Rust workflows around the available set for now.
## Related skills
- `resonate-basic-ephemeral-world-usage-rust` — Client APIs, registration, top-level invocation, promises
- `resonate-basic-debugging-rust` — Rust-specific failure modes, serde errors, spawn semantics, tokio runtime mismatches
- `durable-execution` + `resonate-philosophy` — foundational concepts
- `resonate-basic-durable-world-usage-typescript` + `-python` — sibling SDKs for comparison
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |