Module workflow_interceptors

Expand description

Intercept inbound and outbound calls made during workflow execution.

Workflow interceptors allow observing, transforming, or short-circuit workflow operations without putting that behavior in each workflow implementation.

WorkflowInterceptor has two groups of methods:

Inbound methods wrap calls into workflow code, such as executing the workflow or handling a signal, query, or update.
Outbound methods wrap commands issued by workflow code, such as scheduling an activity, starting a timer, or signaling another workflow.

Each method receives a WorkflowNext continuation. An interceptor can change the input before calling WorkflowNext::run, inspect or change the returned value, or deliberately not call next to short-circuit the operation. Most interceptors should call next exactly once.

Async operation interceptors return WorkflowInterceptorFuture. Wrap an async block with WorkflowInterceptorFuture::new when work must happen after the next interceptor completes. Synchronous methods, including queries and update validators, cannot await workflow operations.

Workers register interceptors with register_workflow_interceptors on their worker options. Interceptors are entered in insertion order for inbound calls and in reverse insertion order for outbound calls.

§Determinism

Interceptors execute as part of the workflow and are replayed with it. They must follow the same determinism rules as workflow code: do not read wall-clock time, perform network or filesystem I/O, use nondeterministic randomness, or await arbitrary futures. Use values from the interceptor context and SDK-provided workflow futures instead. WorkflowInterceptorFuture identifies a future for the workflow scheduler; it does not make an arbitrary future deterministic.

WorkflowInterceptorContext::is_replaying and WorkflowInterceptorContext::is_replaying_history_events can be used to suppress duplicate external observability during replay, but replay state must not change commands or results that affect workflow behavior.

§Example

This interceptor wraps workflow execution and transforms string outputs after the workflow has completed. The constructor is passed to the worker during worker setup.


struct UppercaseStringOutput;

impl WorkflowInterceptor for UppercaseStringOutput {
    fn execute<'a>(
        &'a self,
        _ctx: WorkflowInterceptorContext,
        input: ExecuteWorkflowInput,
        next: WorkflowNext<
            'a,
            ExecuteWorkflowInput,
            WorkflowInterceptorFuture<'a, ExecuteWorkflowResult>,
        >,
    ) -> WorkflowInterceptorFuture<'a, ExecuteWorkflowResult> {
        WorkflowInterceptorFuture::new(async move {
            let output = next.run(input).await?;
            if let Some(value) = output.downcast_ref::<String>() {
                return Ok(Box::new(value.to_uppercase()) as Box<dyn WorkflowOutputValue>);
            }
            Ok(output)
        })
    }
}

fn interceptor_constructor() -> WorkflowInterceptorConstructor {
    WorkflowInterceptorConstructor::new(|_ctx: &WorkflowContextView| UppercaseStringOutput)
}

Structs§

CancelExternalWorkflowInput: Input passed to WorkflowInterceptor::cancel_external_workflow.
CancellableWorkflowOutboundFuture: Future returned by a cancellable outbound interceptor operation.
ContinueAsNewInput: Input passed to WorkflowInterceptor::continue_as_new.
ExecuteWorkflowInput: Input passed to WorkflowInterceptor::execute.
HandleQueryInput: Input passed to WorkflowInterceptor::handle_query.
HandleSignalInput: Input passed to WorkflowInterceptor::handle_signal.
HandleUpdateInput: Input passed to WorkflowInterceptor::handle_update.
InitializeWorkflowInput: Input passed to WorkflowInterceptor::initialize_workflow.
InitializeWorkflowOutput: Result of workflow initialization.
ScheduleActivityInput: Input passed to WorkflowInterceptor::schedule_activity.
ScheduleLocalActivityInput: Input passed to WorkflowInterceptor::schedule_local_activity.
SignalWorkflowInput: Input passed to WorkflowInterceptor::signal_workflow.
StartChildWorkflowInput: Input passed to WorkflowInterceptor::start_child_workflow.
StartNexusOperationInput: Input passed to WorkflowInterceptor::start_nexus_operation.
StartTimerInput: Input passed to WorkflowInterceptor::start_timer.
SyncWorkflowInterceptorContext: Workflow execution context available to sync-only inbound interceptors.
ValidateUpdateInput: Input passed to WorkflowInterceptor::validate_update.
WorkflowCancellationHandle: Cancellation callback retained when an interceptor wraps an operation future.
WorkflowInterceptorConstructor: Creates one interceptor for each in-memory workflow instance.
WorkflowInterceptorContext: Workflow execution context available to async-capable inbound interceptors.
WorkflowInterceptorFuture: Future produced by workflow interceptors.
WorkflowNext: Continuation for a workflow interceptor operation.
WorkflowOutboundFuture: Future returned by a non-cancellable outbound interceptor operation.

Enums§

SignalWorkflowTarget: Workflow targeted by an outbound signal.

Traits§

WorkflowInterceptor: Interceptor for calls into workflow code and commands issued by workflow code.
WorkflowOutboundValue: Type-erased output returned by an intercepted outbound workflow call.
WorkflowOutputValue: Type-erased workflow output carried through the workflow interceptor chain.

Type Aliases§

ChildWorkflowOutboundResult: Result of an intercepted child workflow completion.
ContinueAsNewResult: Result of an intercepted continue-as-new call.
ExecuteWorkflowResult: Result of an intercepted workflow execution.
HandleQueryResult: Result of an intercepted query handler.
HandleSignalResult: Result of an intercepted signal handler.
HandleUpdateResult: Result of an intercepted update handler.
ScheduleActivityResult: Result of an intercepted activity call.
SignalWorkflowResult: Result of an intercepted signal call.
StartChildWorkflowResult: Result of an intercepted child workflow start.
StartNexusOperationResult: Result of an intercepted Nexus operation start.
ValidateUpdateResult: Result of an intercepted update validator.