python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/background_jobs/pgqueuer/supervision.py

@@ -0,0 +1,201 @@
+"""PgQueuer manager readiness、fatal completion 与 task ownership。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+
+from ...errors.lifecycle import ApplicationRuntimeError
+
+
+@dataclass(frozen=True, slots=True)
+class _PgQueuerManagerBinding:
+    component: str
+    task_name: str
+    ready: asyncio.Event
+    run: Callable[[], Awaitable[None]]
+
+
+@dataclass(frozen=True, slots=True)
+class _PgQueuerManagerFailure:
+    component: str
+    error_type: str
+    _source: object = field(default_factory=object, repr=False, compare=False)
+
+
+class _PgQueuerManagerError(ApplicationRuntimeError):
+    """保留 provider 启动失败的类型边界；运行期事实使用已有 ApplicationRuntimeError 契约。"""
+
+
+class _PgQueuerManagerSupervisor:
+    """单个 provider runtime 的 manager owner；只发布脱敏失败事实。"""
+
+    __slots__ = (
+        "_failure",
+        "_reported_tasks",
+        "_startup_complete",
+        "_stopping",
+        "_task_components",
+        "_task_failures",
+        "_tasks",
+    )
+
+    def __init__(self) -> None:
+        self._failure: asyncio.Future[_PgQueuerManagerFailure] | None = None
+        self._startup_complete = False
+        self._stopping = False
+        self._task_components: dict[asyncio.Task[None], str] = {}
+        self._tasks: tuple[asyncio.Task[None], ...] = ()
+        self._reported_tasks: set[asyncio.Task[None]] = set()
+        self._task_failures: dict[asyncio.Task[None], _PgQueuerManagerFailure] = {}
+
+    async def start(self, bindings: tuple[_PgQueuerManagerBinding, ...]) -> None:
+        if self._failure is not None or self._tasks:
+            raise RuntimeError("PgQueuer manager supervisor may only start once")
+        if not bindings:
+            raise RuntimeError("PgQueuer manager supervisor requires an enabled role")
+
+        self._failure = asyncio.get_running_loop().create_future()
+        tasks_by_binding = {
+            asyncio.create_task(self._run(binding), name=binding.task_name): binding
+            for binding in bindings
+        }
+        self._tasks = tuple(tasks_by_binding)
+        self._task_components = {
+            task: binding.component for task, binding in tasks_by_binding.items()
+        }
+        readiness = {
+            asyncio.create_task(
+                binding.ready.wait(),
+                name=f"{binding.task_name}-readiness",
+            ): binding
+            for binding in bindings
+        }
+        try:
+            pending_readiness = set(readiness)
+            while pending_readiness:
+                done, _ = await asyncio.wait(
+                    (*pending_readiness, *self._tasks),
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                failed = next((task for task in self._tasks if task in done), None)
+                if failed is not None:
+                    binding = tasks_by_binding[failed]
+                    raise self._manager_error(binding.component, failed)
+                pending_readiness.difference_update(done)
+
+            # readiness callback 返回只说明 bootstrap I/O 已成功；再让 manager 前进一步，
+            # 防止 callback 后立即失败却被误报为 Application 已启动。
+            self._startup_complete = True
+            await asyncio.sleep(0)
+            failed = next((task for task in self._tasks if task.done()), None)
+            if failed is not None:
+                self._startup_complete = False
+                binding = tasks_by_binding[failed]
+                raise self._manager_error(binding.component, failed)
+        except BaseException:
+            self._startup_complete = False
+            self.begin_stop()
+            self.cancel()
+            await self._collect_outcomes()
+            raise
+        finally:
+            for task in readiness:
+                task.cancel()
+            if readiness:
+                await asyncio.gather(*readiness, return_exceptions=True)
+
+    def begin_stop(self) -> None:
+        self._stopping = True
+
+    async def wait(self) -> None:
+        cancellation: asyncio.CancelledError | None = None
+        try:
+            outcomes = await self._collect_outcomes()
+        except asyncio.CancelledError as error:
+            # deadline 取消 gather 时，已失败的 peer 仍须进入终止聚合，不能被取消掩盖。
+            cancellation = error
+            outcomes = await self._collect_outcomes()
+        failures: list[BaseException] = []
+        for task, outcome in zip(self._tasks, outcomes, strict=True):
+            fact = self._task_failures.get(task)
+            if (
+                fact is not None
+                or (
+                    isinstance(outcome, BaseException)
+                    and not isinstance(outcome, asyncio.CancelledError)
+                )
+            ) and task not in self._reported_tasks:
+                manager_error = _PgQueuerManagerError(
+                    component=self._task_components[task],
+                    error_type=fact.error_type if fact is not None else type(outcome).__name__,
+                )
+                if fact is not None:
+                    manager_error._source = fact._source
+                if isinstance(outcome, BaseException):
+                    manager_error.__cause__ = outcome
+                failures.append(manager_error)
+                self._reported_tasks.add(task)
+        if failures:
+            raise BaseExceptionGroup(
+                "PgQueuer manager drain failed", tuple(failures)
+            ) from cancellation
+        if cancellation is not None:
+            raise cancellation
+
+    async def wait_for_failure(self) -> _PgQueuerManagerFailure:
+        failure = self._failure
+        if failure is None:
+            raise RuntimeError("PgQueuer manager supervisor is not started")
+        return await asyncio.shield(failure)
+
+    def cancel(self) -> None:
+        for task in self._tasks:
+            task.cancel()
+
+    async def close(self) -> None:
+        self.begin_stop()
+        # bootstrap 已报告的原始失败不会重复计数；取消 peer 时 finally 的失败仍须可观察。
+        await self.wait()
+        self._tasks = ()
+        self._task_components = {}
+        self._task_failures.clear()
+        self._reported_tasks.clear()
+
+    async def _run(self, binding: _PgQueuerManagerBinding) -> None:
+        try:
+            await binding.run()
+        except BaseException as original_error:
+            if self._startup_complete and not self._stopping:
+                self._publish_failure(binding.component, type(original_error).__name__)
+            raise
+        if self._startup_complete and not self._stopping:
+            self._publish_failure(binding.component, "UnexpectedCompletion")
+
+    def _publish_failure(self, component: str, error_type: str) -> None:
+        task = asyncio.current_task()
+        assert task is not None
+        fact = _PgQueuerManagerFailure(component=component, error_type=error_type)
+        self._task_failures[task] = fact
+        failure = self._failure
+        if failure is not None and not failure.done():
+            failure.set_result(fact)
+            # 发布不等于 Application 已接收；同源去重只能由最终终止聚合 owner 完成。
+
+    async def _collect_outcomes(self) -> tuple[object, ...]:
+        if not self._tasks:
+            return ()
+        return tuple(await asyncio.gather(*self._tasks, return_exceptions=True))
+
+    def _manager_error(self, component: str, task: asyncio.Task[None]) -> _PgQueuerManagerError:
+        self._reported_tasks.add(task)
+        if task.cancelled():
+            error_type = asyncio.CancelledError.__name__
+        else:
+            error = task.exception()
+            error_type = "UnexpectedCompletion" if error is None else type(error).__name__
+        failure = _PgQueuerManagerError(component=component, error_type=error_type)
+        if not task.cancelled():
+            failure.__cause__ = task.exception()
+        return failure

python_ddd_framework/background_workers/__init__.py

@@ -0,0 +1,22 @@
+"""Provider-neutral non-durable background worker capability。"""
+
+from .catalog import BackgroundWorkerCatalog
+from .contracts import (
+    BackgroundExecutionOptions,
+    BackgroundExecutionProfile,
+    BackgroundWorker,
+    BackgroundWorkerContext,
+    BackgroundWorkerDefinition,
+)
+from .errors import BackgroundWorkerDefinitionError, BackgroundWorkerRuntimeError
+
+__all__ = (
+    "BackgroundExecutionOptions",
+    "BackgroundExecutionProfile",
+    "BackgroundWorker",
+    "BackgroundWorkerCatalog",
+    "BackgroundWorkerContext",
+    "BackgroundWorkerDefinition",
+    "BackgroundWorkerDefinitionError",
+    "BackgroundWorkerRuntimeError",
+)

python_ddd_framework/background_workers/catalog.py

@@ -0,0 +1,118 @@
+"""Module-owned worker metadata 的 Application-local immutable catalog。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+
+from ..modularity import AppModule, ModuleKey, ModuleRegistry
+from .contracts import BackgroundWorker, BackgroundWorkerDefinition, _definition_from_type
+from .errors import BackgroundWorkerDefinitionError
+
+
+class BackgroundWorkerCatalog:
+    __slots__ = ("_declarations", "_definitions", "_fingerprint", "_owners")
+
+    def __init__(
+        self,
+        definitions: tuple[BackgroundWorkerDefinition, ...],
+        *,
+        owners: Mapping[str, ModuleKey],
+        declarations: tuple[tuple[type[AppModule], str, tuple[object, ...]], ...],
+    ) -> None:
+        self._definitions = MappingProxyType({item.name: item for item in definitions})
+        self._owners = MappingProxyType(dict(owners))
+        self._declarations = declarations
+        encoded = json.dumps(
+            [
+                {
+                    "name": item.name,
+                    "enabled": item.enabled,
+                    "owner": str(self._owners[item.name]),
+                    "interval_seconds": item.interval.total_seconds(),
+                    "timeout_seconds": item.iteration_timeout.total_seconds(),
+                }
+                for item in definitions
+            ],
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        self._fingerprint = hashlib.sha256(encoded).hexdigest()
+
+    @property
+    def definitions(self) -> tuple[BackgroundWorkerDefinition, ...]:
+        return tuple(self._definitions.values())
+
+    @property
+    def fingerprint(self) -> str:
+        return self._fingerprint
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._definitions)
+
+    def get(self, name: str) -> BackgroundWorkerDefinition | None:
+        return self._definitions.get(name)
+
+    def owner_for(self, name: str) -> ModuleKey:
+        return self._owners[name]
+
+    def _assert_unchanged(self) -> None:
+        for definition in self.definitions:
+            if isinstance(definition.worker_type, type) and (
+                _definition_from_type(definition.worker_type) != definition
+            ):
+                raise BackgroundWorkerDefinitionError(
+                    worker=definition.name, reason="Worker class metadata changed after build"
+                )
+        for module_type, attribute, declared in self._declarations:
+            if module_type.__dict__.get(attribute, ()) is not declared:
+                raise BackgroundWorkerDefinitionError(
+                    worker=f"{module_type.__module__}.{module_type.__qualname__}",
+                    reason="Module background worker metadata changed after build",
+                )
+
+
+def _build_background_worker_catalog(registry: ModuleRegistry) -> BackgroundWorkerCatalog:
+    definitions: list[BackgroundWorkerDefinition] = []
+    owners: dict[str, ModuleKey] = {}
+    declarations: list[tuple[type[AppModule], str, tuple[object, ...]]] = []
+    for descriptor in registry.dependency_order:
+        for attribute in ("background_workers", "background_worker_definitions"):
+            declared = descriptor.module_type.__dict__.get(attribute, ())
+            if not isinstance(declared, tuple):
+                raise BackgroundWorkerDefinitionError(
+                    worker=str(descriptor.key),
+                    reason=f"Module {attribute} must be an immutable tuple",
+                )
+            declarations.append((descriptor.module_type, attribute, declared))
+            for candidate in declared:
+                definition = _interpret_worker(candidate, attribute)
+                previous = owners.get(definition.name)
+                if previous is not None:
+                    raise BackgroundWorkerDefinitionError(
+                        worker=definition.name,
+                        reason=f"worker is already owned by {previous}",
+                    )
+                owners[definition.name] = descriptor.key
+                definitions.append(definition)
+    return BackgroundWorkerCatalog(
+        tuple(definitions),
+        owners=owners,
+        declarations=tuple(declarations),
+    )
+
+
+def _interpret_worker(candidate: object, attribute: str) -> BackgroundWorkerDefinition:
+    if attribute == "background_workers":
+        if isinstance(candidate, type) and issubclass(candidate, BackgroundWorker):
+            return _definition_from_type(candidate)
+    elif isinstance(candidate, BackgroundWorkerDefinition) and not isinstance(
+        candidate.worker_type, type
+    ):
+        return candidate
+    raise BackgroundWorkerDefinitionError(
+        worker=attribute,
+        reason="background_workers requires Worker types; definitions require async functions",
+    )

