use crate::error::{Error, Result};
use crate::workflow::command::{CancelChildWorkflowCommand, SendEventCommand, WorkflowCommand};
use crate::workflow::WorkflowContext;
use serde::{de::DeserializeOwned, Serialize};
#[derive(Clone)]
pub struct ChildWorkflowHandle {
workflow_id: String,
run_id: String,
workflow_type: String,
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 {
pub(crate) fn new(
workflow_id: String,
run_id: String,
workflow_type: String,
ctx: WorkflowContext,
) -> Self {
Self {
workflow_id,
run_id,
workflow_type,
ctx,
}
}
pub fn id(&self) -> &str {
&self.workflow_id
}
pub fn run_id(&self) -> &str {
&self.run_id
}
pub fn workflow_type(&self) -> &str {
&self.workflow_type
}
pub async fn result<O: DeserializeOwned>(&self) -> Result<O> {
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() {
state.observe(&key);
}
cached
};
let Some(result_bytes) = cached else {
return Err(Error::Workflow(crate::error::WorkflowError::Suspended {
reason: format!("Waiting for child workflow {}", self.workflow_id),
pending_operations: vec![self.workflow_id.clone()],
}));
};
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
))
})
}
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
}
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
}
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};
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)
}
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");
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");
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);
}
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"
);
}
}