python-platform 0.1.1__py3-none-any.whl

python_platform/application_services/execution.py

@@ -0,0 +1,199 @@
+"""一次调用的参数与扩展链执行；静态规则已在 build 冻结。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field, fields, is_dataclass
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from uuid import UUID
+
+from dishka import AsyncContainer
+from pydantic import BaseModel
+
+from .catalog import ApplicationServiceMethod
+from .errors import ApplicationInvocationRejectedError, CrossTaskInvocationError
+from .interceptors import InterceptionStage, InterceptorRegistration
+
+_ARGUMENT_SNAPSHOT_MAX_DEPTH = 64
+
+
+class _InterceptorPipeline:
+    def __init__(
+        self,
+        method: ApplicationServiceMethod,
+        steps: Mapping[InterceptionStage, tuple[InterceptorRegistration, ...]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+    ) -> None:
+        self.method = method
+        self.steps = steps
+        self.arguments = _InvocationArguments(args, dict(kwargs))
+
+    async def run(
+        self,
+        stage: InterceptionStage,
+        container: AsyncContainer,
+        callback: Callable[[], Awaitable[object]],
+    ) -> object:
+        registrations = self.steps[stage]
+
+        async def proceed(index: int) -> object:
+            if index == len(registrations):
+                return await callback()
+            interceptor = await container.get(registrations[index].interceptor)
+            invocation = MethodInvocation(self.method, self.arguments, lambda: proceed(index + 1))
+            try:
+                return await interceptor.intercept(invocation)
+            finally:
+                invocation._close()
+
+        return await proceed(0)
+
+
+@dataclass(slots=True)
+class _InvocationArguments:
+    args: tuple[object, ...]
+    kwargs: dict[str, object]
+    _validated_args: tuple[object, ...] | None = field(default=None, init=False)
+    _validated_kwargs: dict[str, object] = field(default_factory=dict, init=False)
+    _validated_structure: object = field(default=None, init=False)
+    _validated_nodes: list[object] = field(default_factory=list, init=False)
+    exposed: bool = field(default=False, init=False)
+
+    @property
+    def needs_validation(self) -> bool:
+        # 比较绑定值的身份，不调用业务对象的 __eq__；观察者不会重复执行非幂等 validator。
+        return (
+            self._validated_args is None
+            or len(self.args) != len(self._validated_args)
+            or any(
+                left is not right
+                for left, right in zip(self.args, self._validated_args, strict=True)
+            )
+            or self.kwargs.keys() != self._validated_kwargs.keys()
+            or any(value is not self._validated_kwargs[key] for key, value in self.kwargs.items())
+            or (self.exposed and self._structure([]) != self._validated_structure)
+        )
+
+    def mark_validated(self) -> None:
+        # 只在验证成功后记录规范化结果；快照与调用共同归属当前 pipeline。
+        self._validated_args = self.args
+        self._validated_kwargs = dict(self.kwargs)
+        self._validated_nodes = []
+        self._validated_structure = self._structure(self._validated_nodes)
+        # 不重置 exposed：早期扩展可能保留参数引用，并在后续阶段原地修改同一对象。
+
+    def _structure(self, retained: list[object]) -> object:
+        return (
+            _argument_structure(self.args, set(), retained),
+            _argument_structure(self.kwargs, set(), retained),
+        )
+
+
+def _argument_structure(value: object, active: set[int], retained: list[object]) -> object:
+    # 只检查原生值结构，不调用业务对象的比较、复制或序列化；保留引用防止 id 回收复用。
+    retained.append(value)
+    identity = id(value)
+    if type(value) in (
+        type(None),
+        bool,
+        int,
+        float,
+        complex,
+        str,
+        bytes,
+        date,
+        datetime,
+        time,
+        timedelta,
+        Decimal,
+        UUID,
+    ):
+        return identity
+    # Any/object 的内部深度不受 Pydantic 约束；快照不能让合法输入因递归耗尽而失败。
+    if identity in active or len(active) >= _ARGUMENT_SNAPSHOT_MAX_DEPTH:
+        return object()
+    active.add(identity)
+    try:
+        if type(value) in (tuple, list):
+            assert isinstance(value, (tuple, list))
+            return identity, tuple(_argument_structure(item, active, retained) for item in value)
+        if type(value) is dict:
+            return identity, tuple(
+                (
+                    _argument_structure(key, active, retained),
+                    _argument_structure(item, active, retained),
+                )
+                for key, item in value.items()
+            )
+        if type(value) in (set, frozenset):
+            assert isinstance(value, (set, frozenset))
+            return identity, frozenset(
+                _argument_structure(item, active, retained) for item in value
+            )
+        if isinstance(value, BaseModel):
+            return (
+                identity,
+                _argument_structure(value.__dict__, active, retained),
+                _argument_structure(value.__pydantic_extra__, active, retained),
+            )
+        if is_dataclass(value) and not isinstance(value, type):
+            return identity, tuple(
+                (item.name, _argument_structure(getattr(value, item.name), active, retained))
+                for item in fields(value)
+            )
+        # 不透明对象、容器子类和循环无法证明未变时保守重验，不能用身份放行可变值。
+        return object()
+    finally:
+        active.remove(identity)
+
+
+class MethodInvocation:
+    """每个 continuation 独占一次许可；链共享参数，但不共享继续执行的状态。"""
+
+    def __init__(
+        self,
+        method: ApplicationServiceMethod,
+        arguments: _InvocationArguments,
+        continuation: Callable[[], Awaitable[object]],
+    ) -> None:
+        self._method = method
+        self._arguments = arguments
+        self._continuation = continuation
+        self._task = asyncio.current_task()
+        self._consumed = False
+        self._active = True
+
+    @property
+    def method(self) -> ApplicationServiceMethod:
+        return self._method
+
+    @property
+    def args(self) -> tuple[object, ...]:
+        self._arguments.exposed = True
+        return self._arguments.args
+
+    @args.setter
+    def args(self, value: tuple[object, ...]) -> None:
+        self._arguments.exposed = True
+        self._arguments.args = value
+
+    @property
+    def kwargs(self) -> dict[str, object]:
+        self._arguments.exposed = True
+        return self._arguments.kwargs
+
+    async def proceed(self) -> object:
+        if asyncio.current_task() is not self._task:
+            raise CrossTaskInvocationError
+        if self._consumed or not self._active:
+            raise ApplicationInvocationRejectedError(
+                reason="interceptor continuation is no longer available"
+            )
+        self._consumed = True
+        return await self._continuation()
+
+    def _close(self) -> None:
+        self._active = False

python_platform/application_services/interceptors.py

@@ -0,0 +1,44 @@
+"""拦截扩展契约及不可变注册事实；不依赖容器或 HTTP。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleKey
+
+if TYPE_CHECKING:
+    from .catalog import ApplicationServiceMethod
+    from .execution import MethodInvocation
+
+
+class InterceptionStage(Enum):
+    TRACING = "tracing"
+    AUDITING = "auditing"
+    AUTHORIZATION = "authorization"
+    VALIDATION = "validation"
+    UNIT_OF_WORK = "unit_of_work"
+    METHOD = "method"
+
+
+class Interceptor(ABC):
+    @abstractmethod
+    async def intercept(self, invocation: MethodInvocation) -> object: ...
+
+
+@dataclass(frozen=True, slots=True)
+class InterceptorRegistration:
+    interceptor: type[Interceptor]
+    before: InterceptionStage
+    owner: ModuleKey
+    source: SourceLocation
+
+
+@dataclass(frozen=True, slots=True)
+class _InterceptorRule:
+    registration: InterceptorRegistration
+    match: Callable[[ApplicationServiceMethod], bool]

