dex-python-sdk 0.0.2__cp311-abi3-win_amd64.whl

dex/worker.py

@@ -0,0 +1,121 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from __future__ import annotations
+
+import os
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from types import TracebackType
+
+import grpc
+
+from dex._value_hydrator import ValueHydrator
+from dex._value_mapper import ValueMapper
+from dex._worker_dispatcher import WorkerDispatcher
+from dex._worker_service import WorkerService
+from dex.blob_cache import BlobCache
+from dex.dexpb import dex_pb2_grpc
+from dex.flow import Registry
+from dex.worker_options import WorkerOptions, WorkerTarget
+
+
+class Worker:
+    def __init__(
+        self,
+        registry: Registry,
+        blob_cache: BlobCache,
+        options: WorkerOptions | None = None,
+    ) -> None:
+        self.registry = registry
+        self.blob_cache = blob_cache
+        self.options = options or WorkerOptions()
+        self._lock = threading.Lock()
+        self._state = "created"
+        self._flow_channel = grpc.insecure_channel(self.options.server_address)
+        flow_service = dex_pb2_grpc.FlowServiceStub(  # type: ignore[no-untyped-call]
+            self._flow_channel
+        )
+        values = ValueMapper(registry.codec_registry)
+        dispatcher = WorkerDispatcher(
+            registry,
+            values,
+            ValueHydrator(flow_service, blob_cache),
+        )
+        concurrency = max(2, min(32, os.cpu_count() or 2))
+        self._executor = ThreadPoolExecutor(
+            max_workers=concurrency,
+            thread_name_prefix="dex-python-handler",
+        )
+        self._server = grpc.server(
+            self._executor,
+            maximum_concurrent_rpcs=concurrency,
+        )
+        dex_pb2_grpc.add_WorkerServiceServicer_to_server(  # type: ignore[no-untyped-call]
+            WorkerService(dispatcher),
+            self._server,
+        )
+        self._bound_port = self._server.add_insecure_port(self.options.bind_address)
+        if self._bound_port == 0:
+            raise ValueError(
+                f"cannot bind Python Worker to {self.options.bind_address}"
+            )
+        self._worker_target = self.options.worker_target or WorkerTarget(
+            self._target_address(self.options.bind_address, self._bound_port)
+        )
+
+    def __enter__(self) -> Worker:
+        return self
+
+    @property
+    def worker_target(self) -> WorkerTarget:
+        return self._worker_target
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def start(self) -> None:
+        with self._lock:
+            if self._state != "created":
+                raise RuntimeError(f"Worker cannot start from state {self._state}")
+            self._state = "running"
+            self._server.start()
+        self._server.wait_for_termination()
+
+    def stop(self) -> None:
+        with self._lock:
+            if self._state in ("stopped", "closed"):
+                return
+            self._state = "stopping"
+        self._server.stop(grace=5).wait(timeout=10)
+        self._flow_channel.close()
+        self._executor.shutdown(wait=True, cancel_futures=True)
+        with self._lock:
+            if self._state != "closed":
+                self._state = "stopped"
+
+    def close(self) -> None:
+        self.stop()
+        with self._lock:
+            self._state = "closed"
+
+    @staticmethod
+    def _target_address(bind_address: str, bound_port: int) -> str:
+        host, separator, port = bind_address.rpartition(":")
+        if not separator or not port:
+            raise ValueError("Worker bind address requires a port")
+        if host in ("", "0.0.0.0", "::", "[::]"):
+            host = "localhost"
+        return f"{host}:{bound_port}"

dex/worker_options.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Super Durable Source License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class WorkerTarget:
+    address: str
+    headless: bool = False
+
+
+@dataclass(frozen=True)
+class WorkerOptions:
+    bind_address: str = ":8803"
+    worker_target: WorkerTarget | None = None
+    server_address: str = "localhost:8801"

dex/worker_service.py

