rappel 0.7.2__py3-none-macosx_15_0_arm64.whl

proto/messages_pb2_grpc.pyi

@@ -0,0 +1,380 @@
+"""
+@generated by mypy-protobuf.  Do not edit manually!
+isort:skip_file
+"""
+
+import abc
+import collections.abc
+import sys
+import typing
+
+import grpc
+import grpc.aio
+
+from proto import messages_pb2
+
+if sys.version_info >= (3, 13):
+    import typing as typing_extensions
+else:
+    import typing_extensions
+
+_T = typing.TypeVar("_T")
+
+class _MaybeAsyncIterator(
+    collections.abc.AsyncIterator[_T], collections.abc.Iterator[_T], metaclass=abc.ABCMeta
+): ...
+class _ServicerContext(grpc.ServicerContext, grpc.aio.ServicerContext):  # type: ignore[misc, type-arg]
+    ...
+
+GRPC_GENERATED_VERSION: str
+GRPC_VERSION: str
+_WorkerBridgeAttachType = typing_extensions.TypeVar(
+    "_WorkerBridgeAttachType",
+    grpc.StreamStreamMultiCallable[
+        messages_pb2.Envelope,
+        messages_pb2.Envelope,
+    ],
+    grpc.aio.StreamStreamMultiCallable[
+        messages_pb2.Envelope,
+        messages_pb2.Envelope,
+    ],
+    default=grpc.StreamStreamMultiCallable[
+        messages_pb2.Envelope,
+        messages_pb2.Envelope,
+    ],
+)
+
+class WorkerBridgeStub(typing.Generic[_WorkerBridgeAttachType]):
+    """=============================================================================
+    gRPC Service Definitions
+    =============================================================================
+
+    Bidirectional streaming service for worker communication.
+    Workers connect and maintain a persistent stream for action dispatch/results.
+    """
+
+    @typing.overload
+    def __init__(
+        self: WorkerBridgeStub[
+            grpc.StreamStreamMultiCallable[
+                messages_pb2.Envelope,
+                messages_pb2.Envelope,
+            ],
+        ],
+        channel: grpc.Channel,
+    ) -> None: ...
+    @typing.overload
+    def __init__(
+        self: WorkerBridgeStub[
+            grpc.aio.StreamStreamMultiCallable[
+                messages_pb2.Envelope,
+                messages_pb2.Envelope,
+            ],
+        ],
+        channel: grpc.aio.Channel,
+    ) -> None: ...
+
+    Attach: _WorkerBridgeAttachType
+
+WorkerBridgeAsyncStub: typing_extensions.TypeAlias = WorkerBridgeStub[
+    grpc.aio.StreamStreamMultiCallable[
+        messages_pb2.Envelope,
+        messages_pb2.Envelope,
+    ],
+]
+
+class WorkerBridgeServicer(metaclass=abc.ABCMeta):
+    """=============================================================================
+    gRPC Service Definitions
+    =============================================================================
+
+    Bidirectional streaming service for worker communication.
+    Workers connect and maintain a persistent stream for action dispatch/results.
+    """
+
+    @abc.abstractmethod
+    def Attach(
+        self,
+        request_iterator: _MaybeAsyncIterator[messages_pb2.Envelope],
+        context: _ServicerContext,
+    ) -> typing.Union[
+        collections.abc.Iterator[messages_pb2.Envelope],
+        collections.abc.AsyncIterator[messages_pb2.Envelope],
+    ]: ...
+
+def add_WorkerBridgeServicer_to_server(
+    servicer: WorkerBridgeServicer, server: typing.Union[grpc.Server, grpc.aio.Server]
+) -> None: ...
+
+_WorkflowServiceRegisterWorkflowType = typing_extensions.TypeVar(
+    "_WorkflowServiceRegisterWorkflowType",
+    grpc.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterWorkflowRequest,
+        messages_pb2.RegisterWorkflowResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterWorkflowRequest,
+        messages_pb2.RegisterWorkflowResponse,
+    ],
+    default=grpc.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterWorkflowRequest,
+        messages_pb2.RegisterWorkflowResponse,
+    ],
+)
+
+_WorkflowServiceWaitForInstanceType = typing_extensions.TypeVar(
+    "_WorkflowServiceWaitForInstanceType",
+    grpc.UnaryUnaryMultiCallable[
+        messages_pb2.WaitForInstanceRequest,
+        messages_pb2.WaitForInstanceResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.WaitForInstanceRequest,
+        messages_pb2.WaitForInstanceResponse,
+    ],
+    default=grpc.UnaryUnaryMultiCallable[
+        messages_pb2.WaitForInstanceRequest,
+        messages_pb2.WaitForInstanceResponse,
+    ],
+)
+
+_WorkflowServiceRegisterScheduleType = typing_extensions.TypeVar(
+    "_WorkflowServiceRegisterScheduleType",
+    grpc.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterScheduleRequest,
+        messages_pb2.RegisterScheduleResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterScheduleRequest,
+        messages_pb2.RegisterScheduleResponse,
+    ],
+    default=grpc.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterScheduleRequest,
+        messages_pb2.RegisterScheduleResponse,
+    ],
+)
+
+_WorkflowServiceUpdateScheduleStatusType = typing_extensions.TypeVar(
+    "_WorkflowServiceUpdateScheduleStatusType",
+    grpc.UnaryUnaryMultiCallable[
+        messages_pb2.UpdateScheduleStatusRequest,
+        messages_pb2.UpdateScheduleStatusResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.UpdateScheduleStatusRequest,
+        messages_pb2.UpdateScheduleStatusResponse,
+    ],
+    default=grpc.UnaryUnaryMultiCallable[
+        messages_pb2.UpdateScheduleStatusRequest,
+        messages_pb2.UpdateScheduleStatusResponse,
+    ],
+)
+
+_WorkflowServiceDeleteScheduleType = typing_extensions.TypeVar(
+    "_WorkflowServiceDeleteScheduleType",
+    grpc.UnaryUnaryMultiCallable[
+        messages_pb2.DeleteScheduleRequest,
+        messages_pb2.DeleteScheduleResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.DeleteScheduleRequest,
+        messages_pb2.DeleteScheduleResponse,
+    ],
+    default=grpc.UnaryUnaryMultiCallable[
+        messages_pb2.DeleteScheduleRequest,
+        messages_pb2.DeleteScheduleResponse,
+    ],
+)
+
+_WorkflowServiceListSchedulesType = typing_extensions.TypeVar(
+    "_WorkflowServiceListSchedulesType",
+    grpc.UnaryUnaryMultiCallable[
+        messages_pb2.ListSchedulesRequest,
+        messages_pb2.ListSchedulesResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.ListSchedulesRequest,
+        messages_pb2.ListSchedulesResponse,
+    ],
+    default=grpc.UnaryUnaryMultiCallable[
+        messages_pb2.ListSchedulesRequest,
+        messages_pb2.ListSchedulesResponse,
+    ],
+)
+
+class WorkflowServiceStub(
+    typing.Generic[
+        _WorkflowServiceRegisterWorkflowType,
+        _WorkflowServiceWaitForInstanceType,
+        _WorkflowServiceRegisterScheduleType,
+        _WorkflowServiceUpdateScheduleStatusType,
+        _WorkflowServiceDeleteScheduleType,
+        _WorkflowServiceListSchedulesType,
+    ]
+):
+    """Workflow management service for client operations."""
+
+    @typing.overload
+    def __init__(
+        self: WorkflowServiceStub[
+            grpc.UnaryUnaryMultiCallable[
+                messages_pb2.RegisterWorkflowRequest,
+                messages_pb2.RegisterWorkflowResponse,
+            ],
+            grpc.UnaryUnaryMultiCallable[
+                messages_pb2.WaitForInstanceRequest,
+                messages_pb2.WaitForInstanceResponse,
+            ],
+            grpc.UnaryUnaryMultiCallable[
+                messages_pb2.RegisterScheduleRequest,
+                messages_pb2.RegisterScheduleResponse,
+            ],
+            grpc.UnaryUnaryMultiCallable[
+                messages_pb2.UpdateScheduleStatusRequest,
+                messages_pb2.UpdateScheduleStatusResponse,
+            ],
+            grpc.UnaryUnaryMultiCallable[
+                messages_pb2.DeleteScheduleRequest,
+                messages_pb2.DeleteScheduleResponse,
+            ],
+            grpc.UnaryUnaryMultiCallable[
+                messages_pb2.ListSchedulesRequest,
+                messages_pb2.ListSchedulesResponse,
+            ],
+        ],
+        channel: grpc.Channel,
+    ) -> None: ...
+    @typing.overload
+    def __init__(
+        self: WorkflowServiceStub[
+            grpc.aio.UnaryUnaryMultiCallable[
+                messages_pb2.RegisterWorkflowRequest,
+                messages_pb2.RegisterWorkflowResponse,
+            ],
+            grpc.aio.UnaryUnaryMultiCallable[
+                messages_pb2.WaitForInstanceRequest,
+                messages_pb2.WaitForInstanceResponse,
+            ],
+            grpc.aio.UnaryUnaryMultiCallable[
+                messages_pb2.RegisterScheduleRequest,
+                messages_pb2.RegisterScheduleResponse,
+            ],
+            grpc.aio.UnaryUnaryMultiCallable[
+                messages_pb2.UpdateScheduleStatusRequest,
+                messages_pb2.UpdateScheduleStatusResponse,
+            ],
+            grpc.aio.UnaryUnaryMultiCallable[
+                messages_pb2.DeleteScheduleRequest,
+                messages_pb2.DeleteScheduleResponse,
+            ],
+            grpc.aio.UnaryUnaryMultiCallable[
+                messages_pb2.ListSchedulesRequest,
+                messages_pb2.ListSchedulesResponse,
+            ],
+        ],
+        channel: grpc.aio.Channel,
+    ) -> None: ...
+
+    RegisterWorkflow: _WorkflowServiceRegisterWorkflowType
+
+    WaitForInstance: _WorkflowServiceWaitForInstanceType
+
+    RegisterSchedule: _WorkflowServiceRegisterScheduleType
+    """Schedule management"""
+
+    UpdateScheduleStatus: _WorkflowServiceUpdateScheduleStatusType
+
+    DeleteSchedule: _WorkflowServiceDeleteScheduleType
+
+    ListSchedules: _WorkflowServiceListSchedulesType
+
+WorkflowServiceAsyncStub: typing_extensions.TypeAlias = WorkflowServiceStub[
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterWorkflowRequest,
+        messages_pb2.RegisterWorkflowResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.WaitForInstanceRequest,
+        messages_pb2.WaitForInstanceResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.RegisterScheduleRequest,
+        messages_pb2.RegisterScheduleResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.UpdateScheduleStatusRequest,
+        messages_pb2.UpdateScheduleStatusResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.DeleteScheduleRequest,
+        messages_pb2.DeleteScheduleResponse,
+    ],
+    grpc.aio.UnaryUnaryMultiCallable[
+        messages_pb2.ListSchedulesRequest,
+        messages_pb2.ListSchedulesResponse,
+    ],
+]
+
+class WorkflowServiceServicer(metaclass=abc.ABCMeta):
+    """Workflow management service for client operations."""
+
+    @abc.abstractmethod
+    def RegisterWorkflow(
+        self,
+        request: messages_pb2.RegisterWorkflowRequest,
+        context: _ServicerContext,
+    ) -> typing.Union[
+        messages_pb2.RegisterWorkflowResponse,
+        collections.abc.Awaitable[messages_pb2.RegisterWorkflowResponse],
+    ]: ...
+    @abc.abstractmethod
+    def WaitForInstance(
+        self,
+        request: messages_pb2.WaitForInstanceRequest,
+        context: _ServicerContext,
+    ) -> typing.Union[
+        messages_pb2.WaitForInstanceResponse,
+        collections.abc.Awaitable[messages_pb2.WaitForInstanceResponse],
+    ]: ...
+    @abc.abstractmethod
+    def RegisterSchedule(
+        self,
+        request: messages_pb2.RegisterScheduleRequest,
+        context: _ServicerContext,
+    ) -> typing.Union[
+        messages_pb2.RegisterScheduleResponse,
+        collections.abc.Awaitable[messages_pb2.RegisterScheduleResponse],
+    ]:
+        """Schedule management"""
+
+    @abc.abstractmethod
+    def UpdateScheduleStatus(
+        self,
+        request: messages_pb2.UpdateScheduleStatusRequest,
+        context: _ServicerContext,
+    ) -> typing.Union[
+        messages_pb2.UpdateScheduleStatusResponse,
+        collections.abc.Awaitable[messages_pb2.UpdateScheduleStatusResponse],
+    ]: ...
+    @abc.abstractmethod
+    def DeleteSchedule(
+        self,
+        request: messages_pb2.DeleteScheduleRequest,
+        context: _ServicerContext,
+    ) -> typing.Union[
+        messages_pb2.DeleteScheduleResponse,
+        collections.abc.Awaitable[messages_pb2.DeleteScheduleResponse],
+    ]: ...
+    @abc.abstractmethod
+    def ListSchedules(
+        self,
+        request: messages_pb2.ListSchedulesRequest,
+        context: _ServicerContext,
+    ) -> typing.Union[
+        messages_pb2.ListSchedulesResponse,
+        collections.abc.Awaitable[messages_pb2.ListSchedulesResponse],
+    ]: ...
+
+def add_WorkflowServiceServicer_to_server(
+    servicer: WorkflowServiceServicer, server: typing.Union[grpc.Server, grpc.aio.Server]
+) -> None: ...

