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

python_ddd_framework/fastapi/realtime/runtime.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import asyncio
 import logging
-from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import cast
 from uuid import UUID, uuid4
@@ -17,14 +16,14 @@ from ...authorization import AccessTokenAuthenticator, CurrentUser, Unauthentica
 from ...options import Options
 from ...realtime import (
     RealtimeDeliveryReport,
-    RealtimeEnvelope,
+    RealtimeMessage,
     RealtimePublisher,
     RealtimeSnapshot,
 )
-from ...realtime.messages import _encode_envelope
+from ...realtime.messages import _encode_envelope, _message_envelope
 from .connection import (
-    _FRAMEWORK_PROBLEM_MESSAGE_TYPE,
     WebSocketConnection,
+    _FrameworkProblemMessage,
     _WebSocketCloseCode,
 )
 from .options import FastApiRealtimeOptions
@@ -212,21 +211,17 @@ class _FastApiRealtimeRuntime:
     async def send_to_connection(
         self,
         connection_id: UUID,
-        *,
-        message_type: str,
-        payload: Mapping[str, object],
+        message: RealtimeMessage,
     ) -> RealtimeDeliveryReport:
         async with self._lock:
             state = self._connections.get(connection_id)
         states = () if state is None else (state,)
-        return await self._send(states, message_type=message_type, payload=payload)
+        return await self._send(states, message)
 
     async def send_to_user(
         self,
         user_id: UUID,
-        *,
-        message_type: str,
-        payload: Mapping[str, object],
+        message: RealtimeMessage,
     ) -> RealtimeDeliveryReport:
         async with self._lock:
             connection_ids = tuple(self._user_connections.get(user_id, ()))
@@ -235,7 +230,7 @@ class _FastApiRealtimeRuntime:
                 for connection_id in connection_ids
                 if (state := self._connections.get(connection_id)) is not None
             )
-        return await self._send(states, message_type=message_type, payload=payload)
+        return await self._send(states, message)
 
     async def snapshot(self) -> RealtimeSnapshot:
         async with self._lock:
@@ -277,18 +272,10 @@ class _FastApiRealtimeRuntime:
     async def _send(
         self,
         states: tuple[_ConnectionState, ...],
-        *,
-        message_type: str,
-        payload: Mapping[str, object],
+        message: RealtimeMessage,
     ) -> RealtimeDeliveryReport:
         correlation_id = self._invocations.correlation_id() or str(uuid4())
-        text = _encode_envelope(
-            RealtimeEnvelope(
-                message_type=message_type,
-                correlation_id=correlation_id,
-                payload=payload,
-            )
-        )
+        text = _encode_envelope(_message_envelope(message, correlation_id))
         if not states:
             return RealtimeDeliveryReport(matched=0, enqueued=0, dropped=0)
         enqueued = 0
