cadence-python-client 0.1.0__py3-none-any.whl

cadence/_internal/workflow/statemachine/decision_manager.py

@@ -0,0 +1,157 @@
+import asyncio
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Dict, Type, Tuple, ClassVar, List
+
+from cadence._internal.workflow.statemachine.activity_state_machine import (
+    activity_events,
+    ActivityStateMachine,
+)
+from cadence._internal.workflow.statemachine.decision_state_machine import (
+    DecisionId,
+    DecisionStateMachine,
+    DecisionType,
+    DecisionFuture,
+)
+from cadence._internal.workflow.statemachine.event_dispatcher import (
+    EventDispatcher,
+    Action,
+)
+from cadence._internal.workflow.statemachine.timer_state_machine import (
+    TimerStateMachine,
+    timer_events,
+)
+from cadence.api.v1 import decision, history
+from cadence.api.v1.common_pb2 import Payload
+
+DecisionAlias = Tuple[DecisionType, str | int]
+
+
+@dataclass(frozen=True)
+class EventDispatch:
+    decision_type: DecisionType
+    action: Action
+
+
+def _create_dispatch_map(
+    dispatchers: dict[DecisionType, EventDispatcher],
+) -> dict[Type, EventDispatch]:
+    result: dict[Type, EventDispatch] = {}
+    for decision_type, dispatcher in dispatchers.items():
+        for event_type, action in dispatcher.handlers.items():
+            if event_type in result:
+                raise ValueError(
+                    f"Received duplicate registration for {event_type}: {decision_type} and {result[event_type].decision_type}"
+                )
+            result[event_type] = EventDispatch(decision_type, action)
+
+    return result
+
+
+@dataclass
+class DecisionManager:
+    """Aggregates multiple decision state machines and coordinates decisions.
+
+    Typical flow per decision task:
+    - Instantiate/update state machines based on application intent and incoming history
+    - Call collect_pending_decisions() to build the decisions list
+    - Submit via RespondDecisionTaskCompleted
+    """
+
+    type_to_action: ClassVar[Dict[Type, EventDispatch]] = _create_dispatch_map(
+        {
+            DecisionType.ACTIVITY: activity_events,
+            DecisionType.TIMER: timer_events,
+        }
+    )
+    state_machines: OrderedDict[DecisionId, DecisionStateMachine] = field(
+        default_factory=OrderedDict
+    )
+    aliases: Dict[DecisionAlias, DecisionStateMachine] = field(default_factory=dict)
+
+    # ----- Activity API -----
+
+    def schedule_activity(
+        self, attrs: decision.ScheduleActivityTaskDecisionAttributes
+    ) -> asyncio.Future[Payload]:
+        decision_id = DecisionId(DecisionType.ACTIVITY, attrs.activity_id)
+        future = DecisionFuture[Payload](lambda: self._request_cancel(decision_id))
+        machine = ActivityStateMachine(attrs, future)
+        self._add_state_machine(machine)
+
+        return future
+
+    # ----- Timer API -----
+
+    def start_timer(
+        self, attrs: decision.StartTimerDecisionAttributes
+    ) -> asyncio.Future[None]:
+        decision_id = DecisionId(DecisionType.TIMER, attrs.timer_id)
+        future = DecisionFuture[None](lambda: self._request_cancel(decision_id))
+        machine = TimerStateMachine(attrs, future)
+        self._add_state_machine(machine)
+
+        return future
+
+    def _get_machine(self, decision_id: DecisionId) -> DecisionStateMachine:
+        machine = self.state_machines.get(decision_id, None)
+        if machine is None:
+            raise ValueError(f"Unknown state machine: {decision_id}")
+        return machine
+
+    def _add_state_machine(self, state: DecisionStateMachine) -> None:
+        decision_id = state.get_id()
+        if decision_id in self.state_machines:
+            raise ValueError(f"Received duplicate decision: {decision_id}")
+        self.state_machines[decision_id] = state
+        self.aliases[(decision_id.decision_type, decision_id.id)] = state
+
+    # ----- History routing -----
+
+    def handle_history_event(self, event: history.HistoryEvent) -> None:
+        """Dispatch history event to typed handlers using the global transition map."""
+        attr = event.WhichOneof("attributes")
+        # Based on the type of the event, determine what DecisionType it's referencing and
+        # the correct action to take
+        event_attributes = getattr(event, attr)
+        event_action = DecisionManager.type_to_action.get(
+            event_attributes.__class__, None
+        )
+        if event_action is not None:
+            decision_type = event_action.decision_type
+            action = event_action.action
+            # Find what state machine the event references.
+            # This may be a reference via the user id or a reference to a previous event
+            id_for_event = getattr(event_attributes, action.id_attr)
+            alias = (decision_type, id_for_event)
+            machine = self.aliases.get(alias, None)
+            if machine is None:
+                raise KeyError(
+                    f"Event {event.event_id} references unknown state machine {alias}"
+                )
+
+            action.fn(machine, event_attributes)
+
+            # Certain events (scheduled) are often referenced by subsequent events
+            # rather than using the client provided id
+            if action.event_id_is_alias:
+                self.aliases[(decision_type, event.event_id)] = machine
+
+    # ----- Decision aggregation -----
+
+    def collect_pending_decisions(self) -> List[decision.Decision]:
+        decisions: List[decision.Decision] = []
+
+        for machine in self.state_machines.values():
+            to_send = machine.get_decision()
+            if to_send is not None:
+                decisions.append(to_send)
+
+        return decisions
+
+    def _request_cancel(self, decision_id: DecisionId) -> bool:
+        machine = self._get_machine(decision_id)
+        # Interactions with the state machines should move them to the end so that the decisions are ordered as they
+        # happened in the Workflow
+        self.state_machines.move_to_end(decision_id)
+        return machine.request_cancel()

