python-platform 0.1.1__py3-none-any.whl

python_platform/application_services/dispatcher.py

@@ -0,0 +1,423 @@
+"""受管理服务代理与业务管线编排；不拥有 Application admission 或 Session。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, cast
+from uuid import uuid4
+
+from dishka import AsyncContainer
+from dishka.exceptions import NoFactoryError
+
+from ..auditing import ApplicationServiceAuditRecord, AuditSink
+from ..auditing.control import AuditingControl, AuditingOptions
+from ..authorization import PermissionChecker
+from ..authorization.contracts import _AuthorizationRequirement
+from ..authorization.errors import (
+    PermissionCheckerUnavailableError,
+    PermissionDeniedError,
+    UnauthenticatedError,
+)
+from ..observability.context import invocation_span
+from ..options import Options
+from ..settings.provider import SettingProvider
+from ..unit_of_work import UnitOfWorkManager
+from .catalog import (
+    _APPLICATION_SERVICE_COMPONENT,
+    ApplicationServiceCatalog,
+    ApplicationServiceRegistration,
+    _CompiledApplicationService,
+    _CompiledMethod,
+)
+from .contracts import ApplicationService
+from .errors import (
+    ApplicationServiceValidationError,
+    ApplicationServiceValidationIssue,
+    CrossTaskInvocationError,
+    NestedConnectionError,
+)
+from .execution import _InterceptorPipeline
+from .interceptors import InterceptionStage
+from .invocation import _current_task, _InvocationRuntime
+from .validation import _validate_arguments
+
+_LOGGER = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass(slots=True)
+class _HttpInvocationState:
+    service: _CompiledApplicationService
+    method: _CompiledMethod
+    owner_task: asyncio.Task[object]
+    pipeline: _InterceptorPipeline
+    consumed: bool = False
+    is_short_circuited: Callable[[], bool] = lambda: False
+    defer_audit: Callable[[Callable[[BaseException | None], Awaitable[None]]], None] | None = None
+
+
+class _ApplicationServiceProxy:
+    """REQUEST-local Protocol object；只把 cataloged method 转交给统一 dispatcher。"""
+
+    __slots__ = ("_dispatcher", "_service")
+
+    def __init__(
+        self,
+        dispatcher: _ApplicationServiceDispatcher,
+        service: _CompiledApplicationService,
+    ) -> None:
+        self._dispatcher = dispatcher
+        self._service = service
+
+    def __getattr__(self, name: str) -> object:
+        method = self._service.methods.get(name)
+        if method is None:
+            raise AttributeError(name)
+
+        async def invoke(*args: object, **kwargs: object) -> object:
+            return await self._dispatcher.invoke(self._service, method, args, kwargs)
+
+        return invoke
+
+
+class _ApplicationServiceDispatcher:
+    """所有 caller 共用的 validation、ownership、UoW 与 event 顺序 owner。"""
+
+    __slots__ = ("_catalog", "_container", "_http_boundary", "_runtime")
+
+    def __init__(
+        self,
+        container: AsyncContainer,
+        runtime: _InvocationRuntime,
+        catalog: ApplicationServiceCatalog,
+    ) -> None:
+        self._container = container
+        self._runtime = runtime
+        self._catalog = catalog
+        self._http_boundary: ContextVar[_HttpInvocationState | None] = ContextVar(
+            f"python_platform_http_invocation_{runtime.application_id}_{id(self)}",
+            default=None,
+        )
+
+    async def invoke(
+        self,
+        service: _CompiledApplicationService,
+        method: _CompiledMethod,
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+    ) -> object:
+        pipeline = _InterceptorPipeline(method.descriptor, method.interceptor_steps, args, kwargs)
+        async with self._runtime.outer_lease():
+            return await self._invoke_entry(
+                service,
+                method,
+                pipeline,
+                lambda: self._invoke_after_authorization(service, method, pipeline),
+            )
+
+    async def _invoke_entry(
+        self,
+        service: _CompiledApplicationService,
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+        callback: Callable[[], Awaitable[object]],
+    ) -> object:
+        async def authorize() -> object:
+            if not service.registration.is_integration_service:
+                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(
+                        service.registration,
+                        method,
+                        occurred_at=occurred_at,
+                        duration_ns=time.perf_counter_ns() - started_ns,
+                        failure=final_failure,
+                    )
+
+                boundary = self._http_boundary.get()
+                if (
+                    boundary is not None
+                    and boundary.pipeline is pipeline
+                    and boundary.defer_audit is not None
+                ):
+                    boundary.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)
+
+    async def invoke_http_request(
+        self,
+        service: _CompiledApplicationService,
+        method: _CompiledMethod,
+        callback: Callable[[], Awaitable[object]],
+        *,
+        is_short_circuited: Callable[[], bool] = lambda: False,
+        defer_audit: Callable[[Callable[[BaseException | None], Awaitable[None]]], None]
+        | None = None,
+    ) -> object:
+        """原生绑定在授权内执行；同一 HTTP 调用复用编译链且只计一次授权与审计。"""
+        async with self._runtime.outer_lease():
+            if self._http_boundary.get() is not None:
+                raise RuntimeError("HTTP Application Service boundary is already active")
+            pipeline = _InterceptorPipeline(method.descriptor, method.interceptor_steps, (), {})
+            state = _HttpInvocationState(service, method, _current_task(), pipeline)
+            state.is_short_circuited = is_short_circuited
+            state.defer_audit = defer_audit
+            token = self._http_boundary.set(state)
+
+            async def invoke_endpoint() -> object:
+                result = await callback()
+                # 外层 Interceptor 可合法短路；一旦进入原生绑定，必须消费原 endpoint 许可。
+                if not state.consumed and not state.is_short_circuited():
+                    raise RuntimeError("HTTP Application Service endpoint was not invoked")
+                return result
+
+            try:
+                return await self._invoke_entry(service, method, pipeline, invoke_endpoint)
+            finally:
+                self._http_boundary.reset(token)
+
+    async def invoke_http(
+        self,
+        service: _CompiledApplicationService,
+        method: _CompiledMethod,
+        kwargs: dict[str, object],
+    ) -> object:
+        boundary = self._http_boundary.get()
+        if boundary is None:
+            raise RuntimeError("HTTP Application Service boundary is unavailable")
+        if boundary.owner_task is not _current_task():
+            raise CrossTaskInvocationError
+        if boundary.service is not service or boundary.method is not method:
+            raise RuntimeError("HTTP Application Service boundary identity changed")
+        if boundary.consumed:
+            raise RuntimeError("HTTP Application Service boundary was already consumed")
+        boundary.consumed = True
+        boundary.pipeline.arguments.kwargs = dict(kwargs)
+        return await self._invoke_after_authorization(service, method, boundary.pipeline)
+
+    async def _invoke_after_authorization(
+        self,
+        service: _CompiledApplicationService,
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+    ) -> object:
+        async def validate() -> object:
+            await self._validate_pipeline(service.registration, method, pipeline)
+            return await pipeline.run(
+                InterceptionStage.UNIT_OF_WORK,
+                self._container,
+                lambda: self._invoke_work(service.registration, method, pipeline),
+            )
+
+        return await pipeline.run(InterceptionStage.VALIDATION, self._container, validate)
+
+    @staticmethod
+    async def _validate_pipeline(
+        registration: ApplicationServiceRegistration,
+        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, registration, arguments.args, arguments.kwargs
+            )
+        else:
+            # 可选类型验证关闭后，必需参数与参数名仍属于公开调用契约。
+            try:
+                method.signature.bind(None, *arguments.args, **arguments.kwargs)
+            except TypeError:
+                raise ApplicationServiceValidationError(
+                    service=registration.contract,
+                    method_name=method.name,
+                    issues=(
+                        ApplicationServiceValidationIssue(
+                            location=(), error_type="arguments", message="Invalid method arguments"
+                        ),
+                    ),
+                ) from None
+        arguments.mark_validated()
+
+    async def _invoke_work(
+        self,
+        registration: ApplicationServiceRegistration,
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+    ) -> object:
+        ambient = self._runtime.current()
+        if ambient is not None:
+            if _current_task() is not ambient.owner_task:
+                raise CrossTaskInvocationError
+            if registration.connection_name != ambient.context.connection_name:
+                raise NestedConnectionError(
+                    outer=ambient.context.connection_name, requested=registration.connection_name
+                )
+            manager = await self._container.get(UnitOfWorkManager)
+
+            async def nested() -> object:
+                return await self._invoke_target(
+                    ambient.action_container, registration, method, pipeline
+                )
+
+            if method.descriptor.unit_of_work.disabled:
+                manager._check_current(registration.connection_name)
+                return await nested()
+            options = manager._resolve_options(
+                registration.connection_name, method.descriptor.unit_of_work, method.name
+            )
+            async with manager._begin(options) as work:
+                result = await nested()
+                await work.complete()
+                return result
+
+        async def invoke(action: AsyncContainer) -> object:
+            return await self._invoke_target(action, registration, method, pipeline)
+
+        return await self._runtime.run_action(
+            self._container,
+            connection_name=registration.connection_name,
+            callback=invoke,
+            declaration=method.descriptor.unit_of_work,
+            method_name=method.name,
+        )
+
+    async def _invoke_target(
+        self,
+        container: AsyncContainer,
+        registration: ApplicationServiceRegistration,
+        method: _CompiledMethod,
+        pipeline: _InterceptorPipeline,
+    ) -> object:
+        async def invoke() -> object:
+            # 位于验证之后的扩展可以改参数；目标调用不能使用修改前的验证结果。
+            await self._validate_pipeline(registration, method, pipeline)
+            implementation = await container.get(
+                registration.contract, component=_APPLICATION_SERVICE_COMPONENT
+            )
+            # 实例已由当前 ACTION 容器取得，绑定只属于本 Application 的读取服务。
+            cast(ApplicationService, implementation)._setting_provider = await container.get(
+                SettingProvider
+            )
+            return await method.implementation_method(
+                implementation, *pipeline.arguments.args, **pipeline.arguments.kwargs
+            )
+
+        return await pipeline.run(InterceptionStage.METHOD, container, invoke)
+
+    async def _write_audit(
+        self,
+        registration: ApplicationServiceRegistration,
+        method: _CompiledMethod,
+        *,
+        occurred_at: datetime,
+        duration_ns: int,
+        failure: BaseException | None,
+    ) -> None:
+        options = (await self._container.get(Options[AuditingOptions])).value
+        control = await self._container.get(AuditingControl)
+        if (
+            not method.descriptor.auditing_enabled
+            or 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": registration.contract.__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"{registration.contract.__module__}.{registration.contract.__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": registration.contract.__qualname__,
+                    "audit_method": method.name,
+                },
+            )
+
+    async def _authorize(self, requirement: _AuthorizationRequirement) -> None:
+        if requirement.allows_anonymous or not requirement.requires_authenticated_user:
+            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))
+
+
+def _proxy_factory(
+    service: _CompiledApplicationService,
+) -> Callable[[_ApplicationServiceDispatcher], object]:
+    def create(dispatcher: _ApplicationServiceDispatcher) -> object:
+        return _ApplicationServiceProxy(dispatcher, service)
+
+    return create

python_platform/application_services/errors.py

@@ -0,0 +1,89 @@
+"""Application Service definition、validation 与 invocation failure contracts。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..errors.base import FrameworkError
+
+
+class ApplicationServiceDefinitionError(FrameworkError):
+    def __init__(self, *, symbol: str, reason: str) -> None:
+        self.symbol = symbol
+        self.reason = reason
+        super().__init__(f"Invalid Application Service {symbol}: {reason}")
+
+
+class ApplicationServiceMethodError(FrameworkError):
+    def __init__(self, *, service: type[object], method: object, reason: str) -> None:
+        self.service = service
+        self.method = method
+        self.reason = reason
+        method_name = getattr(method, "__qualname__", repr(method))
+        super().__init__(
+            f"Application Service method {service.__module__}.{service.__qualname__}/{method_name} "
+            f"is unavailable: {reason}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationServiceValidationIssue:
+    location: tuple[str | int, ...]
+    error_type: str
+    message: str
+
+
+class ApplicationServiceValidationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        service: type[object],
+        method_name: str,
+        issues: tuple[ApplicationServiceValidationIssue, ...],
+    ) -> None:
+        self.service = service
+        self.method_name = method_name
+        self.issues = issues
+        super().__init__(
+            f"Application Service validation failed for "
+            f"{service.__module__}.{service.__qualname__}.{method_name} ({len(issues)} issue(s))"
+        )
+
+
+class ApplicationInvocationRejectedError(FrameworkError):
+    def __init__(self, *, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"Application invocation rejected: {reason}")
+
+
+class CrossTaskInvocationError(ApplicationInvocationRejectedError):
+    def __init__(self) -> None:
+        super().__init__(reason="ambient ACTION belongs to a different asyncio task")
+
+
+class NestedConnectionError(ApplicationInvocationRejectedError):
+    def __init__(self, *, outer: str, requested: str) -> None:
+        self.outer = outer
+        self.requested = requested
+        super().__init__(
+            reason=f"nested invocation cannot change connection from {outer!r} to {requested!r}"
+        )
+
+
+class ApplicationInvocationCleanupError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        primary: BaseException | None,
+        cleanup_failures: tuple[BaseException, ...],
+        committed: bool,
+    ) -> None:
+        self.primary = primary
+        self.cleanup_failures = cleanup_failures
+        self.committed = committed
+        primary_name = type(primary).__name__ if primary is not None else "none"
+        super().__init__(
+            "Application invocation cleanup failed "
+            f"(primary={primary_name}, cleanup_failures={len(cleanup_failures)}, "
+            f"committed={committed})"
+        )