@@ -327,8 +314,7 @@ class _FastApiRealtimeRuntime:
     ) -> RealtimeDeliveryReport:
         return await self._send(
             (state,),
-            message_type=_FRAMEWORK_PROBLEM_MESSAGE_TYPE,
-            payload={"code": code, "status": status},
+            _FrameworkProblemMessage(code=code, status=status),
         )
 
     async def _request_close(

python_ddd_framework/fastapi/request_context.py

@@ -26,6 +26,7 @@ from ..application_services.invocation import (
 from ..auditing import AuditSink, RequestAuditRecord
 from ..authorization import AccessTokenAuthenticator, CurrentUser, UnauthenticatedError
 from ..invocation.contracts import _is_safe_correlation_id
+from ..invocation.entrypoints import http_request_lease
 from ..unit_of_work import UnitOfWorkManager
 from .errors import FastApiAdapterError
 
@@ -46,7 +47,7 @@ class _RequestScopeMiddleware:
         if scope["type"] != "http":
             await self._other(scope, receive, send)
             return
-        async with self._application._http_request_lease_for_integration():
+        async with http_request_lease(self._application):
             request = Request(scope, receive, send)
             container = self._application._container_for_integration()(
                 {Request: request}, scope=DIScope.REQUEST

python_ddd_framework/fastapi/routing.py

@@ -15,6 +15,7 @@ from fastapi.routing import APIRoute, APIWebSocketRoute, RouteContext, iter_rout
 from starlette.routing import BaseRoute, WebSocketRoute
 
 from ..application import Application
+from ..authorization.module import AuthorizationModule
 from ..diagnostics import SourceLocation
 from ..modularity import ModuleKey
 from .application_services import (
@@ -111,7 +112,7 @@ def _build_route_plan(
                 unknown = tuple(
                     permission
                     for permission in route._definition.authorization.permissions
-                    if permission not in application.permission_catalog
+                    if permission not in application.modules.instance(AuthorizationModule).catalog
                 )
                 if unknown:
                     raise FastApiAdapterError(

python_ddd_framework/fastapi/server.py

@@ -14,6 +14,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from uvicorn import Config, Server
+from uvicorn.supervisors.statreload import StatReload
 
 if TYPE_CHECKING:
     from uvicorn.supervisors.basereload import BaseReload as ChangeReload
@@ -125,12 +126,19 @@ class _HostReload(ChangeReload):
                 self.shutdown()
 
     def restart(self) -> None:
+        # 接管进程退出仍须保留原生 StatReload 的 mtime 重置；否则同一次修改会循环重启。
+        if isinstance(self, StatReload):
+            self.mtimes.clear()
         # 旧进程尚未退出就一直占位；不靠超时／PID 猜测，更不强杀后立即补位。
+        logger = logging.getLogger(__name__)
+        logger.info("Host reload requesting shutdown of process %s", self.process.pid)
         self._shutdown_requested.set()
         self.process.join()
+        logger.info("Host reload previous process %s exited", self.process.pid)
         self._shutdown_requested.clear()
         # 原生 startup 仍负责 spawn、信号接线和 socket 传递，不复制进程创建实现。
         self.startup()
+        logger.info("Host reload spawned replacement process %s", self.process.pid)
 
     def shutdown(self) -> None:
         self._shutdown_requested.set()

python_ddd_framework/fastapi/settings.py

@@ -4,6 +4,7 @@ from ..modularity import AppModule
 from ..settings.management import SettingsManagementApplicationService
 from ..settings.module import SettingsManagementModule
 from . import ApplicationServiceRouteOverride, exposes_application_services
+from .module import FastApiModule
 
 
 @exposes_application_services(
@@ -37,4 +38,4 @@ from . import ApplicationServiceRouteOverride, exposes_application_services
     ),
 )
 class SettingsManagementHttpApiModule(AppModule):
-    dependencies = (SettingsManagementModule,)
+    dependencies = (FastApiModule,)

python_ddd_framework/hosted_services/bridge.py

@@ -15,7 +15,11 @@ from uuid import uuid4
 from dishka import AsyncContainer
 
 from ..application_services import ApplicationServiceCatalog, ApplicationServiceContract
-from ..application_services.invocation import _InvocationRuntime, _ScopedApplicationServiceInvoker
+from ..application_services.invocation import (
+    _InvocationReservation,
+    _InvocationRuntime,
+    _ScopedApplicationServiceInvoker,
+)
 from ..authorization import CurrentUser
 from ..invocation.contracts import _is_safe_correlation_id
 from ..invocation.function_runtime import _invoke_callable
@@ -297,6 +301,21 @@ class _HostedServiceBridge:
             kwargs,
         )
 
+    async def invoke_reserved(
+        self,
+        reservation: _InvocationReservation,
+        function: Callable[..., Awaitable[_R]],
+        *args: object,
+    ) -> _R:
+        """兑现已接受工作的单次许可；不重新开放 bridge/public admission。"""
+        self._require_application_loop("invoke_reserved")
+        runtime = await self._container.get(_InvocationRuntime)
+        async with runtime.reserved_lease(reservation):
+            return cast(
+                _R,
+                await self._invoke_pipeline(str(uuid4()), function, args, {}, callable_entry=True),
+            )
+
     def _validate_call(
         self,
         operation: str,

python_ddd_framework/hosted_services/catalog.py

@@ -12,8 +12,9 @@ from typing import TYPE_CHECKING
 from dishka import DEFAULT_COMPONENT, DependencyKey, Provider, Scope
 
 from ..diagnostics import SourceLocation
-from ..modularity import AppModule, ModuleKey, ModuleRegistry
+from ..modularity import ModuleKey, ModuleRegistry
 from .contracts import HostedService, _validate_service_type
+from .declarations import HostedServices
 from .errors import HostedServiceContractError, HostedServiceDefinitionError
 
 if TYPE_CHECKING:
@@ -36,19 +37,16 @@ class HostedServiceRegistration:
 class HostedServiceCatalog:
     """顺序来自 Module dependency order 与各 Module 的声明顺序。"""
 
-    __slots__ = ("_by_name", "_declarations", "_fingerprint", "_registrations")
+    __slots__ = ("_by_name", "_fingerprint", "_registrations")
 
     def __init__(
         self,
         registrations: tuple[HostedServiceRegistration, ...],
-        *,
-        declarations: tuple[tuple[type[AppModule], tuple[type[HostedService], ...]], ...],
     ) -> None:
         self._registrations = registrations
         self._by_name: Mapping[str, HostedServiceRegistration] = MappingProxyType(
             {item.name: item for item in registrations}
         )
-        self._declarations = declarations
         encoded = json.dumps(
             [
                 {
@@ -100,26 +98,18 @@ class HostedServiceCatalog:
                     service=item.name,
                     reason="HostedService process metadata changed after build",
                 )
-        for module_type, declared in self._declarations:
-            if module_type.__dict__.get("hosted_services", ()) is not declared:
-                raise HostedServiceDefinitionError(
-                    service=f"{module_type.__module__}.{module_type.__qualname__}",
-                    reason="Module hosted_services metadata changed after build",
-                )
 
 
 def _build_hosted_service_catalog(registry: ModuleRegistry) -> HostedServiceCatalog:
     registrations: list[HostedServiceRegistration] = []
-    declarations: list[tuple[type[AppModule], tuple[type[HostedService], ...]]] = []
     names: dict[str, ModuleKey] = {}
-    for descriptor in registry.dependency_order:
-        declared = descriptor.module_type.__dict__.get("hosted_services", ())
+    for descriptor, declaration in registry.declarations(HostedServices):
+        declared = declaration.services
         if not isinstance(declared, tuple):
             raise HostedServiceDefinitionError(
                 service=str(descriptor.key),
                 reason="Module hosted_services must be an immutable tuple",
             )
-        declarations.append((descriptor.module_type, declared))
         for declaration_index, candidate in enumerate(declared):
             _validate_service_type(candidate)
             name = f"{candidate.__module__}.{candidate.__qualname__}"
@@ -140,7 +130,7 @@ def _build_hosted_service_catalog(registry: ModuleRegistry) -> HostedServiceCata
                     run_in_background_processes=candidate.run_in_background_processes,
                 )
             )
-    return HostedServiceCatalog(tuple(registrations), declarations=tuple(declarations))
+    return HostedServiceCatalog(tuple(registrations))
 
 
 def _contribute_hosted_service_defaults(

python_ddd_framework/hosted_services/contracts.py

@@ -7,6 +7,8 @@ from abc import ABC, abstractmethod
 from enum import Enum
 from typing import TYPE_CHECKING, ClassVar
 
+from dishka import Scope
+
 from .errors import HostedServiceDefinitionError
 
 if TYPE_CHECKING:
@@ -17,6 +19,8 @@ if TYPE_CHECKING:
 class HostedService(ABC):
     """APP 单例；start 返回即启动成功，stop 必须等待自身资源退出。"""
 
+    _fixed_service_scope: ClassVar[Scope] = Scope.APP
+
     run_in_background_processes: ClassVar[bool] = False
 
     @abstractmethod

python_ddd_framework/hosted_services/declarations.py

@@ -0,0 +1,15 @@
+"""托管服务声明；顺序属于声明模块，解释和运行状态属于能力模块。"""
+
+from dataclasses import dataclass
+
+from ..modularity import ModuleDeclaration, ModuleDependency, ModuleRef
+from .contracts import HostedService
+
+
+@dataclass(frozen=True, slots=True)
+class HostedServices(ModuleDeclaration):
+    services: tuple[type[HostedService], ...]
+
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef("python_ddd_framework.hosted_services.module:HostedServicesModule")

python_ddd_framework/hosted_services/module.py

@@ -0,0 +1,69 @@
+"""托管服务配置、最终绑定与运行状态的模块 owner。"""
+
+from dishka import Provider, Scope
+
+from ..application_services.module import ApplicationServicesModule
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceDiscoveryContext,
+    ServiceValidationContext,
+)
+from .catalog import (
+    HostedServiceCatalog,
+    _build_hosted_service_catalog,
+    _contribute_hosted_service_defaults,
+    _validate_hosted_service_drafts,
+    _validate_hosted_service_entries,
+)
+from .options import HOSTED_SERVICE_OPTIONS_SECTION, HostedServiceOptions
+from .runtime import _HostedServiceCoordinator
+
+
+class HostedServicesModule(AppModule):
+    dependencies = (ApplicationServicesModule,)
+    catalog: HostedServiceCatalog
+    coordinator: _HostedServiceCoordinator
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure.default(HostedServiceOptions, section=HOSTED_SERVICE_OPTIONS_SECTION)
+        context.services.add_composition(
+            ServiceComposition(
+                discover=self._discover,
+                before_binding=lambda entries: _validate_hosted_service_entries(
+                    entries, self.catalog
+                ),
+                bind=self._bind,
+                validate=self._validate,
+            )
+        )
+
+    def _discover(self, context: ServiceDiscoveryContext) -> None:
+        self.catalog = _build_hosted_service_catalog(context.modules)
+        _contribute_hosted_service_defaults(self.catalog, context.services)
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        _validate_hosted_service_drafts(context.arbitration.drafts, self.catalog)
+        application = context.application
+        self.coordinator = _HostedServiceCoordinator(
+            catalog=self.catalog,
+            options=context.options.get(HostedServiceOptions),
+            state_getter=lambda: application.state,
+        )
+        self.runtime = self.coordinator.runtime_participant()
+        provider = Provider()
+        provider.provide(lambda: self.catalog, provides=HostedServiceCatalog, scope=Scope.APP)
+        provider.provide(
+            lambda: self.coordinator,
+            provides=_HostedServiceCoordinator,
+            scope=Scope.APP,
+        )
+        context.add_provider(provider)
+
+    def _validate(self, context: ServiceValidationContext) -> None:
+        self.coordinator.attach_container(
+            context.container,
+            context.binding.modules.instance(ApplicationServicesModule).catalog,
+        )

python_ddd_framework/hosted_services/runtime.py

@@ -10,7 +10,7 @@ from typing import cast
 from dishka import AsyncContainer
 
 from ..application_services import ApplicationServiceCatalog
-from ..lifecycle import ApplicationState, ShutdownReason
+from ..lifecycle import ApplicationState, RuntimeParticipant, ShutdownReason
 from .bridge import HostedServiceContext, _HostedServiceBridge
 from .catalog import HostedServiceCatalog, HostedServiceRegistration
 from .contracts import HostedService, HostedServiceStatus
@@ -72,6 +72,35 @@ class _HostedServiceCoordinator:
     def readiness(self) -> ApplicationReadinessSnapshot:
         return self._state_owner.snapshot(self._state_getter())
 
+    def runtime_participant(self) -> RuntimeParticipant:
+        enabled = True
+
+        def prepare(run_services: bool) -> None:
+            nonlocal enabled
+            enabled = run_services
+
+        async def start() -> None:
+            if not enabled:
+                return
+            try:
+                await self.start()
+            except HostedServiceLifecycleError:
+                raise
+            except BaseException as error:
+                raise HostedServiceLifecycleError(
+                    service=type(self).__qualname__,
+                    operation="start",
+                    error_type=type(error).__name__,
+                ) from error
+
+        return RuntimeParticipant(
+            prepare=prepare,
+            start=start,
+            stop=self.stop,
+            close_admission=self.close_admission,
+            ready=lambda: self.readiness().ready,
+        )
+
     def select_child(self) -> None:
         if self._started:
             raise RuntimeError("Hosted Service process selection must precede start")

python_ddd_framework/identity/__init__.py

@@ -1,11 +1,17 @@
+from .application import (
+    DefaultAuthenticationApplicationService,
+)
 from .contracts import (
     IDENTITY_ROLES_MANAGE,
+    IDENTITY_USER_EXTENSION,
     IDENTITY_USERS_MANAGE,
     AuthenticationApplicationService,
+    ChangePasswordCommand,
     CreateRoleCommand,
     CreateUserCommand,
     CurrentUserView,
     IdentityAccessStore,
+    IdentityConcurrencyCommand,
     IdentityLoginStore,
     IdentityManagementApplicationService,
     IdentityOptions,
@@ -19,10 +25,16 @@ from .contracts import (
     RefreshSessionStore,
     RefreshTokenCommand,
     RevokeTokenCommand,
+    RolePermissionsView,
     RoleView,
+    SetPasswordCommand,
     SetRolePermissionsCommand,
+    SetUserActiveCommand,
     SetUserRolesCommand,
     TokenPair,
+    UpdateRoleCommand,
+    UpdateUserCommand,
+    UserRolesView,
     UserView,
 )
 from .errors import (
@@ -31,6 +43,7 @@ from .errors import (
     IdentityResourceNotFoundError,
     InvalidCredentialsError,
 )
+from .management import DefaultIdentityManagementApplicationService
 from .module import IdentityModule
 from .passwords import PasswordHasher
 from .services import IdentityAuthenticator
@@ -39,12 +52,17 @@ from .tokens import JwtTokenService
 __all__ = (
     "IDENTITY_ROLES_MANAGE",
     "IDENTITY_USERS_MANAGE",
+    "IDENTITY_USER_EXTENSION",
     "AuthenticationApplicationService",
+    "ChangePasswordCommand",
     "CreateRoleCommand",
     "CreateUserCommand",
     "CurrentUserView",
+    "DefaultAuthenticationApplicationService",
+    "DefaultIdentityManagementApplicationService",
     "IdentityAccessStore",
     "IdentityAuthenticator",
+    "IdentityConcurrencyCommand",
     "IdentityConflictError",
     "IdentityDefinitionError",
     "IdentityLoginStore",
@@ -65,9 +83,15 @@ __all__ = (
     "RefreshSessionStore",
     "RefreshTokenCommand",
     "RevokeTokenCommand",
+    "RolePermissionsView",
     "RoleView",
+    "SetPasswordCommand",
     "SetRolePermissionsCommand",
+    "SetUserActiveCommand",
     "SetUserRolesCommand",
     "TokenPair",
+    "UpdateRoleCommand",
+    "UpdateUserCommand",
+    "UserRolesView",
     "UserView",
 )