cadence/_internal/workflow/statemachine/decision_state_machine.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, Protocol, TypeVar, Optional
+
+from cadence.api.v1 import (
+    decision_pb2 as decision,
+)
+
+
+# TODO: Remove unused states
+class DecisionState(Enum):
+    """Lifecycle states for a decision-producing state machine instance."""
+
+    CREATED = 0
+    DECISION_SENT = 1
+    CANCELED_BEFORE_INITIATED = 2
+    INITIATED = 3
+    STARTED = 4
+    CANCELED_AFTER_INITIATED = 5
+    CANCELED_AFTER_STARTED = 6
+    CANCELLATION_DECISION_SENT = 7
+    COMPLETED_AFTER_CANCELLATION_DECISION_SENT = 8
+    COMPLETED = 9
+
+
+class DecisionType(Enum):
+    """Types of decisions that can be made by state machines."""
+
+    ACTIVITY = 0
+    CHILD_WORKFLOW = 1
+    CANCELLATION = 2
+    MARKER = 3
+    TIMER = 4
+    SIGNAL = 5
+    UPSERT_SEARCH_ATTRIBUTES = 6
+
+
+@dataclass(frozen=True)
+class DecisionId:
+    decision_type: DecisionType
+    id: str
+
+
+class DecisionStateMachine(Protocol):
+    def get_id(self) -> DecisionId: ...
+
+    def get_decision(self) -> decision.Decision | None: ...
+
+    def request_cancel(self) -> bool: ...
+
+
+class BaseDecisionStateMachine(DecisionStateMachine):
+    def __init__(self):
+        self._state = DecisionState.CREATED
+
+    def _transition(
+        self, to: DecisionState, allowed_from: list[DecisionState] | None = None
+    ) -> None:
+        # TODO: Maybe track previous states like the other clients
+        if allowed_from and self.state not in allowed_from:
+            raise RuntimeError(f"unable to transition to {to} from {self.state}")
+        self._state = to
+
+    @property
+    def state(self) -> DecisionState:
+        return self._state
+
+
+T = TypeVar("T")
+CancelFn = Callable[[], bool]
+
+
+class DecisionFuture(asyncio.Future[T]):
+    def __init__(self, request_cancel: CancelFn | None = None) -> None:
+        super().__init__()
+        if request_cancel is None:
+            request_cancel = self.force_cancel
+        self._request_cancel = request_cancel
+
+    def force_cancel(self, message: Optional[str] = None) -> bool:
+        return super().cancel(message)
+
+    def cancel(self, msg=None) -> bool:
+        return self._request_cancel()

