orcher-sdk 0.7.0

Rust SDK for Orcher, a durable workflow engine: workflows, tasks, actors, workers and a client
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
//! Handle a parent workflow uses to wait on a child workflow it started.

use crate::error::{Error, Result};
use crate::workflow::command::{CancelChildWorkflowCommand, SendEventCommand, WorkflowCommand};
use crate::workflow::WorkflowContext;
use serde::{de::DeserializeOwned, Serialize};

/// Handle to a child workflow started without waiting for its result.
///
/// Use [`ChildWorkflowHandle::result`] to wait for the child,
/// [`send_event`](Self::send_event) to send it an event, and
/// [`cancel`](Self::cancel) to cancel it.
///
/// ## Example
///
/// ```rust
/// use orcher_sdk::prelude::*;
/// use std::time::Duration;
///
/// #[derive(Serialize, Deserialize)]
/// struct OrderResult {
///     status: String,
/// }
///
/// #[workflow]
/// async fn parent_workflow(ctx: WorkflowContext, order_id: String) -> Result<String> {
///     // Start the child without waiting for it
///     let child = ctx.start_child_workflow("process_order", order_id).await?;
///
///     // Do other work meanwhile
///     ctx.sleep(Duration::from_secs(60)).await?;
///
///     // Then wait for the child's result
///     let result: OrderResult = child.result().await?;
///
///     Ok(result.status)
/// }
/// ```
#[derive(Clone)]
pub struct ChildWorkflowHandle {
    workflow_id: String,

    run_id: String,

    workflow_type: String,

    /// The parent's context. The runtime injects the child's completion into
    /// `pending_task_results` under `child:{workflow_id}`, the same entry the
    /// execute path reads, so the handle keeps no result state of its own.
    ctx: WorkflowContext,
}

impl std::fmt::Debug for ChildWorkflowHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ChildWorkflowHandle")
            .field("workflow_id", &self.workflow_id)
            .field("run_id", &self.run_id)
            .field("workflow_type", &self.workflow_type)
            .finish_non_exhaustive()
    }
}

impl ChildWorkflowHandle {
    /// Creates a handle; the SDK calls this when it starts a child workflow.
    pub(crate) fn new(
        workflow_id: String,
        run_id: String,
        workflow_type: String,
        ctx: WorkflowContext,
    ) -> Self {
        Self {
            workflow_id,
            run_id,
            workflow_type,
            ctx,
        }
    }

    /// Returns the child workflow ID.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use orcher_sdk::prelude::*;
    /// # async fn example(child: ChildWorkflowHandle) {
    /// let workflow_id = child.id();
    /// println!("Child workflow ID: {}", workflow_id);
    /// # }
    /// ```
    pub fn id(&self) -> &str {
        &self.workflow_id
    }

    /// Returns the child's run ID, which is unique to each run of the workflow.
    pub fn run_id(&self) -> &str {
        &self.run_id
    }

    /// Returns the child workflow type.
    pub fn workflow_type(&self) -> &str {
        &self.workflow_type
    }

    /// Waits for the child workflow to finish and returns its result.
    ///
    /// Until the child finishes, this returns a suspension error; the runtime
    /// then waits for the child and replays the workflow, and on replay the
    /// result is available.
    ///
    /// # Errors
    ///
    /// Returns `ChildWorkflowFailed` if the child did not complete successfully,
    /// and a serialization error if the result does not deserialize into `O`.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use orcher_sdk::prelude::*;
    /// #[derive(Deserialize)]
    /// struct OrderResult {
    ///     order_id: String,
    /// }
    ///
    /// # async fn example(ctx: &WorkflowContext, input: String) -> Result<()> {
    /// let child = ctx.start_child_workflow("process_order", input).await?;
    ///
    /// let result: OrderResult = child.result().await?;
    /// tracing::info!(order_id = %result.order_id, "order processed");
    /// # Ok(())
    /// # }
    /// ```
    pub async fn result<O: DeserializeOwned>(&self) -> Result<O> {
        // The runtime stores the child's completion under `child:{id}`: the
        // result bytes on success, or a `{"__orcher_child_failed__":true,
        // "message":...}` sentinel on failure. The execute path reads the same entry.
        let cached = {
            let state = self.ctx.state.lock().unwrap();
            let key = format!("child:{}", self.workflow_id);
            let cached = state.pending_task_results.get(&key).cloned();
            if cached.is_some() {
                // Received: the workflow's clock moves to when it was journaled.
                state.observe(&key);
            }
            cached
        };

        let Some(result_bytes) = cached else {
            // Not finished yet: suspend so the runtime waits for the child.
            return Err(Error::Workflow(crate::error::WorkflowError::Suspended {
                reason: format!("Waiting for child workflow {}", self.workflow_id),
                pending_operations: vec![self.workflow_id.clone()],
            }));
        };

        // Turn the failure sentinel into an error the workflow can catch.
        if let Ok(v) = serde_json::from_slice::<serde_json::Value>(&result_bytes) {
            if v.get("__orcher_child_failed__")
                .and_then(|b| b.as_bool())
                .unwrap_or(false)
            {
                let msg = v
                    .get("message")
                    .and_then(|m| m.as_str())
                    .unwrap_or("child workflow failed");
                return Err(Error::Workflow(
                    crate::error::WorkflowError::ChildWorkflowFailed {
                        workflow_type: self.workflow_type.clone(),
                        workflow_id: self.workflow_id.clone(),
                        reason: msg.to_string(),
                    },
                ));
            }
        }

        serde_json::from_slice(&result_bytes).map_err(|e| {
            Error::Serialization(format!(
                "Failed to deserialize child workflow result: {}",
                e
            ))
        })
    }