rappel/__init__.py

@@ -0,0 +1,61 @@
+"""Public API for user-defined rappel actions."""
+
+from . import bridge  # noqa: F401
+from . import workflow_runtime as _workflow_runtime  # noqa: F401
+from .actions import (
+    ActionResultPayload,
+    action,
+    deserialize_result_payload,
+    serialize_error_payload,
+    serialize_result_payload,
+)
+from .dependencies import Depend, provide_dependencies
+from .exceptions import (
+    ExhaustedRetries,
+    ExhaustedRetriesError,
+    ScheduleAlreadyExistsError,
+)
+from .ir_builder import UnsupportedPatternError, build_workflow_ir
+from .registry import registry
+from .schedule import (
+    ScheduleInfo,
+    delete_schedule,
+    list_schedules,
+    pause_schedule,
+    resume_schedule,
+    schedule_workflow,
+)
+from .workflow import (
+    RetryPolicy,
+    Workflow,
+    workflow,
+    workflow_registry,
+)
+
+__all__ = [
+    "action",
+    "registry",
+    "ActionResultPayload",
+    "Workflow",
+    "workflow",
+    "workflow_registry",
+    "RetryPolicy",
+    "build_workflow_ir",
+    "serialize_result_payload",
+    "deserialize_result_payload",
+    "serialize_error_payload",
+    "Depend",
+    "provide_dependencies",
+    "bridge",
+    "ExhaustedRetries",
+    "ExhaustedRetriesError",
+    "ScheduleAlreadyExistsError",
+    "UnsupportedPatternError",
+    # Schedule functions
+    "schedule_workflow",
+    "pause_schedule",
+    "resume_schedule",
+    "delete_schedule",
+    "list_schedules",
+    "ScheduleInfo",
+]

