python-platform 0.1.1__py3-none-any.whl

python_platform/application/runtime.py

@@ -0,0 +1,546 @@
+"""公开 Application 状态机、生命周期与非 DI 调用入口。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import asynccontextmanager, contextmanager
+from typing import Concatenate, ParamSpec, TypeAlias, TypeVar, cast
+from uuid import UUID, uuid4
+
+from dishka import AsyncContainer, Scope
+
+from ..application_services import (
+    ApplicationInvocationRejectedError,
+    ApplicationServiceCatalog,
+    ApplicationServiceContract,
+    ApplicationServiceRegistration,
+)
+from ..application_services.dispatcher import _ApplicationServiceDispatcher
+from ..application_services.invocation import (
+    _ScopedApplicationServiceInvoker,
+)
+from ..authorization import CurrentUser, PermissionCatalog
+from ..background_jobs import BackgroundJobCatalog
+from ..background_workers import BackgroundWorkerCatalog
+from ..caching import CacheCatalog
+from ..configuration import ConfigurationRoot
+from ..diagnostics import DiagnosticSnapshot
+from ..errors import (
+    ApplicationRuntimeError,
+    ApplicationStartError,
+    ContainerCleanupError,
+    InvalidApplicationStateError,
+    LifecycleInvocationError,
+)
+from ..errors.lifecycle import (
+    _BackgroundExecutionStartFailure,
+    _exclude_runtime_failure,
+)
+from ..events import LocalEventCatalog
+from ..hosted_services import (
+    ApplicationReadinessSnapshot,
+    HostedServiceCatalog,
+    HostedServiceLifecycleError,
+)
+from ..invocation.function_runtime import _invoke_callable
+from ..lifecycle import ApplicationState, ShutdownReason
+from ..modularity import ModuleRegistry
+from ..options import OptionsSnapshot
+from ..services import ServiceCatalog
+from ..settings import SettingCatalog
+from .runtime_hooks import _RuntimeLifecycle
+from .state import _ApplicationStateRoot
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+_TContract = TypeVar("_TContract", bound=ApplicationServiceContract)
+_StartCleanupFailure: TypeAlias = (
+    LifecycleInvocationError
+    | ContainerCleanupError
+    | _BackgroundExecutionStartFailure
+    | HostedServiceLifecycleError
+)
+
+
+class Application:
+    """拥有单次 build 的 Module instances、状态、transition 与 diagnostics。"""
+
+    __slots__ = ("_root",)
+
+    def __init__(self, root: _ApplicationStateRoot) -> None:
+        self._root = root
+
+    @property
+    def id(self) -> UUID:
+        return self._root.application_id
+
+    @property
+    def state(self) -> ApplicationState:
+        return self._root.state
+
+    @property
+    def modules(self) -> ModuleRegistry:
+        return self._root.registry
+
+    @property
+    def configuration(self) -> ConfigurationRoot:
+        return self._root.configuration
+
+    @property
+    def options(self) -> OptionsSnapshot:
+        return self._root.require_options()
+
+    @property
+    def service_catalog(self) -> ServiceCatalog:
+        return self._root.require_service_catalog()
+
+    @property
+    def application_service_catalog(self) -> ApplicationServiceCatalog:
+        return self._root.require_application_service_catalog()
+
+    @property
+    def event_catalog(self) -> LocalEventCatalog:
+        return self._root.require_event_catalog()
+
+    @property
+    def permission_catalog(self) -> PermissionCatalog:
+        return self._root.require_permission_catalog()
+
+    @property
+    def cache_catalog(self) -> CacheCatalog:
+        return self._root.require_cache_catalog()
+
+    @property
+    def setting_catalog(self) -> SettingCatalog:
+        return self._root.require_setting_catalog()
+
+    @property
+    def background_worker_catalog(self) -> BackgroundWorkerCatalog:
+        return self._root.require_background_worker_catalog()
+
+    @property
+    def background_job_catalog(self) -> BackgroundJobCatalog:
+        return self._root.require_background_job_catalog()
+
+    @property
+    def hosted_service_catalog(self) -> HostedServiceCatalog:
+        return self._root.require_hosted_service_catalog()
+
+    @property
+    def readiness(self) -> ApplicationReadinessSnapshot:
+        return self._root.readiness()
+
+    @property
+    def diagnostics(self) -> DiagnosticSnapshot:
+        return self._root.journal.snapshot(self._root.application_id)
+
+    def _container_for_integration(self) -> AsyncContainer:
+        # 外部 adapter 只能在 composition root 建桥；不把 resolver/container 变成 public API。
+        return self._root.require_container()
+
+    async def start(self) -> None:
+        await self._start(run_services=True)
+
+    async def _start(self, *, run_services: bool) -> None:
+        token = self._root.claim_transition(
+            operation="start",
+            allowed=(ApplicationState.COMPOSED,),
+        )
+        self._root.state = ApplicationState.STARTING
+        if not run_services:
+            # 数据库 CLI 只需要 Module 初始化及正式 invocation；不打开后台生产者或外部 SDK。
+            self._root.require_background_coordinator().disable_for_database()
+        lifecycle = _RuntimeLifecycle(self._root)
+        started = False
+        try:
+            try:
+                await lifecycle.start_modules()
+            except LifecycleInvocationError as primary:
+                self._root.state = ApplicationState.ROLLING_BACK
+                cleanup_failures = await lifecycle.shutdown_touched(
+                    reason=ShutdownReason.START_FAILURE,
+                )
+                container_failures = await lifecycle.close_container(
+                    exception=primary.original_error,
+                )
+                all_cleanup_failures: tuple[
+                    LifecycleInvocationError | ContainerCleanupError,
+                    ...,
+                ] = (
+                    *cleanup_failures,
+                    *container_failures,
+                )
+                self._root.journal.complete_failure(
+                    primary.failure_id,
+                    cleanup_failure_ids=tuple(
+                        failure.failure_id for failure in all_cleanup_failures
+                    ),
+                )
+                self._root.state = ApplicationState.FAILED_START
+                raise ApplicationStartError(
+                    primary=primary,
+                    cleanup_failures=all_cleanup_failures,
+                ) from primary
+            self._root.state = ApplicationState.RUNNING
+            self._root.require_invocation_runtime().start_accepting()
+            try:
+                await self._root.require_background_coordinator().start()
+            except BaseException as original_error:
+                background_failure = _BackgroundExecutionStartFailure(original_error=original_error)
+                runtime_cleanup_failures = await self._rollback_runtime_start(
+                    lifecycle,
+                    primary=background_failure,
+                )
+                raise ApplicationStartError(
+                    primary=background_failure,
+                    cleanup_failures=runtime_cleanup_failures,
+                ) from background_failure
+            try:
+                if run_services:
+                    await self._root.require_hosted_service_coordinator().start()
+            except BaseException as original_error:
+                hosted_failure = (
+                    original_error
+                    if isinstance(original_error, HostedServiceLifecycleError)
+                    else HostedServiceLifecycleError(
+                        service="hosted-service-coordinator",
+                        operation="start",
+                        error_type=type(original_error).__name__,
+                    )
+                )
+                runtime_cleanup_failures = await self._rollback_runtime_start(
+                    lifecycle,
+                    primary=hosted_failure,
+                )
+                raise ApplicationStartError(
+                    primary=hosted_failure,
+                    cleanup_failures=runtime_cleanup_failures,
+                ) from hosted_failure
+            started = True
+        finally:
+            self._root.release_transition(token)
+        if started and (self._root.require_background_coordinator().has_runtime_failure_source):
+            self._root.runtime_monitor_task = asyncio.create_task(
+                self._monitor_runtime_failure(),
+                name=f"python-platform-runtime-monitor:{self.id}",
+            )
+
+    async def _rollback_runtime_start(
+        self,
+        lifecycle: _RuntimeLifecycle,
+        *,
+        primary: BaseException,
+    ) -> tuple[_StartCleanupFailure, ...]:
+        self._root.state = ApplicationState.ROLLING_BACK
+        hosted = self._root.require_hosted_service_coordinator()
+        hosted.close_admission()
+        cleanup_failures: list[_StartCleanupFailure] = []
+        # bootstrap 是严格栈式 ownership：先穷尽已 touch 的 Hosted Service，
+        # 再撤销更早启动的 background，不能复用正常 stop 的并行收口策略。
+        try:
+            hosted_failures = await hosted.stop(ShutdownReason.START_FAILURE)
+        except BaseException as hosted_error:
+            cleanup_failures.append(
+                HostedServiceLifecycleError(
+                    service="hosted-service-coordinator",
+                    operation="stop",
+                    error_type=type(hosted_error).__name__,
+                )
+            )
+        else:
+            cleanup_failures.extend(hosted_failures)
+        try:
+            await self._root.require_background_coordinator().stop()
+        except BaseException as background_error:
+            cleanup_failures.append(
+                _BackgroundExecutionStartFailure(original_error=background_error)
+            )
+        await self._root.require_invocation_runtime().stop_accepting_and_wait()
+        cleanup_failures.extend(
+            await lifecycle.shutdown_touched(reason=ShutdownReason.START_FAILURE)
+        )
+        cleanup_failures.extend(await lifecycle.close_container(exception=primary))
+        self._root.state = ApplicationState.FAILED_START
+        return tuple(cleanup_failures)
+
+    async def stop(self) -> None:
+        if self._root.state in (
+            ApplicationState.STOPPED,
+            ApplicationState.STOPPED_WITH_ERRORS,
+            ApplicationState.FAILED_START,
+        ):
+            return
+
+        token = self._root.claim_transition(
+            operation="stop",
+            allowed=(ApplicationState.COMPOSED, ApplicationState.RUNNING),
+        )
+        self._root.state = ApplicationState.STOPPING
+        # shield 只保留弱引用；局部 task 同时承担 cleanup 的强 ownership。
+        cleanup_task = asyncio.create_task(self._complete_stop())
+        cancellation: asyncio.CancelledError | None = None
+        cleanup_failure: BaseException | None = None
+        try:
+            while not cleanup_task.done():
+                try:
+                    await asyncio.shield(cleanup_task)
+                except asyncio.CancelledError as original_cancellation:
+                    if cancellation is None:
+                        cancellation = original_cancellation
+            cleanup_failure = cleanup_task.result()
+        finally:
+            self._root.release_transition(token)
+
+        if cancellation is not None:
+            if cleanup_failure is not None:
+                raise cancellation from cleanup_failure
+            raise cancellation
+        if cleanup_failure is not None:
+            raise cleanup_failure
+
+    async def _complete_stop(self) -> BaseException | None:
+        lifecycle = _RuntimeLifecycle(self._root)
+        reason = (
+            ShutdownReason.RUNTIME_FAILURE
+            if self._root.runtime_failure is not None
+            else ShutdownReason.NORMAL
+        )
+        hosted = self._root.require_hosted_service_coordinator()
+        # 先关闭 SDK thread bridge，再让 background 与 Hosted Service 并行停止生产新工作。
+        hosted.close_admission()
+        background_task = asyncio.create_task(
+            self._root.require_background_coordinator().stop(),
+            name=f"python-platform-background-stop:{self.id}",
+        )
+        hosted_task = asyncio.create_task(
+            hosted.stop(reason),
+            name=f"python-platform-hosted-service-stop:{self.id}",
+        )
+        background_outcome, hosted_outcome = await asyncio.gather(
+            background_task,
+            hosted_task,
+            return_exceptions=True,
+        )
+        infrastructure_failures: list[BaseException] = []
+        if isinstance(background_outcome, BaseException):
+            infrastructure_failures.append(background_outcome)
+        if isinstance(hosted_outcome, BaseException):
+            infrastructure_failures.append(hosted_outcome)
+        else:
+            infrastructure_failures.extend(hosted_outcome)
+        await self._root.require_invocation_runtime().stop_accepting_and_wait()
+        module_failures = await lifecycle.shutdown_touched(
+            reason=reason,
+        )
+        container_failures = await lifecycle.close_container(exception=None)
+        runtime_failure = self._root.runtime_failure
+        if runtime_failure is not None:
+            infrastructure_failures = [
+                remaining
+                for error in infrastructure_failures
+                if (remaining := _exclude_runtime_failure(error, runtime_failure)) is not None
+            ]
+        cleanup_failures: tuple[BaseException, ...] = (
+            *infrastructure_failures,
+            *module_failures,
+            *container_failures,
+        )
+        terminal_failure: BaseException | None
+        if runtime_failure is not None and cleanup_failures:
+            terminal_failure = BaseExceptionGroup(
+                "Application runtime termination failed",
+                (runtime_failure, *cleanup_failures),
+            )
+        elif runtime_failure is not None:
+            terminal_failure = runtime_failure
+        elif cleanup_failures:
+            terminal_failure = BaseExceptionGroup(
+                "Application shutdown failed",
+                cleanup_failures,
+            )
+        else:
+            terminal_failure = None
+        self._root.state = (
+            ApplicationState.STOPPED_WITH_ERRORS
+            if terminal_failure is not None
+            else ApplicationState.STOPPED
+        )
+        self._root.termination_failure = terminal_failure
+        self._root.termination_event.set()
+        monitor = self._root.runtime_monitor_task
+        if (
+            runtime_failure is None
+            and monitor is not None
+            and monitor is not asyncio.current_task()
+        ):
+            monitor.cancel()
+            await asyncio.gather(monitor, return_exceptions=True)
+            self._root.runtime_monitor_task = None
+        return terminal_failure
+
+    async def wait_for_termination(self) -> None:
+        """等待正常 stop 或受监督 runtime fatal 完整清理，不暴露内部 Task/Future。"""
+
+        allowed = (
+            ApplicationState.RUNNING,
+            ApplicationState.STOPPING,
+            ApplicationState.STOPPED,
+            ApplicationState.STOPPED_WITH_ERRORS,
+        )
+        if self._root.state not in allowed:
+            raise InvalidApplicationStateError(
+                operation="wait_for_termination",
+                current=self._root.state,
+                allowed=allowed,
+            )
+        await self._root.termination_event.wait()
+        failure = self._root.termination_failure
+        if failure is not None:
+            raise failure
+
+    async def _monitor_runtime_failure(self) -> None:
+        current = asyncio.current_task()
+        try:
+            # HostedService 只拥有 start/stop；持久任务等其他能力仍保留自身故障传播。
+            failure = await self._root.require_background_coordinator().wait_for_runtime_failure()
+            if self._root.runtime_failure is None:
+                self._root.runtime_failure = ApplicationRuntimeError(
+                    component=failure.component,
+                    error_type=failure.error_type,
+                )
+                self._root.runtime_failure._source = failure._source
+            try:
+                await self.stop()
+            except InvalidApplicationStateError:
+                # 显式 stop 已拥有 transition 时，由同一 cleanup 路径发布终态。
+                await self._root.termination_event.wait()
+            except BaseException:
+                # stop 已缓存同一个脱敏终态错误；monitor 不制造未观察异常。
+                pass
+        finally:
+            if self._root.runtime_monitor_task is current:
+                self._root.runtime_monitor_task = None
+
+    async def call(
+        self,
+        function: Callable[..., Awaitable[_R]],
+        /,
+        *args: object,
+        **kwargs: object,
+    ) -> _R:
+        """调用异步入口，业务实参显式传入，服务参数由最终 Dishka 图补齐。"""
+        return await self.call_as(
+            self._root.require_invocation_runtime().current_user(),
+            function,
+            *args,
+            **kwargs,
+        )
+
+    async def call_as(
+        self,
+        current_user: CurrentUser,
+        function: Callable[..., Awaitable[_R]],
+        /,
+        *args: object,
+        **kwargs: object,
+    ) -> _R:
+        """可信身份与调用许可覆盖 REQUEST 创建、业务执行和最终资源释放。"""
+        runtime = self._root.require_invocation_runtime()
+        return await _invoke_callable(
+            self._root.require_container(),
+            runtime,
+            current_user,
+            str(uuid4()),
+            function,
+            args,
+            kwargs,
+        )
+
+    async def invoke(
+        self,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R:
+        """匿名调用公开 Protocol method；可信 caller 需显式使用 invoke_as。"""
+
+        return await self.invoke_as(CurrentUser.anonymous(), method, *args, **kwargs)
+
+    async def invoke_as(
+        self,
+        current_user: CurrentUser,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R:
+        """由可信 Host/test 传入已验证身份，身份只绑定当前 Application 与 asyncio Task。"""
+
+        if self._root.state is not ApplicationState.RUNNING:
+            raise ApplicationInvocationRejectedError(
+                reason=f"Application must be running, got {self._root.state.value}"
+            )
+        container = self._root.require_container()
+        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_for_integration(self) -> AsyncIterator[None]:
+        """Web/internal entry 共用的 Application-local drain lease。"""
+
+        async with self._root.require_invocation_runtime().outer_lease():
+            yield
+
+    @asynccontextmanager
+    async def _http_request_lease_for_integration(self) -> AsyncIterator[None]:
+        # Phase 2 health contract 允许 composed/pre-start probe，但该 request 仍参与 stop drain；
+        # lease 中的 capability 会让随后进入 dispatcher 的业务 route 继续 fail closed。
+        async with self._root.require_invocation_runtime().outer_lease(allow_composed_request=True):
+            yield
+
+    @contextmanager
+    def _caller_context_for_integration(
+        self,
+        current_user: CurrentUser,
+        correlation_id: str,
+    ) -> Iterator[None]:
+        """HTTP bridge 的窄化入口；不公开 mutable principal 或 process-global current app。"""
+
+        runtime = self._root.require_invocation_runtime()
+        token = runtime.bind_caller(current_user, correlation_id)
+        try:
+            yield
+        finally:
+            runtime.reset_caller(token)
+
+    async def _invoke_registration(
+        self,
+        registration: ApplicationServiceRegistration,
+        method_name: str,
+    ) -> object:
+        """框架内部 contributor 仍走 dispatcher，但不发布 public single Contract。"""
+
+        if self._root.state is not ApplicationState.RUNNING:
+            raise ApplicationInvocationRejectedError(
+                reason=f"Application must be running, got {self._root.state.value}"
+            )
+        service = self.application_service_catalog._for_registration(registration)
+        method = service.methods.get(method_name)
+        if method is None:
+            raise AssertionError("internal contributor method is absent from its catalog entry")
+        container = self._root.require_container()
+        async with self._invocation_lease_for_integration():
+            with self._caller_context_for_integration(CurrentUser.anonymous(), str(uuid4())):
+                async with container(scope=Scope.REQUEST) as request_container:
+                    dispatcher = await request_container.get(_ApplicationServiceDispatcher)
+                    return await dispatcher.invoke(service, method, (), {})