python-ddd-framework 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

python_ddd_framework/application_services/bindings.py

@@ -9,15 +9,12 @@ from typing import get_origin
 from dishka import (
     DEFAULT_COMPONENT,
     DependencyKey,
-    Provider,
     Scope,
 )
 
 from ..diagnostics import SourceLocation
 from ..modularity import ModuleRegistry
 from ..services.arbitration import (
-    _ArbitrationResult,
-    _provider_with_active_sources,
     _RegistrationDraft,
 )
 from ..services.native_graph import _NativeServiceGraph
@@ -201,64 +198,3 @@ def _validate_application_service_bindings(
                     "or private implementation binding"
                 ),
             )
-
-
-def _runtime_providers(
-    arbitration: _ArbitrationResult,
-    services: tuple[_BoundApplicationService, ...],
-) -> tuple[Provider, ...]:
-    """仅重定位 Application Service factories；其他 Dishka provider 保持原生形状。"""
-
-    related_draft_ids = frozenset(
-        draft_id for service in services for draft_id in service.related_draft_ids
-    )
-    drafts_by_entry: dict[int, list[_RegistrationDraft]] = {}
-    for draft in arbitration.drafts:
-        drafts_by_entry.setdefault(draft.entry.entry_id, []).append(draft)
-
-    providers: list[Provider] = []
-    for entry in arbitration.ordered_entries:
-        entry_drafts = drafts_by_entry[entry.entry_id]
-        active = tuple(
-            draft
-            for draft in entry_drafts
-            if draft.decision is not RegistrationDecision.BACKED_OFF
-            and id(draft) not in related_draft_ids
-        )
-        if not active:
-            continue
-        if len(active) == len(entry_drafts):
-            providers.append(entry.contribution.provider)
-        else:
-            providers.append(_provider_with_active_sources(entry.contribution.provider, active))
-
-    # default component 只发布 REQUEST proxy；ACTION implementation 统一藏入框架私有 component。
-    implementation_provider = Provider(component=_APPLICATION_SERVICE_COMPONENT)
-    for service in services:
-        winner = service.winner
-        assert winner.factory is not None
-        # internal contributor 被 override 时仍以原声明 key 调度；
-        # winner class 只是实现事实，不能改写契约 key。
-        contract = (
-            service.binding.discovery.definition.contract or service.binding.discovery.service_type
-        )
-        implementation_provider.factories.append(
-            winner.factory.replace(
-                dependencies=tuple(
-                    dependency.with_component(DEFAULT_COMPONENT)
-                    for dependency in winner.factory.dependencies
-                ),
-                kw_dependencies={
-                    name: dependency.with_component(DEFAULT_COMPONENT)
-                    for name, dependency in winner.factory.kw_dependencies.items()
-                },
-                provides=DependencyKey(contract, None),
-                when_override=None,
-                when_component=DEFAULT_COMPONENT,
-            )
-        )
-        # ServiceCatalog 的 accepted row 必须描述 relocated native binding，而非旧 default key。
-        winner.key = DependencyKey(contract, _APPLICATION_SERVICE_COMPONENT)
-    if services:
-        providers.append(implementation_provider)
-    return tuple(providers)

python_ddd_framework/application_services/dispatcher.py

@@ -13,6 +13,7 @@ from dishka import AsyncContainer
 from ..invocation.dispatcher import _MethodDispatcher
 from ..invocation.execution import _InterceptorPipeline
 from ..invocation.methods import _CompiledMethod