rappel/actions.py

@@ -0,0 +1,108 @@
+import inspect
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar, overload
+
+from proto import messages_pb2 as pb2
+
+from .dependencies import provide_dependencies
+from .registry import AsyncAction, registry
+from .serialization import dumps, loads
+
+TAsync = TypeVar("TAsync", bound=AsyncAction)
+
+
+@dataclass
+class ActionResultPayload:
+    result: Any | None
+    error: dict[str, Any] | None
+
+
+def serialize_result_payload(value: Any) -> pb2.WorkflowArguments:
+    """Serialize a successful action result."""
+    arguments = pb2.WorkflowArguments()
+    entry = arguments.arguments.add()
+    entry.key = "result"
+    entry.value.CopyFrom(dumps(value))
+    return arguments
+
+
+def serialize_error_payload(_action: str, exc: BaseException) -> pb2.WorkflowArguments:
+    """Serialize an error raised during action execution."""
+    arguments = pb2.WorkflowArguments()
+    entry = arguments.arguments.add()
+    entry.key = "error"
+    entry.value.CopyFrom(dumps(exc))
+    return arguments
+
+
+def deserialize_result_payload(payload: pb2.WorkflowArguments | None) -> ActionResultPayload:
+    """Deserialize WorkflowArguments produced by serialize_result_payload/error."""
+    if payload is None:
+        return ActionResultPayload(result=None, error=None)
+    values = {entry.key: entry.value for entry in payload.arguments}
+    if "error" in values:
+        error_value = values["error"]
+        data = loads(error_value)
+        if not isinstance(data, dict):
+            raise ValueError("error payload must deserialize to a mapping")
+        return ActionResultPayload(result=None, error=data)
+    result_value = values.get("result")
+    if result_value is None:
+        raise ValueError("result payload missing 'result' field")
+    return ActionResultPayload(result=loads(result_value), error=None)
+
+
+@overload
+def action(func: TAsync, /) -> TAsync: ...
+
+
+@overload
+def action(*, name: Optional[str] = None) -> Callable[[TAsync], TAsync]: ...
+
+
+def action(
+    func: Optional[TAsync] = None,
+    *,
+    name: Optional[str] = None,
+) -> Callable[[TAsync], TAsync] | TAsync:
+    """Decorator for registering async actions.
+
+    Actions decorated with @action will automatically resolve Depend() markers
+    when called directly (e.g., during pytest runs where workflows bypass the
+    gRPC bridge).
+    """
+
+    def decorator(target: TAsync) -> TAsync:
+        if not inspect.iscoroutinefunction(target):
+            raise TypeError(f"action '{target.__name__}' must be defined with 'async def'")
+        action_name = name or target.__name__
+        action_module = target.__module__
+
+        @wraps(target)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Convert positional args to kwargs based on the signature
+            sig = inspect.signature(target)
+            params = list(sig.parameters.keys())
+            for i, arg in enumerate(args):
+                if i < len(params):
+                    kwargs[params[i]] = arg
+
+            # Resolve dependencies using the same mechanism as execute_action
+            async with provide_dependencies(target, kwargs) as call_kwargs:
+                return await target(**call_kwargs)
+
+        # Copy over the original function's attributes for introspection
+        wrapper.__wrapped__ = target  # type: ignore[attr-defined]
+        wrapper.__rappel_action_name__ = action_name  # type: ignore[attr-defined]
+        wrapper.__rappel_action_module__ = action_module  # type: ignore[attr-defined]
+
+        # Register the original function (not the wrapper) so execute_action
+        # doesn't double-resolve dependencies
+        registry.register(action_module, action_name, target)
+
+        return wrapper  # type: ignore[return-value]
+
+    if func is not None:
+        return decorator(func)
+    return decorator