Skip to content

resonatehq/resonate-skills / durable-execution

durable-execution

Unverified

Conceptual introduction to durable execution — what it is, why you'd want it, and the tradeoffs between rolling your own (just your DB) versus using a framework like Resonate. Read this BEFORE picking an implementation. For the Resonate SDK's concrete Context API (ctx.run, ctx.sleep, ctx.promise, structured concurrency), use the per-SDK skill for your language — resonate-basic-durable-world-usage-{typescript,python,rust,go}.

references/RESONATE-QUICKSTART.md

View on GitHub
# Resonate Quickstart — Zero to Running in 5 Minutes

The open-source Resonate server (`resonatehq/resonate`) is a single-binary Rust + SQLite server, with tiny SDKs for TypeScript, Python, Rust, and Go. This quickstart uses the **TypeScript** SDK; for your language, follow the same steps with `resonate-basic-durable-world-usage-{typescript,python,rust,go}`. This gets you from nothing to a running durable workflow.

---

## Prerequisites

- The Resonate server prebuilt binary (macOS: `brew install resonatehq/tap/resonate`; other platforms: download from GitHub releases)
- That's it. No Docker, no Postgres, no Redis.

---

## 1. Start the Server

Install the server (macOS):
```bash
brew install resonatehq/tap/resonate
```

