pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/plan.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, Iterable
+
+from pz_core.assembly.apps import AppRegistry, compile_app_registry, compile_provider_declarations
+from pz_core.assembly.cli import CliManifest, compile_cli_manifest
+from pz_core.assembly.events import compile_event_registry
+from pz_core.assembly.extensions import compile_extension_registry
+from pz_core.assembly.infra import compile_infra_context
+from pz_core.assembly.lifecycle import LifecycleManifest, compile_lifecycle_manifest
+from pz_core.assembly.middlewares import MiddlewareManifest, compile_middleware_manifest
+from pz_core.assembly.project import active_project_import_root, compile_project_context
+from pz_core.assembly.resources import ResourceManifest, compile_resource_manifest
+from pz_core.assembly.routes import RouteManifest, compile_route_manifest
+from pz_core.assembly.runtime_manifests import RuntimeManifestMap, compile_runtime_manifests
+from pz_core.assembly.settings import SettingsSnapshot, compile_settings_snapshot
+from pz_core.assembly.project import ProjectContext
+from pz_core.core.events import EventRegistry
+from pz_core.core.extensions import ExtensionRegistry, HostBuilderSpec, SettingsProviderSpec
+from pz_core.infra.settings import InfraContext
+from pz_core.runtime.plan_context import active_runtime_plan
+from pz_core.runtime.registries import CapabilityRegistry, build_capability_registry
+from pz_core.runtime.registries import ProviderDecl, ProviderRegistry
+from pz_core.runtime.settings import (
+    active_settings_project,
+    bound_settings_snapshot,
+)
+
+
+def _compile_host_builder_specs(extension_registry: ExtensionRegistry) -> tuple[HostBuilderSpec, ...]:
+    return tuple(
+        item
+        for item in extension_registry.by_kind("host.builder")
+        if isinstance(item, HostBuilderSpec)
+    )
+
+
+def _compile_settings_provider_specs(extension_registry: ExtensionRegistry) -> tuple[SettingsProviderSpec, ...]:
+    return tuple(
+        item
+        for item in extension_registry.by_kind("settings.provider")
+        if isinstance(item, SettingsProviderSpec)
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimePlan:
+    project: ProjectContext
+    settings: SettingsSnapshot
+    app_registry: AppRegistry
+    event_registry: EventRegistry
+    extension_registry: ExtensionRegistry
+    host_builders: tuple[HostBuilderSpec, ...]
+    settings_providers: tuple[SettingsProviderSpec, ...]
+    provider_declarations: tuple[ProviderDecl, ...]
+    lifecycle_manifest: LifecycleManifest
+    resource_manifest: ResourceManifest
+    cli_manifest: CliManifest
+    infra: InfraContext
+    route_manifest: RouteManifest
+    middleware_manifest: MiddlewareManifest
+    runtime_manifests: RuntimeManifestMap
+    capability_registry: CapabilityRegistry
+    extension_conflicts: tuple[dict[str, Any], ...] = ()
+
+
+def _build_resource_outputs_for_runtime_manifest(
+    *,
+    project: ProjectContext,
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry,
+    event_registry: EventRegistry,
+    extension_registry: ExtensionRegistry,
+    host_builders: tuple[HostBuilderSpec, ...],
+    settings_providers: tuple[SettingsProviderSpec, ...],
+    provider_declarations: tuple[ProviderDecl, ...],
+    lifecycle_manifest: LifecycleManifest,
+    resource_manifest: ResourceManifest,
+) -> None:
+    resource_provider_declarations = tuple(
+        declaration
+        for declaration in provider_declarations
+        if declaration.capability == "resources"
+    )
+    if not resource_provider_declarations:
+        return
+    provider_registry = ProviderRegistry(resource_provider_declarations)
+    providers = SimpleNamespace(
+        activate_declared=provider_registry.activate_declared,
+        require=provider_registry.require,
+        status=provider_registry.status,
+    )
+    bindings = SimpleNamespace(providers=providers)
+    build_plan = SimpleNamespace(
+        project=project,
+        settings=settings,
+        app_registry=app_registry,
+        event_registry=event_registry,
+        extension_registry=extension_registry,
+        host_builders=host_builders,
+        settings_providers=settings_providers,
+        provider_declarations=provider_declarations,
+        lifecycle_manifest=lifecycle_manifest,
+        resource_manifest=resource_manifest,
+        runtime_manifests={},
+    )
+    with active_runtime_plan(build_plan):
+        providers.activate_declared(
+            plan=build_plan,
+            bindings=bindings,
+            host=None,
+            owner="pz_foundation",
+        )
+        provider = providers.require("resources")
+        build = getattr(provider, "build", None)
+        if not callable(build):
+            from pz_core.runtime.errors import PzError
+
+            raise PzError(
+                code="PZ_RESOURCE_PROVIDER_INVALID",
+                message="Registered resources provider does not expose build().",
+                stage="resources",
+                owner="runtime.resources",
+                action="compile_runtime_plan",
+            )
+        build()
+
+
+def compile_runtime_plan(
+    project_dir: Path | str | None = None,
+    *,
+    installed_apps: Iterable[str] | None = None,
+    include_cli_manifest: bool = True,
+) -> RuntimePlan:
+    project = compile_project_context(project_dir=project_dir)
+    settings = compile_settings_snapshot(project)
+    if installed_apps is not None:
+        settings = settings.with_installed_apps(tuple(installed_apps))
+
+    with (
+        bound_settings_snapshot(settings, project_dir=project.project_dir),
+        active_settings_project(project.project_dir),
+        active_project_import_root(
+            project.project_dir,
+            extra_import_roots=settings.import_roots,
+            preserve_loaded_modules=True,
+        ),
+    ):
+        app_registry = compile_app_registry(settings, project_dir=project.project_dir)
+        extension_registry = compile_extension_registry(settings, app_registry)
+        event_registry = compile_event_registry(settings, extension_registry)
+        host_builders = _compile_host_builder_specs(extension_registry)
+        settings_providers = _compile_settings_provider_specs(extension_registry)
+        provider_declarations = compile_provider_declarations(settings, app_registry)
+        lifecycle_manifest = compile_lifecycle_manifest(app_registry, extension_registry)
+        resource_manifest = compile_resource_manifest(
+            project,
+            settings,
+            app_registry,
+            extension_registry=extension_registry,
+        )
+        _build_resource_outputs_for_runtime_manifest(
+            project=project,
+            settings=settings,
+            app_registry=app_registry,
+            event_registry=event_registry,
+            extension_registry=extension_registry,
+            host_builders=host_builders,
+            settings_providers=settings_providers,
+            provider_declarations=provider_declarations,
+            lifecycle_manifest=lifecycle_manifest,
+            resource_manifest=resource_manifest,
+        )
+        cli_manifest = (
+            compile_cli_manifest(app_registry, resource_manifest)
+            if include_cli_manifest
+            else CliManifest(commands=())
+        )
+        infra = compile_infra_context(settings, project, extension_registry=extension_registry)
+        route_manifest = compile_route_manifest(settings)
+        middleware_manifest = compile_middleware_manifest(settings, app_registry)
+        runtime_manifests = compile_runtime_manifests(
+            project=project,
+            settings=settings,
+            app_registry=app_registry,
+            extension_registry=extension_registry,
+            resource_manifest=resource_manifest,
+        )
+        capability_registry = build_capability_registry(infra=infra, app_registry=app_registry)
+
+    return RuntimePlan(
+        project=project,
+        settings=settings,
+        app_registry=app_registry,
+        event_registry=event_registry,
+        extension_registry=extension_registry,
+        host_builders=host_builders,
+        settings_providers=settings_providers,
+        provider_declarations=provider_declarations,
+        lifecycle_manifest=lifecycle_manifest,
+        resource_manifest=resource_manifest,
+        cli_manifest=cli_manifest,
+        infra=infra,
+        route_manifest=route_manifest,
+        middleware_manifest=middleware_manifest,
+        runtime_manifests=runtime_manifests,
+        capability_registry=capability_registry,
+    )
+
+
+__all__ = ["RuntimePlan", "compile_runtime_plan"]

pz_core/runtime/plan_context.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Iterator
+
+if TYPE_CHECKING:
+    from pz_core.runtime.plan import RuntimePlan
+
+
+_ACTIVE_RUNTIME_PLAN: ContextVar["RuntimePlan | None"] = ContextVar(
+    "pz_active_runtime_plan",
+    default=None,
+)
+
+
+@contextmanager
+def active_runtime_plan(plan: "RuntimePlan | None") -> Iterator[None]:
+    token = _ACTIVE_RUNTIME_PLAN.set(plan)
+    try:
+        yield
+    finally:
+        _ACTIVE_RUNTIME_PLAN.reset(token)
+
+
+def current_runtime_plan() -> "RuntimePlan | None":
+    return _ACTIVE_RUNTIME_PLAN.get()
+
+
+__all__ = [
+    "active_runtime_plan",
+    "current_runtime_plan",
+]

pz_core/runtime/plan_snapshot.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import pickle
+from typing import Any
+
+try:  # pragma: no cover - fcntl is unavailable on some platforms.
+    import fcntl
+except Exception:  # pragma: no cover
+    fcntl = None  # type: ignore[assignment]
+
+from pz_core.assembly.project import compile_project_context
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.plan import RuntimePlan
+
+
+RUNTIME_PLAN_SNAPSHOT_ENV = "PZ_RUNTIME_PLAN_SNAPSHOT"
+RUNTIME_PLAN_SNAPSHOT_ID_ENV = "PZ_RUNTIME_PLAN_SNAPSHOT_ID"
+
+
+def _snapshot_path(plan: RuntimePlan, *, invocation_id: str) -> Path:
+    safe_id = "".join(ch for ch in str(invocation_id or "").strip() if ch.isalnum() or ch in {"-", "_"})
+    if not safe_id:
+        raise PzError(
+            code="PZ_RUNTIME_PLAN_SNAPSHOT_ID_INVALID",
+            message="Runtime plan snapshot requires a non-empty runtime invocation id.",
+            stage="runtime",
+            owner="pz_core.runtime.plan_snapshot",
+            action="write_runtime_plan_snapshot",
+        )
+    return Path(plan.project.cache_dir) / "runtime_plan" / f"{safe_id}.pickle"
+
+
+def write_runtime_plan_snapshot(plan: RuntimePlan, *, invocation_id: str) -> Path:
+    if not isinstance(plan, RuntimePlan):
+        raise PzError(
+            code="PZ_RUNTIME_PLAN_SNAPSHOT_PLAN_INVALID",
+            message="Runtime plan snapshot requires a compiled RuntimePlan.",
+            stage="runtime",
+            owner="pz_core.runtime.plan_snapshot",
+            action="write_runtime_plan_snapshot",
+        )
+    path = _snapshot_path(plan, invocation_id=invocation_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    with tmp_path.open("wb") as handle:
+        pickle.dump(plan, handle, protocol=pickle.HIGHEST_PROTOCOL)
+    tmp_path.replace(path)
+    return path
+
+
+def runtime_plan_snapshot_path(
+    *,
+    project_dir: str | Path,
+    invocation_id: str,
+) -> Path:
+    project = compile_project_context(project_dir=project_dir)
+    return _snapshot_path_placeholder(project.cache_dir, invocation_id=invocation_id)
+
+
+def _snapshot_path_placeholder(cache_dir: Path, *, invocation_id: str) -> Path:
+    safe_id = "".join(ch for ch in str(invocation_id or "").strip() if ch.isalnum() or ch in {"-", "_"})
+    if not safe_id:
+        raise PzError(
+            code="PZ_RUNTIME_PLAN_SNAPSHOT_ID_INVALID",
+            message="Runtime plan snapshot requires a non-empty runtime invocation id.",
+            stage="runtime",
+            owner="pz_core.runtime.plan_snapshot",
+            action="runtime_plan_snapshot_path",
+        )
+    return Path(cache_dir) / "runtime_plan" / f"{safe_id}.pickle"
+
+
+def bind_runtime_plan_snapshot_env(path: str | Path | None) -> None:
+    if path is None:
+        os.environ.pop(RUNTIME_PLAN_SNAPSHOT_ENV, None)
+        return
+    snapshot_path = str(Path(path).resolve())
+    if not snapshot_path:
+        os.environ.pop(RUNTIME_PLAN_SNAPSHOT_ENV, None)
+        return
+    os.environ[RUNTIME_PLAN_SNAPSHOT_ENV] = snapshot_path
+
+
+def bind_runtime_plan_snapshot_invocation_env(invocation_id: str | None) -> None:
+    raw = str(invocation_id or "").strip()
+    if not raw:
+        os.environ.pop(RUNTIME_PLAN_SNAPSHOT_ID_ENV, None)
+        return
+    os.environ[RUNTIME_PLAN_SNAPSHOT_ID_ENV] = raw
+
+
+def load_runtime_plan_snapshot(path: str | Path | None = None) -> RuntimePlan | None:
+    raw_path: Any = path if path is not None else os.environ.get(RUNTIME_PLAN_SNAPSHOT_ENV)
+    if not isinstance(raw_path, (str, Path)) or not str(raw_path).strip():
+        return None
+    snapshot_path = Path(raw_path).resolve()
+    if not snapshot_path.is_file():
+        return None
+    try:
+        with snapshot_path.open("rb") as handle:
+            plan = pickle.load(handle)
+    except Exception as exc:
+        raise PzError(
+            code="PZ_RUNTIME_PLAN_SNAPSHOT_LOAD_FAILED",
+            message=f"Failed to load runtime plan snapshot '{snapshot_path}': {exc}",
+            stage="runtime",
+            owner="pz_core.runtime.plan_snapshot",
+            action="load_runtime_plan_snapshot",
+        ) from exc
+    if not isinstance(plan, RuntimePlan):
+        raise PzError(
+            code="PZ_RUNTIME_PLAN_SNAPSHOT_INVALID",
+            message=f"Runtime plan snapshot '{snapshot_path}' did not contain a RuntimePlan.",
+            stage="runtime",
+            owner="pz_core.runtime.plan_snapshot",
+            action="load_runtime_plan_snapshot",
+        )
+    return plan
+
+
+def write_runtime_plan_snapshot_if_requested(
+    plan: RuntimePlan,
+    *,
+    invocation_id: str | None = None,
+) -> Path | None:
+    raw_invocation_id = str(invocation_id or os.environ.get(RUNTIME_PLAN_SNAPSHOT_ID_ENV) or "").strip()
+    if not raw_invocation_id:
+        return None
+    if not isinstance(plan, RuntimePlan):
+        return None
+    snapshot_path = _snapshot_path(plan, invocation_id=raw_invocation_id)
+    if snapshot_path.is_file():
+        return snapshot_path
+    lock_path = Path(plan.project.runtime_dir) / "locks" / f"runtime-plan-{snapshot_path.stem}.lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = lock_path.open("a+", encoding="utf-8")
+    fallback_lock_dir: Path | None = None
+    try:
+        if fcntl is not None:
+            try:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                return None
+        else:  # pragma: no cover
+            fallback_lock_dir = lock_path.with_suffix(lock_path.suffix + ".d")
+            try:
+                fallback_lock_dir.mkdir(parents=False, exist_ok=False)
+            except FileExistsError:
+                return None
+        if snapshot_path.is_file():
+            return snapshot_path
+        return write_runtime_plan_snapshot(plan, invocation_id=raw_invocation_id)
+    finally:
+        try:
+            if fcntl is not None:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            handle.close()
+            if fallback_lock_dir is not None:
+                try:  # pragma: no cover
+                    fallback_lock_dir.rmdir()
+                except FileNotFoundError:  # pragma: no cover
+                    pass
+
+
+__all__ = [
+    "RUNTIME_PLAN_SNAPSHOT_ENV",
+    "RUNTIME_PLAN_SNAPSHOT_ID_ENV",
+    "bind_runtime_plan_snapshot_env",
+    "bind_runtime_plan_snapshot_invocation_env",
+    "load_runtime_plan_snapshot",
+    "runtime_plan_snapshot_path",
+    "write_runtime_plan_snapshot",
+    "write_runtime_plan_snapshot_if_requested",
+]

pz_core/runtime/registries/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from .capabilities import (
+    CapabilityRegistry,
+    CapabilityState,
+    CapabilityStatus,
+    build_capability_registry,
+)
+from .providers import (
+    ProviderActivationContext,
+    ProviderBinding,
+    ProviderDecl,
+    ProviderDiagnostic,
+    ProviderRegistry,
+)
+
+__all__ = [
+    "CapabilityRegistry",
+    "CapabilityState",
+    "CapabilityStatus",
+    "ProviderActivationContext",
+    "ProviderBinding",
+    "ProviderDecl",
+    "ProviderDiagnostic",
+    "ProviderRegistry",
+    "build_capability_registry",
+]

pz_core/runtime/registries/capabilities.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from pz_core.assembly.apps import AppRegistry
+from pz_core.infra.settings import InfraComponent, InfraContext
+
+CapabilityStatus = Literal["disabled", "enabled", "ready", "unavailable"]
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityState:
+    name: str
+    owner: str
+    status: CapabilityStatus
+    reason: str | None = None
+
+    @property
+    def enabled(self) -> bool:
+        return self.status in {"enabled", "ready", "unavailable"}
+
+    @property
+    def ready(self) -> bool:
+        return self.status == "ready"
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityRegistry:
+    capabilities: tuple[CapabilityState, ...]
+
+    def get(self, name: str) -> CapabilityState | None:
+        for capability in self.capabilities:
+            if capability.name == name:
+                return capability
+        return None
+
+    @property
+    def enabled_names(self) -> tuple[str, ...]:
+        return tuple(capability.name for capability in self.capabilities if capability.enabled)
+
+    @property
+    def ready_names(self) -> tuple[str, ...]:
+        return tuple(capability.name for capability in self.capabilities if capability.ready)
+
+    def statuses(self) -> dict[str, CapabilityStatus]:
+        return {capability.name: capability.status for capability in self.capabilities}
+
+
+def _component_status(component: InfraComponent) -> CapabilityStatus:
+    status = str(component.status or "").strip()
+    if status in {"disabled", "enabled", "ready", "unavailable"}:
+        return status  # type: ignore[return-value]
+    return "enabled" if component.enabled else "disabled"
+
+
+def _component_capability(
+    *,
+    name: str,
+    owner: str,
+    component: InfraComponent,
+) -> CapabilityState:
+    return CapabilityState(
+        name=name,
+        owner=owner,
+        status=_component_status(component),
+        reason=component.reason,
+    )
+
+
+def build_capability_registry(
+    *,
+    infra: InfraContext,
+    app_registry: AppRegistry,
+) -> CapabilityRegistry:
+    capabilities: list[CapabilityState] = []
+
+    capabilities.append(_component_capability(name="health", owner="runtime.health", component=infra.health))
+    capabilities.append(_component_capability(name="database", owner="infra.database", component=infra.database))
+    capabilities.append(_component_capability(name="cache", owner="infra.cache", component=infra.cache))
+    capabilities.append(_component_capability(name="metrics", owner="infra.metrics", component=infra.metrics))
+    capabilities.append(_component_capability(name="tracing", owner="infra.tracing", component=infra.tracing))
+    capabilities.append(_component_capability(name="storage", owner="infra.storage", component=infra.storage))
+    capabilities.append(
+        CapabilityState(
+            name="resources",
+            owner="assembly.resources",
+            status="ready",
+        )
+    )
+    capabilities.append(_component_capability(name="mail", owner="infra.mail", component=infra.mail))
+
+    for app in app_registry.apps:
+        capabilities.append(
+            CapabilityState(
+                name=f"app:{app.app_id}",
+                owner=app.module_path,
+                status="enabled",
+            )
+        )
+    return CapabilityRegistry(capabilities=tuple(capabilities))