rappel 0.4.1__py3-none-win_amd64.whl → 0.8.1__py3-none-win_amd64.whl

proto/messages_pb2.pyi

@@ -648,10 +648,23 @@ class WorkflowErrorValue(google.protobuf.message.Message):
     MODULE_FIELD_NUMBER: builtins.int
     MESSAGE_FIELD_NUMBER: builtins.int
     TRACEBACK_FIELD_NUMBER: builtins.int
+    VALUES_FIELD_NUMBER: builtins.int
+    TYPE_HIERARCHY_FIELD_NUMBER: builtins.int
     type: builtins.str
     module: builtins.str
     message: builtins.str
     traceback: builtins.str
+    @property
+    def values(self) -> Global___WorkflowDictArgument: ...
+    @property
+    def type_hierarchy(
+        self,
+    ) -> google.protobuf.internal.containers.RepeatedScalarFieldContainer[builtins.str]:
+        """Exception class hierarchy (MRO) for proper except matching.
+        e.g., for KeyError: ["KeyError", "LookupError", "Exception", "BaseException"]
+        This allows `except LookupError:` to catch KeyError.
+        """
+
     def __init__(
         self,
         *,
@@ -659,11 +672,25 @@ class WorkflowErrorValue(google.protobuf.message.Message):
         module: builtins.str = ...,
         message: builtins.str = ...,
         traceback: builtins.str = ...,
+        values: Global___WorkflowDictArgument | None = ...,
+        type_hierarchy: collections.abc.Iterable[builtins.str] | None = ...,
     ) -> None: ...
+    def HasField(self, field_name: typing.Literal["values", b"values"]) -> builtins.bool: ...
     def ClearField(
         self,
         field_name: typing.Literal[
-            "message", b"message", "module", b"module", "traceback", b"traceback", "type", b"type"
+            "message",
+            b"message",
+            "module",
+            b"module",
+            "traceback",
+            b"traceback",
+            "type",
+            b"type",
+            "type_hierarchy",
+            b"type_hierarchy",
+            "values",
+            b"values",
         ],
     ) -> None: ...
 
@@ -875,17 +902,21 @@ class ScheduleDefinition(google.protobuf.message.Message):
     TYPE_FIELD_NUMBER: builtins.int
     CRON_EXPRESSION_FIELD_NUMBER: builtins.int
     INTERVAL_SECONDS_FIELD_NUMBER: builtins.int
+    JITTER_SECONDS_FIELD_NUMBER: builtins.int
     type: Global___ScheduleType.ValueType
     cron_expression: builtins.str
     """For cron: the cron expression (e.g., "0 * * * *")"""
     interval_seconds: builtins.int
     """For interval: duration in seconds"""
+    jitter_seconds: builtins.int
+    """Optional: jitter window in seconds (random 0..jitter_seconds)"""
     def __init__(
         self,
         *,
         type: Global___ScheduleType.ValueType = ...,
         cron_expression: builtins.str = ...,
         interval_seconds: builtins.int = ...,
+        jitter_seconds: builtins.int = ...,
     ) -> None: ...
     def ClearField(
         self,
@@ -894,6 +925,8 @@ class ScheduleDefinition(google.protobuf.message.Message):
             b"cron_expression",
             "interval_seconds",
             b"interval_seconds",
+            "jitter_seconds",
+            b"jitter_seconds",
             "type",
             b"type",
         ],
@@ -909,7 +942,12 @@ class RegisterScheduleRequest(google.protobuf.message.Message):
     SCHEDULE_FIELD_NUMBER: builtins.int
     INPUTS_FIELD_NUMBER: builtins.int
     REGISTRATION_FIELD_NUMBER: builtins.int
+    SCHEDULE_NAME_FIELD_NUMBER: builtins.int
     workflow_name: builtins.str
+    schedule_name: builtins.str
+    """Required: unique name for this schedule. Allows multiple schedules per workflow
+    with different inputs. Must be unique within a workflow.
+    """
     @property
     def schedule(self) -> Global___ScheduleDefinition: ...
     @property