Or download the prebuilt binary for your platform from [GitHub releases](https://github.com/resonatehq/resonate/releases) (v0.9.8+).

If you want to build from source (requires the Rust toolchain):
```bash
git clone https://github.com/resonatehq/resonate.git
cd resonate
cargo build --release
./target/release/resonate serve
```

Start the server (if installed via brew or prebuilt binary):
```bash
resonate serve
```

Server starts on port 8001. SQLite database created at `./resonate.db`. Zero configuration needed.

Verify it's running:
```bash
curl -s http://localhost:9090/metrics | head -5
```

---

> **Language note.** Code examples here are shown in **TypeScript**. The durable-execution concepts are identical across all four Resonate SDKs — only the syntax differs (Python uses bare `yield`, Rust uses `async fn` + `.await`, Go uses ordinary funcs + `Future.Await`). For concrete, idiomatic syntax in your language, see the per-SDK skills: `resonate-basic-durable-world-usage-{typescript,python,rust,go}` (and the matching pattern/debugging skills).

## 2. Write Your First Worker

Create a new project:

```bash
mkdir my-worker && cd my-worker
bun init -y
```

Install the SDK:
```bash
npm install @resonatehq/sdk
```

Create `src/index.ts`:

```typescript
import { Resonate, type Context } from "@resonatehq/sdk";

const resonate = new Resonate({ url: "http://localhost:8001" });

// Register a durable function — each yield is a crash-safe checkpoint
resonate.register("greet", function* (ctx: Context, name: string) {
  const greeting = yield* ctx.run(function* () {
    return `Hello, ${name}!`;
  });

  yield* ctx.sleep(1000);  // Durable sleep — survives crashes

  const farewell = yield* ctx.run(function* () {
    return `Goodbye, ${name}!`;
  });

  return { greeting, farewell };
});

// Dispatch a workflow and wait for the result
console.log("Worker running...");

const result = await resonate.run("greet-demo", "greet", "World");
console.log("Result:", result);

await resonate.stop();
```

Run it:
```bash
bun run src/index.ts
```

Expected output:
```
Worker running...
Result: { greeting: "Hello, World!", farewell: "Goodbye, World!" }
```

---

## 3. What Just Happened

1. **Worker registered** "greet" function with the server
2. **`resonate.run()`** created a promise (`greet-demo`) and a task on the server, then waited for the result
3. **Server dispatched** the task to the worker via SSE poll
4. **Worker executed** the generator function, checkpointing at each `yield`:
   - `yield* ctx.run(...)` — checkpoint a local step
   - `yield* ctx.sleep(1000)` — checkpoint a durable timer
5. **Server stored** the final result. The promise settled as `resolved`.

If the worker had crashed between steps, the server would re-dispatch the task. A new worker would replay from the top — but completed steps return their cached results instantly. Execution resumes from the first incomplete step.

---

## 4. Key Concepts

### Everything is a Promise

Every workflow, every step, every timer creates a **durable promise** on the server. Promises have:
- An **ID** (deterministic, derived from workflow ID + step sequence)
- A **state** (`pending` → `resolved` or `rejected`)
- A **value** (the result or error, persisted in SQLite)

### How Replay Works

Each durable step hands a **descriptor** to the engine. The engine:
- On first run: executes the step, stores the result as a promise
- On replay: checks if the promise exists, returns the cached result, skips the step

This re-entrancy is the core mechanism in every SDK. The shape that expresses it differs: in TypeScript (shown here) the workflow is a generator function (`function*`) and each step is a `yield*`; Python uses a generator with bare `yield`; Rust/Go use an `async fn`/func that awaits each step.

### Worker Groups

Workers in the same `group` share the workload:
```typescript
const resonate = new Resonate({ url: "http://localhost:8001", group: "order-workers" });
```
Start 3 workers in the same group → the server load-balances tasks across them. One dies → the others pick up its work.

---

## 5. Add More Patterns

### Human-in-the-Loop

```typescript
resonate.register("approval", function* (ctx: Context, orderId: string) {
  // Create the promise — the server assigns its id
  const approval = yield* ctx.promise({
    timeout: 5 * 60 * 1000,
  });

  // Send notification (durable step)
  yield* ctx.run(function* () {
    console.log(`Approve at: http://localhost:5001/approve?promise_id=${approval.id}`);
  });

  // Suspend until human resolves the promise — no process stays alive
  const decision = yield* approval;

  console.log(`Decision: ${decision}`);
  return decision;
});
```

Resolve externally (from an HTTP handler, webhook, or script) — use the id the worker logged:
```typescript
await fetch("http://localhost:8001", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    kind: "promise.settle",
    head: { corrId: crypto.randomUUID(), version: "" },
    data: {
      id: "approval-order-42.0",
      state: "resolved",
      value: { headers: {}, data: btoa(JSON.stringify("approved")) },
    },
  }),
});
```

### Durable Sleep

```typescript
resonate.register("reminder", function* (ctx: Context, userId: string) {
  yield* ctx.run(sendEmail, userId, "Your trial starts now!");
  yield* ctx.sleep(7 * 24 * 60 * 60 * 1000);  // 7 days — process can die, timer still fires
  yield* ctx.run(sendEmail, userId, "Your trial is ending soon.");
});
```

### Cross-Service RPC

```typescript
resonate.register("orchestrator", function* (ctx: Context, orderId: string) {
  // Dispatch to a different worker group — suspends until that worker completes
  const score = yield* ctx.rpc("computeScore", orderId, {
    target: "poll://any@scoring-workers",
  });
  return { orderId, score };
});
```

---

## 6. Server Configuration

All via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `RESONATE_SERVER__HOST` | `localhost` | HTTP server host |
| `RESONATE_SERVER__PORT` | `8001` | HTTP API port |
| `RESONATE_SERVER__BIND` | `0.0.0.0` | Bind address |
| `RESONATE_SERVER__URL` | `http://{host}:{port}` | Externally-reachable URL (required for distributed deployments) |
| `RESONATE_LEVEL` | `info` | Log level: `debug`/`info`/`warn`/`error` |
| `RESONATE_STORAGE__TYPE` | `sqlite` | `sqlite` / `postgres` / `mysql` |
| `RESONATE_STORAGE__SQLITE__PATH` | `resonate.db` | SQLite file path |
| `RESONATE_STORAGE__POSTGRES__URL` | — | Postgres connection string |
| `RESONATE_AUTH__PUBLICKEY` | _(disabled)_ | Path to RS256 PEM public key for JWT auth |
| `RESONATE_TASKS__LEASE_TIMEOUT` | `15000` | Task lease timeout (ms) |
| `RESONATE_TASKS__RETRY_TIMEOUT` | `30000` | Suspend/wake retry interval (ms) |
| `RESONATE_OBSERVABILITY__METRICS_PORT` | `9090` | Prometheus metrics port (`0` disables) |

Run `resonate serve --help` for the full, authoritative flag list.

---

## 7. Next Steps

- **All patterns with full code:** See `RESONATE-PATTERNS.md`
- **SDK API reference:** See `RESONATE-SDK.md`
- **Deploy to production:** See `DEPLOYMENT.md`
- **Test that durability works:** See `TESTING.md`
- **Starter templates:** Copy from `assets/resonate-worker.ts`, `assets/resonate-gateway.ts`, etc.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall