python-ddd-framework 0.4.0__py3-none-any.whl → 0.6.0__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,14 +16,12 @@ from uuid import uuid4
 from dishka import AsyncContainer
 
 from ..application_services import ApplicationServiceCatalog, ApplicationServiceContract
-from ..application_services.invocation import (
-    _InvocationReservation,
-    _InvocationRuntime,
-    _ScopedApplicationServiceInvoker,
-)
+from ..application_services.errors import ApplicationInvocationRejectedError
+from ..application_services.invocation import _ScopedApplicationServiceInvoker
 from ..authorization import CurrentUser
 from ..invocation.contracts import _is_safe_correlation_id
 from ..invocation.function_runtime import _invoke_callable
+from ..invocation.runtime import _InvocationReservation, _InvocationRuntime, _StoppingPermission
 from .errors import HostedServiceInvocationRejectedError
 
 _P = ParamSpec("_P")
@@ -33,6 +32,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 +48,8 @@ class _HostedServiceBridge:
         "_loop",
         "_name",
         "_pending",
+        "_runtime",
+        "_stopping_owners",
     )
 
     def __init__(
@@ -58,6 +60,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 +71,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 +90,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 +122,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 +200,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 +216,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 +241,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 +302,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 +418,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 +427,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 +439,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 +465,7 @@ class HostedServiceContext:
             method,
             cast(tuple[object, ...], args),
             cast(dict[str, object], kwargs),
+            permission=self._permission,
         )
 
     def submit(
@@ -436,4 +490,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 ..invocation.runtime 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/identity/__init__.py

@@ -3,26 +3,17 @@ from .application import (
 )
 from .contracts import (
     IDENTITY_ROLES_MANAGE,
-    IDENTITY_USER_EXTENSION,
     IDENTITY_USERS_MANAGE,
     AuthenticationApplicationService,
+    IdentityManagementApplicationService,
+)
+from .dtos import (
     ChangePasswordCommand,
     CreateRoleCommand,
     CreateUserCommand,
     CurrentUserView,
-    IdentityAccessStore,
     IdentityConcurrencyCommand,
-    IdentityLoginStore,
-    IdentityManagementApplicationService,
-    IdentityOptions,
-    IdentityRepository,
-    IdentityRole,
-    IdentityUser,
     LoginCommand,
-    RefreshRotationResult,
-    RefreshRotationStatus,
-    RefreshSession,
-    RefreshSessionStore,
     RefreshTokenCommand,
     RevokeTokenCommand,
     RolePermissionsView,
@@ -43,10 +34,26 @@ from .errors import (
     IdentityResourceNotFoundError,
     InvalidCredentialsError,
 )
+from .extensions import IDENTITY_USER_EXTENSION
 from .management import DefaultIdentityManagementApplicationService
+from .models import (
+    IdentityRole,
+    IdentityUser,
+    RefreshRotationResult,
+    RefreshRotationStatus,
+    RefreshSession,
+)
 from .module import IdentityModule
+from .options import IdentityOptions
 from .passwords import PasswordHasher
 from .services import IdentityAuthenticator
+from .stores import (
+    IdentityAccessStore,
+    IdentityCredentialStore,
+    IdentityLoginStore,
+    IdentityManagementStore,
+    RefreshSessionStore,
+)
 from .tokens import JwtTokenService
 
 __all__ = (
@@ -64,12 +71,13 @@ __all__ = (
     "IdentityAuthenticator",
     "IdentityConcurrencyCommand",
     "IdentityConflictError",
+    "IdentityCredentialStore",
     "IdentityDefinitionError",
     "IdentityLoginStore",
     "IdentityManagementApplicationService",
+    "IdentityManagementStore",
     "IdentityModule",
     "IdentityOptions",
-    "IdentityRepository",
     "IdentityResourceNotFoundError",
     "IdentityRole",
     "IdentityUser",

python_ddd_framework/identity/application.py

@@ -1,4 +1,4 @@
-"""Identity Application Services：认证、refresh family 与管理员业务编排。"""
+"""Identity 登录、令牌与当前用户认证流程。"""
 
 from __future__ import annotations
 
@@ -8,34 +8,27 @@ from uuid import UUID, uuid4
 from ..application_services import ApplicationService, application_service
 from ..authorization import (
     CurrentUser,
-    PermissionCatalog,
     allow_anonymous,
     authorize,
 )
 from ..options import Options
-from ..seeding.contracts import DataSeedContributor
-from .contracts import (
-    AuthenticationApplicationService,
+from .contracts import AuthenticationApplicationService
+from .domain_rules import _normalize_name
+from .dtos import (
     ChangePasswordCommand,
     CurrentUserView,
-    IdentityLoginStore,
-    IdentityOptions,
-    IdentityRepository,
-    IdentityRole,
-    IdentityUser,
     LoginCommand,
-    RefreshRotationStatus,
-    RefreshSession,
-    RefreshSessionStore,
     RefreshTokenCommand,
     RevokeTokenCommand,
     TokenPair,
-    _normalize_name,
 )
 from .errors import (
     InvalidCredentialsError,
 )
+from .models import RefreshRotationStatus, RefreshSession
+from .options import IdentityOptions
 from .passwords import PasswordHasher
+from .stores import IdentityCredentialStore, IdentityLoginStore, RefreshSessionStore
 from .tokens import (
     BEARER_TOKEN_TYPE,
     JwtTokenService,
@@ -54,7 +47,7 @@ class DefaultAuthenticationApplicationService(ApplicationService):
         passwords: PasswordHasher,
         tokens: JwtTokenService,
         current_user: CurrentUser,
-        repository: IdentityRepository,
+        credentials: IdentityCredentialStore,
         options: Options[IdentityOptions],
     ) -> None:
         self._login_store = login_store
@@ -62,7 +55,7 @@ class DefaultAuthenticationApplicationService(ApplicationService):
         self._passwords = passwords
         self._tokens = tokens
         self._current_user = current_user
-        self._repository = repository
+        self._credentials = credentials
         self._options = options.value
 
     @allow_anonymous
@@ -137,7 +130,7 @@ class DefaultAuthenticationApplicationService(ApplicationService):
             session_id=self._current_user.session_id,
             username=self._current_user.username,
             concurrency_version=(
-                await self._repository.get_user(self._current_user.user_id)
+                await self._credentials.get_user(self._current_user.user_id)
             ).concurrency_version,
         )
 
@@ -145,7 +138,7 @@ class DefaultAuthenticationApplicationService(ApplicationService):
         user_id = self._current_user.user_id
         if user_id is None:
             raise InvalidCredentialsError
-        user = await self._repository.get_user(user_id)
+        user = await self._credentials.get_user(user_id)
         verified, _ = await self._passwords.verify(
             command.old_password.get_secret_value(), user.password_hash
         )
@@ -153,7 +146,7 @@ class DefaultAuthenticationApplicationService(ApplicationService):
             raise InvalidCredentialsError
         password_hash = await self._passwords.hash(command.new_password.get_secret_value())
         # Hash 在线程计算；写入时重新核对版本及旧 hash，拒绝计算期间的凭据竞争。
-        await self._repository.set_password(
+        await self._credentials.set_password(
             user_id,
             password_hash,
             command.concurrency_version,
@@ -175,53 +168,6 @@ class DefaultAuthenticationApplicationService(ApplicationService):
         )
 
 
-class IdentityAdminSeedContributor(DataSeedContributor):
-    def __init__(
-        self,
-        repository: IdentityRepository,
-        passwords: PasswordHasher,
-        permissions: PermissionCatalog,
-        options: Options[IdentityOptions],
-    ) -> None:
-        self._repository = repository
-        self._passwords = passwords
-        self._permissions = permissions
-        self._options = options.value
-
-    async def seed(self) -> None:
-        username = self._options.seed_admin_username
-        password = self._options.seed_admin_password
-        if username is None or password is None:
-            return
-        normalized_username = _normalize_name(username, role="seed administrator username")
-        user = await self._repository.find_user_by_normalized_username(normalized_username)
-        if user is None:
-            user = IdentityUser(
-                uuid4(),
-                username.strip(),
-                normalized_username,
-                await self._passwords.hash(password.get_secret_value()),
-                True,
-                0,
-                None,
-                0,
-            )
-            await self._repository.create_user(user)
-        normalized_role = "administrator"
-        role = await self._repository.find_role_by_normalized_name(normalized_role)
-        if role is None:
-            role = IdentityRole(uuid4(), "Administrator", normalized_role, 0)
-            await self._repository.create_role(role)
-        await self._repository.set_role_permissions(
-            role.role_id,
-            tuple(item.name.value for item in self._permissions.definitions),
-            role.concurrency_version,
-        )
-        await self._repository.set_user_roles(
-            user.user_id, (role.role_id,), user.concurrency_version
-        )
-
-
 def _new_session(user_id: UUID, refresh_token: str, *, now: datetime) -> RefreshSession:
     family_id = uuid4()
     return RefreshSession(