Guides

Versioning, Lifecycle & Queries


Workflow Versioning

As your application evolves, you'll need to change workflow logic — adding steps, changing inputs, or modifying behavior. The version field labels each workflow definition so you can track which version produced a given run and roll out new code deliberately.

The version you set is recorded with each execution, but it is an observability label — not an automatic router. Orcher dispatches work by workflow name and task queue, not by version, and it does not pin an in-flight workflow to the code version it started on. Determinism is why this matters: a workflow already in progress replays its journal against your current code, so changing the step sequence of a running workflow causes non-determinism errors on replay.

To change workflow logic safely while executions are in flight, avoid editing code that in-progress workflows will replay. Instead:

  • Run versions side by side — register the new logic under a distinct workflow name and route new executions there, keeping the old definition deployed until existing runs finish.
  • Drain, then cut over — stop starting new executions on the old code, let in-flight ones complete, then deploy the change.
  • Restart-fresh — for long-running workflows, restart-fresh onto the new logic from a clean journal at a safe point.
1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
// Version 1.0.0
5
#[workflow(
6
name = "order_workflow",
7
version = "1.0.0"
8
)]
9
pub async fn order_workflow_v1(
10
ctx: WorkflowContext,
11
order_id: String,
12
) -> Result<String> {
13
// Original implementation
14
Ok(order_id)
15
}
16
17
// Version 2.0.0 (with new features)
18
#[workflow(
19
name = "order_workflow_v2",
20
version = "2.0.0"
21
)]
22
pub async fn order_workflow_v2(
23
ctx: WorkflowContext,
24
input: OrderInput, // New input type
25
) -> Result<OrderOutput> { // New output type
26
// Enhanced implementation
27
Ok(OrderOutput { order_id: input.order_id })
28
}

Workflow Lifecycle

Every workflow progresses through a set of states. Understanding these states helps you reason about what your workflow is doing at any point and how to handle different scenarios.

Workflow Lifecycle
Pending
dispatched to a worker
Running
suspend →
← resume
Suspended
reaches one terminal state
Completed
Failed
Timed Out
Canceled
Terminated
Reset
Restarted-Fresh
A workflow runs — suspending and resuming as needed — until it settles into exactly one terminal state.
  • Pending — The workflow has been created (via start_workflow) but not yet picked up by a worker. It waits in a task queue for dispatch — typically brief unless every worker is busy.

  • Running — A worker is actively executing the workflow code, progressing through steps, executing tasks, and writing journal entries. A workflow may move between Running and Suspended many times over its life.

  • Suspended — The workflow is waiting for something: a durable timer to fire, an event to arrive, or a child workflow to finish. The worker releases it while it waits, so no resources are consumed. When the condition is met, it is re-dispatched and returns to Running.

  • Completed — The workflow function returned successfully. The result is stored and can be retrieved from the client (for example, handle.result()). Terminal.

  • Failed — The workflow function returned an error (or threw an uncaught exception). The error is stored for inspection. Depending on the retry policy, the workflow may be retried before reaching this state. Terminal.

  • Timed Out — The workflow exceeded its configured execution or run timeout before finishing. Terminal.

  • Canceled — Cancellation was requested through the API and the workflow stopped cooperatively, with an opportunity to run cleanup logic. Terminal.

  • Terminated — The workflow was forcefully terminated through the API. It stops immediately, without a chance to clean up — the blunter counterpart to Canceled. Terminal.

  • Reset — The workflow was rewound to an earlier journal point via the reset API. A new execution replays the journal up to the target event, then re-executes from there making fresh decisions; the original execution is marked Reset. Useful for recovering from a bad deploy or debugging a production failure without re-running from scratch.

  • Restarted-Fresh — The workflow called restart-fresh: the current execution ends and a new one continues the work with a clean journal, keeping history bounded. Terminal for this execution.


Querying Workflows

You can inspect the state of running or completed workflows from outside the workflow. This is useful for building dashboards, checking on long-running processes, or retrieving results.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[tokio::main]
5
async fn main() -> Result<()> {
6
let client = Client::connect("http://localhost:50051").await?;
7
8
// Start workflow
9
let handle = client
10
.start_workflow("process_payment", payment_input)
11
.await?;
12
13
// Get result (waits for completion)
14
let result: PaymentOutput = handle.result().await?;
15
16
Ok(())
17
}

Next Steps