Write async fns; ORCHER journals each step and resumes interrupted runs where they stopped.
- Durable: every step journaled; crashed runs resume on another worker
- Plain Rust:
#[workflow]and#[task]on async functions, no DSL - Deterministic replay: changed code is caught, not silently replayed
- Smart retries: per-task policies and never-retry error types
- Timers and events: sleep for days or wait for an outside event
- Child workflows: compose and run workflows in parallel
- Actors: stateful objects with a single writer per key
- Testing: run workflows in memory with mocks and a fake clock
- Multi-tenant: API keys, organizations and namespaces built in
Install
[]
= "0.5"
= { = "1", = ["full"] }
= { = "1", = ["derive"] }
[!NOTE] You need an ORCHER engine to run workflows against. The SDK is pre-1.0: the API may change between minor releases, and every breaking change is listed in CHANGELOG.md.
Quick start
Define a task and a workflow that calls it. The worker finds every #[workflow]
and #[task] in the binary, registers them with the engine and runs them:
use *;
async
async
async
Start it from any process and wait for the result:
use StartWorkflowOptions;
use *;
let client = connect.await?;
let order = Order ;
let handle = client
.start_workflow_with_options
.await?;
let receipt: String = handle.result.await?;
[!TIP] Workflow code is replayed from its history every time it resumes, so it must be deterministic. Do I/O and anything else that touches the outside world in tasks, and use
ctx.time(),ctx.rand()andctx.sleep()in workflows.
Guide
A timer is recorded by the engine, so no worker is busy while it runs, and a restart doesn't reset it:
use Duration;
async
A workflow can park until a named event arrives, optionally with a deadline:
use Duration;
async
Send the event from a client:
let handle = client.get_workflow_handle.await?;
handle.send_event.await?;
async
Return a TaskError::application naming the failure's type, and list the types
never to retry on the task. A TaskError::non_retryable failure is never
retried, whatever the policy allows:
use TaskError;
async
Any other error is retried. RetryPolicy::with_non_retryable_errors sets the
same list on a policy built in code.
Workers and clients send and receive gRPC messages of up to 32 MiB; set
ORCHER_MAX_MESSAGE_BYTES to change that. The engine accepts one payload (an
input, a result, an event) of up to 8 MiB unless configured otherwise. A task
whose result is too large fails straight away with a PayloadTooLarge failure
that says how large it was, and is not retried: store large data elsewhere and
pass a reference.
ctx.time() reads the time the engine recorded, and ctx.rand() is seeded from
the run, so both give the same answer every time the workflow is replayed:
async
use TestEnv;
async
Crates and features
| Crate | What it is |
|---|---|
orcher-sdk |
The SDK: workflows, tasks, actors, the worker and the client |
orcher-sdk-macros |
#[workflow], #[task], #[actor] and #[derive(Payload)], re-exported by orcher-sdk |
Depend on orcher-sdk alone; the code the macros generate needs nothing else.
| Feature | Default | What it enables |
|---|---|---|
full |
✓ | auto-register, derive and testing |
auto-register |
via full |
Registers every #[workflow] and #[task] with the worker |
derive |
via full |
#[derive(Payload)] |
testing |
via full |
In-memory test environment, task mocks and a mock clock |
compression |
Gzip payload compression |
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for how to build, test and propose a change.
License
Licensed under the Apache License, Version 2.0.
The Rust logo is a trademark of the Rust Foundation, shown here to indicate the language this SDK is for.