cadence/_internal/workflow/statemachine/event_dispatcher.py

@@ -0,0 +1,76 @@
+from dataclasses import dataclass
+from inspect import signature
+from typing import Type, Callable, get_type_hints, TypeVar, Any, cast
+
+from google.protobuf.message import Message
+
+T = TypeVar("T")
+
+EventHandler = Callable[[Any, T], None]
+
+
+@dataclass(
+    frozen=True,
+)
+class Action:
+    fn: EventHandler
+    id_attr: str
+    event_id_is_alias: bool
+
+
+class EventDispatcher:
+    handlers: dict[Type, Action]
+
+    def __init__(self, default_id_attr: str) -> None:
+        self._default_id_attr = default_id_attr
+        self.handlers = {}
+
+    def event(
+        self, id_attr: str = "", event_id_is_alias: bool = False
+    ) -> Callable[[EventHandler], EventHandler]:
+        def decorator(func: EventHandler) -> EventHandler:
+            event_type = _find_event_type(func)
+            event_id_attr = id_attr if id_attr else self._default_id_attr
+
+            _validate_field(func, event_type, event_id_attr)
+            if event_type in self.handlers:
+                raise ValueError(
+                    f"Duplicate handler for {event_type}: {func.__qualname__} and {self.handlers[event_type].fn.__qualname__}"
+                )
+            self.handlers[event_type] = Action(func, event_id_attr, event_id_is_alias)
+            return func
+
+        return decorator
+
+
+def _find_event_type(func: EventHandler) -> Type[Message]:
+    sig = signature(func)
+    type_hints = get_type_hints(func)
+    if len(sig.parameters) != 2:
+        raise ValueError(
+            f"Expected 2 arguments (self, event), {func.__qualname__} has: {sig.parameters}"
+        )
+    (non_self_param, _) = list(sig.parameters.items())[1]
+    if non_self_param not in type_hints:
+        raise ValueError(f"Missing type hint on {func.__qualname__}: {non_self_param}")
+    if "return" in type_hints and type_hints["return"] != None.__class__:
+        raise ValueError(
+            f"Event methods must return None, {func.__qualname__} returns: {type_hints['return']}"
+        )
+
+    event_type = type_hints[non_self_param]
+    if not issubclass(event_type, Message):
+        raise ValueError(
+            f"Event methods must accept a Message, {func.__qualname__} accepts: {event_type}"
+        )
+
+    # Mypy struggles without this for some reason, despite type narrowing being supported
+    return cast(Type[Message], event_type)
+
+
+def _validate_field(func: EventHandler, event_type: Type[Message], field: str) -> None:
+    fields = event_type.DESCRIPTOR.fields_by_name
+    if field not in fields:
+        raise ValueError(
+            f"{func.__qualname__} handles {event_type.__qualname__}, which has no field {field}"
+        )

cadence/_internal/workflow/statemachine/timer_state_machine.py