@@ -0,0 +1,432 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+import traceback
+import typing
+from dataclasses import dataclass
+from typing import List, Union
+
+from dex.command_request import _to_idl_command_request
+from dex.command_results import from_idl_command_results
+from dex.communication import Communication
+from dex.data_attributes import DataAttributes
+from dex.dex_api.models import (
+    EncodedObject,
+    KeyValue,
+    SearchAttribute,
+    SearchAttributeValueType,
+    WorkflowStateExecuteRequest,
+    WorkflowStateExecuteResponse,
+    WorkflowStateWaitUntilRequest,
+    WorkflowStateWaitUntilResponse,
+    WorkflowWorkerRpcRequest,
+    WorkflowWorkerRpcResponse,
+)
+from dex.dex_api.types import Unset
+from dex.object_encoder import ObjectEncoder
+from dex.persistence import Persistence
+from dex.registry import Registry
+from dex.search_attributes import SearchAttributes
+from dex.state_decision import StateDecision, _to_idl_state_decision
+from dex.state_execution_locals import StateExecutionLocals
+from dex.utils.dex_typing import assert_not_unset, unset_to_none
+from dex.workflow_context import WorkflowContext, _from_idl_context
+from dex.workflow_state import get_input_type
+
+@dataclass
+class WorkerOptions:
+    object_encoder: ObjectEncoder
+
+default_worker_options = WorkerOptions(ObjectEncoder.default)
+
+class WorkerService:
+    api_path_workflow_state_wait_until: typing.ClassVar[str] = (
+        "/api/v1/workflowState/start"
+    )
+    api_path_workflow_state_execute: typing.ClassVar[str] = (
+        "/api/v1/workflowState/decide"
+    )
+    api_path_workflow_worker_rpc: typing.ClassVar[str] = "/api/v1/workflowWorker/rpc"
+
+    def __init__(
+        self, registry: Registry, options: WorkerOptions = default_worker_options
+    ):
+        self._registry = registry
+        self._options = options
+
+    @staticmethod
+    def handle_worker_error(exception: Exception):
+        """
+        Handle the exception/error of worker so that Temporal/Cadence WebUI can show the error nicely.
+        Example usage (in Flask):
+            @_flask_app.errorhandler(Exception)
+            def internal_error(exception):
+                return _worker_service.handle_worker_error(exception), 500
+        """
+        stacktrace = traceback.format_exc()
+        index = max(0, stacktrace.find("dex-python-sdk/dex/worker_service.py"))
+        return "WorkerExecutionError: {0}; StackTrace:{1}".format(
+            exception, stacktrace[index:]
+        )
+
+    def handle_workflow_worker_rpc(
+        self,
+        request: WorkflowWorkerRpcRequest,
+    ) -> WorkflowWorkerRpcResponse:
+        wf_type = request.workflow_type
+        rpc_info = self._registry.get_rpc_infos(wf_type)[request.rpc_name]
+
+        internal_channel_types = self._registry.get_internal_channel_type_store(wf_type)
+        signal_channel_types = self._registry.get_signal_channel_types(wf_type)
+        data_attributes_types = self._registry.get_data_attribute_types(wf_type)
+
+        context = _from_idl_context(request.context)
+        _input = self._options.object_encoder.decode(
+            unset_to_none(request.input_), rpc_info.input_type
+        )
+
+        current_data_attributes: dict[str, typing.Union[EncodedObject, None, Unset]] = (
+            {}
+        )
+        if not isinstance(request.data_attributes, Unset):
+            current_data_attributes = {
+                assert_not_unset(attr.key): unset_to_none(attr.value)
+                for attr in request.data_attributes
+            }
+
+        data_attributes = DataAttributes(
+            data_attributes_types,
+            self._options.object_encoder,
+            current_data_attributes,
+        )
+
+        search_attributes_types = self._registry.get_search_attribute_types(wf_type)
+        search_attributes = SearchAttributes(
+            search_attributes_types, unset_to_none(request.search_attributes)
+        )
+        state_execution_locals = StateExecutionLocals(
+            to_map(None), self._options.object_encoder
+        )
+
+        persistence = Persistence(
+            data_attributes, search_attributes, state_execution_locals
+        )
+
+        communication = Communication(
+            internal_channel_types,
+            signal_channel_types,
+            self._options.object_encoder,
+            unset_to_none(request.internal_channel_infos),
+            unset_to_none(request.signal_channel_infos),
+        )
+        params: typing.Any = []
+        if rpc_info.params_order is not None:
+            for param_type in rpc_info.params_order:
+                if param_type == Persistence:
+                    params.append(persistence)
+                elif param_type == Communication:
+                    params.append(communication)
+                elif param_type == WorkflowContext:
+                    params.append(context)
+                else:
+                    params.append(_input)
+
+        output = rpc_info.method_func(*params)
+
+        pubs = communication.get_to_publishing_internal_channel()
+        response = WorkflowWorkerRpcResponse(
+            output=self._options.object_encoder.encode(output)
+        )
+
+        if len(pubs) > 0:
+            response.publish_to_inter_state_channel = pubs
+        if len(data_attributes.get_updated_values_to_return()) > 0:
+            response.upsert_data_attributes = [
+                KeyValue(k, v)
+                for (k, v) in data_attributes.get_updated_values_to_return().items()
+            ]
+        upsert_sas = _create_upsert_search_attributes(
+            search_attributes_types,
+            search_attributes.get_upsert_to_server_int64_attribute_map(),
+            search_attributes.get_upsert_to_server_string_attribute_map(),
+            search_attributes.get_upsert_to_server_bool_attribute_map(),
+            search_attributes.get_upsert_to_server_double_attribute_map(),
+            search_attributes.get_upsert_to_server_string_array_attribute_map(),
+        )
+        if upsert_sas:
+            response.upsert_search_attributes = upsert_sas
+        record_events = state_execution_locals.get_record_events()
+        if len(record_events) > 0:
+            response.record_events = record_events
+        if len(communication.get_to_trigger_state_movements()) > 0:
+            movements = communication.get_to_trigger_state_movements()
+            decision = StateDecision.multi_next_states(*movements)
+            response.state_decision = _to_idl_state_decision(
+                decision,
+                wf_type,
+                self._registry,
+                self._options.object_encoder,
+            )
+        return response
+
+    def handle_workflow_state_wait_until(
+        self,
+        request: WorkflowStateWaitUntilRequest,
+    ) -> WorkflowStateWaitUntilResponse:
+        wf_type = request.workflow_type
+        state = self._registry.get_workflow_state_with_check(
+            wf_type, request.workflow_state_id
+        )
+        internal_channel_types = self._registry.get_internal_channel_type_store(wf_type)
+        signal_channel_types = self._registry.get_signal_channel_types(wf_type)
+        data_attributes_types = self._registry.get_data_attribute_types(wf_type)
+
+        context = _from_idl_context(request.context)
+        _input = self._options.object_encoder.decode(
+            unset_to_none(request.state_input), get_input_type(state)
+        )
+
+        current_data_attributes: dict[str, typing.Union[EncodedObject, None, Unset]] = (
+            {}
+        )
+        if not isinstance(request.data_objects, Unset):
+            current_data_attributes = {
+                assert_not_unset(attr.key): unset_to_none(attr.value)
+                for attr in request.data_objects
+            }
+
+        data_attributes = DataAttributes(
+            data_attributes_types,
+            self._options.object_encoder,
+            current_data_attributes,
+        )
+
+        search_attributes_types = self._registry.get_search_attribute_types(wf_type)
+        search_attributes = SearchAttributes(
+            search_attributes_types, unset_to_none(request.search_attributes)
+        )
+        state_execution_locals = StateExecutionLocals(
+            to_map(None), self._options.object_encoder
+        )
+
+        persistence = Persistence(
+            data_attributes, search_attributes, state_execution_locals
+        )
+
+        communication = Communication(
+            internal_channel_types,
+            signal_channel_types,
+            self._options.object_encoder,
+            None,
+            None,
+        )
+        command_request = state.wait_until(context, _input, persistence, communication)
+
+        pubs = communication.get_to_publishing_internal_channel()
+
+        upsert_sas = _create_upsert_search_attributes(
+            search_attributes_types,
+            search_attributes.get_upsert_to_server_int64_attribute_map(),
+            search_attributes.get_upsert_to_server_string_attribute_map(),
+            search_attributes.get_upsert_to_server_bool_attribute_map(),
+            search_attributes.get_upsert_to_server_double_attribute_map(),
+            search_attributes.get_upsert_to_server_string_array_attribute_map(),
+        )
+
+        upsert_state_locals = (
+            state_execution_locals.get_upsert_state_execution_local_attributes()
+        )
+        record_events = state_execution_locals.get_record_events()
+
+        response = WorkflowStateWaitUntilResponse(
+            command_request=_to_idl_command_request(command_request),
+            publish_to_inter_state_channel=pubs,
+            upsert_data_objects=[
+                KeyValue(k, v)
+                for (k, v) in data_attributes.get_updated_values_to_return().items()
+            ],
+            upsert_state_locals=upsert_state_locals,
+            record_events=record_events,
+        )
+
+        if upsert_sas:
+            response.upsert_search_attributes = upsert_sas
+
+        return response
+
+    def handle_workflow_state_execute(
+        self,
+        request: WorkflowStateExecuteRequest,
+    ) -> WorkflowStateExecuteResponse:
+        wf_type = request.workflow_type
+        state = self._registry.get_workflow_state_with_check(
+            wf_type, request.workflow_state_id
+        )
+        internal_channel_types = self._registry.get_internal_channel_type_store(wf_type)
+        signal_channel_types = self._registry.get_signal_channel_types(wf_type)
+        data_attributes_types = self._registry.get_data_attribute_types(wf_type)
+        context = _from_idl_context(request.context)
+
+        _input = self._options.object_encoder.decode(
+            unset_to_none(request.state_input), get_input_type(state)
+        )
+
+        current_data_attributes: dict[str, typing.Union[EncodedObject, None, Unset]] = (
+            {}
+        )
+        if not isinstance(request.data_objects, Unset):
+            current_data_attributes = {
+                assert_not_unset(attr.key): unset_to_none(attr.value)
+                for attr in request.data_objects
+            }
+
+        data_attributes = DataAttributes(
+            data_attributes_types,
+            self._options.object_encoder,
+            current_data_attributes,
+        )
+
+        search_attributes_types = self._registry.get_search_attribute_types(wf_type)
+        search_attributes = SearchAttributes(
+            search_attributes_types, unset_to_none(request.search_attributes)
+        )
+        state_execution_locals = StateExecutionLocals(
+            to_map(request.state_locals), self._options.object_encoder
+        )
+
+        persistence = Persistence(
+            data_attributes, search_attributes, state_execution_locals
+        )
+
+        communication = Communication(
+            internal_channel_types,
+            signal_channel_types,
+            self._options.object_encoder,
+            None,
+            None,
+        )
+
+        command_results = from_idl_command_results(
+            request.command_results,
+            internal_channel_types,
+            signal_channel_types,
+            self._options.object_encoder,
+        )
+        decision = state.execute(
+            context, _input, command_results, persistence, communication
+        )
+
+        pubs = communication.get_to_publishing_internal_channel()
+
+        upsert_sas = _create_upsert_search_attributes(
+            search_attributes_types,
+            search_attributes.get_upsert_to_server_int64_attribute_map(),
+            search_attributes.get_upsert_to_server_string_attribute_map(),
+            search_attributes.get_upsert_to_server_bool_attribute_map(),
+            search_attributes.get_upsert_to_server_double_attribute_map(),
+            search_attributes.get_upsert_to_server_string_array_attribute_map(),
+        )
+        upsert_state_locals = (
+            state_execution_locals.get_upsert_state_execution_local_attributes()
+        )
+        record_events = state_execution_locals.get_record_events()
+
+        response = WorkflowStateExecuteResponse(
+            state_decision=_to_idl_state_decision(
+                decision,
+                wf_type,
+                self._registry,
+                self._options.object_encoder,
+            ),
+            publish_to_inter_state_channel=pubs,
+            upsert_data_objects=[
+                KeyValue(k, v)
+                for (k, v) in data_attributes.get_updated_values_to_return().items()
+            ],
+            upsert_state_locals=upsert_state_locals,
+            record_events=record_events,
+        )
+
+        if upsert_sas:
+            response.upsert_search_attributes = upsert_sas
+
+        return response
+
+def _create_upsert_search_attributes(
+    type_map: dict[str, SearchAttributeValueType],
+    upsert_to_server_int64_attribute_map: dict[str, Union[int, None]],
+    upsert_to_server_keyword_attribute_map: dict[str, Union[str, None]],
+    upsert_to_server_bool_attribute_map: dict[str, Union[bool, None]],
+    upsert_to_server_double_attribute_map: dict[str, Union[float, None]],
+    upsert_to_server_string_array_attribute_map: dict[str, Union[list[str], None]],
+):
+    sas: list[SearchAttribute] = []
+    for int_key, int_sa in upsert_to_server_int64_attribute_map.items():
+        sa = SearchAttribute(
+            key=int_key,
+            value_type=type_map[int_key],
+        )
+        if int_sa is not None:
+            sa.integer_value = int_sa
+        sas.append(sa)
+
+    for keyword_key, keyword_sa in upsert_to_server_keyword_attribute_map.items():
+        sa = SearchAttribute(
+            key=keyword_key,
+            value_type=type_map[keyword_key],
+        )
+        if keyword_sa is not None:
+            sa.string_value = keyword_sa
+        sas.append(sa)
+
+    for bool_key, bool_sa in upsert_to_server_bool_attribute_map.items():
+        sa = SearchAttribute(
+            key=bool_key,
+            value_type=type_map[bool_key],
+        )
+        if bool_sa is not None:
+            sa.bool_value = bool_sa
+        sas.append(sa)
+
+    for double_key, double_sa in upsert_to_server_double_attribute_map.items():
+        sa = SearchAttribute(
+            key=double_key,
+            value_type=type_map[double_key],
+        )
+        if double_sa is not None:
+            sa.double_value = double_sa
+        sas.append(sa)
+
+    for (
+        string_array_key,
+        string_array_sa,
+    ) in upsert_to_server_string_array_attribute_map.items():
+        sa = SearchAttribute(
+            key=string_array_key,
+            value_type=type_map[string_array_key],
+        )
+        if string_array_sa is not None:
+            sa.string_array_value = string_array_sa
+        sas.append(sa)
+
+    return sas
+
+def to_map(
+    key_values: Union[None, Unset, List[KeyValue]],
+) -> dict[str, Union[EncodedObject, Unset]]:
+    normalized_key_values: List[KeyValue] = unset_to_none(key_values) or []
+    kvs: dict[str, Union[EncodedObject, Unset]] = {}
+    for kv in normalized_key_values:
+        k = unset_to_none(kv.key)
+        v = unset_to_none(kv.value)
+        if k and v:
+            kvs[k] = v
+
+    return kvs

