python-platform 0.1.1__py3-none-any.whl

python_platform/application/runtime_hooks.py

@@ -0,0 +1,327 @@
+"""Async Module runtime hooks、partial shutdown 与 Dishka finalization。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import cast
+
+from ..diagnostics import EventStatus, LifecyclePhase, LifecycleStage
+from ..errors import (
+    ContainerCleanupError,
+    LifecycleInvocationError,
+    LifecycleReturnValueError,
+)
+from ..lifecycle import (
+    InitializeContext,
+    PostInitializeContext,
+    PreInitializeContext,
+    ShutdownContext,
+    ShutdownReason,
+)
+from ..modularity import ModuleDescriptor
+from .state import (
+    LIFECYCLE_ERROR_TYPE,
+    _ApplicationStateRoot,
+    _lifecycle_failure_message,
+)
+
+
+class _RuntimeLifecycle:
+    """拥有一次 Application 的 runtime invocation 与 best-effort cleanup policy。"""
+
+    __slots__ = ("_root",)
+
+    def __init__(self, root: _ApplicationStateRoot) -> None:
+        self._root = root
+
+    async def start_modules(self) -> None:
+        for descriptor in self._root.registry.dependency_order:
+            await self._invoke_pre_initialize(descriptor)
+        for descriptor in self._root.registry.dependency_order:
+            await self._invoke_initialize(descriptor)
+        for descriptor in self._root.registry.dependency_order:
+            await self._invoke_post_initialize(descriptor)
+
+    async def shutdown_touched(
+        self,
+        *,
+        reason: ShutdownReason,
+    ) -> tuple[LifecycleInvocationError, ...]:
+        failures: list[LifecycleInvocationError] = []
+        # hook 调用前即标为 touched，所以失败 hook 自身也会获得一次逆序释放机会。
+        for descriptor in self._root.registry.shutdown_order:
+            if (
+                descriptor.key not in self._root.runtime_touched
+                or descriptor.key in self._root.released_modules
+            ):
+                continue
+            context = ShutdownContext(
+                application_id=self._root.application_id,
+                descriptor=descriptor,
+                stage=LifecycleStage.SHUTDOWN,
+                application=self._root.view(self._root.state),
+                _emit=self._root.diagnostic_emitter(
+                    descriptor,
+                    LifecycleStage.SHUTDOWN,
+                ),
+                configuration=self._root.configuration,
+                options=self._root.require_options(),
+                reason=reason,
+                completed_stages=tuple(self._root.completed_stages[descriptor.key]),
+                container=self._root.require_container(),
+            )
+            failure = await self._invoke_shutdown(descriptor, context)
+            self._root.released_modules.add(descriptor.key)
+            if failure is not None:
+                failures.append(failure)
+        return tuple(failures)
+
+    async def close_container(
+        self,
+        *,
+        exception: BaseException | None,
+    ) -> tuple[ContainerCleanupError, ...]:
+        container = self._root.container
+        if container is None:
+            return ()
+        failures: list[ContainerCleanupError] = []
+        try:
+            while True:
+                try:
+                    await container.close(exception)
+                except BaseException as original_error:
+                    # 当前 lock 解析的 Dishka 会在调用前弹出当前 finalizer；重入 native close
+                    # 才能在 BaseException 后继续穷尽其余资源，而非建立第二套 cleanup engine。
+                    failures.append(self._container_cleanup_error(original_error))
+                    continue
+                break
+        finally:
+            # 只在 native close 已穷尽后撤销引用；stop 后不再暴露可解析容器。
+            self._root.container = None
+        return tuple(failures)
+
+    def _container_cleanup_error(
+        self,
+        original_error: BaseException,
+    ) -> ContainerCleanupError:
+        subject = "dishka-container"
+        failure_id = self._root.journal.begin_failure(
+            error_type=ContainerCleanupError.__name__,
+            phase=LifecyclePhase.CLEANUP,
+            stage=LifecycleStage.SHUTDOWN,
+            subject=subject,
+            message=(f"{subject}/shutdown failed with {type(original_error).__name__}"),
+            source=None,
+            dependency_path=(),
+        )
+        self._root.journal.complete_failure(failure_id)
+        return ContainerCleanupError(
+            failure_id=failure_id,
+            original_error=original_error,
+        )
+
+    async def _invoke_pre_initialize(self, descriptor: ModuleDescriptor) -> None:
+        stage = LifecycleStage.PRE_INITIALIZE
+        context = PreInitializeContext(
+            application_id=self._root.application_id,
+            descriptor=descriptor,
+            stage=stage,
+            application=self._root.view(self._root.state),
+            _emit=self._root.diagnostic_emitter(descriptor, stage),
+            configuration=self._root.configuration,
+            options=self._root.require_options(),
+            container=self._root.require_container(),
+        )
+        callback = cast(
+            Callable[[PreInitializeContext], Awaitable[object]],
+            descriptor.instance.pre_initialize,
+        )
+        await self._invoke_start_hook(
+            descriptor,
+            stage,
+            lambda: callback(context),
+        )
+
+    async def _invoke_initialize(self, descriptor: ModuleDescriptor) -> None:
+        stage = LifecycleStage.INITIALIZE
+        context = InitializeContext(
+            application_id=self._root.application_id,
+            descriptor=descriptor,
+            stage=stage,
+            application=self._root.view(self._root.state),
+            _emit=self._root.diagnostic_emitter(descriptor, stage),
+            configuration=self._root.configuration,
+            options=self._root.require_options(),
+            container=self._root.require_container(),
+        )
+        callback = cast(
+            Callable[[InitializeContext], Awaitable[object]],
+            descriptor.instance.initialize,
+        )
+        await self._invoke_start_hook(
+            descriptor,
+            stage,
+            lambda: callback(context),
+        )
+
+    async def _invoke_post_initialize(self, descriptor: ModuleDescriptor) -> None:
+        stage = LifecycleStage.POST_INITIALIZE
+        context = PostInitializeContext(
+            application_id=self._root.application_id,
+            descriptor=descriptor,
+            stage=stage,
+            application=self._root.view(self._root.state),
+            _emit=self._root.diagnostic_emitter(descriptor, stage),
+            configuration=self._root.configuration,
+            options=self._root.require_options(),
+            container=self._root.require_container(),
+        )
+        callback = cast(
+            Callable[[PostInitializeContext], Awaitable[object]],
+            descriptor.instance.post_initialize,
+        )
+        await self._invoke_start_hook(
+            descriptor,
+            stage,
+            lambda: callback(context),
+        )
+
+    async def _invoke_start_hook(
+        self,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+        callback: Callable[[], Awaitable[object]],
+    ) -> None:
+        subject = str(descriptor.key)
+        self._root.runtime_touched.add(descriptor.key)
+        active_event = self._root.journal.start_event(
+            phase=LifecyclePhase.RUNTIME,
+            stage=stage,
+            subject=subject,
+            source=descriptor.declaration_source,
+        )
+        try:
+            result = await callback()
+            self._validate_lifecycle_result(
+                result,
+                descriptor=descriptor,
+                phase=LifecyclePhase.RUNTIME,
+                stage=stage,
+            )
+        except BaseException as original_error:
+            # cancellation/system error 也必须结构化，start 才能统一回滚 touched Modules。
+            failure_id = self._root.journal.begin_failure(
+                error_type=LIFECYCLE_ERROR_TYPE,
+                phase=LifecyclePhase.RUNTIME,
+                stage=stage,
+                subject=subject,
+                message=_lifecycle_failure_message(subject, stage, original_error),
+                source=descriptor.declaration_source,
+                dependency_path=tuple(str(key) for key in descriptor.dependency_path),
+            )
+            duration_ns = self._root.journal.finish_event(
+                active_event,
+                status=EventStatus.FAILED,
+                failure_id=failure_id,
+            )
+            error = LifecycleInvocationError(
+                failure_id=failure_id,
+                module=descriptor.key,
+                phase=LifecyclePhase.RUNTIME,
+                stage=stage,
+                dependency_path=descriptor.dependency_path,
+                duration_ns=duration_ns,
+                source=descriptor.declaration_source,
+                original_error=original_error,
+            )
+            raise error from original_error
+
+        self._root.journal.finish_event(
+            active_event,
+            status=EventStatus.SUCCEEDED,
+            failure_id=None,
+        )
+        self._root.completed_stages[descriptor.key].append(stage)
+
+    async def _invoke_shutdown(
+        self,
+        descriptor: ModuleDescriptor,
+        context: ShutdownContext,
+    ) -> LifecycleInvocationError | None:
+        stage = LifecycleStage.SHUTDOWN
+        subject = str(descriptor.key)
+        active_event = self._root.journal.start_event(
+            phase=LifecyclePhase.CLEANUP,
+            stage=stage,
+            subject=subject,
+            source=descriptor.declaration_source,
+        )
+        try:
+            callback = cast(
+                Callable[[ShutdownContext], Awaitable[object]],
+                descriptor.instance.shutdown,
+            )
+            result = await callback(context)
+            self._validate_lifecycle_result(
+                result,
+                descriptor=descriptor,
+                phase=LifecyclePhase.CLEANUP,
+                stage=stage,
+            )
+        except BaseException as original_error:
+            # cleanup 首个 cancellation/system error 不能阻止后续 Module 获得释放机会。
+            failure_id = self._root.journal.begin_failure(
+                error_type=LIFECYCLE_ERROR_TYPE,
+                phase=LifecyclePhase.CLEANUP,
+                stage=stage,
+                subject=subject,
+                message=_lifecycle_failure_message(subject, stage, original_error),
+                source=descriptor.declaration_source,
+                dependency_path=tuple(str(key) for key in descriptor.dependency_path),
+            )
+            duration_ns = self._root.journal.finish_event(
+                active_event,
+                status=EventStatus.FAILED,
+                failure_id=failure_id,
+            )
+            error = LifecycleInvocationError(
+                failure_id=failure_id,
+                module=descriptor.key,
+                phase=LifecyclePhase.CLEANUP,
+                stage=stage,
+                dependency_path=descriptor.dependency_path,
+                duration_ns=duration_ns,
+                source=descriptor.declaration_source,
+                original_error=original_error,
+            )
+            self._root.journal.complete_failure(failure_id)
+            return error
+
+        self._root.journal.finish_event(
+            active_event,
+            status=EventStatus.SUCCEEDED,
+            failure_id=None,
+        )
+        self._root.completed_stages[descriptor.key].append(stage)
+        return None
+
+    @staticmethod
+    def _validate_lifecycle_result(
+        result: object,
+        *,
+        descriptor: ModuleDescriptor,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+    ) -> None:
+        if result is None:
+            return
+        if inspect.iscoroutine(result):
+            result.close()
+        returned_type = f"{type(result).__module__}.{type(result).__qualname__}"
+        raise LifecycleReturnValueError(
+            module=descriptor.key,
+            phase=phase,
+            stage=stage,
+            returned_type=returned_type,
+        )

python_platform/application/state.py

@@ -0,0 +1,216 @@
+"""Single-Application mutable root、read-only views 与 transition ownership。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import assert_never
+from uuid import UUID
+
+from dishka import AsyncContainer
+
+from ..application_services import ApplicationServiceCatalog
+from ..application_services.invocation import _InvocationRuntime
+from ..authorization import PermissionCatalog
+from ..background_jobs import BackgroundJobCatalog
+from ..background_workers import BackgroundWorkerCatalog
+from ..background_workers.runtime import _BackgroundCoordinator
+from ..caching import CacheCatalog
+from ..configuration import ConfigurationRoot
+from ..diagnostics import LifecyclePhase, LifecycleStage
+from ..diagnostics.journal import _DiagnosticJournal
+from ..errors import ApplicationRuntimeError, InvalidApplicationStateError, LifecycleInvocationError
+from ..events import LocalEventCatalog
+from ..events.contribution import EventContributionRegistry
+from ..hosted_services import ApplicationReadinessSnapshot, HostedServiceCatalog
+from ..hosted_services.runtime import _HostedServiceCoordinator
+from ..lifecycle import ApplicationState, ApplicationView
+from ..modularity import ModuleDescriptor, ModuleKey, ModuleRegistry
+from ..options import OptionsSnapshot, PreOptionsSnapshot
+from ..options.registry import _OptionsRegistry
+from ..services import ServiceCatalog
+from ..services.contribution import ServiceContributionRegistry
+from ..settings import SettingCatalog
+
+LIFECYCLE_ERROR_TYPE = LifecycleInvocationError.__name__
+
+
+@dataclass(slots=True)
+class _ApplicationStateRoot:
+    """所有可变事实的唯一 owner；Application 之间不共享容器、状态或 journal。"""
+
+    application_id: UUID
+    registry: ModuleRegistry
+    configuration: ConfigurationRoot
+    pre_options_registry: _OptionsRegistry
+    options_registry: _OptionsRegistry
+    service_registry: ServiceContributionRegistry
+    event_registry: EventContributionRegistry
+    permission_catalog: PermissionCatalog
+    cache_catalog: CacheCatalog
+    setting_catalog: SettingCatalog
+    background_worker_catalog: BackgroundWorkerCatalog
+    background_job_catalog: BackgroundJobCatalog
+    hosted_service_catalog: HostedServiceCatalog
+    journal: _DiagnosticJournal
+    pre_options: PreOptionsSnapshot | None = None
+    options: OptionsSnapshot | None = None
+    service_catalog: ServiceCatalog | None = None
+    application_service_catalog: ApplicationServiceCatalog | None = None
+    event_catalog: LocalEventCatalog | None = None
+    invocation_runtime: _InvocationRuntime | None = None
+    background_coordinator: _BackgroundCoordinator | None = None
+    hosted_service_coordinator: _HostedServiceCoordinator | None = None
+    container: AsyncContainer | None = None
+    state: ApplicationState = ApplicationState.COMPOSED
+    transition_token: object | None = None
+    runtime_touched: set[ModuleKey] = field(default_factory=set)
+    released_modules: set[ModuleKey] = field(default_factory=set)
+    completed_stages: dict[ModuleKey, list[LifecycleStage]] = field(default_factory=dict)
+    termination_event: asyncio.Event = field(default_factory=asyncio.Event)
+    runtime_failure: ApplicationRuntimeError | None = None
+    termination_failure: BaseException | None = None
+    runtime_monitor_task: asyncio.Task[None] | None = None
+
+    def require_pre_options(self) -> PreOptionsSnapshot:
+        if self.pre_options is None:
+            raise RuntimeError(
+                "PreOptions snapshot is unavailable before the pre_configure barrier"
+            )
+        return self.pre_options
+
+    def require_options(self) -> OptionsSnapshot:
+        if self.options is None:
+            raise RuntimeError("Options snapshot is unavailable before composition completes")
+        return self.options
+
+    def require_service_catalog(self) -> ServiceCatalog:
+        if self.service_catalog is None:
+            raise RuntimeError("Service catalog is unavailable before composition completes")
+        return self.service_catalog
+
+    def require_container(self) -> AsyncContainer:
+        if self.container is None:
+            raise RuntimeError("Dishka container is unavailable after Application cleanup")
+        return self.container
+
+    def require_application_service_catalog(self) -> ApplicationServiceCatalog:
+        if self.application_service_catalog is None:
+            raise RuntimeError(
+                "Application Service catalog is unavailable before composition completes"
+            )
+        return self.application_service_catalog
+
+    def require_event_catalog(self) -> LocalEventCatalog:
+        if self.event_catalog is None:
+            raise RuntimeError("Local Event catalog is unavailable before composition completes")
+        return self.event_catalog
+
+    def require_permission_catalog(self) -> PermissionCatalog:
+        return self.permission_catalog
+
+    def require_cache_catalog(self) -> CacheCatalog:
+        return self.cache_catalog
+
+    def require_setting_catalog(self) -> SettingCatalog:
+        return self.setting_catalog
+
+    def require_background_worker_catalog(self) -> BackgroundWorkerCatalog:
+        return self.background_worker_catalog
+
+    def require_background_job_catalog(self) -> BackgroundJobCatalog:
+        return self.background_job_catalog
+
+    def require_invocation_runtime(self) -> _InvocationRuntime:
+        if self.invocation_runtime is None:
+            raise RuntimeError("Application invocation runtime is unavailable")
+        return self.invocation_runtime
+
+    def require_background_coordinator(self) -> _BackgroundCoordinator:
+        if self.background_coordinator is None:
+            raise RuntimeError("Application background coordinator is unavailable")
+        return self.background_coordinator
+
+    def require_hosted_service_catalog(self) -> HostedServiceCatalog:
+        return self.hosted_service_catalog
+
+    def require_hosted_service_coordinator(self) -> _HostedServiceCoordinator:
+        if self.hosted_service_coordinator is None:
+            raise RuntimeError("Hosted Service coordinator is unavailable")
+        return self.hosted_service_coordinator
+
+    def readiness(self) -> ApplicationReadinessSnapshot:
+        return self.require_hosted_service_coordinator().readiness()
+
+    def view(self, state: ApplicationState | None) -> ApplicationView:
+        return ApplicationView(
+            application_id=self.application_id,
+            state=state,
+            modules=self.registry.snapshot,
+        )
+
+    def diagnostic_emitter(
+        self,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+    ) -> Callable[[str], None]:
+        phase = _phase_for_stage(stage)
+
+        def emit(code: str) -> None:
+            self.journal.emit(
+                phase=phase,
+                stage=stage,
+                subject=str(descriptor.key),
+                code=code,
+                source=descriptor.declaration_source,
+            )
+
+        return emit
+
+    def claim_transition(
+        self,
+        *,
+        operation: str,
+        allowed: tuple[ApplicationState, ...],
+    ) -> object:
+        # claim 在首次 await 前完成；并发调用立即失败，不排队改变调用者语义。
+        if self.transition_token is not None or self.state not in allowed:
+            raise InvalidApplicationStateError(
+                operation=operation,
+                current=self.state,
+                allowed=allowed,
+            )
+        token = object()
+        self.transition_token = token
+        return token
+
+    def release_transition(self, token: object) -> None:
+        assert self.transition_token is token
+        self.transition_token = None
+
+
+def _phase_for_stage(stage: LifecycleStage) -> LifecyclePhase:
+    match stage:
+        case (
+            LifecycleStage.PRE_CONFIGURE | LifecycleStage.CONFIGURE | LifecycleStage.POST_CONFIGURE
+        ):
+            return LifecyclePhase.COMPOSITION
+        case (
+            LifecycleStage.PRE_INITIALIZE
+            | LifecycleStage.INITIALIZE
+            | LifecycleStage.POST_INITIALIZE
+        ):
+            return LifecyclePhase.RUNTIME
+        case LifecycleStage.SHUTDOWN:
+            return LifecyclePhase.CLEANUP
+        case _ as unreachable:
+            assert_never(unreachable)
+
+
+def _lifecycle_failure_message(
+    subject: str,
+    stage: LifecycleStage,
+    original_error: BaseException,
+) -> str:
+    return f"{subject}/{stage.value} failed with {type(original_error).__name__}"