python_ddd_framework/background_workers/contracts.py

@@ -0,0 +1,152 @@
+"""Non-durable worker contract 与 Host-owned execution options。"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from datetime import timedelta
+from enum import Enum
+from typing import ClassVar, cast
+
+from pydantic import ConfigDict, Field, field_serializer
+
+from ..background_execution import BackgroundJobOptions, BackgroundTaskOptions
+from ..invocation import BackgroundSystemCaller
+from ..options import BaseOptions
+from .errors import BackgroundWorkerDefinitionError
+
+
+class BackgroundExecutionProfile(str, Enum):
+    """Host 对当前 Application background execution ownership 的显式选择。"""
+
+    DISABLED = "disabled"
+    EMBEDDED = "embedded"
+    DEDICATED = "dedicated"
+
+
+class BackgroundExecutionOptions(BaseOptions):
+    """Application 准入和关闭策略；任务声明仍由 Module catalog 唯一拥有。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    profile: BackgroundExecutionProfile = BackgroundExecutionProfile.EMBEDDED
+    workers: Mapping[str, BackgroundTaskOptions] = Field(default_factory=dict)
+    jobs: Mapping[str, BackgroundJobOptions] = Field(default_factory=dict)
+    max_restarts: int = Field(default=3, ge=0)
+    restart_interval: timedelta = Field(default=timedelta(seconds=1), gt=timedelta(0))
+    graceful_shutdown_timeout: timedelta = Field(
+        default=timedelta(seconds=30),
+        gt=timedelta(0),
+    )
+
+    @field_serializer("workers", "jobs")
+    def _serialize_tasks(
+        self, value: Mapping[str, BackgroundJobOptions]
+    ) -> dict[str, BackgroundJobOptions]:
+        # 发布后的 Mapping 已冻结；原生 serializer 接收普通 dict 后继续处理内部 typed Options。
+        return dict(value)
+
+
+class BackgroundWorker(ABC):
+    """一次 iteration 的实现边界；永久 loop 由 Application coordinator 独占。"""
+
+    name: ClassVar[str]
+    interval: ClassVar[timedelta]
+    iteration_timeout: ClassVar[timedelta]
+    enabled: ClassVar[bool] = True
+
+    @abstractmethod
+    async def run_iteration(self, context: BackgroundWorkerContext) -> None:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundWorkerContext:
+    name: str
+    system_caller: BackgroundSystemCaller
+    _stop_event: asyncio.Event = field(repr=False, compare=False)
+
+    @property
+    def stop_requested(self) -> bool:
+        return self._stop_event.is_set()
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundWorkerDefinition:
+    name: str
+    worker_type: type[BackgroundWorker] | Callable[..., Awaitable[None]]
+    interval: timedelta
+    iteration_timeout: timedelta
+    enabled: bool = True
+
+    def __post_init__(self) -> None:
+        _validate_name(self.name)
+        if not isinstance(self.enabled, bool):
+            raise BackgroundWorkerDefinitionError(worker=self.name, reason="enabled must be bool")
+        is_class = isinstance(self.worker_type, type) and issubclass(
+            self.worker_type, BackgroundWorker
+        )
+        if not is_class and not inspect.iscoroutinefunction(self.worker_type):
+            raise BackgroundWorkerDefinitionError(
+                worker=self.name,
+                reason="worker_type must be a BackgroundWorker class or async function",
+            )
+        if isinstance(self.worker_type, type) and not inspect.iscoroutinefunction(
+            cast(type[BackgroundWorker], self.worker_type).run_iteration
+        ):
+            raise BackgroundWorkerDefinitionError(
+                worker=self.name,
+                reason="run_iteration must be async",
+            )
+        if not isinstance(self.interval, timedelta) or self.interval.total_seconds() <= 0:
+            raise BackgroundWorkerDefinitionError(
+                worker=self.name,
+                reason="interval must be a positive timedelta",
+            )
+        if (
+            not isinstance(self.iteration_timeout, timedelta)
+            or self.iteration_timeout.total_seconds() <= 0
+        ):
+            raise BackgroundWorkerDefinitionError(
+                worker=self.name,
+                reason="iteration_timeout must be a positive timedelta",
+            )
+
+
+def _definition_from_type(candidate: type[BackgroundWorker]) -> BackgroundWorkerDefinition:
+    if inspect.isabstract(candidate):
+        raise BackgroundWorkerDefinitionError(
+            worker=candidate.__qualname__, reason="Worker must be concrete"
+        )
+    try:
+        return BackgroundWorkerDefinition(
+            name=candidate.name,
+            worker_type=candidate,
+            interval=candidate.interval,
+            iteration_timeout=candidate.iteration_timeout,
+            enabled=candidate.enabled,
+        )
+    except AttributeError as error:
+        raise BackgroundWorkerDefinitionError(
+            worker=candidate.__qualname__,
+            reason="Worker must declare name, interval and iteration_timeout",
+        ) from error
+
+
+def _validate_name(name: str) -> None:
+    if (
+        not isinstance(name, str)
+        or not name
+        or name != name.strip()
+        or name.startswith(".")
+        or name.endswith(".")
+        or ".." in name
+        or any(not (character.isalnum() or character in "._-") for character in name)
+    ):
+        raise BackgroundWorkerDefinitionError(
+            worker=name if isinstance(name, str) else repr(name),
+            reason="name must be a trimmed stable identifier",
+        )

