pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/facades/providers.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.registries.providers import (
+    ProviderBinding,
+    ProviderActivationContext,
+    ProviderDecl,
+    ProviderDiagnostic,
+    ProviderRegistry,
+)
+
+
+@dataclass(slots=True)
+class ProviderFacade:
+    registry: ProviderRegistry
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.registry, ProviderRegistry):
+            raise PzError(
+                code="PZ_PROVIDER_REGISTRY_INVALID",
+                message="ProviderFacade requires a ProviderRegistry instance.",
+                stage="providers",
+                owner="runtime.providers",
+                action="bind_provider_facade",
+            )
+
+    def declared(self) -> tuple[ProviderDecl, ...]:
+        return self.registry.declared()
+
+    def declared_for(self, capability: str) -> tuple[ProviderDecl, ...]:
+        return self.registry.declared_for(capability)
+
+    def bindings(self) -> tuple[ProviderBinding, ...]:
+        return self.registry.bindings()
+
+    def bindings_for(self, capability: str) -> tuple[ProviderBinding, ...]:
+        return self.registry.bindings_for(capability)
+
+    def register(self, binding_id: str, provider: object) -> str:
+        return self.registry.register(binding_id, provider)
+
+    def unregister(self, token: str) -> bool:
+        return self.registry.unregister(token)
+
+    def reset(self, *, owner: str | None = None) -> int:
+        return self.registry.reset(owner=owner)
+
+    def activate_declared(
+        self,
+        *,
+        plan: object,
+        bindings: object,
+        host: object | None = None,
+        owner: str | None = None,
+    ) -> int:
+        return self.registry.activate_declared(
+            plan=plan,
+            bindings=bindings,
+            host=host,
+            owner=owner,
+        )
+
+    def require(self, capability: str) -> object:
+        return self.registry.require(capability)
+
+    def status(self, capability: str) -> str:
+        return self.registry.status(capability)
+
+    def failed_for(self, capability: str) -> tuple[ProviderDiagnostic, ...]:
+        return self.registry.failed_for(capability)
+
+    def diagnostics(self) -> tuple[ProviderDiagnostic, ...]:
+        return self.registry.diagnostics()

pz_core/runtime/facades/resources.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pz_core.assembly.resources import ResourceManifest, ResourceSource
+from pz_core.infra.resources import ResourceBuildPort, ResourceBuildResult
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.facades.providers import ProviderFacade
+
+
+class ResourceFacade:
+    def __init__(self, manifest: ResourceManifest, providers: ProviderFacade) -> None:
+        if not isinstance(manifest, ResourceManifest):
+            raise PzError(
+                code="PZ_RESOURCE_MANIFEST_INVALID",
+                message="ResourceFacade requires a ResourceManifest instance.",
+                stage="resources",
+                owner="runtime.resources",
+                action="bind_resource_facade",
+            )
+        if not hasattr(providers, "require"):
+            raise PzError(
+                code="PZ_RESOURCE_PROVIDERS_INVALID",
+                message="ResourceFacade providers must expose require().",
+                stage="resources",
+                owner="runtime.resources",
+                action="bind_resource_facade",
+            )
+        self._manifest = manifest
+        self._providers = providers
+
+    def status(self) -> str:
+        return self._providers.status("resources")
+
+    def manifest(self) -> ResourceManifest:
+        return self._manifest
+
+    def app_order(self) -> tuple[str, ...]:
+        return self._manifest.app_order
+
+    def sources(self) -> tuple[ResourceSource, ...]:
+        return self._manifest.sources
+
+    def build(self, *, force: bool = False) -> ResourceBuildResult:
+        provider = self._providers.require("resources")
+        if not isinstance(provider, ResourceBuildPort):
+            raise PzError(
+                code="PZ_RESOURCE_PROVIDER_INVALID",
+                message="Registered resources provider does not implement ResourceBuildPort.",
+                stage="resources",
+                owner="runtime.resources",
+                action="build",
+            )
+        return provider.build(force=force)

