Operations

Workers


A worker is an SDK Worker instance — your application process running the Orcher SDK. Workers are not separate infrastructure. You define workflows and tasks in code, build a Worker with the builder API, and call worker.run(). The Worker connects to the orchestrator via gRPC, polls for work, executes your handlers, and reports results.

  • Stateless — All workflow state lives in the orchestrator's PostgreSQL database, not in the worker
  • Scalable — Add or remove workers dynamically with no state migration
  • Multi-language — Same worker model across Rust, Python, and TypeScript SDKs
  • Self-registering — Workers register their capabilities on startup and deregister on shutdown

Concepts

Worker

A Worker is the top-level object you create from the SDK. It encapsulates everything needed to poll for and execute work: the gRPC connection, registered workflow and task handlers, concurrency limits, and poller threads. A single OS process runs one Worker.

Task Queue

Each Worker polls a single task queue — a named channel through which the orchestrator routes work to workers. When a workflow dispatches a task, the orchestrator places it on the task queue specified in the workflow configuration. Only workers polling that queue will receive the work.

Use separate task queues to isolate workloads with different resource requirements:

1
// CPU-intensive work — lower concurrency, deploy on compute-optimized instances
2
let compute_worker = WorkerBuilder::new()
3
.task_queue("compute")
4
.max_concurrent_tasks(50)
5
.build().await?;
6
7
// I/O-intensive work — higher concurrency, deploy on network-optimized instances
8
let io_worker = WorkerBuilder::new()
9
.task_queue("io-tasks")
10
.max_concurrent_tasks(500)
11
.build().await?;

Worker Identity

Every Worker has an identity string used for logging, debugging, and correlating work back to specific processes. If you don't set one explicitly, each SDK generates a default:

SDKDefault FormatExample
Rustorcher-rust-{uuid}orcher-rust-7e27ab5c-...
Pythonpython-worker-{nanoseconds}python-worker-1710532800000000000
TypeScriptworker-{hostname}-{pid}-{timestamp}worker-ip-10-0-1-42-1-1710532800000

In containerized environments, the auto-generated identity may not be useful — containers often have PID 1 and random hostnames. Set an explicit identity that links back to your deployment context:

1
WorkerBuilder::new()
2
.identity(&format!("order-worker-{}", std::env::var("POD_NAME").unwrap_or_default()))
3
// ...

Next Steps

  • Creating a Worker — Builder API and configuration options
  • Connectivity — Registration, polling, heartbeats, and eager dispatch
  • Scaling — Horizontal scaling, recovery, and performance tuning
  • Operations — Graceful shutdown, monitoring, and troubleshooting