@@ -0,0 +1,73 @@
+from cadence._internal.workflow.statemachine.decision_state_machine import (
+    DecisionState,
+    DecisionFuture,
+    DecisionType,
+    DecisionId,
+    BaseDecisionStateMachine,
+)
+from cadence._internal.workflow.statemachine.event_dispatcher import EventDispatcher
+from cadence.api.v1 import decision, history
+
+timer_events = EventDispatcher("timer_id")
+
+
+class TimerStateMachine(BaseDecisionStateMachine):
+    request: decision.StartTimerDecisionAttributes
+    completed: DecisionFuture[None]
+
+    def __init__(
+        self,
+        request: decision.StartTimerDecisionAttributes,
+        completed: DecisionFuture[None],
+    ) -> None:
+        super().__init__()
+        self.request = request
+        self.completed = completed
+
+    def get_id(self) -> DecisionId:
+        return DecisionId(DecisionType.TIMER, self.request.timer_id)
+
+    def get_decision(self) -> decision.Decision | None:
+        if self.state is DecisionState.CREATED:
+            return decision.Decision(start_timer_decision_attributes=self.request)
+        if self.state is DecisionState.CANCELED_AFTER_INITIATED:
+            return decision.Decision(
+                cancel_timer_decision_attributes=decision.CancelTimerDecisionAttributes(
+                    timer_id=self.request.timer_id,
+                )
+            )
+        return None
+
+    def request_cancel(self) -> bool:
+        if self.state is DecisionState.CREATED:
+            self._transition(DecisionState.COMPLETED)
+            self.completed.force_cancel()
+            return True
+
+        if self.state is DecisionState.INITIATED:
+            self._transition(DecisionState.CANCELED_AFTER_INITIATED)
+            self.completed.force_cancel()
+            return True
+
+        return False
+
+    @timer_events.event()
+    def handle_started(self, _: history.TimerStartedEventAttributes) -> None:
+        self._transition(DecisionState.INITIATED)
+
+    @timer_events.event()
+    def handle_fired(self, _: history.TimerFiredEventAttributes) -> None:
+        self._transition(DecisionState.COMPLETED)
+        self.completed.set_result(None)
+
+    @timer_events.event()
+    def handle_canceled(self, _: history.TimerCanceledEventAttributes) -> None:
+        # Timers resolve immediately regardless of the outcome of the cancellation
+        self._transition(DecisionState.COMPLETED)
+
+    @timer_events.event()
+    def handle_cancel_failed(self, _: history.CancelTimerFailedEventAttributes) -> None:
+        # This leaves the timer in a likely invalid state, but matches the other clients.
+        # The only way for timer cancellation to fail is if the timer ID isn't known, so this
+        # can't really happen in the first place.
+        self._transition(DecisionState.INITIATED)

cadence/_internal/workflow/workflow_engine.py

