durabletask 1.4.0.dev30__tar.gz → 1.4.0.dev32__tar.gz

{durabletask-1.4.0.dev30 → durabletask-1.4.0.dev32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durabletask
-Version: 1.4.0.dev30
+Version: 1.4.0.dev32
 Summary: A Durable Task Client SDK for Python
 License:     MIT License
         

{durabletask-1.4.0.dev30 → durabletask-1.4.0.dev32}/durabletask/__init__.py

@@ -3,6 +3,7 @@
 
 """Durable Task SDK for Python"""
 
+from durabletask.grpc_options import GrpcChannelOptions, GrpcRetryPolicyOptions
 from durabletask.payload.store import LargePayloadStorageOptions, PayloadStore
 from durabletask.worker import (
     ActivityWorkItemFilter,
@@ -17,6 +18,8 @@ __all__ = [
     "ActivityWorkItemFilter",
     "ConcurrencyOptions",
     "EntityWorkItemFilter",
+    "GrpcChannelOptions",
+    "GrpcRetryPolicyOptions",
     "LargePayloadStorageOptions",
     "OrchestrationWorkItemFilter",
     "PayloadStore",

{durabletask-1.4.0.dev30 → durabletask-1.4.0.dev32}/durabletask/client.py

@@ -6,14 +6,17 @@ import uuid
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
-from typing import Any, List, Optional, Sequence, TypeVar, Union
+from typing import Any, Generic, List, Optional, Sequence, TypeVar, Union
 
 import grpc
 import grpc.aio
 
+import durabletask.history as history
 from durabletask.entities import EntityInstanceId
 from durabletask.entities.entity_metadata import EntityMetadata
+from durabletask.grpc_options import GrpcChannelOptions
 import durabletask.internal.helpers as helpers
+import durabletask.internal.history_helpers as history_helpers
 import durabletask.internal.orchestrator_service_pb2 as pb
 import durabletask.internal.orchestrator_service_pb2_grpc as stubs
 import durabletask.internal.shared as shared
@@ -37,6 +40,7 @@ from durabletask.payload.store import PayloadStore
 
 TInput = TypeVar('TInput')
 TOutput = TypeVar('TOutput')
+TItem = TypeVar('TItem')
 
 
 class OrchestrationStatus(Enum):
@@ -99,6 +103,12 @@ class PurgeInstancesResult:
     is_complete: bool
 
 
+@dataclass
+class Page(Generic[TItem]):
+    items: List[TItem]
+    continuation_token: Optional[str]
+
+
 @dataclass
 class CleanEntityStorageResult:
     empty_entities_removed: int
@@ -152,18 +162,22 @@ class TaskHubGrpcClient:
                  metadata: Optional[list[tuple[str, str]]] = None,
                  log_handler: Optional[logging.Handler] = None,
                  log_formatter: Optional[logging.Formatter] = None,
+                 channel: Optional[grpc.Channel] = None,
                  secure_channel: bool = False,
                  interceptors: Optional[Sequence[shared.ClientInterceptor]] = None,
+                 channel_options: Optional[GrpcChannelOptions] = None,
                  default_version: Optional[str] = None,
                  payload_store: Optional[PayloadStore] = None):
 
-        interceptors = prepare_sync_interceptors(metadata, interceptors)
-
-        channel = shared.get_grpc_channel(
-            host_address=host_address,
-            secure_channel=secure_channel,
-            interceptors=interceptors
-        )
+        self._owns_channel = channel is None
+        if channel is None:
+            interceptors = prepare_sync_interceptors(metadata, interceptors)
+            channel = shared.get_grpc_channel(
+                host_address=host_address,
+                secure_channel=secure_channel,
+                interceptors=interceptors,
+                channel_options=channel_options,
+            )
         self._channel = channel
         self._stub = stubs.TaskHubSidecarServiceStub(channel)
         self._logger = shared.get_logger("client", log_handler, log_formatter)
@@ -171,8 +185,15 @@ class TaskHubGrpcClient:
         self._payload_store = payload_store
 
     def close(self) -> None:
-        """Closes the underlying gRPC channel."""
-        self._channel.close()
+        """Closes the underlying gRPC channel.
+
+        Only closes channels created internally. If a pre-configured channel
+        was passed via the ``channel`` constructor parameter, this method is
+        a no-op — the caller retains ownership and is responsible for closing
+        it.
+        """
+        if self._owns_channel:
+            self._channel.close()
 
     def schedule_new_orchestration(self, orchestrator: Union[task.Orchestrator[TInput, TOutput], str], *,
                                    input: Optional[TInput] = None,
@@ -218,6 +239,44 @@ class TaskHubGrpcClient:
             payload_helpers.deexternalize_payloads(res, self._payload_store)
         return new_orchestration_state(req.instanceId, res)
 
+    def get_orchestration_history(self,
+                                  instance_id: str, *,
+                                  execution_id: Optional[str] = None,
+                                  for_work_item_processing: bool = False) -> List[history.HistoryEvent]:
+        req = pb.StreamInstanceHistoryRequest(
+            instanceId=instance_id,
+            executionId=helpers.get_string_value(execution_id),
+            forWorkItemProcessing=for_work_item_processing,
+        )
+        self._logger.info(f"Retrieving history for instance '{instance_id}'.")
+        stream = self._stub.StreamInstanceHistory(req)
+        return history_helpers.collect_history_events(stream, self._payload_store)
+
+    def list_instance_ids(self,
+                          runtime_status: Optional[List[OrchestrationStatus]] = None,
+                          completed_time_from: Optional[datetime] = None,
+                          completed_time_to: Optional[datetime] = None,
+                          page_size: Optional[int] = None,
+                          continuation_token: Optional[str] = None) -> Page[str]:
+        req = pb.ListInstanceIdsRequest(
+            runtimeStatus=[status.value for status in runtime_status] if runtime_status else [],
+            completedTimeFrom=helpers.new_timestamp(completed_time_from) if completed_time_from else None,
+            completedTimeTo=helpers.new_timestamp(completed_time_to) if completed_time_to else None,
+            pageSize=page_size or 0,
+            lastInstanceKey=helpers.get_string_value(continuation_token),
+        )
+        self._logger.info(
+            "Listing terminal instance IDs with filters: "
+            f"runtime_status={[str(status) for status in runtime_status] if runtime_status else None}, "
+            f"completed_time_from={completed_time_from}, "
+            f"completed_time_to={completed_time_to}, "
+            f"page_size={page_size}, "
+            f"continuation_token={continuation_token}"
+        )
+        resp: pb.ListInstanceIdsResponse = self._stub.ListInstanceIds(req)
+        next_token = resp.lastInstanceKey.value if resp.HasField("lastInstanceKey") else None
+        return Page(items=list(resp.instanceIds), continuation_token=next_token)
+
     def get_all_orchestration_states(self,
                                      orchestration_query: Optional[OrchestrationQuery] = None
                                      ) -> List[OrchestrationState]:
@@ -433,18 +492,22 @@ class AsyncTaskHubGrpcClient:
                  metadata: Optional[list[tuple[str, str]]] = None,
                  log_handler: Optional[logging.Handler] = None,
                  log_formatter: Optional[logging.Formatter] = None,
+                 channel: Optional[grpc.aio.Channel] = None,
                  secure_channel: bool = False,
                  interceptors: Optional[Sequence[shared.AsyncClientInterceptor]] = None,
+                 channel_options: Optional[GrpcChannelOptions] = None,
                  default_version: Optional[str] = None,
                  payload_store: Optional[PayloadStore] = None):
 
-        interceptors = prepare_async_interceptors(metadata, interceptors)
-
-        channel = shared.get_async_grpc_channel(
-            host_address=host_address,
-            secure_channel=secure_channel,
-            interceptors=interceptors
-        )
+        self._owns_channel = channel is None
+        if channel is None:
+            interceptors = prepare_async_interceptors(metadata, interceptors)
+            channel = shared.get_async_grpc_channel(
+                host_address=host_address,
+                secure_channel=secure_channel,
+                interceptors=interceptors,
+                channel_options=channel_options,
+            )
         self._channel = channel
         self._stub = stubs.TaskHubSidecarServiceStub(channel)
         self._logger = shared.get_logger("async_client", log_handler, log_formatter)
@@ -452,8 +515,15 @@ class AsyncTaskHubGrpcClient:
         self._payload_store = payload_store
 
     async def close(self) -> None:
-        """Closes the underlying gRPC channel."""
-        await self._channel.close()
+        """Closes the underlying gRPC channel.
+
+        Only closes channels created internally. If a pre-configured channel
+        was passed via the ``channel`` constructor parameter, this method is
+        a no-op — the caller retains ownership and is responsible for closing
+        it.
+        """
+        if self._owns_channel:
+            await self._channel.close()
 
     async def __aenter__(self):
         return self
@@ -502,6 +572,44 @@ class AsyncTaskHubGrpcClient:
             await payload_helpers.deexternalize_payloads_async(res, self._payload_store)
         return new_orchestration_state(req.instanceId, res)
 
+    async def get_orchestration_history(self,
+                                        instance_id: str, *,
+                                        execution_id: Optional[str] = None,
+                                        for_work_item_processing: bool = False) -> List[history.HistoryEvent]:
+        req = pb.StreamInstanceHistoryRequest(
+            instanceId=instance_id,
+            executionId=helpers.get_string_value(execution_id),
+            forWorkItemProcessing=for_work_item_processing,
+        )
+        self._logger.info(f"Retrieving history for instance '{instance_id}'.")
+        stream = self._stub.StreamInstanceHistory(req)
+        return await history_helpers.collect_history_events_async(stream, self._payload_store)
+
+    async def list_instance_ids(self,
+                                runtime_status: Optional[List[OrchestrationStatus]] = None,
+                                completed_time_from: Optional[datetime] = None,
+                                completed_time_to: Optional[datetime] = None,
+                                page_size: Optional[int] = None,
+                                continuation_token: Optional[str] = None) -> Page[str]:
+        req = pb.ListInstanceIdsRequest(
+            runtimeStatus=[status.value for status in runtime_status] if runtime_status else [],
+            completedTimeFrom=helpers.new_timestamp(completed_time_from) if completed_time_from else None,
+            completedTimeTo=helpers.new_timestamp(completed_time_to) if completed_time_to else None,
+            pageSize=page_size or 0,
+            lastInstanceKey=helpers.get_string_value(continuation_token),
+        )
+        self._logger.info(
+            "Listing terminal instance IDs with filters: "
+            f"runtime_status={[str(status) for status in runtime_status] if runtime_status else None}, "
+            f"completed_time_from={completed_time_from}, "
+            f"completed_time_to={completed_time_to}, "
+            f"page_size={page_size}, "
+            f"continuation_token={continuation_token}"
+        )
+        resp: pb.ListInstanceIdsResponse = await self._stub.ListInstanceIds(req)
+        next_token = resp.lastInstanceKey.value if resp.HasField("lastInstanceKey") else None
+        return Page(items=list(resp.instanceIds), continuation_token=next_token)
+
     async def get_all_orchestration_states(self,
                                            orchestration_query: Optional[OrchestrationQuery] = None
                                            ) -> List[OrchestrationState]:

durabletask-1.4.0.dev32/durabletask/grpc_options.py

@@ -0,0 +1,102 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from typing import Any, Optional
+
+
+@dataclass
+class GrpcRetryPolicyOptions:
+    """Configuration for transport-level gRPC retries."""
+
+    max_attempts: int = 4
+    initial_backoff_seconds: float = 0.05
+    max_backoff_seconds: float = 0.25
+    backoff_multiplier: float = 2.0
+    retryable_status_codes: list[str] = field(default_factory=lambda: ["UNAVAILABLE"])
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 2:
+            raise ValueError("max_attempts must be >= 2")
+        if self.initial_backoff_seconds <= 0:
+            raise ValueError("initial_backoff_seconds must be > 0")
+        if self.max_backoff_seconds <= 0:
+            raise ValueError("max_backoff_seconds must be > 0")
+        if self.backoff_multiplier <= 0:
+            raise ValueError("backoff_multiplier must be > 0")
+        if self.max_backoff_seconds < self.initial_backoff_seconds:
+            raise ValueError("max_backoff_seconds must be >= initial_backoff_seconds")
+        if len(self.retryable_status_codes) == 0:
+            raise ValueError("retryable_status_codes cannot be empty")
+        # Validate that backoff values are representable as non-zero gRPC duration strings.
+        self._format_duration(self.initial_backoff_seconds)
+        self._format_duration(self.max_backoff_seconds)
+
+    @staticmethod
+    def _format_duration(seconds: float) -> str:
+        formatted = f"{seconds:.9f}".rstrip('0')
+        if formatted.endswith('.'):
+            formatted += '0'
+        if float(formatted) == 0:
+            raise ValueError(
+                f"Duration {seconds!r} rounds to zero; use a value large enough to "
+                "produce a non-zero gRPC duration string."
+            )
+        return f"{formatted}s"
+
+    def to_service_config(self) -> dict[str, Any]:
+        return {
+            "methodConfig": [
+                {
+                    "name": [{}],
+                    "retryPolicy": {
+                        "maxAttempts": self.max_attempts,
+                        "initialBackoff": self._format_duration(self.initial_backoff_seconds),
+                        "maxBackoff": self._format_duration(self.max_backoff_seconds),
+                        "backoffMultiplier": self.backoff_multiplier,
+                        "retryableStatusCodes": self.retryable_status_codes,
+                    },
+                }
+            ]
+        }
+
+
+@dataclass
+class GrpcChannelOptions:
+    """Configuration for transport-level gRPC channel behavior."""
+
+    max_receive_message_length: Optional[int] = None
+    max_send_message_length: Optional[int] = None
+    keepalive_time_ms: Optional[int] = None
+    keepalive_timeout_ms: Optional[int] = None
+    keepalive_permit_without_calls: Optional[bool] = None
+    retry_policy: Optional[GrpcRetryPolicyOptions] = None
+    raw_options: list[tuple[str, Any]] = field(default_factory=list)
+
+    def to_grpc_options(self) -> list[tuple[str, Any]]:
+        options = list(self.raw_options)
+
+        if self.max_receive_message_length is not None:
+            options.append(("grpc.max_receive_message_length", self.max_receive_message_length))
+        if self.max_send_message_length is not None:
+            options.append(("grpc.max_send_message_length", self.max_send_message_length))
+        if self.keepalive_time_ms is not None:
+            options.append(("grpc.keepalive_time_ms", self.keepalive_time_ms))
+        if self.keepalive_timeout_ms is not None:
+            options.append(("grpc.keepalive_timeout_ms", self.keepalive_timeout_ms))
+        if self.keepalive_permit_without_calls is not None:
+            options.append(
+                (
+                    "grpc.keepalive_permit_without_calls",
+                    1 if self.keepalive_permit_without_calls else 0,
+                )
+            )
+
+        if self.retry_policy is not None:
+            options.append(("grpc.enable_retries", 1))
+            options.append(("grpc.service_config", json.dumps(self.retry_policy.to_service_config())))
+
+        return options