Guides

How Journaling Works


The best way to understand journaling is to see it in action. The examples below show a payment workflow with three steps. On first execution, each step runs normally and its result is journaled. If the workflow crashes and replays, completed steps return their journaled result instantly — the external API calls never happen again.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[task]
5
pub async fn charge_card(_ctx: TaskContext, input: PaymentInput) -> Result<ChargeResult> {
6
// Call Stripe API...
7
}
8
9
#[task]
10
pub async fn reserve_inventory(_ctx: TaskContext, order_id: String) -> Result<InventoryResult> {
11
// Reserve stock...
12
}
13
14
#[task]
15
pub async fn send_confirmation(_ctx: TaskContext, charge_id: String) -> Result<()> {
16
// Send email...
17
}
18
19
#[workflow]
20
pub async fn payment_workflow(
21
ctx: WorkflowContext,
22
order: OrderInput,
23
) -> Result<PaymentResult> {
24
// Step 1: Charge card
25
// First execution: Executes and journals result
26
// Replay: Returns journaled result without re-executing
27
let charge: ChargeResult = ctx
28
.execute_task(charge_card, order.clone())
29
.await?;
30
31
// If crash happens here, step 1 is already journaled
32
33
// Step 2: Reserve inventory
34
// First execution: Executes and journals result
35
// Replay: Returns journaled result
36
let inventory: InventoryResult = ctx
37
.execute_task(reserve_inventory, order.id.clone())
38
.await?;
39
40
// Step 3: Send confirmation
41
// Always executes (not in journal yet)
42
ctx.execute_task(send_confirmation, charge.id.clone()).await?;
43
44
Ok(PaymentResult {
45
charge_id: charge.id,
46
reserved: inventory.reserved,
47
})
48
}

Execution vs Replay

The diagram below contrasts what happens during a workflow's first execution versus a replay after a crash. On first execution, each step runs its real logic and the result is journaled. On replay, the SDK loads the journal and returns cached results — the original code is never re-invoked.

First execution · normal flow
1
charge_card
Call Stripe API · journal StepCompleted → ch_123 · execution log → completed
2
reserve_inventory
Update database · journal StepCompleted → ok · execution log → completed
💥 Crash — server restart, network failure, etc.
Replay after crash
Server loads the journal → the SDK bridge converts entries to RequestJobs → inject_step_results() populates the in-memory cache before the handler runs.
1
charge_card cache HIT
Returns ch_123 from cache — Stripe API is not called again
2
reserve_inventory cache HIT
Returns ok from cache — the database is not updated again
3
send_confirmation cache MISS
No journal entry → executes for the first time (send email) · journal StepCompleted → sent
Workflow completed — no committed step ran again

Under the Hood

This section traces the full path a step takes — from your SDK call, through the server's command processor, into PostgreSQL, and back out during replay. Understanding this flow helps you reason about what happens when things go wrong.

SDK Rust · Python · TypeScript
ctx.execute_task(charge_card, input)
is_replaying? → check pendingTaskResults cache
HIT → return cached result (no command emitted)
MISS → emit ScheduleTaskCommand, suspend
ctx.execute("step_name", closure)
HIT → return cached result
MISS → run closure, emit RecordStepResult
commands · protobuf
Server CommandProcessor
ScheduleTaskCommand
create TaskExecution (scheduled) · dispatch to outbox queue · append TaskScheduled
RecordStepResultCommand
upsert execution_log · append StepCompleted
persisted · PostgreSQL
On next poll replay
1 · load journal (HighPerfCache → DB fallback)
2 · sdk-core bridge journal_to_jobs(): StepCompleted → CompleteStep · EventReceived → HandleEvent · TimerFired → FireTimer
3 · set is_replaying = true
4 · inject_step_results() → populate cache
5 · run workflow handler (cache hits skip re-execution)

Two Storage Layers

LayerTableKeyPurpose
Execution Logexecution_log(workflow_id, step_name)Step-level idempotency cache. Stores result, status, attempt count. Used for ctx.execute() replay protection.
Journalworkflow_execution_journal(workflow_id, execution_id, event_id)Append-only event history. Full audit trail. Provides the entries that drive replay via journal_to_jobs().

In-Memory Cache (HighPerfCache)

Orcher uses a Moka-based cache to avoid hitting PostgreSQL on every replay:

  • TTL: 60 seconds per entry
  • Max entries: 5,000 cached journals
  • Incremental loading: On cache hit, only loads entries with event_id > max_cached_event_id (partial DB query instead of full reload)
  • Optimistic append: When a new entry is written, it's appended to the in-memory cache immediately (no DB roundtrip to refresh)
  • Metrics: journal_hits, journal_misses, journal_hit_rate() tracked for observability

Journal Entry Structure

Each entry in the workflow_execution_journal table:

1
{
2
"id": 12345,
3
"workflow_id": "order-processing-abc123",
4
"execution_id": "exec_xyz789",
5
"event_id": 3,
6
"event_type": "StepCompleted",
7
"timestamp": "2024-01-15T10:30:45.123Z",
8
"payload": {
9
"step_name": "charge_card",
10
"result": {
11
"charge_id": "ch_abc123",
12
"status": "succeeded"
13
}
14
},
15
"version": 0,
16
"task_id": 456,
17
"organization_id": "org_123",
18
"shard_id": 0,
19
"created_at": "2024-01-15T10:30:45.123Z"
20
}

Journal Entry Types

Orcher records different types of entries throughout workflow execution:

Step Events

Step events track the completion of individual operations within a workflow. These are the most common entry type and drive the replay mechanism.

  • StepCompleted — A step finished (inline closure, distributed task, child workflow, or side effect). This is the primary entry type that drives replay.

Workflow Lifecycle

These events mark the major state transitions of a workflow execution — from start through completion, failure, cancellation, or timeout.

  • WorkflowExecutionStarted — Workflow begins execution
  • WorkflowExecutionCompleted — Workflow completes successfully
  • WorkflowExecutionFailed — Workflow fails with error
  • WorkflowExecutionCanceled — Workflow is cancelled
  • WorkflowExecutionTimedOut — Workflow exceeds timeout
  • WorkflowExecutionRestartedFresh — Workflow restarted with clean state

Task Events

Task events track the lifecycle of distributed tasks dispatched to task queues. These entries record when a task is scheduled, completes, fails, or is cancelled.

  • TaskScheduled — Task dispatched to task queue
  • TaskCompleted — Task completes successfully
  • TaskFailed — Task fails with error
  • TaskCanceled — Task is cancelled

Signal and Event Events

Signal events record inter-workflow communication. These track when external events are delivered to a workflow or when a workflow sends a signal to another workflow.

  • EventReceived — External signal/event delivered to workflow (data is base64-encoded in the payload field)
  • ExternalEventSent — Workflow sent a signal to another workflow

Child Workflow Events

Child workflow events track the full lifecycle of workflows spawned by a parent. These entries enable the parent to monitor and replay child workflow results.

  • ChildWorkflowExecutionInitiated — Child workflow created
  • ChildWorkflowExecutionStarted — Child workflow begins running
  • ChildWorkflowExecutionCompleted — Child workflow completes
  • ChildWorkflowExecutionFailed — Child workflow fails
  • ChildWorkflowExecutionTimedOut — Child workflow exceeds timeout
  • ChildWorkflowExecutionCanceled — Child workflow is cancelled

Timer Events

Timer events record durable sleeps and delays within a workflow.

  • TimerFired — Timer/sleep completes

Next Steps