dex/workflow.py

@@ -0,0 +1,79 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from abc import ABC
+
+from dex.communication_schema import CommunicationSchema
+from dex.persistence_options import PersistenceOptions
+from dex.persistence_schema import PersistenceSchema
+from dex.state_schema import StateSchema
+
+class ObjectWorkflow(ABC):
+    """ObjectWorkflow is the interface to define a workflow definition.
+    ObjectWorkflow is a top level concept in Dex. Any object that is long-lasting
+    can be modeled as an ObjectWorkflow.
+    """
+
+    def get_workflow_states(self) -> StateSchema:
+        """
+        GetWorkflowStates defines the states of the workflow. A state represents
+            a step of the workflow state machine.
+            A state can execute some commands (signal/timer) and wait for result
+            See more details in the WorkflowState interface.
+            It can return an empty list, meaning no states.
+            There can be at most one startingState in the list.
+            If there is no startingState or with the default empty state list, the workflow
+            will not start any state execution after workflow stated. Application can still
+            use RPC to invoke new state execution in the future.
+        Returns:
+            A list of workflow state definitions. Default to empty.
+        """
+        return StateSchema()
+
+    def get_persistence_schema(self) -> PersistenceSchema:
+        """
+        GetPersistenceSchema defines all the persistence fields for this workflow, includes:
+          1. Data attributes
+          2. Search attributes
+        Data attributes can be read/upsert in WorkflowState WaitUntil/Execute API
+        Data attributes  can also be read by getDataAttributes API by external applications using Client
+        Search attributes can be read/upsert in WorkflowState WaitUntil/Execute API
+        Search attributes can also be read by GetSearchAttributes Client API by external applications.
+        External applications can also use "SearchWorkflow" API to find workflows by SQL-like query
+
+        Returns:
+            A persistence schema. Default to empty.
+        """
+        return PersistenceSchema()
+
+    def get_persistence_options(self) -> PersistenceOptions:
+        return PersistenceOptions.get_default()
+
+    def get_communication_schema(self) -> CommunicationSchema:
+        """
+        GetCommunicationSchema defines all the communication methods for this workflow, this includes
+          1. Signal channel
+          2. Interstate channel
+        Signal channel is for external applications to send signal to workflow execution.
+        ObjectWorkflow execution can listen on the signal in the WorkflowState WaitUntil API and receive in
+        the WorkflowState Execute API
+        InterStateChannel is for synchronization communications between WorkflowStates.
+        E.g. WorkflowStateA will continue after receiving a value from WorkflowStateB
+
+        Returns:
+            A communication schema. Default to empty.
+        """
+        return CommunicationSchema()
+
+def get_workflow_type(wf: ObjectWorkflow) -> str:
+    return wf.__class__.__name__
+
+def get_workflow_type_by_class(wf_class: type[ObjectWorkflow]) -> str:
+    return wf_class.__name__

