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

python_ddd_framework/hosted_services/bridge.py

@@ -8,6 +8,7 @@ import functools
 import inspect
 import threading
 from collections.abc import Awaitable, Callable
+from contextvars import Context
 from dataclasses import dataclass, field
 from typing import Concatenate, ParamSpec, TypeVar, cast
 from uuid import uuid4
@@ -15,10 +16,12 @@ from uuid import uuid4
 from dishka import AsyncContainer
 
 from ..application_services import ApplicationServiceCatalog, ApplicationServiceContract
+from ..application_services.errors import ApplicationInvocationRejectedError
 from ..application_services.invocation import (
     _InvocationReservation,
     _InvocationRuntime,
     _ScopedApplicationServiceInvoker,
+    _StoppingPermission,
 )
 from ..authorization import CurrentUser
 from ..invocation.contracts import _is_safe_correlation_id
@@ -33,6 +36,7 @@ _TContract = TypeVar("_TContract", bound=ApplicationServiceContract)
 @dataclass(slots=True)
 class _PendingInvocation:
     external_future: concurrent.futures.Future[object] | None
+    reservation: _InvocationReservation
     task: asyncio.Task[object] | None = None
 
 
@@ -48,6 +52,8 @@ class _HostedServiceBridge:
         "_loop",
         "_name",
         "_pending",
+        "_runtime",
+        "_stopping_owners",
     )
 
     def __init__(
@@ -58,6 +64,8 @@ class _HostedServiceBridge:
         container: AsyncContainer,
         catalog: ApplicationServiceCatalog,
         limit: int,
+        runtime: _InvocationRuntime,
+        stopping_owners: tuple[type[object], ...] = (),
     ) -> None:
         self._name = name
         self._loop = loop
@@ -67,6 +75,8 @@ class _HostedServiceBridge:
         self._lock = threading.RLock()
         self._pending: dict[object, _PendingInvocation] = {}
         self._accepting = False
+        self._runtime = runtime
+        self._stopping_owners = stopping_owners
 
     def open(self) -> None:
         with self._lock:
@@ -84,18 +94,25 @@ class _HostedServiceBridge:
         kwargs: dict[str, object],
         *,
         callable_entry: bool = False,
+        permission: _StoppingPermission | None = None,
     ) -> _R:
         operation = "invoke"
         self._require_application_loop(operation)
         self._validate_call(operation, correlation_id, method, callable_entry=callable_entry)
         token = object()
         with self._lock:
-            self._admit(token, operation, external_future=None)
+            self._admit(token, operation, permission=permission)
             task = asyncio.create_task(
-                self._invoke_pipeline(
-                    correlation_id, method, args, kwargs, callable_entry=callable_entry
+                self._invoke_accepted(
+                    self._pending[token].reservation,
+                    correlation_id,
+                    method,
+                    args,
+                    kwargs,
+                    callable_entry=callable_entry,
                 ),
                 name=f"python-ddd-framework-hosted-service-invoke:{self._name}",
+                context=Context(),
             )
             self._pending[token].task = task
             task.add_done_callback(functools.partial(self._release_task, token))
@@ -109,24 +126,26 @@ class _HostedServiceBridge:
         kwargs: dict[str, object],
         *,
         callable_entry: bool = False,
+        permission: _StoppingPermission | None = None,
     ) -> concurrent.futures.Future[_R]:
         operation = "submit"
         self._require_external_thread(operation)
         self._validate_call(operation, correlation_id, method, callable_entry=callable_entry)
         token = object()
         with self._lock:
-            self._admit(token, operation, external_future=None)
+            self._admit(token, operation, permission=permission)
             invocation = self._invoke_submitted(
                 token, correlation_id, method, args, kwargs, callable_entry=callable_entry
             )
             try:
