aga-runtime 0.4.0__py3-none-any.whl

aga_runtime/__init__.py

@@ -0,0 +1,99 @@
+"""Aga — durable execution for Python.
+
+import aga_runtime as aga
+
+app = aga.App("checkout")
+
+@app.step()
+def charge(order): ...
+
+@app.workflow()
+async def checkout(order):
+    return await charge(order)
+
+app.serve()
+"""
+
+# The one version string lives in _version.py — metadata, __version__, and
+# the wire handshake all derive from it. See that module for why.
+from ._version import __version__
+from .app import (
+    App,
+    Approval,
+    ExecutionInfo,
+    FrameworkAdapter,
+    Handle,
+    Remote,
+    ResourceRef,
+    RetryPolicy,
+    Step,
+    Workflow,
+    cancel,
+    event,
+    info,
+    join,
+    signal,
+    sleep,
+)
+from .errors import (
+    AgaError,
+    CasConflict,
+    Conflict,
+    InvalidConfig,
+    NondeterminismDetected,
+    NotFound,
+    PermissionDenied,
+    Stale,
+    Timeout,
+    TooLarge,
+    Unavailable,
+    Unsupported,
+)
+from .protocol.wire import (
+    OVERLAP_ALLOW,
+    OVERLAP_SKIP,
+)
+from .workflow._runtime.execution import deadline
+
+deadline.__module__ = __name__
+RetryPolicy.__module__ = __name__
+
+__all__ = [
+    "OVERLAP_ALLOW",
+    "OVERLAP_SKIP",
+    "App",
+    "Approval",
+    "CasConflict",
+    "Conflict",
+    "ExecutionInfo",
+    "FrameworkAdapter",
+    "Handle",
+    "InvalidConfig",
+    "NondeterminismDetected",
+    "NotFound",
+    "AgaError",
+    "PermissionDenied",
+    "Remote",
+    "ResourceRef",
+    "RetryPolicy",
+    "Stale",
+    "Step",
+    "Timeout",
+    "TooLarge",
+    "Unavailable",
+    "Unsupported",
+    "Workflow",
+    "__version__",
+    "cancel",
+    "deadline",
+    "event",
+    "info",
+    "join",
+    "signal",
+    "sleep",
+]
+
+# Importing private lowering helpers loads the ``aga_runtime.workflow`` package as an
+# implementation detail. Do not accidentally advertise that module as the
+# removed root-level ``workflow`` decorator.
+globals().pop("workflow", None)

aga_runtime/_authoring/__init__.py

@@ -0,0 +1,3 @@
+"""Private implementation of the public :mod:`aga_runtime.app` facade."""
+
+__all__: list[str] = []

aga_runtime/_authoring/adapters.py

