Skip to main content

Crate orcher_sdk

Crate orcher_sdk 

Source
Expand description

§Orcher Rust SDK

Build durable workflows and tasks for the Orcher workflow engine.

Workflows are async functions whose progress the engine records, so they survive crashes and restarts and resume where they left off. Tasks are the steps that touch the outside world, and are retried under a policy when they fail. A Worker polls the engine and runs both; a Client starts workflows and reads their results.

§Quick start

use orcher_sdk::prelude::*;

// A worker is I/O-bound, so a single-threaded runtime is enough.
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    let worker = Worker::builder()
        .server_url("http://localhost:50051")
        .task_queue("my-queue")
        .build()
        .await?;

    worker.run().await
}

§Tokio runtime

A worker spends its time waiting on gRPC long-polls, so the single-threaded runtime (#[tokio::main(flavor = "current_thread")]) is recommended: its event loop sleeps while it waits, whereas the multi-threaded work-stealing scheduler keeps its threads busy even when the worker is idle.

Run CPU-heavy work with tokio::task::spawn_blocking(), which uses a separate thread pool and does not hold up the event loop:

use orcher_sdk::prelude::*;

#[task]
async fn checksum(_ctx: TaskContext, data: Vec<u8>) -> Result<u64> {
    let sum = tokio::task::spawn_blocking(move || {
        // CPU-intensive work here.
        data.iter().map(|&b| u64::from(b)).sum::<u64>()
    })
    .await
    .map_err(|e| Error::Other(e.to_string()))?;
    Ok(sum)
}

§Modules

  • workflow: the workflow context and the durable operations it offers
  • task: the task context, retry policies and task options
  • actor: keyed actors with durable state
  • worker: building and running a worker
  • client: starting, querying and sending events to workflows
  • error: the SDK’s error types
  • prelude: the imports most programs need

Re-exports§

pub use actor::ActorContext;
pub use actor::ActorKey;
pub use actor::SharedActorContext;
pub use client::Client;
pub use error::Error;
pub use error::ErrorCode;
pub use error::Result;
pub use error::Severity;
pub use error::TaskFailureCode;
pub use payload::PayloadCodec;
pub use task::Task;
pub use task::TaskContext;
pub use worker::HealthReport;
pub use worker::HealthStatus;
pub use worker::RuntimeStats;
pub use worker::Worker;
pub use worker::WorkerBuilder;
pub use workflow::Workflow;
pub use workflow::WorkflowContext;

Modules§

actor
Worker-side actor runtime.
client
Client for starting and controlling workflows on the ORCHER orchestrator.
debugging
Tools for inspecting workflow execution while debugging and testing.
error
Error types for the Orcher Rust SDK.
interceptor
Interceptor framework for cross-cutting concerns.
payload
Converting values to and from Payloads.
prelude
The imports most programs need.
task
Tasks: the units of work a workflow schedules.
testing
Testing utilities for Orcher workflows.
worker
Workers: processes that poll the orchestrator and run workflows and tasks.
workflow
Workflow APIs for defining and executing durable workflows.

Macros§

initialize_handlers
Calls the crate’s generated __orcher_force_registration() function.

Structs§

ListWorkflowsOptions
Filter, sort, and pagination options for listing workflows.
MethodStats
A worker’s wire measurements; see Worker::wire_metrics. What one RPC method has done, as WireMetrics::snapshot reports it.
Namespace
A namespace, as the namespace calls on Client return it. A namespace, as the engine reports it.
Payload
Serialized data together with metadata describing its encoding.
SearchWorkflowsOptions
Pagination options for searching workflows.
WireMetricsSnapshot
A worker’s wire measurements; see Worker::wire_metrics. A copy of a worker’s wire measurements at one moment.
WorkStats
A worker’s wire measurements; see Worker::wire_metrics. The work a worker has handed to its language and reported back, as WireMetrics::snapshot reports it.
WorkflowExecutionDescription
Detailed description of a workflow execution.
WorkflowExecutionInfo
Summary of a workflow execution, as returned in list and search results.
WorkflowListPage
One page of workflow execution summaries.

Enums§

ListWorkflowsSortOrder
Sort order for listing workflows.
WorkflowStatus
Status of a workflow execution.

Constants§

SDK_NAME
The name this SDK reports itself under.
VERSION
The version of this crate.

Attribute Macros§

actor
Marks a struct as a stateful actor type.
event
Declares an event: an asynchronous message sent to a running workflow to trigger an action or a state change. The sender does not wait for a result.
operations
Defines the operations of an actor on its impl block.
query
Declares a query: a read of a running workflow’s state that does not affect its execution.
task
Turns an async fn into a task that workers can run.
tasks
Defines a group of tasks as methods on an impl block.
update
Turns an async fn into an update handler for a running workflow.
workflow
Turns an async fn into a workflow definition.

Derive Macros§

Payload
Derives JSON payload conversion methods for a type.