pz_core/runtime/facades/storage.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from pz_core.runtime.errors import PzError
+from pz_core.infra.storage import PresignInfo, StoragePort, StoredObject
+from pz_core.runtime.facades._capabilities import merged_capability_status
+from pz_core.runtime.access import get_runtime
+from pz_core.runtime.facades.providers import ProviderFacade
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+
+
+def _require_storage_key(key: str, *, action: str) -> str:
+    if not isinstance(key, str) or not key.strip():
+        raise PzError(
+            code="PZ_STORAGE_KEY_INVALID",
+            message="Storage key must be a non-empty string.",
+            stage="storage",
+            owner="runtime.storage",
+            action=action,
+        )
+    return key
+
+
+def _require_storage_mode(mode: str, *, action: str) -> str:
+    if not isinstance(mode, str) or not mode.strip():
+        raise PzError(
+            code="PZ_STORAGE_MODE_INVALID",
+            message="Storage mode must be a non-empty string.",
+            stage="storage",
+            owner="runtime.storage",
+            action=action,
+        )
+    return mode
+
+
+def _require_storage_method(method: str, *, action: str) -> str:
+    if not isinstance(method, str) or not method.strip():
+        raise PzError(
+            code="PZ_STORAGE_METHOD_INVALID",
+            message="Storage method must be a non-empty string.",
+            stage="storage",
+            owner="runtime.storage",
+            action=action,
+        )
+    return method
+
+
+def _require_storage_expires_in(expires_in: int | None, *, action: str) -> int | None:
+    if expires_in is None:
+        return None
+    if isinstance(expires_in, bool) or not isinstance(expires_in, int) or expires_in <= 0:
+        raise PzError(
+            code="PZ_STORAGE_EXPIRES_IN_INVALID",
+            message="Storage expires_in must be a positive integer when configured.",
+            stage="storage",
+            owner="runtime.storage",
+            action=action,
+        )
+    return expires_in
+
+
+class StorageFacade:
+    def __init__(self, plan: RuntimePlan, providers: ProviderFacade) -> None:
+        if not isinstance(plan, RuntimePlan):
+            raise PzError(
+                code="PZ_STORAGE_PLAN_INVALID",
+                message="StorageFacade requires a RuntimePlan instance.",
+                stage="storage",
+                owner="runtime.storage",
+                action="bind_storage_facade",
+            )
+        if not hasattr(providers, "require"):
+            raise PzError(
+                code="PZ_STORAGE_PROVIDERS_INVALID",
+                message="StorageFacade providers must expose require().",
+                stage="storage",
+                owner="runtime.storage",
+                action="bind_storage_facade",
+            )
+        self._plan = plan
+        self._providers = providers
+
+    def status(self) -> CapabilityStatus:
+        return merged_capability_status(self._plan, self._providers, "storage")
+
+    def _storage(self) -> StoragePort:
+        provider = self._providers.require("storage")
+        if not isinstance(provider, StoragePort):
+            raise PzError(
+                code="PZ_STORAGE_PROVIDER_INVALID",
+                message="Registered storage provider does not implement StoragePort.",
+                stage="storage",
+                owner="infra.storage",
+                action="resolve_storage",
+            )
+        return provider
+
+    def open(self, key: str, *, mode: str = "rb"):
+        key = _require_storage_key(key, action="open")
+        mode = _require_storage_mode(mode, action="open")
+        provider = self._providers.require("storage")
+        opener = getattr(provider, "open", None)
+        if callable(opener):
+            return opener(key, mode=mode)
+        raise PzError(
+            code="PZ_STORAGE_OPEN_UNSUPPORTED",
+            message="Registered storage provider does not expose open().",
+            stage="storage",
+            owner="infra.storage",
+            action="open",
+        )
+
+    def save(
+        self,
+        key: str,
+        payload: object,
+        *,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> StoredObject:
+        key = _require_storage_key(key, action="save")
+        del metadata
+        if isinstance(payload, bytes):
+            body = payload
+        elif isinstance(payload, str):
+            body = payload.encode("utf-8")
+        elif hasattr(payload, "read"):
+            body = payload.read()
+            if isinstance(body, str):
+                body = body.encode("utf-8")
+        else:
+            raise PzError(
+                code="PZ_STORAGE_PAYLOAD_INVALID",
+                message="StorageFacade.save() payload must be bytes, str, or file-like.",
+                stage="storage",
+                owner="infra.storage",
+                action="save",
+            )
+        if not isinstance(body, bytes):
+            raise PzError(
+                code="PZ_STORAGE_PAYLOAD_INVALID",
+                message="StorageFacade.save() payload reader must return bytes or str.",
+                stage="storage",
+                owner="infra.storage",
+                action="save",
+            )
+        return self._storage().store_bytes(key, body, content_type=content_type)
+
+    def delete(self, key: str) -> None:
+        key = _require_storage_key(key, action="delete")
+        self._storage().delete(key)
+
+    def url(
+        self,
+        key: str,
+        *,
+        expires_in: int | None = None,
+        download_name: str | None = None,
+    ) -> str | None:
+        key = _require_storage_key(key, action="url")
+        expires_in = _require_storage_expires_in(expires_in, action="url")
+        del download_name
+        provider = self._providers.require("storage")
+        url_factory = getattr(provider, "url", None)
+        if callable(url_factory):
+            return url_factory(key, expires_in=expires_in)
+        return None
+
+    def presign(
+        self,
+        key: str,
+        *,
+        method: str = "GET",
+        expires_in: int | None = None,
+    ) -> PresignInfo:
+        key = _require_storage_key(key, action="presign")
+        method = _require_storage_method(method, action="presign")
+        expires_in = _require_storage_expires_in(expires_in, action="presign")
+        provider = self._providers.require("storage")
+        presign_factory = getattr(provider, "presign", None)
+        if callable(presign_factory):
+            return presign_factory(key, method=method, expires_in=expires_in)
+        if method.upper() == "GET":
+            return self._storage().presign_get(
+                key,
+                expires_in_seconds=expires_in if expires_in is not None else 300,
+            )
+        raise PzError(
+            code="PZ_STORAGE_PRESIGN_UNSUPPORTED",
+            message="Registered storage provider does not expose presign() for this method.",
+            stage="storage",
+            owner="infra.storage",
+            action="presign",
+        )
+
+
+@dataclass(slots=True)
+class RuntimePresignInfo:
+    method: str
+    url: str
+    expires: int | None = None
+    headers: dict[str, str] | None = None
+    fields: dict[str, str] | None = None
+
+
+@dataclass(slots=True)
+class RuntimeStoredObject:
+    path: str
+    size: int | None = None
+    content_type: str | None = None
+
+
+@runtime_checkable
+class RuntimeStoragePort(Protocol):
+    def open(self, key: str, *, mode: str = "rb"): ...
+
+    def save(self, key: str, payload: Any, *, content_type: str | None = None) -> RuntimeStoredObject: ...
+
+    def delete(self, key: str) -> None: ...
+
+    def url(self, key: str, *, expires_in: int | None = None) -> str | None: ...
+
+    def presign_upload(
+        self,
+        key: str,
+        *,
+        content_type: str | None = None,
+        expires_in: int = 300,
+    ) -> RuntimePresignInfo: ...
+
+    def presign_download(self, key: str, *, expires_in: int = 300) -> RuntimePresignInfo: ...
+
+class StorageClient:
+    def __init__(self, namespace: str | None = None, *, request: Any | None = None) -> None:
+        self.namespace = namespace
+        self._storage = get_runtime(request=request).bindings.storage
+
+    def open(self, key: str, *, mode: str = "rb"):
+        return self._storage.open(key, mode=mode)
+
+    def save(self, key: str, payload: Any, *, content_type: str | None = None) -> RuntimeStoredObject:
+        stored = self._storage.save(key, payload, content_type=content_type)
+        object_key = getattr(stored, "object_key", key)
+        return RuntimeStoredObject(
+            path=str(object_key),
+            size=getattr(stored, "size", None),
+            content_type=getattr(stored, "content_type", content_type),
+        )
+
+    def delete(self, key: str) -> None:
+        self._storage.delete(key)
+
+    def url(self, key: str, *, expires_in: int | None = None) -> str | None:
+        return self._storage.url(key, expires_in=expires_in)
+
+    def presign_upload(
+        self,
+        key: str,
+        *,
+        content_type: str | None = None,
+        expires_in: int = 300,
+    ) -> RuntimePresignInfo:
+        del content_type
+        presign = self._storage.presign(key, method="PUT", expires_in=expires_in)
+        return RuntimePresignInfo(
+            method=presign.method,
+            url=presign.url,
+            expires=presign.expires_in_seconds,
+            headers={},
+            fields={},
+        )
+
+    def presign_download(self, key: str, *, expires_in: int = 300) -> RuntimePresignInfo:
+        presign = self._storage.presign(key, method="GET", expires_in=expires_in)
+        return RuntimePresignInfo(
+            method=presign.method,
+            url=presign.url,
+            expires=presign.expires_in_seconds,
+            headers={},
+            fields={},
+        )
+
+
+def get_storage(namespace: str | None = None):
+    if namespace is None:
+        def _dependency(request: Any) -> StorageClient:
+            return StorageClient(request=request)
+        return _dependency
+
+    def _dependency(request: Any) -> StorageClient:
+        return StorageClient(namespace=namespace, request=request)
+
+    return _dependency

pz_core/runtime/health/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .service import HealthSnapshot, build_health_snapshot
+
+__all__ = ["HealthSnapshot", "build_health_snapshot"]

pz_core/runtime/health/service.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+from pz_core.runtime.lifecycle import LifecycleState
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityState, CapabilityStatus
+from pz_core.runtime.errors import PzError
+
+
+def _capability_map(
+    plan: RuntimePlan,
+    state: LifecycleState | None,
+) -> tuple[CapabilityState, ...]:
+    if state and state.capability_states:
+        return state.capability_states
+    return plan.capability_registry.capabilities
+
+
+def _aggregate_status(statuses: tuple[CapabilityStatus, ...], *, active: bool) -> str:
+    if any(status == "unavailable" for status in statuses):
+        return "unavailable"
+    if active and any(status == "ready" for status in statuses):
+        return "ok"
+    if any(status == "enabled" for status in statuses):
+        return "starting"
+    if any(status == "ready" for status in statuses):
+        return "ok"
+    return "disabled"
+
+
+def _normalize_extra_capability_statuses(
+    extra_capability_statuses: Mapping[str, CapabilityStatus] | None,
+) -> dict[str, CapabilityStatus]:
+    if not extra_capability_statuses:
+        return {}
+    normalized: dict[str, CapabilityStatus] = {}
+    for name, status in extra_capability_statuses.items():
+        if not isinstance(name, str) or not name.strip():
+            raise PzError(
+                code="PZ_CAPABILITY_NAME_INVALID",
+                message="extra capability status names must be non-empty strings.",
+                stage="health",
+                owner="runtime.health",
+                action="build_health_snapshot",
+            )
+        if status not in {"disabled", "enabled", "ready", "unavailable"}:
+            raise PzError(
+                code="PZ_CAPABILITY_STATUS_INVALID",
+                message=(
+                    f"extra capability status for '{name.strip()}' must be one of: "
+                    "disabled, enabled, ready, unavailable."
+                ),
+                stage="health",
+                owner=name.strip(),
+                action="build_health_snapshot",
+            )
+        normalized[name.strip()] = status
+    return normalized
+
+
+@dataclass(frozen=True, slots=True)
+class HealthSnapshot:
+    status: str
+    phase: str
+    active: bool
+    enabled_components: tuple[str, ...]
+    activated_capabilities: tuple[str, ...]
+    capability_statuses: dict[str, CapabilityStatus]
+    unavailable_capabilities: tuple[str, ...]
+
+
+def build_health_snapshot(
+    plan: RuntimePlan,
+    state: LifecycleState | None = None,
+    *,
+    extra_capability_statuses: Mapping[str, CapabilityStatus] | None = None,
+) -> HealthSnapshot:
+    lifecycle = state or LifecycleState()
+    capabilities = _capability_map(plan, lifecycle if state else None)
+    capability_statuses = {capability.name: capability.status for capability in capabilities}
+    normalized_extra = _normalize_extra_capability_statuses(extra_capability_statuses)
+    if normalized_extra:
+        capability_statuses.update(normalized_extra)
+    statuses = tuple(capability.status for capability in capabilities)
+    if normalized_extra:
+        statuses += tuple(normalized_extra.values())
+    unavailable_capabilities = tuple(
+        name
+        for name, status in capability_statuses.items()
+        if status == "unavailable"
+    )
+    return HealthSnapshot(
+        status=_aggregate_status(statuses, active=lifecycle.active),
+        phase=lifecycle.phase,
+        active=lifecycle.active,
+        enabled_components=plan.infra.enabled_components,
+        activated_capabilities=lifecycle.activated_capabilities,
+        capability_statuses=capability_statuses,
+        unavailable_capabilities=unavailable_capabilities,
+    )