qail_workflow/runtime.rs
1//! Runtime safety contracts for workflow execution.
2//!
3//! These types describe optional production guarantees that app executors can
4//! back with database rows, advisory locks, outbox tables, or provider-specific
5//! idempotency keys.
6
7use std::time::Duration;
8
9use serde_json::Value;
10
11/// Optional runtime controls for a workflow run/resume/timeout operation.
12#[derive(Debug, Clone, Default, PartialEq, Eq)]
13pub struct WorkflowRunOptions {
14 /// Optional per-workflow lease acquired before execution starts.
15 pub lease: Option<WorkflowLeaseOptions>,
16 /// Optional idempotency key for the external operation being handled.
17 pub idempotency_key: Option<String>,
18}
19
20impl WorkflowRunOptions {
21 /// Add a per-workflow lease requirement.
22 pub fn with_lease(mut self, owner: impl Into<String>, ttl: Duration) -> Self {
23 self.lease = Some(WorkflowLeaseOptions {
24 owner: owner.into(),
25 ttl,
26 });
27 self
28 }
29
30 /// Add an operation idempotency key.
31 pub fn with_idempotency_key(mut self, key: impl Into<String>) -> Self {
32 self.idempotency_key = Some(key.into());
33 self
34 }
35}
36
37/// Per-workflow lease acquisition request.
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub struct WorkflowLeaseOptions {
40 /// Worker/process identity that owns the lease while executing.
41 pub owner: String,
42 /// Lease time-to-live. Backends should expire abandoned leases after this.
43 pub ttl: Duration,
44}
45
46/// Lease held for the duration of one workflow operation.
47#[derive(Debug, Clone, PartialEq, Eq)]
48pub struct WorkflowLease {
49 /// Workflow instance id.
50 pub workflow_id: String,
51 /// Worker/process identity that owns the lease.
52 pub owner: String,
53 /// Lease time-to-live.
54 pub ttl: Duration,
55}
56
57/// High-level workflow operation kind for idempotency ledgers.
58#[derive(Debug, Clone, PartialEq, Eq)]
59pub enum WorkflowOperationKind {
60 /// Direct run from the current state.
61 Run,
62 /// Resume from an external event.
63 Resume {
64 /// Event name accepted by the wait cursor.
65 event: String,
66 },
67 /// Execute a timed-out wait fallback.
68 Timeout,
69}
70
71/// Idempotent workflow operation request.
72#[derive(Debug, Clone, PartialEq, Eq)]
73pub struct WorkflowOperation {
74 /// Workflow definition name.
75 pub workflow_name: String,
76 /// Workflow instance id.
77 pub workflow_id: String,
78 /// Caller-provided idempotency key.
79 pub idempotency_key: String,
80 /// Operation kind.
81 pub kind: WorkflowOperationKind,
82}
83
84/// Operation ledger decision.
85#[derive(Debug, Clone, PartialEq, Eq)]
86pub enum WorkflowOperationStatus {
87 /// This caller owns execution for this idempotency key.
88 Started,
89 /// Another worker is currently handling this idempotency key.
90 InProgress,
91 /// This idempotency key already completed with a final state.
92 Completed {
93 /// Previously completed workflow state.
94 state: String,
95 },
96}
97
98/// Side-effect kind used for idempotent outbox/provider calls.
99#[derive(Debug, Clone, Copy, PartialEq, Eq)]
100pub enum WorkflowSideEffectKind {
101 /// QAIL query execution.
102 Query,
103 /// External notification delivery.
104 Notify,
105 /// Payment charge creation.
106 Charge,
107}
108
109impl WorkflowSideEffectKind {
110 /// Stable lowercase identifier for operation keys.
111 pub fn as_str(self) -> &'static str {
112 match self {
113 Self::Query => "query",
114 Self::Notify => "notify",
115 Self::Charge => "charge",
116 }
117 }
118}
119
120/// Stable side-effect operation identity.
121#[derive(Debug, Clone, PartialEq, Eq)]
122pub struct WorkflowSideEffect {
123 /// Workflow instance id.
124 pub workflow_id: String,
125 /// Workflow state that owns this step.
126 pub state: String,
127 /// Stable nested step path within the workflow definition.
128 pub step_path: String,
129 /// Side-effect kind.
130 pub kind: WorkflowSideEffectKind,
131 /// Stable operation id for DB uniqueness/idempotency.
132 pub operation_id: String,
133}
134
135/// Side-effect ledger decision.
136#[derive(Debug, Clone, PartialEq)]
137pub enum WorkflowSideEffectStatus {
138 /// Execute the side effect now.
139 Execute,
140 /// The side effect already completed. `result` is used for query/charge
141 /// steps that need to restore stored context values.
142 AlreadyCompleted {
143 /// Previously recorded side-effect result.
144 result: Option<Value>,
145 },
146}
147
148/// Result of one workflow timeout attempt in a timeout drain batch.
149#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct WorkflowTimeoutOutcome {
151 /// Workflow instance id.
152 pub workflow_id: String,
153 /// Final/current state if timeout execution succeeded.
154 pub state: Option<String>,
155 /// Error text if timeout execution failed.
156 pub error: Option<String>,
157}