@@ -0,0 +1,132 @@
+"""Atomic framework-adapter registration and ordered hook invocation."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from .catalog import CatalogSnapshot, DefinitionCatalog
+from .ports import AdapterHooks, AppIdentity, RegistrationGate
+
+
+class AdapterRegistry:
+    """Own adapters while delegating definitions and host state explicitly."""
+
+    def __init__(
+        self,
+        owner: AppIdentity,
+        catalog: DefinitionCatalog,
+        gate: RegistrationGate,
+    ):
+        self._owner = owner
+        self._catalog = catalog
+        self._gate = gate
+        self._adapters: dict[str, AdapterHooks] = {}
+
+    @property
+    def values(self) -> tuple[AdapterHooks, ...]:
+        return tuple(self._adapters.values())
+
+    def install(self, adapter: AdapterHooks) -> AdapterHooks:
+        with self._gate.adapter_hook(registration=True):
+            name = self._validate_shape(adapter)
+            if name in self._adapters:
+                raise ValueError(f"framework adapter {name!r} is already installed")
+            catalog_snapshot = self._catalog.snapshot()
+            adapter_snapshot = dict(self._adapters)
+            try:
+                self._adapters[name] = adapter
+                self.call(adapter, "install", required=True)
+            except BaseException:
+                self._restore(catalog_snapshot, adapter_snapshot)
+                raise
+        return adapter
+
+    def validate(self) -> None:
+        for adapter in self._adapters.values():
+            catalog_snapshot = self._catalog.snapshot()
+            adapter_snapshot = dict(self._adapters)
+            try:
+                with self._gate.adapter_hook(registration=False):
+                    self.call(adapter, "validate")
+            except BaseException:
+                self._restore(catalog_snapshot, adapter_snapshot)
+                raise
+            if not self._catalog.unchanged(catalog_snapshot):
+                self._restore(catalog_snapshot, adapter_snapshot)
+                raise RuntimeError(
+                    f"framework adapter {adapter.name!r} mutated App registration "
+                    "during validate; use install(app) for registration"
+                )
+
+    def call(
+        self,
+        adapter: AdapterHooks,
+        hook_name: str,
+        *,
+        required: bool = False,
+    ) -> None:
+        hook = getattr(adapter, hook_name, None)
+        if hook is None:
+            if required:
+                raise TypeError(f"framework adapter {adapter.name!r} requires {hook_name}(app)")
+            return
+        result = hook(self._owner)
+        if inspect.isawaitable(result):
+            close = getattr(result, "close", None)
+            if callable(close):
+                close()
+            raise TypeError(
+                f"framework adapter {adapter.name!r} {hook_name}(app) must be synchronous"
+            )
+        if result is not None:
+            raise TypeError(f"framework adapter {adapter.name!r} {hook_name}(app) must return None")
+
+    @staticmethod
+    def _validate_shape(adapter: Any) -> str:
+        name = getattr(adapter, "name", "")
+        if not isinstance(name, str) or not name or name != name.strip():
+            raise ValueError("a framework adapter requires a stable name")
+        if not callable(getattr(adapter, "install", None)):
+            raise TypeError(f"framework adapter {name!r} requires install(app)")
+        for hook_name in ("validate", "start", "stop"):
+            hook = getattr(adapter, hook_name, None)
+            if hook is not None and not callable(hook):
+                raise TypeError(f"framework adapter {name!r} {hook_name} hook must be callable")
+        return name
+
+    def _restore(
+        self,
+        catalog_snapshot: CatalogSnapshot,
+        adapter_snapshot: dict[str, AdapterHooks],
+    ) -> None:
+        self._catalog.restore(catalog_snapshot)
+        self._adapters.clear()
+        self._adapters.update(adapter_snapshot)
+
+
+def attach_cleanup_diagnostics(
+    error: BaseException,
+    stop_errors: list[tuple[str, BaseException]],
+    *,
+    prefix: str,
+) -> None:
+    """Attach cleanup details without replacing the selected primary error."""
+    try:
+        try:
+            detail = "; ".join(f"{name}: {failure}" for name, failure in stop_errors)
+        except BaseException:
+            detail = "cleanup error details are not printable"
+        add_note = getattr(error, "add_note", None)
+        if callable(add_note):
+            add_note(f"{prefix}: {detail}")
+            return
+    except BaseException:
+        pass
+    try:
+        error.aga_adapter_stop_errors = tuple(stop_errors)  # type: ignore[attr-defined]
+    except BaseException:
+        pass
+
+
+__all__: list[str] = []

aga_runtime/_authoring/catalog.py

@@ -0,0 +1,304 @@
+"""Owned registry for typed durable definitions and schedules."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from ..protocol.wire import MAX_SCHEDULE_REVISION
+from ..workflow._runtime.replay import ReplayRuntime
+from ..workflow._runtime.serialization import JsonCodec
+from ..workflow._runtime.signals import Suspended
+from ..workflow.decorators import RetryPolicy, ScheduleSpec, StepSpec, WorkflowSpec
+from .contracts import FunctionContract
+from .definitions import (
+    Remote,
+    Step,
+    Workflow,
+    _Workflow,
+    create_remote,
+    create_step,
+    create_workflow,
+    require_registered_step,
+)
+from .models import UNSET, RemoteOptions
+from .ports import AppIdentity, RegistrationGate
+from .scope import ExecutionScope, active_scope
+
+
+@dataclass(frozen=True)
+class CatalogSnapshot:
+    steps: dict[str, StepSpec]
+    workflows: dict[str, WorkflowSpec]
+    remotes: dict[tuple[str, str], Remote[Any, Any]]
+    schedules: dict[str, ScheduleSpec | None]
+
+
+class DefinitionCatalog:
+    """Own all declarations for one App and their atomic snapshots."""
+
+    def __init__(
+        self,
+        owner: AppIdentity,
+        gate: RegistrationGate,
+        codec: JsonCodec,
+    ):
+        self._owner = owner
+        self._gate = gate
+        self._codec = codec
+        self._steps: dict[str, StepSpec] = {}
+        self._workflows: dict[str, WorkflowSpec] = {}
+        self._remotes: dict[tuple[str, str], Remote[Any, Any]] = {}
+
+    @property
+    def steps(self) -> dict[str, StepSpec]:
+        return self._steps
+
+    @property
+    def workflows(self) -> dict[str, WorkflowSpec]:
+        return self._workflows
+
+    def step(
+        self,
+        *,
+        name: str | None,
+        target: str | None,
+        retry: RetryPolicy | None,
+        timeout: int,
+        attempt_timeout: int,
+        compensate_with: str | Step[Any, Any] | None,
+        pivot: bool,
+    ) -> Callable[[Callable[..., Any]], Step[Any, Any]]:
+        def decorate(user_fn: Callable[..., Any]) -> Step[Any, Any]:
+            with self._gate.registration():
+                step_name = name or getattr(user_fn, "__name__", "")
+                if not step_name:
+                    raise ValueError("a durable step requires a name")
+                if step_name in self._steps:
+                    raise ValueError(
+                        f"step {step_name!r} is already registered in App {self._owner.name!r}"
+                    )
+                compensation: str | None
+                if compensate_with is None or isinstance(compensate_with, str):
+                    compensation = compensate_with
+                else:
+                    compensation = require_registered_step(
+                        compensate_with,
+                        self._owner,
+                    ).__aga_step_name__
+                contract = FunctionContract(user_fn, step_name)
+                spec = StepSpec(
+                    name=step_name,
+                    fn=lambda *args, **kwargs: contract.invoke(tuple(args), dict(kwargs)),
+                    target=target,
+                    retry=retry,
+                    timeout=timeout,
+                    attempt_timeout=attempt_timeout,
+                    compensate_with=compensation,
+                    pivot=pivot,
+                )
+                definition = create_step(self._owner, contract, spec)
+                self._steps[step_name] = spec
+                return definition
+
+        return decorate
+
+    def remote(
+        self,
+        service: str,
+        *,
+        name: str | None,
+        timeout: float | None,
+    ) -> Callable[[Callable[..., Any]], Remote[Any, Any]]:
+        if not service:
+            raise ValueError("a remote function requires a service name")
+
+        def decorate(stub: Callable[..., Any]) -> Remote[Any, Any]:
+            with self._gate.registration():
+                method = name or getattr(stub, "__name__", "")
+                if not method:
+                    raise ValueError("a remote function requires a method name")
+                key = (service, method)
+                if key in self._remotes:
+                    raise ValueError(f"remote {service}.{method} is already declared")
+                contract = FunctionContract(stub, f"{service}.{method}")
+                parameters = tuple(contract.signature.parameters.values())
+                portable = (
+                    inspect.Parameter.POSITIONAL_ONLY,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    inspect.Parameter.KEYWORD_ONLY,
+                )
+                if (
+                    len(parameters) != 1
+                    or parameters[0].kind not in portable
+                    or parameters[0].default is not inspect.Parameter.empty
+                ):
+                    raise TypeError(
+                        f"remote {service}.{method} must declare exactly one required "
+                        "request parameter for cross-language portability"
+                    )
+                definition = create_remote(
+                    self._owner,
+                    service,
+                    method,
+                    contract,
+                    RemoteOptions(timeout=timeout),
+                )
+                self._remotes[key] = definition
+                return definition
+
+        return decorate
+
+    def workflow(
+        self,
+        *,
+        name: str | None,
+        version: str,
+        execution: str,
+        target: str | None,
+    ) -> Callable[[Callable[..., Any]], Workflow[Any, Any]]:
+        def decorate(user_fn: Callable[..., Any]) -> Workflow[Any, Any]:
+            with self._gate.registration():
+                workflow_name = name or getattr(user_fn, "__name__", "")
+                if not workflow_name:
+                    raise ValueError("a durable workflow requires a name")
+                if workflow_name in self._workflows:
+                    raise ValueError(
+                        f"workflow {workflow_name!r} is already registered in App "
+                        f"{self._owner.name!r}"
+                    )
+                if not inspect.iscoroutinefunction(user_fn):
+                    raise TypeError(f"@app.workflow {workflow_name!r} must be `async def`")
+                if execution not in ("async", "async_distributed"):
+                    raise ValueError(
+                        "workflow execution must be 'async' or 'async_distributed', "
+                        f"got {execution!r}"
+                    )
+                internal = "async_sticky" if execution == "async" else "async_distributed"
+                contract = FunctionContract(user_fn, workflow_name)
+
+                async def registered(runtime: ReplayRuntime, param: Any) -> Any:
+                    args, kwargs = contract.unpack(param)
+                    scope = ExecutionScope(runtime, self._owner)
+                    token = active_scope.set(scope)
+                    try:
+                        result = contract.invoke(args, kwargs)
+                        if inspect.isawaitable(result):
+                            result = await result
+                        await scope.finish()
+                        return result
+                    except Suspended:
+                        raise
+                    except Exception:
+                        scope.cancel_unfinished()
+                        raise
+                    finally:
+                        active_scope.reset(token)
+
+                spec = WorkflowSpec(
+                    name=workflow_name,
+                    fn=registered,
+                    version=version,
+                    execution=internal,
+                    target=target or self._owner.target,
+                )
+                definition = create_workflow(self._owner, contract, spec)
+                self._workflows[workflow_name] = spec
+                return definition
+
+        return decorate
+
+    def schedule(
+        self,
+        cron: str,
+        *,
+        schedule_id: str,
+        input_value: Any,
+        timeout_ms: int,
+        overlap: int,
+        catch_up_window_ms: int,
+        paused: bool,
+        revision: int,
+    ) -> Callable[[Workflow[Any, Any]], Workflow[Any, Any]]:
+        def decorate(definition: Workflow[Any, Any]) -> Workflow[Any, Any]:
+            with self._gate.registration():
+                registered = self._validate_schedule(definition, revision)
+                resolved_id = schedule_id or registered._spec.name
+                self._assert_schedule_id_available(registered, resolved_id)
+                args = () if input_value is UNSET else (input_value,)
+                packed = registered._contract.pack(args, {})
+                snapshot = self._codec.decode(self._codec.encode(packed))
+                registered._spec.schedule = ScheduleSpec(
+                    cron=cron,
+                    schedule_id=resolved_id,
+                    input_payload=snapshot,
+                    timeout_ms=timeout_ms,
+                    overlap=overlap,
+                    catch_up_window_ms=catch_up_window_ms,
+                    paused=paused,
+                    revision=revision,
+                )
+                return registered
+
+        return decorate
+
+    def _validate_schedule(
+        self,
+        definition: Any,
+        revision: int,
+    ) -> _Workflow[Any, Any]:
+        if not isinstance(definition, _Workflow):
+            raise TypeError(
+                "@app.schedule must wrap an @app.workflow definition "
+                "(place @app.schedule above @app.workflow)"
+            )
+        if definition._app is not self._owner:
+            raise TypeError("@app.schedule cannot decorate another App's workflow")
+        registered = definition
+        if revision < 1 or revision > MAX_SCHEDULE_REVISION:
+            raise ValueError(f"@app.schedule revision must be in 1..{MAX_SCHEDULE_REVISION}")
+        if registered._spec.schedule is not None:
+            raise ValueError(f"workflow {registered._spec.name!r} already has a schedule")
+        return registered
+
+    def _assert_schedule_id_available(
+        self,
+        definition: _Workflow[Any, Any],
+        schedule_id: str,
+    ) -> None:
+        for registered in self._workflows.values():
+            schedule = registered.schedule
+            if (
+                registered is not definition._spec
+                and schedule is not None
+                and schedule.schedule_id == schedule_id
+            ):
+                raise ValueError(
+                    f"schedule {schedule_id!r} is already declared for workflow {registered.name!r}"
+                )
+
+    def snapshot(self) -> CatalogSnapshot:
+        return CatalogSnapshot(
+            dict(self._steps),
+            dict(self._workflows),
+            dict(self._remotes),
+            {name: spec.schedule for name, spec in self._workflows.items()},
+        )
+
+    def restore(self, snapshot: CatalogSnapshot) -> None:
+        self._steps.clear()
+        self._steps.update(snapshot.steps)
+        self._workflows.clear()
+        self._workflows.update(snapshot.workflows)
+        self._remotes.clear()
+        self._remotes.update(snapshot.remotes)
+        for name, schedule in snapshot.schedules.items():
+            self._workflows[name].schedule = schedule
+
+    def unchanged(self, snapshot: CatalogSnapshot) -> bool:
+        current = self.snapshot()
+        return current == snapshot
+
+
+__all__: list[str] = []