@@ -931,6 +969,7 @@ class RegisterScheduleRequest(google.protobuf.message.Message):
         schedule: Global___ScheduleDefinition | None = ...,
         inputs: Global___WorkflowArguments | None = ...,
         registration: Global___WorkflowRegistration | None = ...,
+        schedule_name: builtins.str = ...,
     ) -> None: ...
     def HasField(
         self,
@@ -947,6 +986,8 @@ class RegisterScheduleRequest(google.protobuf.message.Message):
             b"registration",
             "schedule",
             b"schedule",
+            "schedule_name",
+            b"schedule_name",
             "workflow_name",
             b"workflow_name",
         ],
@@ -982,16 +1023,28 @@ class UpdateScheduleStatusRequest(google.protobuf.message.Message):
 
     WORKFLOW_NAME_FIELD_NUMBER: builtins.int
     STATUS_FIELD_NUMBER: builtins.int
+    SCHEDULE_NAME_FIELD_NUMBER: builtins.int
     workflow_name: builtins.str
     status: Global___ScheduleStatus.ValueType
+    schedule_name: builtins.str
+    """Required: name of the schedule to update."""
     def __init__(
         self,
         *,
         workflow_name: builtins.str = ...,
         status: Global___ScheduleStatus.ValueType = ...,
+        schedule_name: builtins.str = ...,
     ) -> None: ...
     def ClearField(
-        self, field_name: typing.Literal["status", b"status", "workflow_name", b"workflow_name"]
+        self,
+        field_name: typing.Literal[
+            "schedule_name",
+            b"schedule_name",
+            "status",
+            b"status",
+            "workflow_name",
+            b"workflow_name",
+        ],
     ) -> None: ...
 
 Global___UpdateScheduleStatusRequest: typing_extensions.TypeAlias = UpdateScheduleStatusRequest
@@ -1016,13 +1069,22 @@ class DeleteScheduleRequest(google.protobuf.message.Message):
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
     WORKFLOW_NAME_FIELD_NUMBER: builtins.int
+    SCHEDULE_NAME_FIELD_NUMBER: builtins.int
     workflow_name: builtins.str
+    schedule_name: builtins.str
+    """Required: name of the schedule to delete."""
     def __init__(
         self,
         *,
         workflow_name: builtins.str = ...,
+        schedule_name: builtins.str = ...,
+    ) -> None: ...
+    def ClearField(
+        self,
+        field_name: typing.Literal[
+            "schedule_name", b"schedule_name", "workflow_name", b"workflow_name"
+        ],
     ) -> None: ...
-    def ClearField(self, field_name: typing.Literal["workflow_name", b"workflow_name"]) -> None: ...
 
 Global___DeleteScheduleRequest: typing_extensions.TypeAlias = DeleteScheduleRequest
 
@@ -1086,6 +1148,8 @@ class ScheduleInfo(google.protobuf.message.Message):
     LAST_INSTANCE_ID_FIELD_NUMBER: builtins.int
     CREATED_AT_FIELD_NUMBER: builtins.int
     UPDATED_AT_FIELD_NUMBER: builtins.int
+    SCHEDULE_NAME_FIELD_NUMBER: builtins.int
+    JITTER_SECONDS_FIELD_NUMBER: builtins.int
     id: builtins.str
     workflow_name: builtins.str
     schedule_type: Global___ScheduleType.ValueType
@@ -1104,6 +1168,10 @@ class ScheduleInfo(google.protobuf.message.Message):
     """ISO 8601 timestamp"""
     updated_at: builtins.str
     """ISO 8601 timestamp"""