python_platform/application_services/__init__.py

@@ -0,0 +1,54 @@
+from ..invocation import ApplicationInvocationContext
+from .catalog import (
+    ApplicationServiceCatalog,
+    ApplicationServiceMethod,
+    ApplicationServiceRegistration,
+)
+from .contracts import (
+    ApplicationService,
+    ApplicationServiceContract,
+    IntegrationService,
+    application_service,
+)
+from .errors import (
+    ApplicationInvocationCleanupError,
+    ApplicationInvocationRejectedError,
+    ApplicationServiceDefinitionError,
+    ApplicationServiceMethodError,
+    ApplicationServiceValidationError,
+    ApplicationServiceValidationIssue,
+    CrossTaskInvocationError,
+    NestedConnectionError,
+)
+from .execution import MethodInvocation
+from .interceptors import InterceptionStage, Interceptor, InterceptorRegistration
+from .policies import disable_validation, enable_validation
+from .seeding import DataSeedContributor, DataSeeder, DataSeedError
+
+__all__ = (
+    "ApplicationInvocationCleanupError",
+    "ApplicationInvocationContext",
+    "ApplicationInvocationRejectedError",
+    "ApplicationService",
+    "ApplicationServiceCatalog",
+    "ApplicationServiceContract",
+    "ApplicationServiceDefinitionError",
+    "ApplicationServiceMethod",
+    "ApplicationServiceMethodError",
+    "ApplicationServiceRegistration",
+    "ApplicationServiceValidationError",
+    "ApplicationServiceValidationIssue",
+    "CrossTaskInvocationError",
+    "DataSeedContributor",
+    "DataSeedError",
+    "DataSeeder",
+    "IntegrationService",
+    "InterceptionStage",
+    "Interceptor",
+    "InterceptorRegistration",
+    "MethodInvocation",
+    "NestedConnectionError",
+    "application_service",
+    "disable_validation",
+    "enable_validation",
+)