-                external = asyncio.run_coroutine_threadsafe(
+                external = Context().run(
+                    asyncio.run_coroutine_threadsafe,
                     invocation,
                     self._loop,
                 )
             except RuntimeError:
                 invocation.close()
-                self._pending.pop(token, None)
+                self._release_pending(token)
                 raise HostedServiceInvocationRejectedError(
                     service=self._name,
                     operation=operation,
@@ -185,9 +204,11 @@ class _HostedServiceBridge:
         token: object,
         operation: str,
         *,
-        external_future: concurrent.futures.Future[object] | None,
+        permission: _StoppingPermission | None,
     ) -> None:
-        if not self._accepting:
+        if (permission is None and not self._accepting) or (
+            permission is not None and permission.owner not in self._stopping_owners
+        ):
             raise HostedServiceInvocationRejectedError(
                 service=self._name,
                 operation=operation,
@@ -199,7 +220,13 @@ class _HostedServiceBridge:
                 operation=operation,
                 error_type="CapacityExceeded",
             )
-        self._pending[token] = _PendingInvocation(external_future=external_future)
+        try:
+            reservation = self._runtime.reserve(permission)
+        except ApplicationInvocationRejectedError:
+            raise HostedServiceInvocationRejectedError(
+                service=self._name, operation=operation, error_type="NotAccepting"
+            ) from None
+        self._pending[token] = _PendingInvocation(None, reservation)
 
     async def _invoke_submitted(
         self,
@@ -218,18 +245,28 @@ class _HostedServiceBridge:
             assert pending is not None
             pending.task = cast(asyncio.Task[object], task)
         try:
-            return await self._invoke_pipeline(
-                correlation_id, method, args, kwargs, callable_entry=callable_entry
+            return await self._invoke_accepted(
+                pending.reservation,
+                correlation_id,
+                method,
+                args,
+                kwargs,
+                callable_entry=callable_entry,
             )
         finally:
             # concurrent Future 可先进入 cancelled；只有 loop Task finalizer 完成才释放容量。
             with self._lock:
-                self._pending.pop(token, None)
+                self._release_pending(token)
 
     def _release_task(self, token: object, task: asyncio.Task[object]) -> None:
         del task
         with self._lock:
-            self._pending.pop(token, None)
+            self._release_pending(token)
+
+    def _release_pending(self, token: object) -> None:
+        pending = self._pending.pop(token, None)
+        if pending is not None and not pending.reservation.executing:
+            self._runtime.release_reservation(pending.reservation)
 
     def _observe_external_completion(
         self,
@@ -269,7 +306,22 @@ class _HostedServiceBridge:
                 and pending.task is None
                 and external.cancelled()
             ):
-                self._pending.pop(token, None)
+                self._release_pending(token)
+
+    async def _invoke_accepted(
+        self,
+        reservation: _InvocationReservation,
+        correlation_id: str,
+        method: Callable[..., Awaitable[object]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+        *,
+        callable_entry: bool,
+    ) -> object:
+        async with self._runtime.reserved_lease(reservation):
+            return await self._invoke_pipeline(
+                correlation_id, method, args, kwargs, callable_entry=callable_entry
+            )
 
     async def _invoke_pipeline(
         self,
@@ -370,6 +422,7 @@ class HostedServiceContext:
 
     name: str
     _bridge: _HostedServiceBridge = field(repr=False, compare=False)
+    _permission: _StoppingPermission | None = field(default=None, repr=False, compare=False)
 
     async def call(
         self,
@@ -378,7 +431,9 @@ class HostedServiceContext:
         *args: object,
         **kwargs: object,
     ) -> _R:
-        return await self._bridge.invoke(str(uuid4()), function, args, kwargs, callable_entry=True)
+        return await self._bridge.invoke(
+            str(uuid4()), function, args, kwargs, callable_entry=True, permission=self._permission
+        )
 
     def submit_call(
         self,
@@ -388,7 +443,9 @@ class HostedServiceContext:
         **kwargs: object,
     ) -> concurrent.futures.Future[_R]:
         """外部线程继续经过同一 admission/drain bridge，不直接接触异步容器。"""
-        return self._bridge.submit(str(uuid4()), function, args, kwargs, callable_entry=True)
+        return self._bridge.submit(
+            str(uuid4()), function, args, kwargs, callable_entry=True, permission=self._permission
+        )
 
     async def invoke(
         self,
@@ -412,6 +469,7 @@ class HostedServiceContext:
             method,
             cast(tuple[object, ...], args),
             cast(dict[str, object], kwargs),
+            permission=self._permission,
         )
 
     def submit(
@@ -436,4 +494,5 @@ class HostedServiceContext:
             method,
             cast(tuple[object, ...], args),
             cast(dict[str, object], kwargs),
+            permission=self._permission,
         )

python_ddd_framework/hosted_services/contracts.py

@@ -27,6 +27,10 @@ class HostedService(ABC):
     async def start(self, context: HostedServiceContext) -> None:
         raise NotImplementedError
 
+    async def stopping(self, context: HostedServiceContext, reason: ShutdownReason) -> None:
+        """在依赖仍存活时发起业务收尾并等待回调；context 只在本钩子内有效。"""
+        return None
+
     @abstractmethod
     async def stop(self, reason: ShutdownReason) -> None:
         raise NotImplementedError
@@ -52,7 +56,7 @@ def _validate_service_type(candidate: type[HostedService]) -> None:
         )
     if inspect.isabstract(candidate):
         raise HostedServiceDefinitionError(service=name, reason="service type must be concrete")
-    for operation in ("start", "stop"):
+    for operation in ("start", "stopping", "stop"):
         if not inspect.iscoroutinefunction(getattr(candidate, operation, None)):
             raise HostedServiceDefinitionError(
                 service=name, reason=f"{operation} must use async def"

python_ddd_framework/hosted_services/runtime.py

@@ -10,6 +10,7 @@ from typing import cast
 from dishka import AsyncContainer
 
 from ..application_services import ApplicationServiceCatalog
+from ..application_services.invocation import _InvocationRuntime
 from ..lifecycle import ApplicationState, RuntimeParticipant, ShutdownReason
 from .bridge import HostedServiceContext, _HostedServiceBridge
 from .catalog import HostedServiceCatalog, HostedServiceRegistration
@@ -25,6 +26,8 @@ class _HostedServiceEntry:
     service: HostedService
     context: HostedServiceContext
     bridge: _HostedServiceBridge
+    started: bool = False
+    failed: bool = False
 
 
 class _HostedServiceCoordinator:
@@ -97,7 +100,10 @@ class _HostedServiceCoordinator:
             prepare=prepare,
             start=start,
             stop=self.stop,
+            quiesce=self.close_admission,
+            stopping=self.stopping,
             close_admission=self.close_admission,
+            drain=self.drain,
             ready=lambda: self.readiness().ready,
         )
 
@@ -126,6 +132,7 @@ class _HostedServiceCoordinator:
         if container is None or application_service_catalog is None:
             raise RuntimeError("Hosted Service coordinator container is unavailable")
         self._started = True
+        runtime = await container.get(_InvocationRuntime)
         for registration in self._registrations:
             self._state_owner.set_status(registration.name, HostedServiceStatus.STARTING)
             try:
@@ -150,17 +157,55 @@ class _HostedServiceCoordinator:
                 container=container,
                 catalog=application_service_catalog,
                 limit=self._options.max_pending_invocations,
+                runtime=runtime,
+                stopping_owners=(registration.service_type,),
             )
             context = HostedServiceContext(registration.name, bridge)
             entry = _HostedServiceEntry(registration, resolved, context, bridge)
             self._entries.append(entry)
             bridge.open()
             await self._start_entry(entry)
+            entry.started = True
 
     def close_admission(self) -> None:
         for entry in self._entries:
             entry.bridge.close()
 
+    async def stopping(self, reason: ShutdownReason) -> tuple[BaseException, ...]:
+        failures: list[BaseException] = []
+        for entry in reversed(self._entries):
+            self._state_owner.set_status(entry.registration.name, HostedServiceStatus.STOPPING)
+            if not entry.started:
+                continue
+            assert self._container is not None
+            runtime = await self._container.get(_InvocationRuntime)
+            permission = runtime.grant_stopping(entry.registration.service_type)
+            context = HostedServiceContext(entry.registration.name, entry.bridge, permission)
+            try:
+                failure = await self._stop_entry(entry, reason, context=context)
+            except BaseException as error:
+                failures.append(error)
+                entry.failed = True
+            else:
+                if failure is not None:
+                    failures.append(failure)
+                    entry.failed = True
+            finally:
+                runtime.revoke_stopping(permission)
+        return tuple(failures)
+
+    async def drain(self) -> None:
+        outcomes = await asyncio.gather(
+            *(
+                entry.bridge.drain(self._options.shutdown_timeout.total_seconds())
+                for entry in self._entries
+            ),
+            return_exceptions=True,
+        )
+        failures = tuple(item for item in outcomes if isinstance(item, BaseException))
+        if failures:
+            raise BaseExceptionGroup("Hosted Service invocation drain failed", failures)
+
     async def stop(
         self,
         reason: ShutdownReason,
@@ -176,19 +221,14 @@ class _HostedServiceCoordinator:
             if failure is not None:
                 failures.append(failure)
 
-        if self._entries:
-            await asyncio.gather(
-                *(
-                    entry.bridge.drain(self._options.shutdown_timeout.total_seconds())
-                    for entry in self._entries
-                )
-            )
         failed_names = {failure.service for failure in failures}
         for entry in self._entries:
             name = entry.registration.name
             self._state_owner.set_status(
                 name,
-                HostedServiceStatus.FAILED if name in failed_names else HostedServiceStatus.STOPPED,
+                HostedServiceStatus.FAILED
+                if name in failed_names or entry.failed
+                else HostedServiceStatus.STOPPED,
             )
         self._started = False
         return tuple(failures)
@@ -253,18 +293,29 @@ class _HostedServiceCoordinator:
         self,
         entry: _HostedServiceEntry,
         reason: ShutdownReason,
+        *,
+        context: HostedServiceContext | None = None,
     ) -> HostedServiceLifecycleError | None:
         name = entry.registration.name
-        callback = cast(
-            Callable[[ShutdownReason], Awaitable[object]],
-            entry.service.stop,
-        )
+        operation = "stopping" if context is not None else "stop"
 
         async def invoke_stop() -> object:
-            return await callback(reason)
+            if context is None:
+                callback = cast(Callable[[ShutdownReason], Awaitable[object]], entry.service.stop)
+                return await callback(reason)
+            stopping_callback = cast(
+                Callable[[HostedServiceContext, ShutdownReason], Awaitable[object]],
+                entry.service.stopping,
+            )
+            try:
+                return await stopping_callback(context, reason)
+            finally:
+                # 返回和失败都在用户钩子的 task 内撤权，不留下一轮调度的准入窗口。
+                assert context._permission is not None
+                context._permission.runtime.revoke_stopping(context._permission)
 
         stop_task = asyncio.create_task(
-            invoke_stop(), name=f"python-ddd-framework-hosted-service-stop:{name}"
+            invoke_stop(), name=f"python-ddd-framework-hosted-service-{operation}:{name}"
         )
         done, _ = await asyncio.wait(
             (stop_task,), timeout=self._options.shutdown_timeout.total_seconds()
@@ -272,25 +323,28 @@ class _HostedServiceCoordinator:
         timed_out = not done
         if timed_out:
             # 取消只是一项请求。实现可能在 finally 中异步释放 SDK 资源；完成前不能释放容器。
+            if context is not None:
+                assert context._permission is not None
+                context._permission.runtime.revoke_stopping(context._permission)
             stop_task.cancel()
         try:
             result = await stop_task
         except BaseException as original_error:
             return HostedServiceLifecycleError(
                 service=name,
-                operation="stop",
+                operation=operation,
                 error_type="TimeoutError"
                 if timed_out and isinstance(original_error, asyncio.CancelledError)
                 else type(original_error).__name__,
             )
         if timed_out:
             return HostedServiceLifecycleError(
-                service=name, operation="stop", error_type="TimeoutError"
+                service=name, operation=operation, error_type="TimeoutError"
             )
         if result is not None:
             return HostedServiceLifecycleError(
                 service=name,
-                operation="stop",
+                operation=operation,
                 error_type="InvalidReturnValue",
             )
         return None

python_ddd_framework/lifecycle/participants.py

@@ -16,6 +16,8 @@ class RuntimeParticipant:
     ready: Callable[[], bool] | None = None
     failure: Callable[[], Awaitable[ApplicationRuntimeError] | None] | None = None
     drain: Callable[[], Awaitable[None]] | None = None
+    quiesce: Callable[[], None] | None = None
+    stopping: Callable[[ShutdownReason], Awaitable[tuple[BaseException, ...]]] | None = None
 
     def __post_init__(self) -> None:
         if not callable(self.start) or not callable(self.stop):
@@ -28,6 +30,8 @@ class RuntimeParticipant:
                 self.ready,
                 self.failure,
                 self.drain,
+                self.quiesce,
+                self.stopping,
             )
         ):
             raise TypeError("runtime callbacks must be callable")

python_ddd_framework/messaging/channel.py

@@ -38,9 +38,11 @@ class MessageChannel(Generic[T]):
 
     def __init__(self, definition: MessageChannelDefinition[T]) -> None:
         self._definition = definition
+        self._stopping_owners = definition.stopping_owners
         self._pending: dict[Hashable, _Delivery[T]] = {}
         self._active: _Delivery[T] | None = None
         self._accepting = False
+        self._closed = True
         self._failure: BaseException | None = None
         self._context: HostedServiceContext | None = None
         self._bridge: _HostedServiceBridge | None = None
@@ -49,16 +51,24 @@ class MessageChannel(Generic[T]):
         self._send: MemoryObjectSendStream[Hashable] | None = None
         self._receive: MemoryObjectReceiveStream[Hashable] | None = None
 
-    async def send(self, message: T) -> MessageReceipt:
+    async def send(
+        self, message: T, *, stopping: HostedServiceContext | None = None
+    ) -> MessageReceipt:
         """返回只表示接受；本入口无等待发送者、无后台发送 task。"""
         self._require_loop()
         if self._failure is not None:
             raise MessageRejectedError("consumer_failed")
-        if not self._accepting:
+        if self._closed or (stopping is None and not self._accepting):
             raise MessageRejectedError("closed")
         assert self._runtime is not None
+        permission = stopping._permission if stopping is not None else None
         try:
-            self._runtime.require_accepting_work()
+            if stopping is None:
+                self._runtime.require_accepting_work()
+            elif permission is not None and permission.owner in self._stopping_owners:
+                self._runtime.require_stopping(permission)
+            else:
+                raise MessageRejectedError("closed")
         except ApplicationInvocationRejectedError:
             raise MessageRejectedError("closed") from None
         if not isinstance(message, self._definition.message_type):
@@ -76,18 +86,24 @@ class MessageChannel(Generic[T]):
             raise MessageRejectedError("capacity_exceeded")
         assert self._runtime is not None and self._send is not None
         # 接受与许可预留在同一 loop turn 完成；slot 的许可随最终快照转交，不携带 scope。
-        reservation = self._runtime.reserve()
+        reservation = self._runtime.reserve(permission)
         self._pending[key] = _Delivery(message, receipt, reservation)
         self._send.send_nowait(key)
         return receipt
 
-    def submit(self, message: T) -> concurrent.futures.Future[MessageReceipt]:
+    def submit(
+        self, message: T, *, stopping: HostedServiceContext | None = None
+    ) -> concurrent.futures.Future[MessageReceipt]:
         """外部线程入口；bridge pending 上限等于通道容量，Future 结果才表示接受。"""
         context = self._context
         if context is None:
             raise MessageRejectedError("closed")
+        if stopping is not None:
+            if stopping._permission is None:
+                raise MessageRejectedError("closed")
+            context = HostedServiceContext(context.name, context._bridge, stopping._permission)
         # to_thread 可能复制生产者的 ContextVar；线程交接只传消息值，不传调用 scope。
-        return Context().run(context.submit_call, self.send, message)
+        return Context().run(context.submit_call, self.send, message, stopping=stopping)
 
     def _start(
         self,
@@ -110,17 +126,28 @@ class MessageChannel(Generic[T]):
             container=container,
             catalog=catalog,
             limit=self._definition.capacity,
+            runtime=runtime,
+            stopping_owners=self._stopping_owners,
         )
         self._context = HostedServiceContext(
             self._definition.message_type.__qualname__, self._bridge
         )
         self._bridge.open()
         self._accepting = True
+        self._closed = False
 
-    def _close(self) -> None:
+    def _quiesce(self) -> None:
         self._accepting = False
         if self._bridge is not None:
             self._bridge.close()
+
+    def _assert_unchanged(self) -> None:
+        if self._definition.stopping_owners != self._stopping_owners:
+            raise TypeError("Message stopping owners changed after build")
+
+    def _close(self) -> None:
+        self._quiesce()
+        self._closed = True
         if self._send is not None:
             # 发送端仅由此 owner 持有，不向生产者暴露 clone；因此关闭即关闭全部发送端。
             self._send.close()

python_ddd_framework/messaging/contracts.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Generic, TypeVar
 
+from ..hosted_services.contracts import HostedService
 from ..modularity import ModuleDeclaration, ModuleDependency, ModuleRef
 
 T = TypeVar("T")
@@ -25,8 +26,16 @@ class MessageChannelDefinition(ModuleDeclaration, Generic[T]):
     handler: type[MessageHandler[T]]
     capacity: int = 64
     snapshot_key: Callable[[T], Hashable] | None = None
+    stopping_owners: tuple[type[HostedService], ...] = ()
 
     def __post_init__(self) -> None:
+        if not isinstance(self.stopping_owners, tuple) or any(
+            not isinstance(owner, type) or not issubclass(owner, HostedService)
+            for owner in self.stopping_owners
+        ):
+            raise TypeError("stopping_owners must be an immutable tuple of HostedService types")
+        if len(set(self.stopping_owners)) != len(self.stopping_owners):
+            raise ValueError("stopping_owners must not contain duplicates")
         if not isinstance(self.message_type, type):
             raise TypeError("message_type must be a concrete type")
         if (

python_ddd_framework/messaging/module.py

@@ -35,10 +35,23 @@ class MessagingModule(AppModule):
     def _bind(self, context: ServiceBindingContext) -> None:
         invocation = context.modules.instance(InvocationModule)
         definitions = context.modules.declarations(MessageChannelDefinition)
+        hosted = context.modules.instance(HostedServicesModule).catalog
         channels: dict[type[object], MessageChannel[object]] = {}
         provider = Provider()
         for owner, raw_definition in definitions:
             definition = cast(MessageChannelDefinition[object], raw_definition)
+            for service_type in definition.stopping_owners:
+                registration = next(
+                    (item for item in hosted.registrations if item.service_type is service_type),
+                    None,
+                )
+                if registration is None:
+                    raise TypeError("stopping owner must be declared in HostedServiceCatalog")
+                context.modules.require_dependency(
+                    owner.key,
+                    context.modules[registration.owner].module_type,
+                    source=owner.declaration_source,
+                )
             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, ""))

python_ddd_framework/messaging/runtime.py

@@ -40,12 +40,16 @@ class _MessagingRuntime:
             prepare=self._prepare,
             start=self.start,
             stop=self.stop,
+            quiesce=self.quiesce,
             close_admission=self.close,
+            drain=self.drain,
             ready=self.ready,
             failure=self.failure,
         )
 
     def _prepare(self, enabled: bool) -> None:
+        for channel in self.channels:
+            channel._assert_unchanged()
         self._enabled = enabled
 
     def ready(self) -> bool:
@@ -97,6 +101,11 @@ class _MessagingRuntime:
         for channel in self.channels:
             channel._close()
 
+    def quiesce(self) -> None:
+        self._stopping = True
+        for channel in self.channels:
+            channel._quiesce()
+
     def failure(self) -> Awaitable[ApplicationRuntimeError] | None:
         return self._wait_failure() if self._enabled else None
 
@@ -105,6 +114,10 @@ class _MessagingRuntime:
         return self._failures[0]
 
     async def stop(self, reason: ShutdownReason) -> tuple[BaseException, ...]:
+        self.close()
+        return ()
+
+    async def drain(self) -> None:
         import anyio
 
         self._stopping = True
@@ -121,4 +134,6 @@ class _MessagingRuntime:
                 await self._task
         for channel in self.channels:
             await channel._drain_bridge(timeout)
-        return (*failures, *self._failures)
+        failures.extend(self._failures)
+        if failures:
+            raise BaseExceptionGroup("Message drain failed", failures)