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

python_ddd_framework/invocation/dispatcher.py

@@ -0,0 +1,291 @@
+"""受管理服务代理与业务管线编排；不拥有 Application admission 或 Session。"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from dishka import AsyncContainer
+from dishka.exceptions import NoFactoryError
+
+from ..application_services.errors import (
+    ApplicationServiceValidationError,
+    ApplicationServiceValidationIssue,
+    CrossTaskInvocationError,
+    NestedConnectionError,
+)
+from ..application_services.invocation import _current_task, _InvocationRuntime
+from ..auditing import ApplicationServiceAuditRecord, AuditSink
+from ..auditing.control import AuditingControl, AuditingOptions
+from ..authorization import AuthorizationOptions, PermissionChecker
+from ..authorization.contracts import _AuthorizationRequirement
+from ..authorization.errors import (
+    PermissionCheckerUnavailableError,
+    PermissionDeniedError,
+    UnauthenticatedError,
+)
+from ..invocation.arguments import _validate_arguments
+from ..invocation.execution import _InterceptorPipeline
+from ..invocation.interceptors import InterceptionStage
+from ..observability.context import invocation_span
+from ..options import Options
+from ..unit_of_work import UnitOfWorkManager
+from .methods import _CompiledMethod
+
+_LOGGER = logging.getLogger(__name__)
+
+_MethodTarget = Callable[[AsyncContainer, tuple[object, ...], dict[str, object]], Awaitable[object]]
+
+
+class _MethodDispatcher:
+    """共享调用阶段；实例解析和 HTTP 身份由对应入口拥有。"""
+
+    __slots__ = ("_auditing_enabled", "_container", "_runtime", "_unit_of_work_enabled")
+
+    def __init__(
+        self,
+        container: AsyncContainer,
+        runtime: _InvocationRuntime,
+        *,
+        unit_of_work_enabled: bool = True,
+        auditing_enabled: bool = True,
+    ) -> None:
+        self._container = container
+        self._runtime = runtime
+        self._unit_of_work_enabled = unit_of_work_enabled
+        self._auditing_enabled = auditing_enabled
+
+    async def invoke_method(
+        self,
+        method: _CompiledMethod,
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+        target: _MethodTarget,
+        connection_name: str,
+    ) -> object:
+        pipeline = _InterceptorPipeline(method.descriptor, method.interceptor_steps, args, kwargs)
+        return await self._invoke_entry(
+            method,
+            pipeline,
+            lambda: self._invoke_validated(method, pipeline, target, connection_name),
+        )
+
+    async def _invoke_validated(
+        self,
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+        target: _MethodTarget,
+        connection_name: str,
+    ) -> object:
+        async def validate() -> object:
+            await self._validate_pipeline(method, pipeline)
+            return await pipeline.run(
+                InterceptionStage.UNIT_OF_WORK,
+                self._container,
+                lambda: self._invoke_work(method, pipeline, target, connection_name),
+            )
+
+        return await pipeline.run(InterceptionStage.VALIDATION, self._container, validate)
+
+    async def _invoke_work(
+        self,
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+        target: _MethodTarget,
+        connection_name: str,
+    ) -> object:
+        async def invoke(container: AsyncContainer) -> object:
+            async def execute() -> object:
+                # METHOD 扩展改写参数后仍须通过同一个验证边界。
+                await self._validate_pipeline(method, pipeline)
+                return await target(container, pipeline.arguments.args, pipeline.arguments.kwargs)
+
+            result = await pipeline.run(InterceptionStage.METHOD, container, execute)
+            return (
+                method.result_adapter.validate_python(result) if method.result_adapter else result
+            )
+
+        ambient = self._runtime.current()
+        if ambient is not None:
+            if _current_task() is not ambient.owner_task:
+                raise CrossTaskInvocationError
+            if connection_name != ambient.context.connection_name:
+                raise NestedConnectionError(
+                    outer=ambient.context.connection_name, requested=connection_name
+                )
+            if not self._unit_of_work_enabled:
+                return await invoke(ambient.action_container)
+            manager = await self._container.get(UnitOfWorkManager)
+            if method.descriptor.unit_of_work.disabled:
+                manager._check_current(connection_name)
+                return await invoke(ambient.action_container)
+            options = manager._resolve_options(
+                connection_name, method.descriptor.unit_of_work, method.name
+            )
+            async with manager._begin(options) as work:
+                result = await invoke(ambient.action_container)
+                await work.complete()
+                return result
+        return await self._runtime.run_action(
+            self._container,
+            connection_name=connection_name,
+            callback=invoke,
+            declaration=method.descriptor.unit_of_work,
+            method_name=method.name,
+            unit_of_work_enabled=self._unit_of_work_enabled,
+        )
+
+    async def _invoke_entry(
+        self,
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+        callback: Callable[[], Awaitable[object]],
+        *,
+        defer_audit: Callable[[Callable[[BaseException | None], Awaitable[None]]], None]
+        | None = None,
+    ) -> object:
+        async def authorize() -> object:
+            await self._authorize(method.authorization)
+            return await callback()
+
+        async def audit() -> object:
+            occurred_at = datetime.now(UTC)
+            started_ns = time.perf_counter_ns()
+            failure: BaseException | None = None
+            try:
+                return await pipeline.run(
+                    InterceptionStage.AUTHORIZATION, self._container, authorize
+                )
+            except BaseException as error:
+                failure = error
+                raise
+            finally:
+
+                async def write(final_failure: BaseException | None) -> None:
+                    await self._write_audit(
+                        method,
+                        occurred_at=occurred_at,
+                        duration_ns=time.perf_counter_ns() - started_ns,
+                        failure=final_failure,
+                    )
+
+                if defer_audit is not None:
+                    defer_audit(write)
+                else:
+                    await write(failure)
+
+        async def trace() -> object:
+            with invocation_span(self._runtime.tracer, method.contract_method.__qualname__):
+                return await pipeline.run(InterceptionStage.AUDITING, self._container, audit)
+
+        return await pipeline.run(InterceptionStage.TRACING, self._container, trace)
+
+    @staticmethod
+    async def _validate_pipeline(
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+    ) -> None:
+        arguments = pipeline.arguments
+        if not arguments.needs_validation:
+            return
+        if method.descriptor.validation_enabled:
+            arguments.args, arguments.kwargs = await _validate_arguments(
+                method, arguments.args, arguments.kwargs
+            )
+        else:
+            # 可选类型验证关闭后，必需参数与参数名仍属于公开调用契约。
+            try:
+                method.signature.bind(None, *arguments.args, **arguments.kwargs)
+            except TypeError:
+                raise ApplicationServiceValidationError(
+                    service=method.descriptor.service,
+                    method_name=method.name,
+                    issues=(
+                        ApplicationServiceValidationIssue(
+                            location=(), error_type="arguments", message="Invalid method arguments"
+                        ),
+                    ),
+                ) from None
+        arguments.mark_validated()
+
+    async def _write_audit(
+        self,
+        method: _CompiledMethod,
+        *,
+        occurred_at: datetime,
+        duration_ns: int,
+        failure: BaseException | None,
+    ) -> None:
+        if not self._auditing_enabled or not method.descriptor.auditing_enabled:
+            return
+        options = (await self._container.get(Options[AuditingOptions])).value
+        control = await self._container.get(AuditingControl)
+        if not options.is_enabled or not control.is_enabled:
+            return
+        try:
+            sink = await self._container.get(AuditSink)
+        except NoFactoryError:
+            return
+        except Exception as audit_error:
+            _LOGGER.error(
+                "application service audit write failed",
+                exc_info=audit_error,
+                extra={
+                    "audit_exception_type": type(audit_error).__name__,
+                    "audit_contract": method.descriptor.service.__qualname__,
+                    "audit_method": method.name,
+                },
+            )
+            return
+        try:
+            current_user = self._runtime.current_user()
+            correlation_id = self._runtime.correlation_id() or str(uuid4())
+            await sink.write_application_service(
+                ApplicationServiceAuditRecord(
+                    occurred_at=occurred_at,
+                    user_id=current_user.user_id,
+                    session_id=current_user.session_id,
+                    correlation_id=correlation_id,
+                    contract=(
+                        f"{method.descriptor.service.__module__}.{method.descriptor.service.__qualname__}"
+                    ),
+                    method=method.name,
+                    succeeded=failure is None,
+                    duration_ns=duration_ns,
+                    exception_type=None if failure is None else type(failure).__name__,
+                )
+            )
+        except Exception as audit_error:
+            # sink resolution/context/write 都属于独立观测边界；失败不能覆盖业务结果。
+            _LOGGER.error(
+                "application service audit write failed",
+                exc_info=audit_error,
+                extra={
+                    "audit_exception_type": type(audit_error).__name__,
+                    "audit_contract": method.descriptor.service.__qualname__,
+                    "audit_method": method.name,
+                },
+            )
+
+    async def _authorize(self, requirement: _AuthorizationRequirement) -> None:
+        if requirement.allows_anonymous or not requirement.requires_authenticated_user:
+            return
+        # 所有受管理入口共用此阶段；放行不改变认证器或 CurrentUser。
+        options = await self._container.get(Options[AuthorizationOptions])
+        if options.value.always_allow:
+            return
+        current_user = self._runtime.current_user()
+        if not current_user.is_authenticated:
+            raise UnauthenticatedError
+        if not requirement.permissions:
+            return
+        try:
+            checker = await self._container.get(PermissionChecker)
+        except NoFactoryError:
+            raise PermissionCheckerUnavailableError from None
+        for permission in requirement.permissions:
+            if not await checker.is_granted(current_user, permission):
+                raise PermissionDeniedError(permission=str(permission))

python_ddd_framework/invocation/entries.py

@@ -2,37 +2,14 @@
 
 from __future__ import annotations
 
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable
 from typing import cast
 
-from dishka import AsyncContainer, BaseScope, Scope
+from dishka import AsyncContainer, BaseScope
 
-from ..background_jobs import BackgroundJobCatalog
-from ..background_workers import BackgroundWorkerCatalog
-from ..events import LocalEventCatalog, LocalEventPhase
 from .callables import _CallablePlan
 
 
-def _validate_callable_entries(
-    container: AsyncContainer,
-    jobs: BackgroundJobCatalog,
-    workers: BackgroundWorkerCatalog,
-    events: LocalEventCatalog,
-    *,
-    event_implementations: Mapping[type[object], type[object]],
-) -> None:
-    for job in jobs.definitions:
-        _validate_entry(container, job.handler_type, "execute", 2, Scope.ACTION)
-    for worker in workers.definitions:
-        _validate_entry(container, worker.worker_type, "run_iteration", 1, Scope.ACTION)
-    for subscription in events.subscriptions:
-        scope = Scope.ACTION if subscription.phase is LocalEventPhase.DOMAIN else Scope.REQUEST
-        target = subscription.handler_type
-        if isinstance(target, type):
-            target = event_implementations[target]
-        _validate_entry(container, target, "handle", 1, scope)
-
-
 def _validate_entry(
     container: AsyncContainer,
     target: type[object] | Callable[..., Awaitable[None]],

python_ddd_framework/invocation/entrypoints.py

@@ -0,0 +1,126 @@
+"""Host 的正式调用入口；作用域和服务解析始终复用 Application 的原生容器。"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Concatenate, ParamSpec, TypeVar, cast
+from uuid import uuid4
+
+from ..application import Application
+from ..application_services import (
+    ApplicationInvocationRejectedError,
+    ApplicationServiceContract,
+)
+from ..application_services.invocation import _InvocationRuntime, _ScopedApplicationServiceInvoker
+from ..authorization import CurrentUser
+from ..lifecycle import ApplicationState
+from .function_runtime import _invoke_callable
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+_TContract = TypeVar("_TContract", bound=ApplicationServiceContract)
+
+
+async def call(
+    application: Application,
+    function: Callable[..., Awaitable[_R]],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> _R:
+    if application.state not in (ApplicationState.STARTING, ApplicationState.RUNNING):
+        raise ApplicationInvocationRejectedError(
+            reason=f"Application must be running, got {application.state.value}",
+        )
+    runtime = await application._container_for_integration().get(_InvocationRuntime)
+    return await call_as(application, runtime.current_user(), function, *args, **kwargs)
+
+
+async def call_as(
+    application: Application,
+    current_user: CurrentUser,
+    function: Callable[..., Awaitable[_R]],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> _R:
+    if application.state not in (ApplicationState.STARTING, ApplicationState.RUNNING):
+        raise ApplicationInvocationRejectedError(
+            reason=f"Application must be running, got {application.state.value}",
+        )
+    container = application._container_for_integration()
+    runtime = await container.get(_InvocationRuntime)
+    return await _invoke_callable(
+        container,
+        runtime,
+        current_user,
+        str(uuid4()),
+        function,
+        args,
+        kwargs,
+    )
+
+
+async def invoke(
+    application: Application,
+    method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+    /,
+    *args: _P.args,
+    **kwargs: _P.kwargs,
+) -> _R:
+    return await invoke_as(application, CurrentUser.anonymous(), method, *args, **kwargs)
+
+
+async def invoke_as(
+    application: Application,
+    current_user: CurrentUser,
+    method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+    /,
+    *args: _P.args,
+    **kwargs: _P.kwargs,
+) -> _R:
+    if application.state not in (ApplicationState.STARTING, ApplicationState.RUNNING):
+        raise ApplicationInvocationRejectedError(
+            reason=f"Application must be running, got {application.state.value}",
+        )
+    container = application._container_for_integration()
+    invoker = await container.get(_ScopedApplicationServiceInvoker)
+    result = await invoker.invoke(
+        container,
+        current_user,
+        str(uuid4()),
+        cast(Callable[..., Awaitable[object]], method),
+        cast(tuple[object, ...], args),
+        cast(dict[str, object], kwargs),
+    )
+    return cast(_R, result)
+
+
+@asynccontextmanager
+async def invocation_lease(application: Application) -> AsyncIterator[None]:
+    runtime = await application._container_for_integration().get(_InvocationRuntime)
+    async with runtime.outer_lease():
+        yield
+
+
+@asynccontextmanager
+async def http_request_lease(application: Application) -> AsyncIterator[None]:
+    runtime = await application._container_for_integration().get(_InvocationRuntime)
+    # composed/pre-start 健康探测仍参与 drain，业务调用的 RUNNING 限制由 dispatcher 保证。
+    async with runtime.outer_lease(allow_composed_request=True):
+        yield
+
+
+@asynccontextmanager
+async def caller_context(
+    application: Application,
+    current_user: CurrentUser,
+    correlation_id: str,
+) -> AsyncIterator[None]:
+    runtime = await application._container_for_integration().get(_InvocationRuntime)
+    token = runtime.bind_caller(current_user, correlation_id)
+    try:
+        yield
+    finally:
+        runtime.reset_caller(token)

python_ddd_framework/{application_services → invocation}/execution.py

@@ -12,8 +12,11 @@ from uuid import UUID
 from dishka import AsyncContainer
 from pydantic import BaseModel
 
-from .catalog import ApplicationServiceMethod
-from .errors import ApplicationInvocationRejectedError, CrossTaskInvocationError
+from ..application_services.errors import (
+    ApplicationInvocationRejectedError,
+    CrossTaskInvocationError,
+)
+from ..invocation.methods import ServiceMethod
 from .interceptors import InterceptionStage, InterceptorRegistration
 
 _ARGUMENT_SNAPSHOT_MAX_DEPTH = 64
@@ -22,7 +25,7 @@ _ARGUMENT_SNAPSHOT_MAX_DEPTH = 64
 class _InterceptorPipeline:
     def __init__(
         self,
-        method: ApplicationServiceMethod,
+        method: ServiceMethod,
         steps: Mapping[InterceptionStage, tuple[InterceptorRegistration, ...]],
         args: tuple[object, ...],
         kwargs: dict[str, object],
@@ -155,7 +158,7 @@ class MethodInvocation:
 
     def __init__(
         self,
-        method: ApplicationServiceMethod,
+        method: ServiceMethod,
         arguments: _InvocationArguments,
         continuation: Callable[[], Awaitable[object]],
     ) -> None:
@@ -167,7 +170,7 @@ class MethodInvocation:
         self._active = True
 
     @property
-    def method(self) -> ApplicationServiceMethod:
+    def method(self) -> ServiceMethod:
         return self._method
 
     @property

python_ddd_framework/invocation/function_runtime.py

@@ -26,6 +26,8 @@ async def _invoke_callable(
     args: tuple[object, ...],
     kwargs: dict[str, object],
 ) -> _R:
+    from ..application_services.invocation import _managed_request
+
     async with runtime.outer_lease():
         ambient = runtime.current()
         existing = ambient.action_container if ambient is not None else runtime.current_call_scope()
@@ -41,7 +43,7 @@ async def _invoke_callable(
         token = runtime.bind_caller(current_user, correlation_id)
         try:
             plan = _CallablePlan.compile(function, container, Scope.REQUEST)
-            async with container(scope=Scope.REQUEST) as request:
+            async with _managed_request(container) as request:
                 with runtime.call_scope(request):
                     return await plan.invoke(function, request, args, kwargs)
         finally: