GitHub

workflow_engine

API reference for workflow_engine.

Workflow engines (Effect's effect/workflow/WorkflowEngine): the WorkflowEngine service, make_unsafe building one from an engine working on encoded values, and layer_memory, an engine keeping its state in memory (for tests and local development; nothing survives the process).

Re-exports

Values

AttributeTypeDescription
layer_memoryLayer[WorkflowEngine]

An engine keeping its state in memory: for tests and local development, not for workflows that must survive the process.

DEFAULT_SUSPENDED_RETRY_SCHEDULESchedule[Any, Any, Any, Any]

How a caller outside any workflow polls a suspended execution: exponential from 200 ms, at most 30 s apart.

Classes

Functions

make_deferred_state

make_deferred_state() -> DeferredState

Returns DeferredState

def make_deferred_state() -> DeferredState:
    return DeferredState()

make_unsafe

make_unsafe(options) -> WorkflowEngineService

A WorkflowEngineService over options, which must persist, resume and encode workflow state correctly.

ParameterTypeDescription
optionsEncoded

Returns WorkflowEngineService

def make_unsafe(options: Encoded) -> WorkflowEngineService:
    """A ``WorkflowEngineService`` over ``options``, which must persist,
    resume and encode workflow state correctly."""

    def register(workflow: AnyWorkflow, execute: Handler) -> Effect[None, Never, Scope]:
        def body() -> Generator[Effect[Any, Never, Any], Any]:
            services = yield from context()

            def handler(payload: Any, execution_id: str) -> Effect[Any, Any, Any]:
                return _Locally(
                    suspend(lambda: execute(payload, execution_id)),
                    services.merge,
                )

            yield from options.register(workflow, handler)

        return gen(body)

    def execute(
        workflow: AnyWorkflow,
        /,
        *,
        execution_id: str,
        payload: object,
        discard: bool = False,
        detached: bool = False,
        suspended_retry_schedule: Schedule[Any, Any, Any, Any] | None = None,
    ) -> Effect[Any, Any]:
        def body() -> Generator[Effect[Any, Any, Any], Any, Any]:
            if detached and not discard:
                return (
                    yield from die(
                        RuntimeError(f"{workflow.tag}.execute: detached requires discard")
                    )
                )
            schedule = (
                DEFAULT_SUSPENDED_RETRY_SCHEDULE
                if suspended_retry_schedule is None
                else suspended_retry_schedule
            )
            yield from annotate_current_span({"executionId": execution_id})
            result: list[Result[Any, Any]] = []

            # Link interruption with the parent workflow.
            parent = yield from service_option(WorkflowInstance)
            parent_instance = None if parent is None else parent.value
            if parent_instance is not None and not detached:
                linked = parent_instance

                def interrupt_child(_: Exit[Any, Any]) -> Effect[None]:
                    if not linked.interrupted or (result and isinstance(result[0], Complete)):
                        return succeed(None)
                    return options.interrupt(workflow, execution_id)

                yield from add_finalizer(interrupt_child)

            run = options.execute(
                workflow,
                execution_id=execution_id,
                payload=payload,
                discard=discard,
                parent=parent_instance,
                detached=detached,
            )
            if discard:
                yield from run
                return execution_id

            if parent_instance is not None:
                wrapped = yield from wrap_activity_result(
                    cast("Effect[Result[Any, Any], Never, Never]", run),
                    lambda r: isinstance(r, Suspended),
                )
                result[:] = [wrapped]
                if isinstance(wrapped, Suspended):
                    return (yield from suspend_run(parent_instance))
                # A child's interrupt is an outcome for the parent, not an
                # interrupt of the parent's run: the parent sees a defect.
                if isinstance(wrapped.exit, Failure) and wrapped.exit.cause.has_interrupts_only:
                    return (
                        yield from die(
                            f'{workflow.tag}.execute: execution "{execution_id}" was interrupted'
                        )
                    )
                return (yield from from_exit(wrapped.exit))

            step: Callable[[Any], Effect[Any, Any, Any]] | None = None
            while True:
                wrapped = cast("Result[Any, Any]", (yield from run))
                result[:] = [wrapped]
                if isinstance(wrapped, Complete):
                    return (yield from from_exit(wrapped.exit))
                if step is None:
                    step = yield from to_step_with_sleep(schedule)
                sleep = _sleep_step(step, workflow)
                # Completion wakes the caller early; the schedule is the fallback.
                yield from (
                    sleep
                    if options.await_complete is None
                    else sleep.race_first(options.await_complete(workflow, execution_id))
                )

        return cast("Effect[Any, Any]", gen(body))

    def activity_execute(
        activity: Activity[Any, Any, Any], attempt: int, /
    ) -> Effect[Result[Any, Any], Never, WorkflowInstance]:
        def decoded(result: Result[Any, Any]) -> Effect[Result[Any, Any]]:
            if isinstance(result, Suspended):
                return succeed(result)
            return (
                decode_unknown_effect(activity.exit_schema_partial)(result.exit)
                .or_die()
                .map(Complete)
            )

        return options.activity_execute(activity, attempt).flat_map(decoded)

    def deferred_result(
        deferred: DurableDeferred[Any, Any], /
    ) -> Effect[Exit[Any, Any] | None, Never, WorkflowInstance]:
        def body() -> Generator[Effect[Any, Never, Any], Any, Exit[Any, Any] | None]:
            instance = yield from WorkflowInstance()
            yield from annotate_current_span({"executionId": instance.execution_id})
            found = yield from options.deferred_result(deferred)
            if found is None:
                return None
            return (yield from decode_unknown_effect(deferred.exit_schema)(found).or_die())

        return gen(body).with_span(
            "WorkflowEngine.deferredResult",
            attributes={"name": deferred.name},
            capture_stack_trace=False,
        )

    def deferred_done(
        deferred: DurableDeferred[Any, Any],
        /,
        *,
        workflow_name: str,
        execution_id: str,
        deferred_name: str,
        exit: Exit[Any, Any],
    ) -> Effect[None]:
        return (
            encode_unknown_effect(deferred.exit_schema)(exit)
            .or_die()
            .flat_map(
                lambda encoded: options.deferred_done(
                    workflow_name=workflow_name,
                    execution_id=execution_id,
                    deferred_name=deferred_name,
                    exit=encoded,
                )
            )
            .with_span(
                "WorkflowEngine.deferredDone",
                attributes={"name": deferred_name, "executionId": execution_id},
                capture_stack_trace=False,
            )
        )

    def schedule_clock(
        workflow: AnyWorkflow, /, *, execution_id: str, clock: DurableClock
    ) -> Effect[None]:
        return options.schedule_clock(workflow, execution_id, clock).with_span(
            "WorkflowEngine.scheduleClock",
            attributes={"executionId": execution_id, "name": clock.name},
            capture_stack_trace=False,
        )

    return WorkflowEngineService(
        register=register,
        execute=execute,
        poll=options.poll,
        interrupt=options.interrupt,
        interrupt_unsafe=options.interrupt_unsafe,
        resume=options.resume,
        activity_execute=activity_execute,
        deferred_result=deferred_result,
        deferred_done=deferred_done,
        schedule_clock=schedule_clock,
    )