dex/workflow_context.py

@@ -0,0 +1,44 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from dataclasses import dataclass
+from typing import Optional
+
+from dex.dex_api.models.context import Context
+from dex.utils.dex_typing import unset_to_none
+
+@dataclass
+class WorkflowContext:
+    workflow_id: str
+    workflow_run_id: str
+    workflow_start_timestamp_seconds: int
+    state_execution_id: Optional[str] = None
+    first_attempt_timestamp_seconds: Optional[int] = None
+    attempt: Optional[int] = None
+    child_workflow_request_id: Optional[str] = None
+
+def _from_idl_context(idl_context: Context) -> WorkflowContext:
+    state_execution_id = unset_to_none(idl_context.state_execution_id)
+
+    return WorkflowContext(
+        workflow_id=idl_context.workflow_id,
+        workflow_run_id=idl_context.workflow_run_id,
+        workflow_start_timestamp_seconds=idl_context.workflow_started_timestamp,
+        state_execution_id=state_execution_id,
+        first_attempt_timestamp_seconds=unset_to_none(
+            idl_context.first_attempt_timestamp,
+        ),
+        attempt=unset_to_none(idl_context.attempt),
+        child_workflow_request_id=(
+            idl_context.workflow_run_id + "-" + state_execution_id
+            if state_execution_id is not None
+            else None
+        ),
+    )