python_ddd_framework/background_workers/errors.py

@@ -0,0 +1,20 @@
+"""Non-durable background worker definition 与 runtime failures。"""
+
+from __future__ import annotations
+
+from ..errors.base import FrameworkError
+
+
+class BackgroundWorkerDefinitionError(FrameworkError):
+    def __init__(self, *, worker: str, reason: str) -> None:
+        self.worker = worker
+        self.reason = reason
+        super().__init__(f"Invalid background worker {worker!r}: {reason}")
+
+
+class BackgroundWorkerRuntimeError(FrameworkError):
+    def __init__(self, *, worker: str, operation: str, error_type: str) -> None:
+        self.worker = worker
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(f"Background worker {worker!r} {operation} failed with {error_type}")

python_ddd_framework/background_workers/execution.py

@@ -0,0 +1,133 @@
+"""单个 Worker 的 fixed-delay loop 与每次执行的原生作用域。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import AsyncExitStack
+from uuid import uuid4
+
+from dishka import AsyncContainer, Scope
+
+from ..application_services.contracts import _DEFAULT_CONNECTION_NAME
+from ..application_services.errors import ApplicationInvocationRejectedError
+from ..application_services.invocation import _InvocationRuntime
+from ..authorization import CurrentUser
+from ..background_execution.lifecycle import _TaskExecution
+from ..invocation import BackgroundSystemCaller
+from .contracts import BackgroundWorkerContext, BackgroundWorkerDefinition
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class _WorkerExecution:
+    def __init__(
+        self,
+        definition: BackgroundWorkerDefinition,
+        container: AsyncContainer,
+        invocation_runtime: _InvocationRuntime,
+        caller: BackgroundSystemCaller,
+    ) -> None:
+        self._definition = definition
+        self._container = container
+        self._invocation_runtime = invocation_runtime
+        self._caller = caller
+        self._stop_event = asyncio.Event()
+        self._task: asyncio.Task[None] | None = None
+
+    @property
+    def binding(self) -> _TaskExecution:
+        return _TaskExecution(self.start, self._stop_event.set, self.wait, None, self.cancel)
+
+    async def start(self) -> None:
+        self._stop_event.clear()
+        self._task = asyncio.create_task(
+            self._worker_loop(self._definition),
+            name=f"python-ddd-framework-worker:{self._definition.name}",
+        )
+
+    async def wait(self) -> None:
+        if self._task is not None:
+            await self._task
+
+    def cancel(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+
+    async def _worker_loop(self, definition: BackgroundWorkerDefinition) -> None:
+        while not self._stop_event.is_set():
+            try:
+                await self._run_worker_iteration(definition)
+            except asyncio.CancelledError:
+                raise
+            except Exception as original_error:
+                if self._stop_event.is_set():
+                    raise
+                # payload/secret 不进入日志；下一次 fixed-delay iteration 仍按 contract 执行。
+                _LOGGER.error(
+                    "background worker iteration failed",
+                    exc_info=original_error,
+                    extra={
+                        "background_worker": definition.name,
+                        "background_exception_type": type(original_error).__name__,
+                    },
+                )
+            if self._stop_event.is_set():
+                break
+            try:
+                await asyncio.wait_for(
+                    self._stop_event.wait(),
+                    timeout=definition.interval.total_seconds(),
+                )
+            except TimeoutError:
+                pass
+
+    async def _run_worker_iteration(self, definition: BackgroundWorkerDefinition) -> None:
+        container = self._container
+        context = BackgroundWorkerContext(
+            name=definition.name,
+            system_caller=self._caller,
+            _stop_event=self._stop_event,
+        )
+
+        # 原生 timeout 在当前 Worker Task 内执行、取消并等待清理；finally 失败直接传播。
+        # 不创建额外迭代 Task，调用许可、caller 和业务作用域保持同一 owner。
+        async with (
+            asyncio.timeout(definition.iteration_timeout.total_seconds()),
+            AsyncExitStack() as scope,
+        ):
+            # 关闭可能撤回尚未取得的许可；只处理 enter 的拒绝，不吞业务或 finally 异常。
+            try:
+                await scope.enter_async_context(self._invocation_runtime.outer_lease())
+            except ApplicationInvocationRejectedError:
+                return
+            token = self._invocation_runtime.bind_caller(CurrentUser.anonymous(), str(uuid4()))
+            try:
+                try:
+                    async with container(scope=Scope.REQUEST) as request_container:
+                        from ..invocation.interception import _EntryInterceptionCatalog
+
+                        entries = await request_container.get(_EntryInterceptionCatalog)
+                        await entries.invoke(
+                            self._invocation_runtime,
+                            request_container,
+                            definition.worker_type,
+                            "run_iteration",
+                            (context,),
+                            connection_name=_DEFAULT_CONNECTION_NAME,
+                        )
+                except Exception as error:
+                    if self._stop_event.is_set():
+                        # 关闭中的异常可能来自被取消业务的 finally，不能按普通迭代失败吞掉。
+                        raise
+                    # lease/caller 尚有效；普通迭代失败在 owner 内记录，然后继续下一轮。
+                    _LOGGER.error(
+                        "background worker iteration failed",
+                        exc_info=error,
+                        extra={
+                            "background_worker": definition.name,
+                            "background_exception_type": type(error).__name__,
+                        },
+                    )
+            finally:
+                self._invocation_runtime.reset_caller(token)