@@ -0,0 +1,245 @@
+import logging
+from dataclasses import dataclass
+import traceback
+from typing import List
+
+from cadence._internal.workflow.context import Context
+from cadence._internal.workflow.decision_events_iterator import DecisionEventsIterator
+from cadence._internal.workflow.statemachine.decision_manager import DecisionManager
+from cadence._internal.workflow.workflow_intance import WorkflowInstance
+from cadence.api.v1.common_pb2 import Failure, Payload
+from cadence.api.v1.decision_pb2 import (
+    CompleteWorkflowExecutionDecisionAttributes,
+    Decision,
+    FailWorkflowExecutionDecisionAttributes,
+)
+from cadence.api.v1.history_pb2 import (
+    HistoryEvent,
+    WorkflowExecutionStartedEventAttributes,
+)
+from cadence.api.v1.service_worker_pb2 import PollForDecisionTaskResponse
+from cadence.error import WorkflowFailure
+from cadence.workflow import WorkflowDefinition, WorkflowInfo
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DecisionResult:
+    decisions: list[Decision]
+
+
+class WorkflowEngine:
+    def __init__(self, info: WorkflowInfo, workflow_definition: WorkflowDefinition):
+        self._workflow_instance = WorkflowInstance(
+            workflow_definition, info.data_converter
+        )
+        self._decision_manager = (
+            DecisionManager()
+        )  # TODO: remove this stateful object and use the context instead
+        self._context = Context(info, self._decision_manager)
+
+    def process_decision(
+        self,
+        events: List[HistoryEvent],
+    ) -> DecisionResult:
+        """
+        Process a decision task and generate decisions using DecisionEventsIterator.
+
+        This method follows the Java client pattern of using DecisionEventsIterator
+        to drive the decision processing pipeline with proper replay handling.
+
+        Args:
+            decision_task: The PollForDecisionTaskResponse from the service
+
+        Returns:
+            DecisionResult containing the list of decisions
+        """
+        try:
+            # Activate workflow context for the entire decision processing
+            with self._context._activate() as ctx:
+                # Log decision task processing start with full context (matches Java ReplayDecisionTaskHandler)
+                logger.info(
+                    "Processing decision task for workflow",
+                    extra={
+                        "workflow_type": ctx.info().workflow_type,
+                        "workflow_id": ctx.info().workflow_id,
+                        "run_id": ctx.info().workflow_run_id,
+                    },
+                )
+
+                # Create DecisionEventsIterator for structured event processing
+                events_iterator = DecisionEventsIterator(events)
+
+                # Process decision events using iterator-driven approach
+                self._process_decision_events(ctx, events_iterator)
+
+                # Collect all pending decisions from state machines
+                decisions = self._decision_manager.collect_pending_decisions()
+
+                # complete workflow if it is done
+                if self._workflow_instance.is_done():
+                    try:
+                        result = self._workflow_instance.get_result()
+                    except WorkflowFailure as e:
+                        decisions.append(
+                            Decision(
+                                fail_workflow_execution_decision_attributes=FailWorkflowExecutionDecisionAttributes(
+                                    failure=_failure_from_workflow_failure(e)
+                                )
+                            )
+                        )
+                    # TODO: handle cancellation error
+                    except Exception:
+                        raise
+                    else:
+                        decisions.append(
+                            Decision(
+                                complete_workflow_execution_decision_attributes=CompleteWorkflowExecutionDecisionAttributes(
+                                    result=result
+                                )
+                            )
+                        )
+                return DecisionResult(decisions=decisions)
+
+        except Exception as e:
+            # Log decision task failure with full context (matches Java ReplayDecisionTaskHandler)
+            logger.error(
+                "Decision task processing failed",
+                extra={
+                    "workflow_type": ctx.info().workflow_type,
+                    "workflow_id": ctx.info().workflow_id,
+                    "run_id": ctx.info().workflow_run_id,
+                    "error_type": type(e).__name__,
+                },
+                exc_info=True,
+            )
+            # Re-raise the exception so the handler can properly handle the failure
+            raise
+
+    def is_done(self) -> bool:
+        return self._workflow_instance.is_done()
+
+    def _process_decision_events(
+        self,
+        ctx: Context,
+        events_iterator: DecisionEventsIterator,
+    ) -> None:
+        """
+        Process decision events using the iterator-driven approach similar to Java client.
+
+        This method implements the three-phase event processing pattern:
+        1. Process markers first (for deterministic replay)
+        2. Process regular events (trigger workflow state changes)
+        3. Execute workflow logic
+        4. Process decision events from previous decisions
+
+        Args:
+            events_iterator: The DecisionEventsIterator for structured event processing
+            decision_task: The original decision task
+        """
+
+        # Check if there are any decision events to process
+        for decision_events in events_iterator:
+            # Log decision events batch processing (matches Go client patterns)
+            logger.debug(
+                "Processing decision events batch",
+                extra={
+                    "workflow_id": ctx.info().workflow_id,
+                    "markers_count": len(decision_events.markers),
+                    "replay_mode": decision_events.replay,
+                    "replay_time": decision_events.replay_current_time_milliseconds,
+                },
+            )
+
+            # Update context with replay information
+            ctx.set_replay_mode(decision_events.replay)
+            if decision_events.replay_current_time_milliseconds:
+                ctx.set_replay_current_time_milliseconds(
+                    decision_events.replay_current_time_milliseconds
+                )
+
+            # Phase 1: Process markers first
+            for marker_event in decision_events.markers:
+                logger.debug(
+                    "Processing marker event",
+                    extra={
+                        "workflow_id": ctx.info().workflow_id,
+                        "marker_name": getattr(marker_event, "marker_name", "unknown"),
+                        "event_id": getattr(marker_event, "event_id", None),
+                        "replay_mode": decision_events.replay,
+                    },
+                )
+                # Process through state machines (DecisionsHelper now delegates to DecisionManager)
+                self._decision_manager.handle_history_event(marker_event)
+
+            # Phase 2: Process regular input events
+            for event in decision_events.input:
+                logger.debug(
+                    "Processing history event",
+                    extra={
+                        "workflow_id": ctx.info().workflow_id,
+                        "event_type": getattr(event, "event_type", "unknown"),
+                        "event_id": getattr(event, "event_id", None),
+                        "replay_mode": decision_events.replay,
+                    },
+                )
+                # start workflow on workflow started event
+                if (
+                    event.WhichOneof("attributes")
+                    == "workflow_execution_started_event_attributes"
+                ):
+                    started_attrs: WorkflowExecutionStartedEventAttributes = (
+                        event.workflow_execution_started_event_attributes
+                    )
+                    if started_attrs and hasattr(started_attrs, "input"):
+                        self._workflow_instance.start(started_attrs.input)
+
+                # Process through state machines (DecisionsHelper now delegates to DecisionManager)
+                self._decision_manager.handle_history_event(event)
+
+            # Phase 3: Execute workflow logic
+            self._workflow_instance.run_once()
+
+            # Phase 4: update state machine with output events
+            for event in decision_events.output:
+                self._decision_manager.handle_history_event(event)
+
+    def _extract_workflow_input(
+        self, decision_task: PollForDecisionTaskResponse
+    ) -> Payload:
+        """
+        Extract workflow input from the decision task history.
+
+        Args:
+            decision_task: The decision task containing workflow history
+
+        Returns:
+            The workflow input data, or None if not found
+        """
+        if not decision_task.history or not hasattr(decision_task.history, "events"):
+            raise ValueError("No history events found in decision task")
+
+        # Look for WorkflowExecutionStarted event
+        for event in decision_task.history.events:
+            if hasattr(event, "workflow_execution_started_event_attributes"):
+                started_attrs: WorkflowExecutionStartedEventAttributes = (
+                    event.workflow_execution_started_event_attributes
+                )
+                if started_attrs and hasattr(started_attrs, "input"):
+                    return started_attrs.input
+
+        raise ValueError("No WorkflowExecutionStarted event found in history")
+
+
+def _failure_from_workflow_failure(e: WorkflowFailure) -> Failure:
+    cause = e.__cause__
+
+    stacktrace = "".join(traceback.format_exception(cause))
+
+    details = f"message: {str(cause)}\nstacktrace: {stacktrace}"
+
+    return Failure(
+        reason=type(cause).__name__,
+        details=details.encode("utf-8"),
+    )