    /// Sends an event to the child workflow, which receives it with
    /// [`WorkflowContext::wait_for_event`].
    ///
    /// The send is journaled as a step: it reaches the engine with the commands
    /// of the run that makes it, and a replay of the parent does not send it
    /// again.
    ///
    /// # Errors
    ///
    /// Returns a serialization error if `arg` cannot be serialized.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use orcher_sdk::prelude::*;
    /// # use serde::{Serialize, Deserialize};
    /// # async fn example(child: ChildWorkflowHandle) -> Result<()> {
    /// #[derive(Serialize, Deserialize)]
    /// struct ApprovalData {
    ///     approved: bool,
    ///     approver: String,
    /// }
    ///
    /// child.send_event("approve_order", ApprovalData {
    ///     approved: true,
    ///     approver: "manager@example.com".to_string(),
    /// }).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn send_event<E: Serialize>(&self, event_name: &str, arg: E) -> Result<()> {
        let data = serde_json::to_vec(&arg).map_err(|e| {
            Error::Serialization(format!("Failed to serialize event payload: {}", e))
        })?;
        let command = WorkflowCommand::SendEvent(SendEventCommand {
            sequence: self.ctx.next_sequence(),
            workflow_id: self.workflow_id.clone(),
            event_name: event_name.to_string(),
            data,
        });
        self.emit_once(
            &format!("send_event:{}:{}", self.workflow_id, event_name),
            command,
        )
        .await
    }

    /// Requests cancellation of the child workflow.
    ///
    /// The child is canceled the way a client cancels a workflow, and
    /// [`result`](Self::result) then fails with `ChildWorkflowFailed`. Like
    /// [`send_event`](Self::send_event), the request is journaled as a step and
    /// not repeated on replay; canceling a child that has already finished does
    /// nothing.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use orcher_sdk::prelude::*;
    /// # async fn example(child: ChildWorkflowHandle) -> Result<()> {
    /// child.cancel().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn cancel(&self) -> Result<()> {
        let command = WorkflowCommand::CancelChildWorkflow(CancelChildWorkflowCommand {
            sequence: self.ctx.next_sequence(),
            workflow_id: self.workflow_id.clone(),
        });
        self.emit_once(&format!("cancel_child:{}", self.workflow_id), command)
            .await
    }

    /// Emits `command` once across replays.
    ///
    /// The engine keeps no record a worker could read for these commands, so
    /// the emission runs as an inline step: the first run adds the command and
    /// journals the step, and a replay returns the journaled step without
    /// adding it again.
    async fn emit_once(&self, step_name: &str, command: WorkflowCommand) -> Result<()> {
        let ctx = self.ctx.clone();
        self.ctx
            .execute(step_name, move || async move {
                ctx.add_command(command);
                Ok(())
            })
            .await
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::workflow::{WorkflowContext, WorkflowExecution};

    /// Builds a handle on a fresh context's state, so `result()` reads the same
    /// `child:{id}` entry the runtime writes.
    fn make_handle(child_id: &str) -> (WorkflowContext, ChildWorkflowHandle) {
        let execution = WorkflowExecution {
            workflow_id: "parent-wf".to_string(),
            run_id: "parent-run".to_string(),
            workflow_type: "ParentWorkflow".to_string(),
            attempt: 1,
            namespace: "default".to_string(),
            task_queue: "test-queue".to_string(),
        };
        let ctx = WorkflowContext::new(execution, false, "1.0".to_string());
        let handle = ChildWorkflowHandle::new(
            child_id.to_string(),
            "run-456".to_string(),
            "OrderWorkflow".to_string(),
            ctx.clone(),
        );
        (ctx, handle)
    }

    /// Stores a child completion the way the runtime does on a
    /// ChildWorkflowCompleted or ChildWorkflowFailed job.
    fn inject_child(ctx: &WorkflowContext, child_id: &str, bytes: Vec<u8>) {
        ctx.state
            .lock()
            .unwrap()
            .pending_task_results
            .insert(format!("child:{}", child_id), bytes);
    }

    #[test]
    fn test_child_workflow_handle_creation() {
        let (_ctx, handle) = make_handle("child-wf-123");

        assert_eq!(handle.id(), "child-wf-123");
        assert_eq!(handle.run_id(), "run-456");
        assert_eq!(handle.workflow_type(), "OrderWorkflow");
    }

    #[tokio::test]
    async fn test_child_workflow_result_not_ready() {
        let (_ctx, handle) = make_handle("child-wf-123");

        // No completion stored yet, so the call suspends.
        let result: Result<String> = handle.result().await;
        assert!(matches!(
            result,
            Err(Error::Workflow(
                crate::error::WorkflowError::Suspended { .. }
            ))
        ));
    }

    #[tokio::test]
    async fn test_child_workflow_result_from_cache() {
        let (ctx, handle) = make_handle("child-wf-123");
        inject_child(
            &ctx,
            "child-wf-123",
            serde_json::to_vec(&"success".to_string()).unwrap(),
        );

        let result: String = handle.result().await.unwrap();
        assert_eq!(result, "success");
    }

    #[tokio::test]
    async fn test_child_workflow_failure_sentinel() {
        let (ctx, handle) = make_handle("child-wf-123");
        // The runtime stores a failed child as this sentinel.
        let sentinel = serde_json::json!({
            "__orcher_child_failed__": true,
            "message": "workflow failed",
        });
        inject_child(&ctx, "child-wf-123", serde_json::to_vec(&sentinel).unwrap());

        let result: Result<String> = handle.result().await;
        if let Err(Error::Workflow(crate::error::WorkflowError::ChildWorkflowFailed {
            workflow_type,
            workflow_id,
            reason,
        })) = result
        {
            assert_eq!(workflow_type, "OrderWorkflow");
            assert_eq!(workflow_id, "child-wf-123");
            assert_eq!(reason, "workflow failed");
        } else {
            panic!("Expected ChildWorkflowFailed error");
        }
    }

    #[tokio::test]
    async fn test_child_workflow_result_deserialization() {
        use serde::{Deserialize, Serialize};

        #[derive(Serialize, Deserialize, PartialEq, Debug)]
        struct OrderResult {
            order_id: String,
            total: f64,
        }

        let (ctx, handle) = make_handle("child-wf-123");
        let order_result = OrderResult {
            order_id: "order-999".to_string(),
            total: 99.99,
        };
        inject_child(
            &ctx,
            "child-wf-123",
            serde_json::to_vec(&order_result).unwrap(),
        );

        let result: OrderResult = handle.result().await.unwrap();
        assert_eq!(result, order_result);
    }

    /// Runs `op` on a fresh parent, then again on a replay that has the first
    /// run's journaled steps, and returns the commands each run emitted.
    async fn first_run_and_replay<F, Fut>(op: F) -> (Vec<WorkflowCommand>, Vec<WorkflowCommand>)
    where
        F: Fn(ChildWorkflowHandle) -> Fut,
        Fut: std::future::Future<Output = Result<()>>,
    {
        let (ctx, handle) = make_handle("child-wf-123");
        op(handle).await.unwrap();
        let first = ctx.commands_for_test();

        let journaled = crate::workflow::closure_commands::extract_closure_commands(&ctx).unwrap();
        assert_eq!(journaled.len(), 1, "the command is journaled as one step");

        let (replay, handle) = make_handle("child-wf-123");
        replay.set_replaying_for_test(true);
        for step in journaled {
            replay.inject_step_result(step.step_name, step.result);
        }
        op(handle).await.unwrap();
        (first, replay.commands_for_test())
    }

    #[tokio::test]
    async fn test_child_workflow_send_event_is_sent_once() {
        let (first, replay) =
            first_run_and_replay(|handle| async move { handle.send_event("approve", true).await })
                .await;

        let sent: Vec<_> = first
            .iter()
            .filter_map(|c| match c {
                WorkflowCommand::SendEvent(e) => Some(e),
                _ => None,
            })
            .collect();
        assert_eq!(sent.len(), 1);
        assert_eq!(sent[0].workflow_id, "child-wf-123");
        assert_eq!(sent[0].event_name, "approve");
        assert_eq!(sent[0].data, b"true");

        assert!(
            !replay
                .iter()
                .any(|c| matches!(c, WorkflowCommand::SendEvent(_))),
            "a replay must not send the event again"
        );
    }

    #[tokio::test]
    async fn test_child_workflow_cancel_is_requested_once() {
        let (first, replay) =
            first_run_and_replay(|handle| async move { handle.cancel().await }).await;

        let canceled: Vec<_> = first
            .iter()
            .filter_map(|c| match c {
                WorkflowCommand::CancelChildWorkflow(c) => Some(c),
                _ => None,
            })
            .collect();
        assert_eq!(canceled.len(), 1);
        assert_eq!(canceled[0].workflow_id, "child-wf-123");

        assert!(
            !replay
                .iter()
                .any(|c| matches!(c, WorkflowCommand::CancelChildWorkflow(_))),
            "a replay must not request cancellation again"
        );
    }
}