python_platform/application_services/invocation.py

@@ -0,0 +1,427 @@
+"""Application-local admission、调用身份、REQUEST 入场与现有 ACTION/UoW owner。"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+from uuid import UUID, uuid4
+
+from dishka import AsyncContainer, Scope
+
+from ..authorization import CurrentUser
+from ..invocation import ApplicationInvocationContext
+from ..invocation.contracts import _is_safe_correlation_id
+from ..lifecycle import ApplicationState
+from ..unit_of_work import UnitOfWork, UnitOfWorkManager
+from ..unit_of_work.options import UnitOfWorkDeclaration
+from .catalog import (
+    ApplicationServiceCatalog,
+)
+from .errors import (
+    ApplicationInvocationCleanupError,
+    ApplicationInvocationRejectedError,
+    CrossTaskInvocationError,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Tracer
+
+
+@dataclass(slots=True)
+class _InvocationState:
+    context: ApplicationInvocationContext
+    owner_task: asyncio.Task[object]
+    action_container: AsyncContainer
+
+
+@dataclass(frozen=True, slots=True)
+class _CallerContext:
+    current_user: CurrentUser
+    correlation_id: str
+    owner_task: asyncio.Task[object]
+    transferable: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class _OuterInvocationLease:
+    owner_task: asyncio.Task[object]
+    allows_invocation: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _CallScope:
+    container: AsyncContainer
+    owner_task: asyncio.Task[object]
+
+
+class _InvocationRuntime:
+    """每个 Application 独占 admission 与 ContextVar，禁止进程级 current app。"""
+
+    __slots__ = (
+        "_active",
+        "_ambient",
+        "_application_id",
+        "_authenticating",
+        "_call_scope",
+        "_caller",
+        "_condition",
+        "_http_method",
+        "_is_accepting",
+        "_lease",
+        "_state_getter",
+        "tracer",
+    )
+
+    def __init__(
+        self,
+        *,
+        application_id: UUID,
+        state_getter: Callable[[], ApplicationState],
+    ) -> None:
+        self._application_id = application_id
+        self._authenticating: ContextVar[bool] = ContextVar(
+            f"python_platform_authenticating_{application_id}", default=False
+        )
+        self._http_method: ContextVar[str | None] = ContextVar(
+            f"python_platform_http_method_{application_id}", default=None
+        )
+        self.tracer: Tracer | None = None
+        self._state_getter = state_getter
+        self._ambient: ContextVar[_InvocationState | None] = ContextVar(
+            f"python_platform_invocation_{application_id}",
+            default=None,
+        )
+        self._caller: ContextVar[_CallerContext | None] = ContextVar(
+            f"python_platform_caller_{application_id}",
+            default=None,
+        )
+        self._lease: ContextVar[_OuterInvocationLease | None] = ContextVar(
+            f"python_platform_invocation_lease_{application_id}",
+            default=None,
+        )
+        self._condition = asyncio.Condition()
+        self._is_accepting = False
+        self._active = 0
+        self._call_scope: ContextVar[_CallScope | None] = ContextVar(
+            f"python_platform_call_scope_{application_id}",
+            default=None,
+        )
+
+    @contextmanager
+    def call_scope(self, container: AsyncContainer) -> Iterator[None]:
+        token = self._call_scope.set(_CallScope(container, _current_task()))
+        try:
+            yield
+        finally:
+            self._call_scope.reset(token)
+
+    def current_call_scope(self) -> AsyncContainer | None:
+        scope = self._call_scope.get()
+        if scope is None:
+            return None
+        if scope.owner_task is not _current_task():
+            raise CrossTaskInvocationError
+        return scope.container
+
+    def http_method(self) -> str | None:
+        return self._http_method.get()
+
+    @contextmanager
+    def http_scope(self, method: str) -> Iterator[None]:
+        token = self._http_method.set(method)
+        try:
+            yield
+        finally:
+            self._http_method.reset(token)
+
+    @contextmanager
+    def detached_execution(self, container: AsyncContainer) -> Iterator[None]:
+        token = self._ambient.set(None)
+        try:
+            with self.call_scope(container):
+                yield
+        finally:
+            self._ambient.reset(token)
+
+    @property
+    def application_id(self) -> UUID:
+        return self._application_id
+
+    def start_accepting(self) -> None:
+        self._is_accepting = True
+
+    async def stop_accepting_and_wait(self) -> None:
+        async with self._condition:
+            self._is_accepting = False
+            await self._condition.wait_for(lambda: self._active == 0)
+
+    @asynccontextmanager
+    async def outer_lease(self, *, allow_composed_request: bool = False) -> AsyncIterator[None]:
+        owner_task = _current_task()
+        inherited = self._lease.get()
+        if inherited is not None:
+            if inherited.owner_task is not owner_task:
+                # asyncio.create_task 会复制 ContextVar；child task 不得继承 parent admission。
+                raise CrossTaskInvocationError
+            if not inherited.allows_invocation and not allow_composed_request:
+                raise ApplicationInvocationRejectedError(
+                    reason=(
+                        "Application must be running and accepting invocations, got "
+                        f"{self._state_getter().value}"
+                    )
+                )
+            yield
+            return
+
+        async with self._condition:
+            state = self._state_getter()
+            allows_invocation = self._is_accepting and state is ApplicationState.RUNNING
+            allows_composed_request = allow_composed_request and state is ApplicationState.COMPOSED
+            if not allows_invocation and not allows_composed_request:
+                raise ApplicationInvocationRejectedError(
+                    reason=(
+                        f"Application must be running and accepting invocations, got {state.value}"
+                    )
+                )
+            self._active += 1
+        token = self._lease.set(_OuterInvocationLease(owner_task, allows_invocation))
+        try:
+            yield
+        finally:
+            self._lease.reset(token)
+            async with self._condition:
+                assert self._active > 0
+                self._active -= 1
+                if self._active == 0:
+                    self._condition.notify_all()
+
+    def current(self) -> _InvocationState | None:
+        return self._ambient.get()
+
+    def bind(self, state: _InvocationState) -> Token[_InvocationState | None]:
+        return self._ambient.set(state)
+
+    def reset(self, token: Token[_InvocationState | None]) -> None:
+        self._ambient.reset(token)
+
+    def current_user(self) -> CurrentUser:
+        if self._authenticating.get():
+            raise ApplicationInvocationRejectedError(
+                reason="authentication cannot depend on the final CurrentUser"
+            )
+        caller = self._caller.get()
+        if caller is None:
+            return CurrentUser.anonymous()
+        if not caller.transferable and caller.owner_task is not _current_task():
+            raise CrossTaskInvocationError
+        return caller.current_user
+
+    def correlation_id(self) -> str | None:
+        caller = self._caller.get()
+        if caller is None:
+            return None
+        if not caller.transferable and caller.owner_task is not _current_task():
+            raise CrossTaskInvocationError
+        return caller.correlation_id
+
+    def diagnostic_correlation_id(self) -> str | None:
+        # 日志允许只读关联复制到线程的上下文；这不授予 child task/线程调用业务的 lease。
+        caller = self._caller.get()
+        return None if caller is None else caller.correlation_id
+
+    def bind_caller(
+        self,
+        current_user: CurrentUser,
+        correlation_id: str,
+    ) -> Token[_CallerContext | None]:
+        if not isinstance(current_user, CurrentUser):
+            raise TypeError("current_user must be CurrentUser")
+        if not _is_safe_correlation_id(correlation_id):
+            raise ValueError("correlation_id must be a safe non-empty identifier")
+        return self._caller.set(
+            _CallerContext(
+                current_user=current_user,
+                correlation_id=correlation_id,
+                owner_task=_current_task(),
+            )
+        )
+
+    def reset_caller(self, token: Token[_CallerContext | None]) -> None:
+        self._caller.reset(token)
+
+    @contextmanager
+    def authenticating(self) -> Iterator[None]:
+        token = self._authenticating.set(True)
+        try:
+            yield
+        finally:
+            self._authenticating.reset(token)
+
+    @contextmanager
+    def trusted_http_task(
+        self, container: AsyncContainer, user: CurrentUser, correlation_id: str, method: str
+    ) -> Iterator[None]:
+        # 只有 adapter 的受监督入口可交接许可；普通 create_task 仍受原有 task guard 约束。
+        lease = self._lease.get()
+        if lease is None or self.current() is not None:
+            raise CrossTaskInvocationError
+        task = _current_task()
+        lease_token = self._lease.set(_OuterInvocationLease(task, lease.allows_invocation))
+        caller_token = self._caller.set(_CallerContext(user, correlation_id, task, True))
+        try:
+            with self.call_scope(container), self.http_scope(method):
+                yield
+        finally:
+            self._caller.reset(caller_token)
+            self._lease.reset(lease_token)
+
+    async def run_action(
+        self,
+        container: AsyncContainer,
+        *,
+        connection_name: str,
+        callback: Callable[[AsyncContainer], Awaitable[object]],
+        declaration: UnitOfWorkDeclaration,
+        method_name: str = "execute",
+    ) -> object:
+        """执行 scope 独立于数据库 UoW；自动边界只完成自己创建或加入的工作。"""
+        context = ApplicationInvocationContext(
+            application_id=self.application_id,
+            invocation_id=uuid4(),
+            parent_invocation_id=None,
+            connection_name=connection_name,
+        )
+        work: UnitOfWork | None = None
+        async with _managed_action(
+            container, context, committed=lambda: work is not None and work.committed
+        ) as action:
+            state = _InvocationState(context, _current_task(), action)
+            token = self.bind(state)
+            try:
+                manager = await action.get(UnitOfWorkManager)
+                if declaration.disabled:
+                    manager._check_current(connection_name)
+                    return await callback(action)
+                options = manager._resolve_options(connection_name, declaration, method_name)
+                async with manager._begin(options) as work:
+                    result = await callback(action)
+                    await work.complete()
+                    return result
+            finally:
+                self.reset(token)
+
+
+@asynccontextmanager
+async def _managed_action(
+    parent: AsyncContainer,
+    context: ApplicationInvocationContext,
+    *,
+    committed: Callable[[], bool],
+) -> AsyncIterator[AsyncContainer]:
+    action = parent(context={ApplicationInvocationContext: context}, scope=Scope.ACTION)
+    primary: BaseException | None = None
+    try:
+        yield action
+    except BaseException as error:
+        primary = error
+    primary, failures = await _close_action(action, primary)
+    _raise_scope_failure(primary, failures, committed())
+
+
+async def _close_action(
+    action: AsyncContainer, primary: BaseException | None
+) -> tuple[BaseException | None, tuple[BaseException, ...]]:
+    # Dishka generator 可能拥有 ContextVar token，进入与退出必须保持同一 task。
+    # 具体 provider 负责保护自己的原生 I/O（SQL UoW 已在 scope 关闭前回收）；
+    # finalizer 的 BaseException 仍需继续原生 close，穷尽其余资源。
+    failures: list[BaseException] = []
+    while True:
+        try:
+            await action.close(primary)
+            return primary, tuple(failures)
+        except asyncio.CancelledError as cancellation:
+            if primary is None:
+                primary = cancellation
+            else:
+                failures.append(cancellation)
+        except BaseException as error:
+            failures.append(error)
+
+
+def _raise_scope_failure(
+    primary: BaseException | None, failures: tuple[BaseException, ...], committed: bool
+) -> None:
+    if failures:
+        inherited = primary.__cause__ if isinstance(primary, asyncio.CancelledError) else primary
+        if isinstance(inherited, ApplicationInvocationCleanupError):
+            failures = (*inherited.cleanup_failures, *failures)
+            if not isinstance(primary, asyncio.CancelledError):
+                primary = inherited.primary
+        failure = ApplicationInvocationCleanupError(
+            primary=primary, cleanup_failures=failures, committed=committed
+        )
+        if isinstance(primary, asyncio.CancelledError):
+            raise primary from failure
+        raise failure from (primary or failures[0])
+    if primary is not None:
+        raise primary
+
+
+class _ScopedApplicationServiceInvoker:
+    """从 Application root 或其 SESSION 建立 REQUEST，不向 caller 暴露 resolver。"""
+
+    __slots__ = ("_catalog", "_root_container", "_runtime")
+
+    def __init__(
+        self,
+        container: AsyncContainer,
+        runtime: _InvocationRuntime,
+        catalog: ApplicationServiceCatalog,
+    ) -> None:
+        self._root_container = container
+        self._runtime = runtime
+        self._catalog = catalog
+
+    async def invoke(
+        self,
+        parent: AsyncContainer,
+        current_user: CurrentUser,
+        correlation_id: str,
+        method: Callable[..., Awaitable[object]],
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+    ) -> object:
+        self._require_owned_parent(parent)
+        service, compiled = self._catalog._resolve_method(method)
+        async with self._runtime.outer_lease():
+            caller_token = self._runtime.bind_caller(current_user, correlation_id)
+            try:
+                async with parent(scope=Scope.REQUEST) as request_container:
+                    proxy = await request_container.get(service.registration.contract)
+                    call = cast(
+                        Callable[..., Awaitable[object]],
+                        getattr(proxy, compiled.name),
+                    )
+                    return await call(*args, **kwargs)
+            finally:
+                self._runtime.reset_caller(caller_token)
+
+    def _require_owned_parent(self, parent: AsyncContainer) -> None:
+        if parent is self._root_container:
+            return
+        if parent.scope is not Scope.SESSION or parent.parent_container is not self._root_container:
+            raise RuntimeError("scoped invocation parent is not owned by this Application")
+
+
+def _current_task() -> asyncio.Task[object]:
+    task = asyncio.current_task()
+    if task is None:
+        raise RuntimeError("Application Service invocation requires an asyncio Task")
+    return cast(asyncio.Task[object], task)