pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/lifecycle/manager.py

@@ -0,0 +1,533 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+import inspect
+from typing import Any, TYPE_CHECKING
+from typing import Literal
+
+from pz_core.runtime.errors import PzError, as_pz_error
+from pz_core.runtime.plan_context import active_runtime_plan
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityState, CapabilityStatus
+from pz_core.core.extensions import LifecycleContributionSpec
+
+if TYPE_CHECKING:
+    from pz_core.runtime.bindings import RuntimeBindings
+
+LifecyclePhase = Literal["declared", "compiled", "bound", "started", "stopped"]
+
+
+def _activate_status(status: CapabilityStatus) -> CapabilityStatus:
+    if status == "enabled":
+        return "ready"
+    return status
+
+
+def _deactivate_status(status: CapabilityStatus) -> CapabilityStatus:
+    if status == "ready":
+        return "enabled"
+    return status
+
+
+@dataclass(frozen=True, slots=True)
+class AppLifecycleState:
+    app_id: str
+    phase: LifecyclePhase
+
+
+@dataclass(frozen=True, slots=True)
+class LifecycleState:
+    phase: LifecyclePhase = "declared"
+    active: bool = False
+    capability_states: tuple[CapabilityState, ...] = field(default_factory=tuple)
+    app_states: tuple[AppLifecycleState, ...] = field(default_factory=tuple)
+
+    @property
+    def activated_capabilities(self) -> tuple[str, ...]:
+        return tuple(
+            capability.name
+            for capability in self.capability_states
+            if capability.status == "ready"
+        )
+
+    def get(self, name: str) -> CapabilityState | None:
+        for capability in self.capability_states:
+            if capability.name == name:
+                return capability
+        return None
+
+    def get_app(self, app_id: str) -> AppLifecycleState | None:
+        for app in self.app_states:
+            if app.app_id == app_id:
+                return app
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeContext:
+    plan: RuntimePlan
+    bindings: "RuntimeBindings"
+    lifecycle: LifecycleState
+
+
+def _call_handler(
+    item: LifecycleContributionSpec,
+    *,
+    host: object | None,
+    context: RuntimeContext,
+) -> None:
+    hook = item.handler
+    if not callable(hook):
+        raise PzError(
+            code="PZ_LIFECYCLE_HANDLER_INVALID",
+            message=f"Lifecycle contribution '{item.id}' exposes a non-callable handler.",
+            stage="lifecycle",
+            owner=item.owner_app,
+            action=item.phase,
+        )
+    signature = inspect.signature(hook)
+    param_count = len(signature.parameters)
+    try:
+        if param_count == 0:
+            result = hook()
+        elif param_count == 1:
+            result = hook(context)
+        else:
+            result = hook(host, context)
+        if inspect.isawaitable(result):
+            try:
+                asyncio.get_running_loop()
+            except RuntimeError:
+                asyncio.run(result)
+                return
+            raise PzError(
+                code="PZ_LIFECYCLE_HANDLER_ASYNC_IN_RUNNING_LOOP",
+                message=(
+                    f"Lifecycle contribution '{item.id}' returned an awaitable inside a running loop. "
+                    "Use the runtime's explicit async host integration instead."
+                ),
+                stage="lifecycle",
+                owner=item.owner_app,
+                action=item.phase,
+            )
+    except PzError:
+        raise
+    except Exception as exc:
+        raise PzError(
+            code="PZ_LIFECYCLE_HANDLER_FAILED",
+            message=f"Lifecycle contribution '{item.id}' failed.",
+            stage="lifecycle",
+            owner=item.owner_app,
+            action=item.phase,
+            summary=f"Lifecycle contribution '{item.id}' failed.",
+            detail=str(exc) or exc.__class__.__name__,
+        ) from exc
+
+
+async def _call_handler_async(
+    item: LifecycleContributionSpec,
+    *,
+    host: object | None,
+    context: RuntimeContext,
+) -> None:
+    hook = item.handler
+    if not callable(hook):
+        raise PzError(
+            code="PZ_LIFECYCLE_HANDLER_INVALID",
+            message=f"Lifecycle contribution '{item.id}' exposes a non-callable handler.",
+            stage="lifecycle",
+            owner=item.owner_app,
+            action=item.phase,
+        )
+    signature = inspect.signature(hook)
+    param_count = len(signature.parameters)
+    try:
+        if param_count == 0:
+            result = hook()
+        elif param_count == 1:
+            result = hook(context)
+        else:
+            result = hook(host, context)
+        if inspect.isawaitable(result):
+            await result
+    except PzError:
+        raise
+    except Exception as exc:
+        raise PzError(
+            code="PZ_LIFECYCLE_HANDLER_FAILED",
+            message=f"Lifecycle contribution '{item.id}' failed.",
+            stage="lifecycle",
+            owner=item.owner_app,
+            action=item.phase,
+            summary=f"Lifecycle contribution '{item.id}' failed.",
+            detail=str(exc) or exc.__class__.__name__,
+        ) from exc
+
+
+def _rollback_startup_failure(
+    plan: RuntimePlan,
+    *,
+    startup_items: tuple[LifecycleContributionSpec, ...],
+    started_owners: list[str],
+    bindings: "RuntimeBindings",
+    host: object | None,
+) -> tuple[PzError, ...]:
+    rollback_errors: list[PzError] = []
+    rollback_state = LifecycleState(
+        phase="stopped",
+        active=False,
+        capability_states=tuple(
+            CapabilityState(
+                name=capability.name,
+                owner=capability.owner,
+                status=_deactivate_status(capability.status),
+                reason=capability.reason,
+            )
+            for capability in plan.capability_registry.capabilities
+        ),
+        app_states=tuple(
+            AppLifecycleState(app_id=app.app_id, phase="stopped")
+            for app in plan.app_registry.apps
+        ),
+    )
+    context = RuntimeContext(plan=plan, bindings=bindings, lifecycle=rollback_state)
+    for item in reversed(tuple(plan.lifecycle_manifest.for_phase("shutdown"))):
+        if item.owner_app not in started_owners:
+            continue
+        try:
+            _call_handler(item, host=host, context=context)
+        except Exception as exc:
+            rollback_errors.append(
+                as_pz_error(
+                    exc,
+                    code="PZ_LIFECYCLE_ROLLBACK_FAILED",
+                    stage="lifecycle",
+                    owner=item.owner_app,
+                    action="shutdown",
+                )
+            )
+        finally:
+            bindings.providers.reset(owner=item.owner_app)
+            bindings.events.reset(owner=item.owner_app)
+    bindings.providers.reset()
+    bindings.events.reset()
+    return tuple(rollback_errors)
+
+
+def _merge_rollback_errors(exc: Exception, rollback_errors: tuple[PzError, ...]) -> PzError:
+    error = as_pz_error(
+        exc,
+        stage="lifecycle",
+        owner="runtime.lifecycle",
+        action="activate_runtime_plan",
+    )
+    if not rollback_errors:
+        return error
+    fragments: list[str] = []
+    if error.detail:
+        fragments.append(error.detail)
+    for rollback_error in rollback_errors:
+        fragments.append(
+            f"rollback[{rollback_error.owner}:{rollback_error.action}:{rollback_error.code}] "
+            f"{rollback_error.summary or rollback_error.message}"
+        )
+    error.detail = " | ".join(fragment for fragment in fragments if fragment)
+    return error
+
+
+def _startup_items(plan: RuntimePlan) -> tuple[LifecycleContributionSpec, ...]:
+    return tuple(plan.lifecycle_manifest.for_phase("startup"))
+
+
+def compile_lifecycle_state(plan: RuntimePlan) -> LifecycleState:
+    return LifecycleState(
+        phase="compiled",
+        active=False,
+        capability_states=plan.capability_registry.capabilities,
+        app_states=tuple(
+            AppLifecycleState(app_id=app.app_id, phase="compiled")
+            for app in plan.app_registry.apps
+        ),
+    )
+
+
+def bind_runtime_plan(
+    plan: RuntimePlan,
+    state: LifecycleState | None = None,
+) -> LifecycleState:
+    source = state or compile_lifecycle_state(plan)
+    if source.phase == "stopped":
+        raise PzError(
+            code="PZ_LIFECYCLE_STOPPED_REBIND_FORBIDDEN",
+            message="Stopped lifecycle state cannot be rebound or reactivated.",
+            stage="lifecycle",
+            owner="runtime.lifecycle",
+            action="bind_runtime_plan",
+            summary="Stopped lifecycle state cannot be rebound or reactivated.",
+        )
+    if source.phase == "started":
+        return source
+    return LifecycleState(
+        phase="bound",
+        active=False,
+        capability_states=source.capability_states,
+        app_states=tuple(
+            AppLifecycleState(app_id=app.app_id, phase="bound")
+            for app in plan.app_registry.apps
+        ),
+    )
+
+
+def activate_runtime_plan(
+    plan: RuntimePlan,
+    state: LifecycleState | None = None,
+    *,
+    bindings: "RuntimeBindings" | None = None,
+    host: object | None = None,
+) -> LifecycleState:
+    if state is not None and state.phase == "started":
+        return state
+    from pz_core.runtime.settings import (
+        active_settings_project,
+        bind_settings_snapshot,
+        reset_settings_binding,
+    )
+
+    project_dir = str(plan.project.project_dir)
+    bind_settings_snapshot(plan.settings, project_dir=project_dir)
+    bound = bind_runtime_plan(plan, state)
+    activated = tuple(
+        CapabilityState(
+            name=capability.name,
+            owner=capability.owner,
+            status=_activate_status(capability.status),
+            reason=capability.reason,
+        )
+        for capability in bound.capability_states
+    )
+    started = LifecycleState(
+        phase="started",
+        active=True,
+        capability_states=activated,
+        app_states=tuple(
+            AppLifecycleState(app_id=app.app_id, phase="started")
+            for app in plan.app_registry.apps
+        ),
+    )
+    if bindings is not None:
+        with active_settings_project(project_dir), active_runtime_plan(plan):
+            context = RuntimeContext(plan=plan, bindings=bindings, lifecycle=started)
+            startup_items = _startup_items(plan)
+            started_owners: list[str] = []
+            try:
+                bindings.providers.activate_declared(
+                    plan=plan,
+                    bindings=bindings,
+                    host=host,
+                )
+                for item in startup_items:
+                    _call_handler(item, host=host, context=context)
+                    started_owners.append(item.owner_app)
+            except Exception as exc:
+                rollback_errors = _rollback_startup_failure(
+                    plan,
+                    startup_items=startup_items,
+                    started_owners=started_owners,
+                    bindings=bindings,
+                    host=host,
+                )
+                reset_settings_binding(project_dir)
+                raise _merge_rollback_errors(exc, rollback_errors) from exc
+    return started
+
+
+def shutdown_runtime_plan(
+    plan: RuntimePlan,
+    state: LifecycleState | None = None,
+    *,
+    bindings: "RuntimeBindings" | None = None,
+    host: object | None = None,
+) -> LifecycleState:
+    if state and state.phase == "stopped":
+        return state
+    from pz_core.runtime.settings import (
+        active_settings_project,
+        reset_settings_binding,
+    )
+
+    project_dir = str(plan.project.project_dir)
+    source_state = state or bind_runtime_plan(plan)
+    source = source_state.capability_states if state else plan.capability_registry.capabilities
+    deactivated = tuple(
+        CapabilityState(
+            name=capability.name,
+            owner=capability.owner,
+            status=_deactivate_status(capability.status),
+            reason=capability.reason,
+        )
+        for capability in source
+    )
+    stopped = LifecycleState(
+        phase="stopped",
+        active=False,
+        capability_states=deactivated,
+        app_states=tuple(
+            AppLifecycleState(app_id=app.app_id, phase="stopped")
+            for app in plan.app_registry.apps
+        ),
+    )
+    if bindings is not None:
+        with active_settings_project(project_dir), active_runtime_plan(plan):
+            context = RuntimeContext(plan=plan, bindings=bindings, lifecycle=stopped)
+            for item in reversed(tuple(plan.lifecycle_manifest.for_phase("shutdown"))):
+                _call_handler(item, host=host, context=context)
+                bindings.providers.reset(owner=item.owner_app)
+                bindings.events.reset(owner=item.owner_app)
+            bindings.providers.reset()
+            bindings.events.reset()
+    reset_settings_binding(project_dir)
+    return stopped
+
+
+async def activate_runtime_plan_async(
+    plan: RuntimePlan,
+    state: LifecycleState | None = None,
+    *,
+    bindings: "RuntimeBindings" | None = None,
+    host: object | None = None,
+) -> LifecycleState:
+    if state is not None and state.phase == "started":
+        return state
+    from pz_core.runtime.settings import (
+        active_settings_project,
+        bind_settings_snapshot,
+        reset_settings_binding,
+    )
+
+    project_dir = str(plan.project.project_dir)
+    bind_settings_snapshot(plan.settings, project_dir=project_dir)
+    bound = bind_runtime_plan(plan, state)
+    activated = tuple(
+        CapabilityState(
+            name=capability.name,
+            owner=capability.owner,
+            status=_activate_status(capability.status),
+            reason=capability.reason,
+        )
+        for capability in bound.capability_states
+    )
+    started = LifecycleState(
+        phase="started",
+        active=True,
+        capability_states=activated,
+        app_states=tuple(
+            AppLifecycleState(app_id=app.app_id, phase="started")
+            for app in plan.app_registry.apps
+        ),
+    )
+    if bindings is not None:
+        with active_settings_project(project_dir), active_runtime_plan(plan):
+            context = RuntimeContext(plan=plan, bindings=bindings, lifecycle=started)
+            startup_items = _startup_items(plan)
+            started_owners: list[str] = []
+            try:
+                bindings.providers.activate_declared(
+                    plan=plan,
+                    bindings=bindings,
+                    host=host,
+                )
+                for item in startup_items:
+                    await _call_handler_async(item, host=host, context=context)
+                    started_owners.append(item.owner_app)
+            except Exception as exc:
+                rollback_errors: list[PzError] = []
+                rollback_state = LifecycleState(
+                    phase="stopped",
+                    active=False,
+                    capability_states=tuple(
+                        CapabilityState(
+                            name=capability.name,
+                            owner=capability.owner,
+                            status=_deactivate_status(capability.status),
+                            reason=capability.reason,
+                        )
+                        for capability in plan.capability_registry.capabilities
+                    ),
+                    app_states=tuple(
+                        AppLifecycleState(app_id=app.app_id, phase="stopped")
+                        for app in plan.app_registry.apps
+                    ),
+                )
+                rollback_context = RuntimeContext(plan=plan, bindings=bindings, lifecycle=rollback_state)
+                for item in reversed(tuple(plan.lifecycle_manifest.for_phase("shutdown"))):
+                    if item.owner_app not in started_owners:
+                        continue
+                    try:
+                        await _call_handler_async(item, host=host, context=rollback_context)
+                    except Exception as rollback_exc:
+                        rollback_errors.append(
+                            as_pz_error(
+                                rollback_exc,
+                                code="PZ_LIFECYCLE_ROLLBACK_FAILED",
+                                stage="lifecycle",
+                                owner=item.owner_app,
+                                action="shutdown",
+                            )
+                        )
+                    finally:
+                        bindings.providers.reset(owner=item.owner_app)
+                        bindings.events.reset(owner=item.owner_app)
+                bindings.providers.reset()
+                bindings.events.reset()
+                reset_settings_binding(project_dir)
+                raise _merge_rollback_errors(exc, tuple(rollback_errors)) from exc
+    return started
+
+
+async def shutdown_runtime_plan_async(
+    plan: RuntimePlan,
+    state: LifecycleState | None = None,
+    *,
+    bindings: "RuntimeBindings" | None = None,
+    host: object | None = None,
+) -> LifecycleState:
+    if state and state.phase == "stopped":
+        return state
+    from pz_core.runtime.settings import (
+        active_settings_project,
+        reset_settings_binding,
+    )
+
+    project_dir = str(plan.project.project_dir)
+    source_state = state or bind_runtime_plan(plan)
+    source = source_state.capability_states if state else plan.capability_registry.capabilities
+    deactivated = tuple(
+        CapabilityState(
+            name=capability.name,
+            owner=capability.owner,
+            status=_deactivate_status(capability.status),
+            reason=capability.reason,
+        )
+        for capability in source
+    )
+    stopped = LifecycleState(
+        phase="stopped",
+        active=False,
+        capability_states=deactivated,
+        app_states=tuple(
+            AppLifecycleState(app_id=app.app_id, phase="stopped")
+            for app in plan.app_registry.apps
+        ),
+    )
+    if bindings is not None:
+        with active_settings_project(project_dir), active_runtime_plan(plan):
+            context = RuntimeContext(plan=plan, bindings=bindings, lifecycle=stopped)
+            for item in reversed(tuple(plan.lifecycle_manifest.for_phase("shutdown"))):
+                await _call_handler_async(item, host=host, context=context)
+                bindings.providers.reset(owner=item.owner_app)
+                bindings.events.reset(owner=item.owner_app)
+            bindings.providers.reset()
+            bindings.events.reset()
+    reset_settings_binding(project_dir)
+    return stopped