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

cadence/client.py

@@ -0,0 +1,382 @@
+import os
+import socket
+import uuid
+from datetime import timedelta
+from typing import TypedDict, Unpack, Any, cast, Union
+
+from grpc import ChannelCredentials, Compression
+from google.protobuf.duration_pb2 import Duration
+
+from cadence._internal.rpc.error import CadenceErrorInterceptor
+from cadence._internal.rpc.retry import RetryInterceptor
+from cadence._internal.rpc.yarpc import YarpcMetadataInterceptor
+from cadence.api.v1.service_domain_pb2_grpc import DomainAPIStub
+from cadence.api.v1.service_worker_pb2_grpc import WorkerAPIStub
+from grpc.aio import Channel, ClientInterceptor, secure_channel, insecure_channel
+from cadence.api.v1.service_workflow_pb2_grpc import WorkflowAPIStub
+from cadence.api.v1.service_workflow_pb2 import (
+    SignalWorkflowExecutionRequest,
+    StartWorkflowExecutionRequest,
+    StartWorkflowExecutionResponse,
+    SignalWithStartWorkflowExecutionRequest,
+    SignalWithStartWorkflowExecutionResponse,
+)
+from cadence.api.v1.common_pb2 import WorkflowType, WorkflowExecution
+from cadence.api.v1.tasklist_pb2 import TaskList
+from cadence.data_converter import DataConverter, DefaultDataConverter
+from cadence.metrics import MetricsEmitter, NoOpMetricsEmitter
+from cadence.workflow import WorkflowDefinition
+
+
+class StartWorkflowOptions(TypedDict, total=False):
+    """Options for starting a workflow execution."""
+
+    task_list: str
+    execution_start_to_close_timeout: timedelta
+    workflow_id: str
+    task_start_to_close_timeout: timedelta
+    cron_schedule: str
+
+
+def _validate_and_apply_defaults(options: StartWorkflowOptions) -> StartWorkflowOptions:
+    """Validate required fields and apply defaults to StartWorkflowOptions."""
+    if not options.get("task_list"):
+        raise ValueError("task_list is required")
+
+    execution_timeout = options.get("execution_start_to_close_timeout")
+    if not execution_timeout:
+        raise ValueError("execution_start_to_close_timeout is required")
+    if execution_timeout <= timedelta(0):
+        raise ValueError("execution_start_to_close_timeout must be greater than 0")
+
+    # Apply default for task_start_to_close_timeout if not provided (matching Go/Java clients)
+    task_timeout = options.get("task_start_to_close_timeout")
+    if task_timeout is None:
+        options["task_start_to_close_timeout"] = timedelta(seconds=10)
+    elif task_timeout <= timedelta(0):
+        raise ValueError("task_start_to_close_timeout must be greater than 0")
+
+    return options
+
+
+class ClientOptions(TypedDict, total=False):
+    domain: str
+    target: str
+    data_converter: DataConverter
+    identity: str
+    service_name: str
+    caller_name: str
+    channel_arguments: dict[str, Any]
+    credentials: ChannelCredentials | None
+    compression: Compression
+    metrics_emitter: MetricsEmitter
+    interceptors: list[ClientInterceptor]
+
+
+_DEFAULT_OPTIONS: ClientOptions = {
+    "data_converter": DefaultDataConverter(),
+    "identity": f"{os.getpid()}@{socket.gethostname()}",
+    "service_name": "cadence-frontend",
+    "caller_name": "cadence-client",
+    "channel_arguments": {},
+    "credentials": None,
+    "compression": Compression.NoCompression,
+    "metrics_emitter": NoOpMetricsEmitter(),
+    "interceptors": [],
+}
+
+
+class Client:
+    def __init__(self, **kwargs: Unpack[ClientOptions]) -> None:
+        self._options = _validate_and_copy_defaults(ClientOptions(**kwargs))
+        self._channel = _create_channel(self._options)
+        self._worker_stub = WorkerAPIStub(self._channel)
+        self._domain_stub = DomainAPIStub(self._channel)
+        self._workflow_stub = WorkflowAPIStub(self._channel)
+
+    @property
+    def data_converter(self) -> DataConverter:
+        return self._options["data_converter"]
+
+    @property
+    def domain(self) -> str:
+        return self._options["domain"]
+
+    @property
+    def identity(self) -> str:
+        return self._options["identity"]
+
+    @property
+    def domain_stub(self) -> DomainAPIStub:
+        return self._domain_stub
+
+    @property
+    def worker_stub(self) -> WorkerAPIStub:
+        return self._worker_stub
+
+    @property
+    def workflow_stub(self) -> WorkflowAPIStub:
+        return self._workflow_stub
+
+    @property
+    def metrics_emitter(self) -> MetricsEmitter:
+        return self._options["metrics_emitter"]
+
+    async def ready(self) -> None:
+        await self._channel.channel_ready()
+
+    async def close(self) -> None:
+        await self._channel.close()
+
+    async def __aenter__(self) -> "Client":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    def _build_start_workflow_request(
+        self,
+        workflow: Union[str, WorkflowDefinition],
+        args: tuple[Any, ...],
+        options: StartWorkflowOptions,
+    ) -> StartWorkflowExecutionRequest:
+        """Build a StartWorkflowExecutionRequest from parameters."""
+        # Generate workflow ID if not provided
+        workflow_id = options.get("workflow_id") or str(uuid.uuid4())
+
+        # Determine workflow type name
+        if isinstance(workflow, str):
+            workflow_type_name = workflow
+        else:
+            # For WorkflowDefinition, use the name property
+            workflow_type_name = workflow.name
+
+        # Encode input arguments
+        input_payload = None
+        if args:
+            try:
+                input_payload = self.data_converter.to_data(list(args))
+            except Exception as e:
+                raise ValueError(f"Failed to encode workflow arguments: {e}")
+
+        # Convert timedelta to protobuf Duration
+        execution_timeout = Duration()
+        execution_timeout.FromTimedelta(options["execution_start_to_close_timeout"])
+
+        task_timeout = Duration()
+        task_timeout.FromTimedelta(options["task_start_to_close_timeout"])
+
+        # Build the request
+        request = StartWorkflowExecutionRequest(
+            domain=self.domain,
+            workflow_id=workflow_id,
+            workflow_type=WorkflowType(name=workflow_type_name),
+            task_list=TaskList(name=options["task_list"]),
+            identity=self.identity,
+            request_id=str(uuid.uuid4()),
+        )
+
+        # Set required timeout fields
+        request.execution_start_to_close_timeout.CopyFrom(execution_timeout)
+        request.task_start_to_close_timeout.CopyFrom(task_timeout)
+
+        # Set optional fields
+        if input_payload:
+            request.input.CopyFrom(input_payload)
+        if options.get("cron_schedule"):
+            request.cron_schedule = options["cron_schedule"]
+
+        return request
+
+    async def start_workflow(
+        self,
+        workflow: Union[str, WorkflowDefinition],
+        *args,
+        **options_kwargs: Unpack[StartWorkflowOptions],
+    ) -> WorkflowExecution:
+        """
+        Start a workflow execution asynchronously.
+
+        Args:
+            workflow: WorkflowDefinition or workflow type name string
+            *args: Arguments to pass to the workflow
+            **options_kwargs: StartWorkflowOptions as keyword arguments
+
+        Returns:
+            WorkflowExecution with workflow_id and run_id
+
+        Raises:
+            ValueError: If required parameters are missing or invalid
+            Exception: If the gRPC call fails
+        """
+        # Convert kwargs to StartWorkflowOptions and validate
+        options = _validate_and_apply_defaults(StartWorkflowOptions(**options_kwargs))
+
+        # Build the gRPC request
+        request = self._build_start_workflow_request(workflow, args, options)
+
+        # Execute the gRPC call
+        try:
+            response: StartWorkflowExecutionResponse = (
+                await self.workflow_stub.StartWorkflowExecution(request)
+            )
+
+            # Emit metrics if available
+            if self.metrics_emitter:
+                # TODO: Add workflow start metrics similar to Go client
+                pass
+
+            execution = WorkflowExecution()
+            execution.workflow_id = request.workflow_id
+            execution.run_id = response.run_id
+            return execution
+        except Exception:
+            raise
+
+    async def signal_workflow(
+        self,
+        workflow_id: str,
+        run_id: str,
+        signal_name: str,
+        *signal_args: Any,
+    ) -> None:
+        """
+        Send a signal to a running workflow execution.
+
+        Args:
+            workflow_id: The workflow ID
+            run_id: The run ID (can be empty string to signal current run)
+            signal_name: Name of the signal
+            *signal_args: Arguments to pass to the signal handler
+
+        Raises:
+            ValueError: If signal encoding fails
+            Exception: If the gRPC call fails
+        """
+        signal_payload = None
+        if signal_args:
+            try:
+                signal_payload = self.data_converter.to_data(list[Any](signal_args))
+            except Exception as e:
+                raise ValueError(f"Failed to encode signal input: {e}")
+
+        workflow_execution = WorkflowExecution()
+        workflow_execution.workflow_id = workflow_id
+        if run_id:
+            workflow_execution.run_id = run_id
+
+        signal_request = SignalWorkflowExecutionRequest(
+            domain=self.domain,
+            workflow_execution=workflow_execution,
+            identity=self.identity,
+            request_id=str(uuid.uuid4()),
+            signal_name=signal_name,
+        )
+
+        if signal_payload:
+            signal_request.signal_input.CopyFrom(signal_payload)
+
+        await self.workflow_stub.SignalWorkflowExecution(signal_request)
+
+    async def signal_with_start_workflow(
+        self,
+        workflow: Union[str, WorkflowDefinition],
+        signal_name: str,
+        signal_args: list[Any],
+        *workflow_args: Any,
+        **options_kwargs: Unpack[StartWorkflowOptions],
+    ) -> WorkflowExecution:
+        """
+        Signal a workflow execution, starting it if it is not already running.
+
+        Args:
+            workflow: WorkflowDefinition or workflow type name string
+            signal_name: Name of the signal
+            signal_args: List of arguments to pass to the signal handler
+            *workflow_args: Arguments to pass to the workflow if it needs to be started
+            **options_kwargs: StartWorkflowOptions as keyword arguments
+
+        Returns:
+            WorkflowExecution with workflow_id and run_id
+
+        Raises:
+            ValueError: If required parameters are missing or invalid
+            Exception: If the gRPC call fails
+        """
+        # Convert kwargs to StartWorkflowOptions and validate
+        options = _validate_and_apply_defaults(StartWorkflowOptions(**options_kwargs))
+
+        # Build the start workflow request
+        start_request = self._build_start_workflow_request(
+            workflow, workflow_args, options
+        )
+
+        # Encode signal input
+        signal_payload = None
+        if signal_args:
+            try:
+                signal_payload = self.data_converter.to_data(signal_args)
+            except Exception as e:
+                raise ValueError(f"Failed to encode signal input: {e}")
+
+        # Build the SignalWithStartWorkflowExecution request
+        request = SignalWithStartWorkflowExecutionRequest(
+            start_request=start_request,
+            signal_name=signal_name,
+        )
+
+        if signal_payload:
+            request.signal_input.CopyFrom(signal_payload)
+
+        # Execute the gRPC call
+        try:
+            response: SignalWithStartWorkflowExecutionResponse = (
+                await self.workflow_stub.SignalWithStartWorkflowExecution(request)
+            )
+
+            execution = WorkflowExecution()
+            execution.workflow_id = start_request.workflow_id
+            execution.run_id = response.run_id
+            return execution
+        except Exception:
+            raise
+
+
+def _validate_and_copy_defaults(options: ClientOptions) -> ClientOptions:
+    if "target" not in options:
+        raise ValueError("target must be specified")
+
+    if "domain" not in options:
+        raise ValueError("domain must be specified")
+
+    # Set default values for missing options
+    for key, value in _DEFAULT_OPTIONS.items():
+        if key not in options:
+            cast(dict, options)[key] = value
+
+    return options
+
+
+def _create_channel(options: ClientOptions) -> Channel:
+    interceptors = list(options["interceptors"])
+    interceptors.append(
+        YarpcMetadataInterceptor(options["service_name"], options["caller_name"])
+    )
+    interceptors.append(RetryInterceptor())
+    interceptors.append(CadenceErrorInterceptor())
+
+    if options["credentials"]:
+        return secure_channel(
+            options["target"],
+            options["credentials"],
+            options["channel_arguments"],
+            options["compression"],
+            interceptors,
+        )
+    else:
+        return insecure_channel(
+            options["target"],
+            options["channel_arguments"],
+            options["compression"],
+            interceptors,
+        )

