python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/messaging/channel.py

@@ -0,0 +1,205 @@
+"""单通道的接受、顺序消费与待执行快照 owner；原生 stream 持有顺序。"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+from collections.abc import Callable, Hashable
+from contextvars import Context
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from dishka import AsyncContainer
+
+from ..application_services import ApplicationServiceCatalog
+from ..application_services.errors import ApplicationInvocationRejectedError
+from ..application_services.invocation import _InvocationReservation, _InvocationRuntime
+from ..hosted_services.bridge import HostedServiceContext, _HostedServiceBridge
+from ..invocation.interception import _EntryInterceptionCatalog
+from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME
+from .contracts import MessageChannelDefinition, MessageRejectedError, MessageState
+from .receipt import MessageReceipt
+
+T = TypeVar("T")
+
+if TYPE_CHECKING:
+    from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+
+@dataclass(slots=True)
+class _Delivery(Generic[T]):
+    message: T
+    receipt: MessageReceipt
+    reservation: _InvocationReservation
+
+
+class MessageChannel(Generic[T]):
+    """APP 注入的类型化发送入口；容量包含正在执行的消息，满载明确拒绝。"""
+
+    def __init__(self, definition: MessageChannelDefinition[T]) -> None:
+        self._definition = definition
+        self._pending: dict[Hashable, _Delivery[T]] = {}
+        self._active: _Delivery[T] | None = None
+        self._accepting = False
+        self._failure: BaseException | None = None
+        self._context: HostedServiceContext | None = None
+        self._bridge: _HostedServiceBridge | None = None
+        self._runtime: _InvocationRuntime | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._send: MemoryObjectSendStream[Hashable] | None = None
+        self._receive: MemoryObjectReceiveStream[Hashable] | None = None
+
+    async def send(self, message: T) -> MessageReceipt:
+        """返回只表示接受；本入口无等待发送者、无后台发送 task。"""
+        self._require_loop()
+        if self._failure is not None:
+            raise MessageRejectedError("consumer_failed")
+        if not self._accepting:
+            raise MessageRejectedError("closed")
+        assert self._runtime is not None
+        try:
+            self._runtime.require_accepting_work()
+        except ApplicationInvocationRejectedError:
+            raise MessageRejectedError("closed") from None
+        if not isinstance(message, self._definition.message_type):
+            raise TypeError("Message does not match the declared channel type")
+        key = self._definition.snapshot_key(message) if self._definition.snapshot_key else object()
+        hash(key)
+        receipt = MessageReceipt()
+        if key in self._pending:
+            delivery = self._pending[key]
+            delivery.receipt._finish(MessageState.SUPERSEDED)
+            delivery.message = message
+            delivery.receipt = receipt
+            return receipt
+        if len(self._pending) + (self._active is not None) >= self._definition.capacity:
+            raise MessageRejectedError("capacity_exceeded")
+        assert self._runtime is not None and self._send is not None
+        # 接受与许可预留在同一 loop turn 完成；slot 的许可随最终快照转交，不携带 scope。
+        reservation = self._runtime.reserve()
+        self._pending[key] = _Delivery(message, receipt, reservation)
+        self._send.send_nowait(key)
+        return receipt
+
+    def submit(self, message: T) -> concurrent.futures.Future[MessageReceipt]:
+        """外部线程入口；bridge pending 上限等于通道容量，Future 结果才表示接受。"""
+        context = self._context
+        if context is None:
+            raise MessageRejectedError("closed")
+        # to_thread 可能复制生产者的 ContextVar；线程交接只传消息值，不传调用 scope。
+        return Context().run(context.submit_call, self.send, message)
+
+    def _start(
+        self,
+        container: AsyncContainer,
+        catalog: ApplicationServiceCatalog,
+        runtime: _InvocationRuntime,
+    ) -> None:
+        import anyio
+
+        if self._loop is not None:
+            raise RuntimeError("Channel instances cannot be restarted; build a new Application")
+        self._loop = asyncio.get_running_loop()
+        self._runtime = runtime
+        self._send, self._receive = anyio.create_memory_object_stream[Hashable](
+            self._definition.capacity
+        )
+        self._bridge = _HostedServiceBridge(
+            name=f"message:{self._definition.message_type.__qualname__}",
+            loop=self._loop,
+            container=container,
+            catalog=catalog,
+            limit=self._definition.capacity,
+        )
+        self._context = HostedServiceContext(
+            self._definition.message_type.__qualname__, self._bridge
+        )
+        self._bridge.open()
+        self._accepting = True
+
+    def _close(self) -> None:
+        self._accepting = False
+        if self._bridge is not None:
+            self._bridge.close()
+        if self._send is not None:
+            # 发送端仅由此 owner 持有，不向生产者暴露 clone；因此关闭即关闭全部发送端。
+            self._send.close()
+
+    async def _dispatch(self, message: T, container: AsyncContainer) -> None:
+        runtime = await container.get(_InvocationRuntime)
+        entries = await container.get(_EntryInterceptionCatalog)
+        await entries.invoke(
+            runtime,
+            container,
+            self._definition.handler,
+            "handle",
+            (message,),
+            connection_name=_DEFAULT_CONNECTION_NAME,
+        )
+
+    async def _execute(self, delivery: _Delivery[T]) -> None:
+        import anyio
+
+        assert self._bridge is not None and self._runtime is not None
+        # bridge 执行任务不复制消费者/生产者的 ACTION、UoW 或 AnyIO 取消上下文。
+        task = asyncio.create_task(
+            self._bridge.invoke_reserved(delivery.reservation, self._dispatch, delivery.message),
+            context=Context(),
+        )
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            task.cancel()
+            # CancelScope 只请求取消；task 的真实退出才是事务和 finalizer 完成依据。
+            with anyio.CancelScope(shield=True):
+                await task
+            # 处理器处理取消后若正常返回，应保留真实完成事实；下一次 receive 仍会取消。
+        finally:
+            if not delivery.reservation.executing:
+                with anyio.CancelScope(shield=True):
+                    await self._runtime.discard(delivery.reservation)
+
+    async def _consume(self, report: Callable[[BaseException], None]) -> None:
+        import anyio
+
+        assert self._receive is not None and self._runtime is not None
+        try:
+            async with self._receive:
+                async for key in self._receive:
+                    delivery = self._pending.pop(key)
+                    self._active = delivery
+                    delivery.receipt._state = MessageState.PROCESSING
+                    try:
+                        await self._execute(delivery)
+                    except BaseException as error:
+                        state = (
+                            MessageState.CANCELLED
+                            if isinstance(error, asyncio.CancelledError)
+                            else MessageState.FAILED
+                        )
+                        delivery.receipt._finish(state, error)
+                        raise
+                    else:
+                        delivery.receipt._finish(MessageState.COMPLETED)
+                    finally:
+                        self._active = None
+        except BaseException as error:
+            self._failure = error
+            report(error)
+        finally:
+            self._close()
+            with anyio.CancelScope(shield=True):
+                for delivery in self._pending.values():
+                    await self._runtime.discard(delivery.reservation)
+                    delivery.receipt._finish(MessageState.ABORTED, self._failure)
+                self._pending.clear()
+
+    async def _drain_bridge(self, timeout: float) -> None:
+        if self._bridge is not None:
+            await self._bridge.drain(timeout)
+
+    def _require_loop(self) -> None:
+        if self._loop is None:
+            raise MessageRejectedError("closed")
+        if asyncio.get_running_loop() is not self._loop:
+            raise MessageRejectedError("wrong_event_loop")

python_ddd_framework/messaging/contracts.py

@@ -0,0 +1,69 @@
+"""进程内消息声明与处理结果；不提供持久化、事务提交或外部确认契约。"""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Hashable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Generic, TypeVar
+
+from ..modularity import ModuleDeclaration, ModuleDependency, ModuleRef
+
+T = TypeVar("T")
+
+
+class MessageHandler(ABC, Generic[T]):
+    @abstractmethod
+    async def handle(self, message: T) -> None: ...
+
+
+@dataclass(frozen=True)
+class MessageChannelDefinition(ModuleDeclaration, Generic[T]):
+    message_type: type[T]
+    handler: type[MessageHandler[T]]
+    capacity: int = 64
+    snapshot_key: Callable[[T], Hashable] | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.message_type, type):
+            raise TypeError("message_type must be a concrete type")
+        if (
+            not isinstance(self.handler, type)
+            or not issubclass(self.handler, MessageHandler)
+            or inspect.isabstract(self.handler)
+        ):
+            raise TypeError("handler must be a concrete MessageHandler")
+        if type(self.capacity) is not int or self.capacity < 1:
+            raise ValueError("capacity must be a positive integer")
+        if self.snapshot_key is not None and (
+            not callable(self.snapshot_key) or inspect.iscoroutinefunction(self.snapshot_key)
+        ):
+            raise TypeError("snapshot_key must be a synchronous business identity function")
+
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef("python_ddd_framework.messaging.module:MessagingModule")
+
+
+class MessageState(str, Enum):
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    SUPERSEDED = "superseded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    ABORTED = "aborted"
+
+
+@dataclass(frozen=True, slots=True)
+class MessageOutcome:
+    state: MessageState
+    error: BaseException | None = None
+
+
+class MessageRejectedError(RuntimeError):
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"Message not accepted: {reason}")

python_ddd_framework/messaging/module.py

@@ -0,0 +1,101 @@
+"""消息声明、类型化 DI 绑定与消费者生命周期的唯一能力 owner。"""
+
+from collections.abc import Callable
+from typing import cast, get_type_hints
+
+from dishka import DEFAULT_COMPONENT, DependencyKey, Provider, Scope
+
+from ..hosted_services.module import HostedServicesModule
+from ..invocation.interception import InvocationEntry
+from ..invocation.module import InvocationModule
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..modularity.discovery import _require_type_dependencies
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceValidationContext,
+)
+from .channel import MessageChannel
+from .contracts import MessageChannelDefinition, MessageHandler
+from .options import MessagingOptions
+from .runtime import _MessagingRuntime
+
+
+class MessagingModule(AppModule):
+    dependencies = (HostedServicesModule,)
+    _runtime: _MessagingRuntime
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure.default(MessagingOptions, section="messaging")
+        context.services.add_composition(
+            ServiceComposition(bind=self._bind, validate=self._validate)
+        )
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        invocation = context.modules.instance(InvocationModule)
+        definitions = context.modules.declarations(MessageChannelDefinition)
+        channels: dict[type[object], MessageChannel[object]] = {}
+        provider = Provider()
+        for owner, raw_definition in definitions:
+            definition = cast(MessageChannelDefinition[object], raw_definition)
+            if definition.message_type in channels:
+                raise ValueError("A message type must have exactly one channel owner")
+            factory = context.arbitration.single_factory(DependencyKey(definition.handler, ""))
+            if (
+                factory is None
+                or factory.scope is not Scope.ACTION
+                or not factory.cache
+                or not isinstance(factory.source, type)
+                or not issubclass(factory.source, MessageHandler)
+            ):
+                raise TypeError("MessageHandler requires a cached ACTION single class binding")
+            hints = get_type_hints(factory.source.handle)
+            if hints.get("message") is not definition.message_type or hints.get(
+                "return"
+            ) is not type(None):
+                raise TypeError("MessageHandler.handle must declare (message: ChannelType) -> None")
+            contribution = next(
+                item.contribution for item in context.arbitration.drafts if item.factory is factory
+            )
+            _require_type_dependencies(
+                context.modules, contribution.owner, factory.source, source=contribution.source
+            )
+            invocation.entries.append(
+                InvocationEntry(
+                    definition.handler,
+                    "handle",
+                    owner.key,
+                    1,
+                    managed_method=True,
+                )
+            )
+            channel = MessageChannel(definition)
+            channels[definition.message_type] = channel
+            # 闭合泛型 key 来自唯一声明；原生 Provider 唯一拥有 APP 缓存。
+            provider.provide(
+                _channel_factory(channel),
+                # DI key 来自已验证的运行时类型，静态 checker 无法表达该值。
+                provides=MessageChannel[definition.message_type],  # type: ignore[name-defined]
+                scope=Scope.APP,
+            )
+        self._runtime = _MessagingRuntime(
+            tuple(channels.values()), context.options.get(MessagingOptions)
+        )
+        self.runtime = self._runtime.participant()
+        context.add_provider(provider)
+
+    def _validate(self, context: ServiceValidationContext) -> None:
+        for _, definition in context.binding.modules.declarations(MessageChannelDefinition):
+            key = DependencyKey(definition.handler, DEFAULT_COMPONENT)
+            row = next((row for row in context.native_graph if row.key == key), None)
+            if row is None:
+                raise TypeError("MessageHandler has no final single binding")
+            factory = context.native_graph.effective_factory(row)
+            if factory.scope is not Scope.ACTION or not factory.cache:
+                raise TypeError("Final MessageHandler binding must be cached ACTION")
+        self._runtime.container = context.container
+
+
+def _channel_factory(channel: MessageChannel[object]) -> Callable[[], MessageChannel[object]]:
+    return lambda: channel

python_ddd_framework/messaging/options.py

@@ -0,0 +1,13 @@
+"""Host 配置消息消费者的退出期限。"""
+
+from datetime import timedelta
+
+from pydantic import ConfigDict, Field
+
+from ..options import BaseOptions
+
+
+class MessagingOptions(BaseOptions):
+    model_config = ConfigDict(extra="forbid")
+
+    shutdown_timeout: timedelta = Field(default=timedelta(seconds=30), gt=timedelta(0))

python_ddd_framework/messaging/receipt.py

@@ -0,0 +1,27 @@
+"""单次接受回执；观察者取消不撤销已经接受的消息。"""
+
+from .contracts import MessageOutcome, MessageState
+
+
+class MessageReceipt:
+    def __init__(self) -> None:
+        import anyio
+
+        self._state = MessageState.PENDING
+        self._outcome: MessageOutcome | None = None
+        self._done = anyio.Event()
+
+    @property
+    def state(self) -> MessageState:
+        return self._state
+
+    async def wait(self) -> MessageOutcome:
+        await self._done.wait()
+        assert self._outcome is not None
+        return self._outcome
+
+    def _finish(self, state: MessageState, error: BaseException | None = None) -> None:
+        assert self._outcome is None
+        self._state = state
+        self._outcome = MessageOutcome(state, error)
+        self._done.set()

python_ddd_framework/messaging/runtime.py

@@ -0,0 +1,124 @@
+"""消息能力的 Application-local 生命周期；内核只看通用参与者。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable
+from contextvars import Context
+from typing import TYPE_CHECKING
+
+from dishka import AsyncContainer
+
+from ..application_services import ApplicationServiceCatalog
+from ..application_services.invocation import _InvocationRuntime
+from ..errors import ApplicationRuntimeError
+from ..lifecycle import RuntimeParticipant, ShutdownReason
+from .channel import MessageChannel
+from .options import MessagingOptions
+
+if TYPE_CHECKING:
+    import anyio
+
+
+class _MessagingRuntime:
+    def __init__(
+        self, channels: tuple[MessageChannel[object], ...], options: MessagingOptions
+    ) -> None:
+        self.channels = channels
+        self.options = options
+        self.container: AsyncContainer | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._scope: anyio.CancelScope | None = None
+        self._started = asyncio.Event()
+        self._failed = asyncio.Event()
+        self._failures: list[ApplicationRuntimeError] = []
+        self._stopping = False
+        self._enabled = True
+
+    def participant(self) -> RuntimeParticipant:
+        return RuntimeParticipant(
+            prepare=self._prepare,
+            start=self.start,
+            stop=self.stop,
+            close_admission=self.close,
+            ready=self.ready,
+            failure=self.failure,
+        )
+
+    def _prepare(self, enabled: bool) -> None:
+        self._enabled = enabled
+
+    def ready(self) -> bool:
+        return not self._enabled or (
+            self._started.is_set() and not self._failures and not self._stopping
+        )
+
+    async def start(self) -> None:
+        if not self._enabled:
+            return
+        self._task = asyncio.create_task(self._run(), context=Context())
+        await self._started.wait()
+        if self._failures:
+            raise self._failures[0]
+
+    async def _run(self) -> None:
+        import anyio
+
+        try:
+            assert self.container is not None
+            runtime = await self.container.get(_InvocationRuntime)
+            catalog = await self.container.get(ApplicationServiceCatalog)
+            if self._stopping:
+                return
+            async with anyio.create_task_group() as group:
+                self._scope = group.cancel_scope
+                for channel in self.channels:
+                    channel._start(self.container, catalog, runtime)
+                    group.start_soon(channel._consume, self._report)
+                self._started.set()
+        except BaseException as error:
+            self._report(error)
+        finally:
+            self._started.set()
+
+    def _report(self, error: BaseException) -> None:
+        if isinstance(error, asyncio.CancelledError) and self._stopping:
+            if error.__cause__ is None:
+                return
+            # 取消本身是正常的停止请求，但其 cause 中的清理失败仍必须报告。
+            error = error.__cause__
+        self._failures.append(
+            ApplicationRuntimeError(component="messaging", error_type=type(error).__name__)
+        )
+        self._failed.set()
+        self.close()
+
+    def close(self) -> None:
+        for channel in self.channels:
+            channel._close()
+
+    def failure(self) -> Awaitable[ApplicationRuntimeError] | None:
+        return self._wait_failure() if self._enabled else None
+
+    async def _wait_failure(self) -> ApplicationRuntimeError:
+        await self._failed.wait()
+        return self._failures[0]
+
+    async def stop(self, reason: ShutdownReason) -> tuple[BaseException, ...]:
+        import anyio
+
+        self._stopping = True
+        self.close()
+        failures: list[BaseException] = []
+        timeout = self.options.shutdown_timeout.total_seconds()
+        if self._task is not None:
+            with anyio.move_on_after(timeout) as deadline:
+                await asyncio.shield(self._task)
+            if deadline.cancel_called:
+                failures.append(TimeoutError("Message drain deadline exceeded"))
+                if self._scope is not None:
+                    self._scope.cancel()
+                await self._task
+        for channel in self.channels:
+            await channel._drain_bridge(timeout)
+        return (*failures, *self._failures)