+    schedule_name: builtins.str
+    """Name of this schedule (allows multiple per workflow)"""
+    jitter_seconds: builtins.int
+    """0 if no jitter configured"""
     def __init__(
         self,
         *,
@@ -1118,6 +1186,8 @@ class ScheduleInfo(google.protobuf.message.Message):
         last_instance_id: builtins.str = ...,
         created_at: builtins.str = ...,
         updated_at: builtins.str = ...,
+        schedule_name: builtins.str = ...,
+        jitter_seconds: builtins.int = ...,
     ) -> None: ...
     def ClearField(
         self,
@@ -1130,12 +1200,16 @@ class ScheduleInfo(google.protobuf.message.Message):
             b"id",
             "interval_seconds",
             b"interval_seconds",
+            "jitter_seconds",
+            b"jitter_seconds",
             "last_instance_id",
             b"last_instance_id",
             "last_run_at",
             b"last_run_at",
             "next_run_at",
             b"next_run_at",
+            "schedule_name",
+            b"schedule_name",
             "schedule_type",
             b"schedule_type",
             "status",

rappel/__init__.py

@@ -10,7 +10,11 @@ from .actions import (
     serialize_result_payload,
 )
 from .dependencies import Depend, provide_dependencies
-from .exceptions import ExhaustedRetries, ExhaustedRetriesError
+from .exceptions import (
+    ExhaustedRetries,
+    ExhaustedRetriesError,
+    ScheduleAlreadyExistsError,
+)
 from .ir_builder import UnsupportedPatternError, build_workflow_ir
 from .registry import registry
 from .schedule import (
@@ -45,6 +49,7 @@ __all__ = [
     "bridge",
     "ExhaustedRetries",
     "ExhaustedRetriesError",
+    "ScheduleAlreadyExistsError",
     "UnsupportedPatternError",
     # Schedule functions
     "schedule_workflow",

rappel/actions.py

@@ -1,9 +1,11 @@
 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
 
@@ -13,7 +15,7 @@ TAsync = TypeVar("TAsync", bound=AsyncAction)
 @dataclass
 class ActionResultPayload:
     result: Any | None
-    error: dict[str, str] | None
+    error: dict[str, Any] | None
 
 
 def serialize_result_payload(value: Any) -> pb2.WorkflowArguments:
@@ -64,17 +66,42 @@ def action(
     *,
     name: Optional[str] = None,
 ) -> Callable[[TAsync], TAsync] | TAsync:
-    """Decorator for registering async actions."""
+    """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)
-        target.__rappel_action_name__ = action_name
-        target.__rappel_action_module__ = action_module
-        return target
+
+        return wrapper  # type: ignore[return-value]
 
     if func is not None:
         return decorator(func)

rappel/bridge.py

@@ -8,7 +8,6 @@ from dataclasses import dataclass
 from pathlib import Path
 from threading import Lock, RLock
 from typing import AsyncIterator, Optional
-from urllib.parse import urlparse
 
 import grpc
 from grpc import aio  # type: ignore[attr-defined]
@@ -21,10 +20,11 @@ DEFAULT_HOST = "127.0.0.1"
 LOGGER = configure_logger("rappel.bridge")
 
 _PORT_LOCK = RLock()
-_CACHED_PORT: Optional[int] = None
+_CACHED_GRPC_PORT: Optional[int] = None
 _GRPC_TARGET: Optional[str] = None
 _GRPC_CHANNEL: Optional[aio.Channel] = None
 _GRPC_STUB: Optional[pb2_grpc.WorkflowServiceStub] = None
+_GRPC_LOOP: Optional[asyncio.AbstractEventLoop] = None
 _BOOT_MUTEX = Lock()
 _ASYNC_BOOT_LOCK: asyncio.Lock = asyncio.Lock()
 
@@ -45,29 +45,31 @@ def _boot_command() -> list[str]:
     return [binary]
 
 
-def _remember_port(port: int) -> int:
-    global _CACHED_PORT
+def _remember_grpc_port(port: int) -> int:
+    global _CACHED_GRPC_PORT
     with _PORT_LOCK:
-        _CACHED_PORT = port
+        _CACHED_GRPC_PORT = port
     return port
 
 
-def _cached_port() -> Optional[int]:
+def _cached_grpc_port() -> Optional[int]:
     with _PORT_LOCK:
-        return _CACHED_PORT
+        return _CACHED_GRPC_PORT
 
 
-def _env_port_override() -> Optional[int]:
-    override = os.environ.get("RAPPEL_SERVER_PORT")
+def _env_grpc_port_override() -> Optional[int]:
+    """Check for explicit gRPC port override via environment."""
+    override = os.environ.get("RAPPEL_BRIDGE_GRPC_PORT")
     if not override:
         return None
     try:
         return int(override)
     except ValueError as exc:  # pragma: no cover
-        raise RuntimeError(f"invalid RAPPEL_SERVER_PORT value: {override}") from exc
+        raise RuntimeError(f"invalid RAPPEL_BRIDGE_GRPC_PORT value: {override}") from exc
 
 
 def _boot_singleton_blocking() -> int:
+    """Boot the singleton and return the gRPC port."""
     command = _boot_command()
     with tempfile.NamedTemporaryFile(mode="w+", suffix=".txt") as f:
         output_file = Path(f.name)
@@ -99,89 +101,87 @@ def _boot_singleton_blocking() -> int:
             # pipe to the subprocess and therefore never correctly close the file descriptor and signal
             # exit process status to Python.
             port_str = output_file.read_text().strip()
-            port = int(port_str)
-            LOGGER.info("boot command reported singleton port %s", port)
-            return port
+            grpc_port = int(port_str)
+            LOGGER.info("boot command reported singleton gRPC port %s", grpc_port)
+            return grpc_port
         except (ValueError, FileNotFoundError) as exc:  # pragma: no cover
             raise RuntimeError(f"unable to read port from output file: {exc}") from exc
 
 
-def _resolve_port() -> int:
-    cached = _cached_port()
+def _resolve_grpc_port() -> int:
+    """Resolve the gRPC port, booting singleton if necessary."""
+    cached = _cached_grpc_port()
     if cached is not None:
         return cached
-    env_port = _env_port_override()
+    env_port = _env_grpc_port_override()
     if env_port is not None:
-        return _remember_port(env_port)
+        return _remember_grpc_port(env_port)
     with _BOOT_MUTEX:
-        cached = _cached_port()
+        cached = _cached_grpc_port()
         if cached is not None:
             return cached
         port = _boot_singleton_blocking()
-        return _remember_port(port)
+        return _remember_grpc_port(port)
 
 
-async def _ensure_port_async() -> int:
-    cached = _cached_port()
+async def _ensure_grpc_port_async() -> int:
+    """Ensure we have a gRPC port, booting singleton if necessary."""
+    cached = _cached_grpc_port()
     if cached is not None:
         return cached
-    env_port = _env_port_override()
+    env_port = _env_grpc_port_override()
     if env_port is not None:
-        return _remember_port(env_port)
+        return _remember_grpc_port(env_port)
     async with _ASYNC_BOOT_LOCK:
-        cached = _cached_port()
+        cached = _cached_grpc_port()
         if cached is not None:
             return cached
         loop = asyncio.get_running_loop()
         LOGGER.info("No cached singleton found, booting new instance")
         port = await loop.run_in_executor(None, _boot_singleton_blocking)
-        LOGGER.info("Singleton ready on port %s", port)
-        return _remember_port(port)
+        LOGGER.info("Singleton ready on gRPC port %s", port)
+        return _remember_grpc_port(port)
 
 
 @asynccontextmanager
 async def ensure_singleton() -> AsyncIterator[int]:
-    """Yield the HTTP port for the singleton server, booting it exactly once."""
-    port = await _ensure_port_async()
+    """Yield the gRPC port for the singleton server, booting it exactly once."""
+    port = await _ensure_grpc_port_async()
     yield port
 
 
 def _grpc_target() -> str:
-    explicit = os.environ.get("RAPPEL_GRPC_ADDR")
+    """Get the gRPC target address for the bridge server."""
+    # Check for explicit full address override
+    explicit = os.environ.get("RAPPEL_BRIDGE_GRPC_ADDR")
     if explicit:
         return explicit
-    http_url = os.environ.get("RAPPEL_SERVER_URL")
-    host_from_url = None
-    port_from_url = None
-    if http_url:
-        parsed = urlparse(http_url)
-        host_from_url = parsed.hostname
-        port_from_url = parsed.port
-    host = host_from_url or os.environ.get("RAPPEL_SERVER_HOST", DEFAULT_HOST)
-    port_override = os.environ.get("RAPPEL_GRPC_PORT")
-    if port_override:
-        try:
-            port = int(port_override)
-        except ValueError as exc:  # pragma: no cover
-            raise RuntimeError(f"invalid RAPPEL_GRPC_PORT value: {port_override}") from exc
-    else:
-        http_port = port_from_url if port_from_url is not None else _resolve_port()
-        port = http_port + 1
+
+    # Otherwise, use host + port
+    host = os.environ.get("RAPPEL_BRIDGE_GRPC_HOST", DEFAULT_HOST)
+    port = _resolve_grpc_port()
     return f"{host}:{port}"
 
 
 async def _workflow_stub() -> pb2_grpc.WorkflowServiceStub:
-    global _GRPC_TARGET, _GRPC_CHANNEL, _GRPC_STUB
+    global _GRPC_TARGET, _GRPC_CHANNEL, _GRPC_STUB, _GRPC_LOOP
     target = _grpc_target()
+    loop = asyncio.get_running_loop()
     channel_to_wait: Optional[aio.Channel] = None
     with _PORT_LOCK:
-        if _GRPC_STUB is not None and _GRPC_TARGET == target:
+        if (
+            _GRPC_STUB is not None
+            and _GRPC_TARGET == target
+            and _GRPC_LOOP is loop
+            and not loop.is_closed()
+        ):
             return _GRPC_STUB
         channel = aio.insecure_channel(target)
         stub = pb2_grpc.WorkflowServiceStub(channel)
         _GRPC_CHANNEL = channel
         _GRPC_STUB = stub
         _GRPC_TARGET = target
+        _GRPC_LOOP = loop
         channel_to_wait = channel
     if channel_to_wait is not None:
         await channel_to_wait.channel_ready()

rappel/dependencies.py

@@ -7,26 +7,40 @@ from typing import Annotated, Any, AsyncIterator, Callable, Optional, get_args,
 
 
 @dataclass(frozen=True)
-class Depend:
-    """Marker for dependency injection, mirroring FastAPI's Depends syntax."""
+class DependMarker:
+    """Internal marker for dependency injection."""
 
     dependency: Optional[Callable[..., Any]] = None
     use_cache: bool = True
 
 
-def _depend_from_annotation(annotation: Any) -> Depend | None:
+def Depend(  # noqa: N802
+    dependency: Optional[Callable[..., Any]] = None,
+    *,
+    use_cache: bool = True,
+) -> Any:
+    """Marker for dependency injection, mirroring FastAPI's Depends syntax.
+
+    Returns Any to allow usage as a default parameter value:
+        def my_func(service: MyService = Depend(get_service)):
+            ...
+    """
+    return DependMarker(dependency=dependency, use_cache=use_cache)
+
+
+def _depend_from_annotation(annotation: Any) -> DependMarker | None:
     origin = get_origin(annotation)
     if origin is not Annotated:
         return None
     metadata = get_args(annotation)[1:]
     for meta in metadata:
-        if isinstance(meta, Depend):
+        if isinstance(meta, DependMarker):
             return meta
     return None
 
 
-def _dependency_marker(parameter: inspect.Parameter) -> Depend | None:
-    if isinstance(parameter.default, Depend):
+def _dependency_marker(parameter: inspect.Parameter) -> DependMarker | None:
+    if isinstance(parameter.default, DependMarker):
         return parameter.default
     return _depend_from_annotation(parameter.annotation)
 
@@ -69,7 +83,7 @@ class _DependencyResolver:
             raise TypeError(f"Missing required parameter '{name}' for {func_name}")
         return call_kwargs
 
-    async def _resolve_dependency(self, marker: Depend) -> Any:
+    async def _resolve_dependency(self, marker: DependMarker) -> Any:
         dependency = marker.dependency
         if dependency is None:
             raise TypeError("Depend requires a dependency callable")

rappel/exceptions.py

@@ -9,3 +9,10 @@ class ExhaustedRetriesError(Exception):
 
 
 ExhaustedRetries = ExhaustedRetriesError
+
+
+class ScheduleAlreadyExistsError(Exception):
+    """Raised when a schedule name is already registered."""
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(message or "schedule already exists")