cadence/_internal/workflow/workflow_intance.py

@@ -0,0 +1,44 @@
+from asyncio import CancelledError, InvalidStateError, Task
+from typing import Any, Optional
+from cadence._internal.workflow.deterministic_event_loop import DeterministicEventLoop
+from cadence.api.v1.common_pb2 import Payload
+from cadence.data_converter import DataConverter
+from cadence.error import WorkflowFailure
+from cadence.workflow import WorkflowDefinition
+
+
+class WorkflowInstance:
+    def __init__(
+        self, workflow_definition: WorkflowDefinition, data_converter: DataConverter
+    ):
+        self._definition = workflow_definition
+        self._data_converter = data_converter
+        self._instance = workflow_definition.cls()  # construct a new workflow object
+        self._loop = DeterministicEventLoop()
+        self._task: Optional[Task] = None
+
+    def start(self, input: Payload):
+        if self._task is None:
+            run_method = self._definition.get_run_method(self._instance)
+            # TODO handle multiple inputs
+            workflow_input = self._data_converter.from_data(input, [Any])
+            self._task = self._loop.create_task(run_method(*workflow_input))
+
+    def run_once(self):
+        self._loop.run_until_yield()
+
+    def is_done(self) -> bool:
+        return self._task is not None and self._task.done()
+
+    # TODO: consider cache result to avoid multiple data conversions
+    def get_result(self) -> Payload:
+        if self._task is None:
+            raise RuntimeError("Workflow is not started yet")
+        try:
+            result = self._task.result()
+        except (CancelledError, InvalidStateError) as e:
+            raise e
+        except Exception as e:
+            raise WorkflowFailure(f"Workflow failed: {e}") from e
+        # TODO: handle result with multiple outputs
+        return self._data_converter.to_data([result])