python_ddd_framework/modularity/__init__.py

@@ -1,10 +1,19 @@
 """Module contracts、graph builder 与 immutable registry capability。"""
 
-from .contracts import AppModule, ModuleDependency, ModuleDependencyEdge, ModuleKey, ModuleRef
+from .contracts import (
+    AppModule,
+    ModuleDeclaration,
+    ModuleDependency,
+    ModuleDependencyEdge,
+    ModuleKey,
+    ModuleRef,
+    ModuleRequirement,
+)
 from .registry import ModuleDescriptor, ModuleGraphSnapshot, ModuleRegistry
 
 __all__ = (
     "AppModule",
+    "ModuleDeclaration",
     "ModuleDependency",
     "ModuleDependencyEdge",
     "ModuleDescriptor",
@@ -12,4 +21,5 @@ __all__ = (
     "ModuleKey",
     "ModuleRef",
     "ModuleRegistry",
+    "ModuleRequirement",
 )

python_ddd_framework/modularity/contracts.py

@@ -2,18 +2,15 @@
 
 from __future__ import annotations
 
+from abc import ABC, abstractmethod
 from collections.abc import Mapping
 from dataclasses import dataclass
-from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, ClassVar, TypeAlias
+from types import FunctionType, MappingProxyType
+from typing import TYPE_CHECKING, ClassVar, TypeAlias
 
 from ..diagnostics import SourceLocation
 
 if TYPE_CHECKING:
-    from ..background_jobs import BackgroundJobDefinition, BackgroundJobSchedule
-    from ..background_workers import BackgroundWorker, BackgroundWorkerDefinition
-    from ..caching import CacheDefinition
-    from ..hosted_services import HostedService
     from ..lifecycle import (
         ConfigureContext,
         InitializeContext,
@@ -21,10 +18,9 @@ if TYPE_CHECKING:
         PostInitializeContext,
         PreConfigureContext,
         PreInitializeContext,
+        RuntimeParticipant,
         ShutdownContext,
     )
-    from ..notifications import NotificationDefinition
-    from ..settings.handlers import SettingHandlerDefinition
 
 
 @dataclass(frozen=True, slots=True)
@@ -51,20 +47,55 @@ class ModuleDependencyEdge:
     source: SourceLocation
 
 
+class ModuleDeclaration(ABC):
+    """能力拥有的不可变声明；内核只认识其依赖，不解释声明内容。"""
+
+    @property
+    @abstractmethod
+    def required_module(self) -> ModuleDependency:
+        """解释此声明的能力 owner；声明不自动启用该模块。"""
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleRequirement(ModuleDeclaration):
+    """供扫描角色或装饰器携带的依赖事实；ModuleRef 允许契约延迟引用实现模块。"""
+
+    module: ModuleDependency
+
+    @property
+    def required_module(self) -> ModuleDependency:
+        return self.module
+
+
+def _module_declarations(candidate: type[object]) -> dict[str, ModuleDeclaration]:
+    attributes = {
+        name: value for base in reversed(candidate.__mro__) for name, value in vars(base).items()
+    }
+    declarations = {
+        name: value for name, value in attributes.items() if isinstance(value, ModuleDeclaration)
+    }
+    # 方法声明与类声明使用同一依赖权威；内核不识别具体策略或能力名称。
+    for name, value in attributes.items():
+        targets = (
+            (value, value.__func__) if isinstance(value, (staticmethod, classmethod)) else (value,)
+        )
+        for target in targets:
+            if isinstance(target, (FunctionType, staticmethod, classmethod)):
+                declarations.update(
+                    (f"{name}.{attribute}", declaration)
+                    for attribute, declaration in vars(target).items()
+                    if isinstance(declaration, ModuleDeclaration)
+                )
+    return declarations
+
+
 class AppModule:
     """模块 Template Method；每次 Application build 都创建独立实例。"""
 
     dependencies: ClassVar[tuple[type[AppModule] | ModuleRef, ...]] = ()
     scan_packages: ClassVar[tuple[str, ...]] = ()
     configuration_defaults: ClassVar[Mapping[str, object]] = MappingProxyType({})
-    cache_definitions: ClassVar[tuple[CacheDefinition[Any], ...]] = ()
-    setting_handler_definitions: ClassVar[tuple[SettingHandlerDefinition[Any], ...]] = ()
-    notification_definitions: ClassVar[tuple[NotificationDefinition[Any], ...]] = ()
-    background_worker_definitions: ClassVar[tuple[BackgroundWorkerDefinition, ...]] = ()
-    background_workers: ClassVar[tuple[type[BackgroundWorker], ...]] = ()
-    background_job_definitions: ClassVar[tuple[BackgroundJobDefinition[Any], ...]] = ()
-    background_job_schedules: ClassVar[tuple[BackgroundJobSchedule, ...]] = ()
-    hosted_services: ClassVar[tuple[type[HostedService], ...]] = ()
+    runtime: RuntimeParticipant | None = None
 
     def pre_configure(self, context: PreConfigureContext) -> None:
         pass