cadence/data_converter.py

@@ -0,0 +1,78 @@
+from abc import abstractmethod
+from typing import Protocol, List, Type, Any
+
+from cadence.api.v1.common_pb2 import Payload
+from json import JSONDecoder
+from msgspec import json, convert
+
+_SPACE = " ".encode()
+
+
+class DataConverter(Protocol):
+    @abstractmethod
+    def from_data(self, payload: Payload, type_hints: List[Type | None]) -> List[Any]:
+        raise NotImplementedError()
+
+    @abstractmethod
+    def to_data(self, values: List[Any]) -> Payload:
+        raise NotImplementedError()
+
+
+class DefaultDataConverter(DataConverter):
+    def __init__(self) -> None:
+        self._encoder = json.Encoder()
+        # Need to use std lib decoder in order to decode the custom whitespace delimited data format
+        self._decoder = JSONDecoder(strict=False)
+
+    def from_data(self, payload: Payload, type_hints: List[Type | None]) -> List[Any]:
+        if not payload.data:
+            return DefaultDataConverter._convert_into([], type_hints)
+
+        payload_str = payload.data.decode()
+
+        return self._decode_whitespace_delimited(payload_str, type_hints)
+
+    def _decode_whitespace_delimited(
+        self, payload: str, type_hints: List[Type | None]
+    ) -> List[Any]:
+        results: List[Any] = []
+        start, end = 0, len(payload)
+        while start < end and len(results) < len(type_hints):
+            remaining = payload[start:end]
+            (value, value_end) = self._decoder.raw_decode(remaining)
+            start += value_end + 1
+            results.append(value)
+
+        return DefaultDataConverter._convert_into(results, type_hints)
+
+    @staticmethod
+    def _convert_into(values: List[Any], type_hints: List[Type | None]) -> List[Any]:
+        results: List[Any] = []
+        for i, type_hint in enumerate(type_hints):
+            if not type_hint:
+                value = values[i]
+            elif i < len(values):
+                value = convert(values[i], type_hint)
+            else:
+                value = DefaultDataConverter._get_default(type_hint)
+
+            results.append(value)
+
+        return results
+
+    @staticmethod
+    def _get_default(type_hint: Type) -> Any:
+        if type_hint in (int, float):
+            return 0
+        if type_hint is bool:
+            return False
+        return None
+
+    def to_data(self, values: List[Any]) -> Payload:
+        result = bytearray()
+        for index, value in enumerate(values):
+            self._encoder.encode_into(value, result, -1)
+            if index < len(values) - 1:
+                result += _SPACE
+
+        return Payload(data=bytes(result))