+from ..invocation.runtime import _current_task, _InvocationRuntime
 from ..settings.provider import SettingProvider
 from .catalog import (
     _APPLICATION_SERVICE_COMPONENT,
@@ -22,7 +23,6 @@ from .contracts import ApplicationService
 from .errors import (
     CrossTaskInvocationError,
 )
-from .invocation import _current_task, _InvocationRuntime
 
 
 @dataclass(slots=True)

python_ddd_framework/application_services/invocation.py

@@ -1,563 +1,14 @@
-"""Application-local admission、调用身份、REQUEST 入场与现有 ACTION/UoW owner。"""
+"""应用服务 Contract 的 REQUEST 代理入口；准入与 scope 清理由 Invocation 拥有。"""
 
-from __future__ import annotations
-
-import asyncio
-import logging
-import threading
-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 collections.abc import Awaitable, Callable
+from typing import cast
 
 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, RuntimeParticipant, ShutdownReason
-from ..unit_of_work import UnitOfWork, UnitOfWorkManager
-from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME, UnitOfWorkDeclaration
-from .catalog import (
-    ApplicationServiceCatalog,
-)
-from .errors import (
-    ApplicationInvocationCleanupError,
-    ApplicationInvocationRejectedError,
-    CrossTaskInvocationError,
-    NestedConnectionError,
-)
-
-_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]
-
-
-@dataclass(eq=False, slots=True)
-class _InvocationReservation:
-    """只携带准入事实，不携带 caller、DI scope 或事务；由接受工作的 owner 收口。"""
-
-    runtime: _InvocationRuntime
-    executing: bool = False
-
-
-@dataclass(eq=False, frozen=True, slots=True)
-class _StoppingPermission:
-    """单 Application、服务 owner 与单次收尾钩子的准入身份，不携带业务 scope。"""
-
-    runtime: _InvocationRuntime
-    owner: type[object]
-
-
-class _InvocationRuntime:
-    """每个 Application 独占 admission 与 ContextVar，禁止进程级 current app。"""
-
-    __slots__ = (
-        "_active",
-        "_admission_lock",
-        "_ambient",
-        "_application_id",
-        "_authenticating",
-        "_call_scope",
-        "_caller",
-        "_changed",
-        "_http_method",
-        "_is_accepting",
-        "_lease",
-        "_loop",
-        "_permissions",
-        "_reservations",
-        "_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_ddd_framework_authenticating_{application_id}", default=False
-        )
-        self._http_method: ContextVar[str | None] = ContextVar(
-            f"python_ddd_framework_http_method_{application_id}", default=None
-        )
-        self.tracer: Tracer | None = None
-        self._state_getter = state_getter
-        self._ambient: ContextVar[_InvocationState | None] = ContextVar(
-            f"python_ddd_framework_invocation_{application_id}",
-            default=None,
-        )
-        self._caller: ContextVar[_CallerContext | None] = ContextVar(
-            f"python_ddd_framework_caller_{application_id}",
-            default=None,
-        )
-        self._lease: ContextVar[_OuterInvocationLease | None] = ContextVar(
-            f"python_ddd_framework_invocation_lease_{application_id}",
-            default=None,
-        )
-        self._admission_lock = threading.RLock()
-        self._changed = asyncio.Event()
-        self._loop: asyncio.AbstractEventLoop | None = None
-        self._permissions: set[_StoppingPermission] = set()
-        self._is_accepting = False
-        self._active = 0
-        self._reservations: set[_InvocationReservation] = set()
-        self._call_scope: ContextVar[_CallScope | None] = ContextVar(
-            f"python_ddd_framework_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._loop = asyncio.get_running_loop()
-        self._is_accepting = True
-
-    def runtime_participant(self) -> RuntimeParticipant:
-        async def start() -> None:
-            self.start_accepting()
-
-        async def stop(reason: ShutdownReason) -> tuple[BaseException, ...]:
-            self.close_admission()
-            return ()
-
-        return RuntimeParticipant(
-            start=start,
-            stop=stop,
-            quiesce=self.quiesce,
-            close_admission=self.close_admission,
-            drain=self.stop_accepting_and_wait,
-        )
-
-    def quiesce(self) -> None:
-        with self._admission_lock:
-            self._is_accepting = False
-
-    def close_admission(self) -> None:
-        with self._admission_lock:
-            self._is_accepting = False
-            self._permissions.clear()
-
-    def grant_stopping(self, owner: type[object]) -> _StoppingPermission:
-        with self._admission_lock:
-            if self._state_getter() not in (
-                ApplicationState.STOPPING,
-                ApplicationState.ROLLING_BACK,
-            ):
-                raise ApplicationInvocationRejectedError(reason="Not in the stopping phase")
-            permission = _StoppingPermission(self, owner)
-            self._permissions.add(permission)
-            return permission
-
-    def revoke_stopping(self, permission: _StoppingPermission) -> None:
-        with self._admission_lock:
-            self._permissions.discard(permission)
-
-    def require_stopping(self, permission: _StoppingPermission) -> None:
-        with self._admission_lock:
-            if permission.runtime is not self or permission not in self._permissions:
-                raise ApplicationInvocationRejectedError(reason="Invalid stopping permission")
-
-    async def stop_accepting_and_wait(self) -> None:
-        self.close_admission()
-        while True:
-            self._changed.clear()
-            with self._admission_lock:
-                if self._active == 0 and not self._reservations:
-                    return
-            await self._changed.wait()
-
-    def reserve(self, permission: _StoppingPermission | None = None) -> _InvocationReservation:
-        # SDK thread 与权限撤销在同一锁下线性化；已接受许可独立于钩子权限的寿命。
-        with self._admission_lock:
-            if permission is None:
-                self.require_accepting_work()
-            else:
-                self.require_stopping(permission)
-            reservation = _InvocationReservation(self)
-            self._reservations.add(reservation)
-            return reservation
-
-    def require_accepting_work(self) -> None:
-        if not self._is_accepting or self._state_getter() not in (
-            ApplicationState.STARTING,
-            ApplicationState.RUNNING,
-        ):
-            raise ApplicationInvocationRejectedError(reason="Application is not accepting work")
-
-    async def discard(self, reservation: _InvocationReservation) -> None:
-        self.release_reservation(reservation)
-
-    def release_reservation(self, reservation: _InvocationReservation) -> None:
-        with self._admission_lock:
-            if reservation.runtime is not self or reservation not in self._reservations:
-                raise ApplicationInvocationRejectedError(reason="Invalid or released reservation")
-            self._reservations.remove(reservation)
-        if self._loop is not None and not self._loop.is_closed():
-            try:
-                self._loop.call_soon_threadsafe(self._changed.set)
-            except RuntimeError:
-                # 外部 submit 可能在 loop 关闭竞争中退回许可；此时已无 loop 排空等待者。
-                if not self._loop.is_closed():
-                    raise
-
-    @asynccontextmanager
-    async def reserved_lease(self, reservation: _InvocationReservation) -> AsyncIterator[None]:
-        if (
-            reservation.runtime is not self
-            or reservation not in self._reservations
-            or reservation.executing
-            or self._lease.get() is not None
-            or self.current() is not None
-            or self.current_call_scope() is not None
-        ):
-            raise ApplicationInvocationRejectedError(reason="Invalid reservation execution owner")
-        reservation.executing = True
-        token = self._lease.set(_OuterInvocationLease(_current_task(), True))
-        try:
-            yield
-        finally:
-            self._lease.reset(token)
-            await self.discard(reservation)
-
-    @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
-
-        with self._admission_lock:
-            state = self._state_getter()
-            # HostedService.start 可调用业务入口，但全部后台启动成功前 readiness 仍为 false。
-            allows_invocation = self._is_accepting and state in (
-                ApplicationState.STARTING,
-                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)
-            with self._admission_lock:
-                assert self._active > 0
-                self._active -= 1
-                if self._active == 0:
-                    self._changed.set()
-
-    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)
-
-    def context_for_action(self, container: AsyncContainer) -> ApplicationInvocationContext:
-        """由原生 ACTION factory 缓存上下文，DI 与调用管线共享同一身份。"""
-        # Dishka 1.10 的公开 context 属性已弃用；这里只读取原生 scope 的输入，
-        # 不写 context/cache，也不复制容器的解析或缓存。第三方字段访问集中于此。
-        native_context = container._context
-        if native_context is None or ApplicationInvocationContext not in native_context:
-            return self._new_context(_DEFAULT_CONNECTION_NAME)
-        supplied: object = native_context[ApplicationInvocationContext]
-        if not isinstance(supplied, ApplicationInvocationContext):
-            raise ApplicationInvocationRejectedError(reason="invalid ACTION invocation context")
-        if supplied.application_id != self.application_id:
-            raise ApplicationInvocationRejectedError(
-                reason="ACTION invocation context belongs to another Application"
-            )
-        return supplied
-
-    def _new_context(self, connection_name: str) -> ApplicationInvocationContext:
-        return ApplicationInvocationContext(
-            application_id=self.application_id,
-            invocation_id=uuid4(),
-            parent_invocation_id=None,
-            connection_name=connection_name,
-        )
-
-    async def run_action(
-        self,
-        container: AsyncContainer,
-        *,
-        connection_name: str,
-        callback: Callable[[AsyncContainer], Awaitable[object]],
-        declaration: UnitOfWorkDeclaration,
-        method_name: str = "execute",
-        unit_of_work_enabled: bool = True,
-    ) -> object:
-        """执行 scope 独立于数据库 UoW；自动边界只完成自己创建或加入的工作。"""
-        context = (
-            await container.get(ApplicationInvocationContext)
-            if container.scope is Scope.ACTION
-            else self._new_context(connection_name)
-        )
-        if context.connection_name != connection_name:
-            raise NestedConnectionError(outer=context.connection_name, requested=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:
-                if not unit_of_work_enabled:
-                    return await callback(action)
-                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_request(parent: AsyncContainer) -> AsyncIterator[AsyncContainer]:
-    """排空入口自己创建的 REQUEST；不推断业务事务是否已经提交。"""
-    request = parent(scope=Scope.REQUEST)
-    primary: BaseException | None = None
-    try:
-        yield request
-    except BaseException as error:
-        primary = error
-    primary, failures = await _close_action(request, primary)
-    if failures:
-        # REQUEST 无事务 owner；保留业务原异常及已有 cause，不伪造 committed=False。
-        inherited = (primary.__cause__,) if primary is not None and primary.__cause__ else ()
-        cleanup = BaseExceptionGroup("REQUEST cleanup failed", (*inherited, *failures))
-        if primary is not None:
-            raise primary from cleanup
-        raise cleanup
-    if primary is not None:
-        raise primary
-
-
-@asynccontextmanager
-async def _managed_action(
-    parent: AsyncContainer,
-    context: ApplicationInvocationContext,
-    *,
-    committed: Callable[[], bool],
-) -> AsyncIterator[AsyncContainer]:
-    if parent.scope is Scope.ACTION:
-        # 普通服务可能已经由调用方的 ACTION 解析；资源仍由该 scope 的 owner 关闭。
-        yield parent
-        return
-    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
+from ..invocation.runtime import _InvocationRuntime
+from ..invocation.scopes import _managed_request
+from .catalog import ApplicationServiceCatalog
 
 
 class _ScopedApplicationServiceInvoker:
@@ -589,7 +40,7 @@ class _ScopedApplicationServiceInvoker:
         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:
+                async with _managed_request(parent) as request_container:
                     proxy = await request_container.get(service.registration.contract)
                     call = cast(
                         Callable[..., Awaitable[object]],
@@ -604,10 +55,3 @@ class _ScopedApplicationServiceInvoker:
             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)