Skip to main content

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}