cadence/error.py

@@ -0,0 +1,111 @@
+import grpc
+
+
+class ActivityFailure(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class WorkflowFailure(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class CadenceRpcError(Exception):
+    def __init__(self, message: str, code: grpc.StatusCode, *args):
+        super().__init__(message, code, *args)
+        self.code = code
+
+
+class WorkflowExecutionAlreadyStartedError(CadenceRpcError):
+    def __init__(
+        self, message: str, code: grpc.StatusCode, start_request_id: str, run_id: str
+    ) -> None:
+        super().__init__(message, code, start_request_id, run_id)
+        self.start_request_id = start_request_id
+        self.run_id = run_id
+
+
+class EntityNotExistsError(CadenceRpcError):
+    def __init__(
+        self,
+        message: str,
+        code: grpc.StatusCode,
+        current_cluster: str,
+        active_cluster: str,
+        active_clusters: list[str],
+    ) -> None:
+        super().__init__(
+            message, code, current_cluster, active_cluster, active_clusters
+        )
+        self.current_cluster = current_cluster
+        self.active_cluster = active_cluster
+        self.active_clusters = active_clusters
+
+
+class WorkflowExecutionAlreadyCompletedError(CadenceRpcError):
+    pass
+
+
+class DomainNotActiveError(CadenceRpcError):
+    def __init__(
+        self,
+        message: str,
+        code: grpc.StatusCode,
+        domain: str,
+        current_cluster: str,
+        active_cluster: str,
+        active_clusters: list[str],
+    ) -> None:
+        super().__init__(
+            message, code, domain, current_cluster, active_cluster, active_clusters
+        )
+        self.domain = domain
+        self.current_cluster = current_cluster
+        self.active_cluster = active_cluster
+        self.active_clusters = active_clusters
+
+
+class ClientVersionNotSupportedError(CadenceRpcError):
+    def __init__(
+        self,
+        message: str,
+        code: grpc.StatusCode,
+        feature_version: str,
+        client_impl: str,
+        supported_versions: str,
+    ) -> None:
+        super().__init__(
+            message, code, feature_version, client_impl, supported_versions
+        )
+        self.feature_version = feature_version
+        self.client_impl = client_impl
+        self.supported_versions = supported_versions
+
+
+class FeatureNotEnabledError(CadenceRpcError):
+    def __init__(self, message: str, code: grpc.StatusCode, feature_flag: str) -> None:
+        super().__init__(message, code, feature_flag)
+        self.feature_flag = feature_flag
+
+
+class CancellationAlreadyRequestedError(CadenceRpcError):
+    pass
+
+
+class DomainAlreadyExistsError(CadenceRpcError):
+    pass
+
+
+class LimitExceededError(CadenceRpcError):
+    pass
+
+
+class QueryFailedError(CadenceRpcError):
+    pass
+
+
+class ServiceBusyError(CadenceRpcError):
+    def __init__(self, message: str, code: grpc.StatusCode, reason: str) -> None:
+        super().__init__(message, code, reason)
+        self.reason = reason

cadence/metrics/__init__.py

@@ -0,0 +1,12 @@
+"""Metrics collection components for Cadence client."""
+
+from .metrics import MetricsEmitter, NoOpMetricsEmitter, MetricType
+from .prometheus import PrometheusMetrics, PrometheusConfig
+
+__all__ = [
+    "MetricsEmitter",
+    "NoOpMetricsEmitter",
+    "MetricType",
+    "PrometheusMetrics",
+    "PrometheusConfig",
+]