pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/facades/events.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+import inspect
+from typing import Any, Awaitable, Callable
+from uuid import uuid4
+
+from pz_core.runtime.errors import PzError
+from pz_core.core.events import EventRegistry
+
+EventHandler = Callable[[dict[str, Any]], Any]
+
+
+@dataclass(frozen=True, slots=True)
+class EventSubscription:
+    subscription_id: str
+    event_name: str
+    owner: str
+    handler_name: str
+    wildcard: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class EventDispatchResult:
+    event_name: str
+    owner: str
+    handler_name: str
+    ok: bool
+    subscribed_event: str | None = None
+    scheduler: str | None = None
+    code: str | None = None
+    message: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class EventDispatchTicket:
+    event_name: str
+    owner: str
+    scheduled_handlers: int
+    scheduler: str
+
+
+def _coerce_handler_name(handler: EventHandler) -> str:
+    return getattr(handler, "__qualname__", getattr(handler, "__name__", handler.__class__.__name__))
+
+
+def _read_required_event_name(
+    value: object,
+    *,
+    code: str,
+    action: str,
+    owner: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message="event_name must be a non-empty string.",
+            stage="events",
+            owner=owner,
+            action=action,
+        )
+    return value.strip()
+
+
+def _read_required_owner(
+    value: object,
+    *,
+    code: str,
+    message: str,
+    action: str,
+    owner: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="events",
+            owner=owner,
+            action=action,
+        )
+    return value.strip()
+
+
+def _read_dispatched_event_name(
+    envelope: dict[str, Any],
+    *,
+    fallback: str,
+) -> str:
+    raw = envelope.get("event")
+    if raw is None:
+        return fallback
+    return _read_required_event_name(
+        raw,
+        code="PZ_EVENT_NAME_INVALID",
+        action="dispatch",
+        owner="runtime.events",
+    )
+
+
+@dataclass(slots=True)
+class EventBusFacade:
+    registry: EventRegistry
+    _subscriptions: dict[str, tuple[EventSubscription, EventHandler]] = field(default_factory=dict)
+    _dispatch_results: list[EventDispatchResult] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.registry, EventRegistry):
+            raise PzError(
+                code="PZ_EVENT_REGISTRY_INVALID",
+                message="EventBusFacade requires an EventRegistry instance.",
+                stage="events",
+                owner="runtime.events",
+                action="bind_event_bus",
+            )
+
+    def _ensure_declared(self, event_name: str) -> None:
+        normalized = _read_required_event_name(
+            event_name,
+            code="PZ_EVENT_NAME_INVALID",
+            action="publish",
+            owner="runtime.events",
+        )
+        if normalized not in self.registry.by_name():
+            raise PzError(
+                code="PZ_EVENT_UNDECLARED",
+                message=f"Event '{normalized}' is not declared in EventRegistry.",
+                stage="events",
+                owner=normalized,
+                action="publish",
+            )
+
+    def subscribe(
+        self,
+        event_name: str,
+        handler: EventHandler,
+        *,
+        owner: str,
+        wildcard: bool = False,
+    ) -> str:
+        normalized_owner = _read_required_owner(
+            owner,
+            code="PZ_EVENT_SUBSCRIBER_OWNER_INVALID",
+            message="event subscriber must declare owner as a non-empty string.",
+            action="subscribe",
+            owner="runtime.events",
+        )
+        normalized_event = _read_required_event_name(
+            event_name,
+            code="PZ_EVENT_NAME_INVALID",
+            action="subscribe",
+            owner=normalized_owner,
+        )
+        if not wildcard:
+            self._ensure_declared(normalized_event)
+        subscription = EventSubscription(
+            subscription_id=uuid4().hex,
+            event_name=normalized_event,
+            owner=normalized_owner,
+            handler_name=_coerce_handler_name(handler),
+            wildcard=wildcard,
+        )
+        self._subscriptions[subscription.subscription_id] = (subscription, handler)
+        return subscription.subscription_id
+
+    def unsubscribe(self, subscription_id: str) -> bool:
+        if not isinstance(subscription_id, str) or not subscription_id.strip():
+            raise PzError(
+                code="PZ_EVENT_SUBSCRIPTION_ID_INVALID",
+                message="event subscription_id must be a non-empty string.",
+                stage="events",
+                owner="runtime.events",
+                action="unsubscribe",
+            )
+        return self._subscriptions.pop(subscription_id, None) is not None
+
+    def reset(self, *, owner: str | None = None) -> int:
+        if owner is None:
+            removed = len(self._subscriptions)
+            self._subscriptions.clear()
+            self._dispatch_results.clear()
+            return removed
+        target = _read_required_owner(
+            owner,
+            code="PZ_EVENT_RESET_OWNER_INVALID",
+            message="event reset owner must be a non-empty string.",
+            action="reset",
+            owner="runtime.events",
+        )
+        to_remove = [
+            subscription_id
+            for subscription_id, (subscription, _) in self._subscriptions.items()
+            if subscription.owner == target
+        ]
+        for subscription_id in to_remove:
+            self._subscriptions.pop(subscription_id, None)
+        self._dispatch_results[:] = [
+            result for result in self._dispatch_results if result.owner != target
+        ]
+        return len(to_remove)
+
+    def subscriptions_for(self, event_name: str) -> tuple[EventSubscription, ...]:
+        normalized = _read_required_event_name(
+            event_name,
+            code="PZ_EVENT_NAME_INVALID",
+            action="subscriptions_for",
+            owner="runtime.events",
+        )
+        return tuple(
+            subscription
+            for subscription, _ in self._subscriptions.values()
+            if subscription.event_name == normalized or subscription.wildcard
+        )
+
+    def diagnostics(self) -> tuple[EventDispatchResult, ...]:
+        return tuple(self._dispatch_results)
+
+    async def _invoke_handler(
+        self,
+        subscription: EventSubscription,
+        handler: EventHandler,
+        envelope: dict[str, Any],
+        *,
+        scheduler: str,
+    ) -> EventDispatchResult:
+        try:
+            dispatched_event = _read_dispatched_event_name(
+                envelope,
+                fallback=subscription.event_name,
+            )
+        except PzError as exc:
+            dispatch = EventDispatchResult(
+                event_name=subscription.event_name,
+                owner=subscription.owner,
+                handler_name=subscription.handler_name,
+                ok=False,
+                subscribed_event=subscription.event_name,
+                scheduler=scheduler,
+                code=exc.code,
+                message=exc.summary or exc.message,
+            )
+            self._dispatch_results.append(dispatch)
+            return dispatch
+        try:
+            if inspect.iscoroutinefunction(handler):
+                await handler(envelope)
+            else:
+                result = await asyncio.to_thread(handler, envelope)
+                if inspect.isawaitable(result):
+                    await result
+        except PzError as exc:
+            dispatch = EventDispatchResult(
+                event_name=dispatched_event,
+                owner=subscription.owner,
+                handler_name=subscription.handler_name,
+                ok=False,
+                subscribed_event=subscription.event_name,
+                scheduler=scheduler,
+                code=exc.code,
+                message=exc.summary or exc.message,
+            )
+            self._dispatch_results.append(dispatch)
+            return dispatch
+        except Exception as exc:
+            dispatch = EventDispatchResult(
+                event_name=dispatched_event,
+                owner=subscription.owner,
+                handler_name=subscription.handler_name,
+                ok=False,
+                subscribed_event=subscription.event_name,
+                scheduler=scheduler,
+                code="PZ_EVENT_HANDLER_FAILED",
+                message=str(exc) or exc.__class__.__name__,
+            )
+            self._dispatch_results.append(dispatch)
+            return dispatch
+        dispatch = EventDispatchResult(
+            event_name=dispatched_event,
+            owner=subscription.owner,
+            handler_name=subscription.handler_name,
+            ok=True,
+            subscribed_event=subscription.event_name,
+            scheduler=scheduler,
+        )
+        self._dispatch_results.append(dispatch)
+        return dispatch
+
+    async def publish(
+        self,
+        event_name: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        owner: str,
+    ) -> tuple[EventDispatchResult, ...]:
+        normalized_event = _read_required_event_name(
+            event_name,
+            code="PZ_EVENT_NAME_INVALID",
+            action="publish",
+            owner="runtime.events",
+        )
+        normalized_owner = _read_required_owner(
+            owner,
+            code="PZ_EVENT_PUBLISH_OWNER_INVALID",
+            message="event publisher must declare owner as a non-empty string.",
+            action="publish",
+            owner=normalized_event,
+        )
+        self._ensure_declared(normalized_event)
+        envelope = {
+            "event": normalized_event,
+            "owner": normalized_owner,
+            "payload": dict(payload or {}),
+        }
+        subscriptions = self.subscriptions_for(normalized_event)
+        results: list[EventDispatchResult] = []
+        for subscription in subscriptions:
+            _, handler = self._subscriptions[subscription.subscription_id]
+            results.append(
+                await self._invoke_handler(
+                    subscription,
+                    handler,
+                    envelope,
+                    scheduler="await",
+                )
+            )
+        return tuple(results)
+
+    def publish_nowait(
+        self,
+        event_name: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        owner: str,
+    ) -> EventDispatchTicket:
+        normalized_event = _read_required_event_name(
+            event_name,
+            code="PZ_EVENT_NAME_INVALID",
+            action="publish_nowait",
+            owner="runtime.events",
+        )
+        normalized_owner = _read_required_owner(
+            owner,
+            code="PZ_EVENT_PUBLISH_OWNER_INVALID",
+            message="event publisher must declare owner as a non-empty string.",
+            action="publish_nowait",
+            owner=normalized_event,
+        )
+        self._ensure_declared(normalized_event)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError as exc:
+            raise PzError(
+                code="PZ_EVENT_LOOP_REQUIRED",
+                message="publish_nowait() requires an active asyncio loop.",
+                stage="events",
+                owner=normalized_event,
+                action="publish_nowait",
+            ) from exc
+        subscriptions = self.subscriptions_for(normalized_event)
+        envelope = {
+            "event": normalized_event,
+            "owner": normalized_owner,
+            "payload": dict(payload or {}),
+        }
+        for subscription in subscriptions:
+            _, handler = self._subscriptions[subscription.subscription_id]
+            loop.create_task(
+                self._invoke_handler(
+                    subscription,
+                    handler,
+                    envelope,
+                    scheduler="asyncio.create_task",
+                )
+            )
+        return EventDispatchTicket(
+            event_name=normalized_event,
+            owner=normalized_owner,
+            scheduled_handlers=len(subscriptions),
+            scheduler="asyncio.create_task",
+        )

pz_core/runtime/facades/health.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import replace
+import time
+from typing import TYPE_CHECKING
+
+from pz_core.runtime.facades._capabilities import merged_capability_status
+from pz_core.runtime.health import HealthSnapshot, build_health_snapshot
+from pz_core.runtime.http_timing import log_http_timing
+from pz_core.runtime.lifecycle import LifecycleState
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+from pz_core.runtime.errors import PzError
+
+if TYPE_CHECKING:
+    from pz_core.runtime.facades.providers import ProviderFacade
+
+
+class HealthFacade:
+    def __init__(
+        self,
+        plan: RuntimePlan,
+        state: LifecycleState | None = None,
+        *,
+        providers: "ProviderFacade | None" = None,
+    ) -> None:
+        if not isinstance(plan, RuntimePlan):
+            raise PzError(
+                code="PZ_HEALTH_PLAN_INVALID",
+                message="HealthFacade requires a RuntimePlan instance.",
+                stage="health",
+                owner="runtime.health",
+                action="bind_health_facade",
+            )
+        if state is not None and not isinstance(state, LifecycleState):
+            raise PzError(
+                code="PZ_HEALTH_STATE_INVALID",
+                message="HealthFacade state must be a LifecycleState when configured.",
+                stage="health",
+                owner="runtime.health",
+                action="bind_health_facade",
+            )
+        if providers is not None and not hasattr(providers, "declared"):
+            raise PzError(
+                code="PZ_HEALTH_PROVIDERS_INVALID",
+                message="HealthFacade providers must expose declared() when configured.",
+                stage="health",
+                owner="runtime.health",
+                action="bind_health_facade",
+            )
+        self._plan = plan
+        self._state = state
+        self._providers = providers
+
+    def _provider_capability_statuses(self) -> dict[str, CapabilityStatus]:
+        if self._providers is None:
+            return {}
+        statuses: dict[str, CapabilityStatus] = {}
+        for declaration in self._providers.declared():
+            capability = declaration.capability
+            base = self._plan.capability_registry.get(capability)
+            if base is not None and base.status == "disabled":
+                statuses[capability] = "disabled"
+                continue
+            statuses[capability] = merged_capability_status(
+                self._plan,
+                self._providers,
+                capability,
+            )
+        return statuses
+
+    def liveness(self) -> HealthSnapshot:
+        started_at = time.perf_counter()
+        provider_started_at = started_at
+        extra_capability_statuses = self._provider_capability_statuses()
+        providers_ms = (time.perf_counter() - provider_started_at) * 1000.0
+        snapshot_started_at = time.perf_counter()
+        snapshot = build_health_snapshot(
+            self._plan,
+            self._state,
+            extra_capability_statuses=extra_capability_statuses,
+        )
+        snapshot_ms = (time.perf_counter() - snapshot_started_at) * 1000.0
+        total_ms = (time.perf_counter() - started_at) * 1000.0
+        log_http_timing("health.providers", total_ms=providers_ms)
+        log_http_timing("health.snapshot", total_ms=snapshot_ms)
+        log_http_timing("health.liveness", total_ms=total_ms)
+        return snapshot
+
+    def readiness(self) -> HealthSnapshot:
+        started_at = time.perf_counter()
+        snapshot = self.liveness()
+        if not bool(self._plan.infra.health.get("readiness_enabled", True)):
+            readiness_snapshot = replace(snapshot, status="disabled")
+            log_http_timing("health.readiness", total_ms=(time.perf_counter() - started_at) * 1000.0)
+            return readiness_snapshot
+        log_http_timing("health.readiness", total_ms=(time.perf_counter() - started_at) * 1000.0)
+        return snapshot
+
+    def capabilities(self) -> dict[str, CapabilityStatus]:
+        return dict(self.liveness().capability_statuses)

pz_core/runtime/facades/mail.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.facades._capabilities import merged_capability_status
+from pz_core.runtime.facades.providers import ProviderFacade
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+
+
+def _require_mail_template(template: str, *, action: str) -> str:
+    if not isinstance(template, str) or not template.strip():
+        raise PzError(
+            code="PZ_MAIL_TEMPLATE_INVALID",
+            message="Mail template must be a non-empty string.",
+            stage="mail",
+            owner="runtime.mail",
+            action=action,
+        )
+    return template
+
+
+def _require_mail_context(context: dict[str, object], *, action: str) -> dict[str, object]:
+    if not isinstance(context, dict):
+        raise PzError(
+            code="PZ_MAIL_CONTEXT_INVALID",
+            message="Mail context must be a mapping.",
+            stage="mail",
+            owner="runtime.mail",
+            action=action,
+        )
+    return context
+
+
+def _read_optional_mail_locale(locale: str | None, *, action: str) -> str | None:
+    if locale is None:
+        return None
+    if not isinstance(locale, str) or not locale.strip():
+        raise PzError(
+            code="PZ_MAIL_LOCALE_INVALID",
+            message="Mail locale must be a non-empty string when configured.",
+            stage="mail",
+            owner="runtime.mail",
+            action=action,
+        )
+    return locale
+
+
+class MailFacade:
+    def __init__(self, plan: RuntimePlan, providers: ProviderFacade) -> None:
+        if not isinstance(plan, RuntimePlan):
+            raise PzError(
+                code="PZ_MAIL_PLAN_INVALID",
+                message="MailFacade requires a RuntimePlan instance.",
+                stage="mail",
+                owner="runtime.mail",
+                action="bind_mail_facade",
+            )
+        if not hasattr(providers, "require"):
+            raise PzError(
+                code="PZ_MAIL_PROVIDERS_INVALID",
+                message="MailFacade providers must expose require().",
+                stage="mail",
+                owner="runtime.mail",
+                action="bind_mail_facade",
+            )
+        self._plan = plan
+        self._providers = providers
+
+    def status(self) -> CapabilityStatus:
+        return merged_capability_status(self._plan, self._providers, "mail")
+
+    def _provider(self) -> object:
+        return self._providers.require("mail")
+
+    def render(
+        self,
+        template: str,
+        context: dict[str, object],
+        *,
+        locale: str | None = None,
+    ) -> object:
+        template = _require_mail_template(template, action="render")
+        context = _require_mail_context(context, action="render")
+        locale = _read_optional_mail_locale(locale, action="render")
+        provider = self._provider()
+        renderer = getattr(provider, "render", None)
+        if not callable(renderer):
+            raise PzError(
+                code="PZ_MAIL_RENDER_UNSUPPORTED",
+                message="Registered mail provider does not expose render().",
+                stage="mail",
+                owner="infra.mail",
+                action="render",
+            )
+        return renderer(template, context, locale=locale)
+
+    def send(self, message: object) -> object:
+        provider = self._provider()
+        sender = getattr(provider, "send", None)
+        if not callable(sender):
+            raise PzError(
+                code="PZ_MAIL_SEND_UNSUPPORTED",
+                message="Registered mail provider does not expose send().",
+                stage="mail",
+                owner="infra.mail",
+                action="send",
+            )
+        return sender(message)
+
+    def enqueue(self, message: object) -> object:
+        provider = self._provider()
+        enqueue = getattr(provider, "enqueue", None)
+        if not callable(enqueue):
+            raise PzError(
+                code="PZ_MAIL_ENQUEUE_UNSUPPORTED",
+                message="Registered mail provider does not expose enqueue().",
+                stage="mail",
+                owner="infra.mail",
+                action="enqueue",
+            )
+        return enqueue(message)

pz_core/runtime/facades/observability.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pz_core.runtime.errors import PzError
+from pz_core.infra.observability import NoopObservability, ObservabilityPort
+from pz_core.runtime.facades._capabilities import merged_capability_status
+from pz_core.runtime.facades.providers import ProviderFacade
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+
+
+def _require_observability_name(name: str, *, action: str) -> str:
+    if not isinstance(name, str) or not name.strip():
+        raise PzError(
+            code="PZ_OBSERVABILITY_NAME_INVALID",
+            message="Observability name must be a non-empty string.",
+            stage="observability",
+            owner="runtime.observability",
+            action=action,
+        )
+    return name
+
+
+class ObservabilityFacade:
+    def __init__(self, plan: RuntimePlan, providers: ProviderFacade) -> None:
+        if not isinstance(plan, RuntimePlan):
+            raise PzError(
+                code="PZ_OBSERVABILITY_PLAN_INVALID",
+                message="ObservabilityFacade requires a RuntimePlan instance.",
+                stage="observability",
+                owner="runtime.observability",
+                action="bind_observability_facade",
+            )
+        if not hasattr(providers, "require") or not hasattr(providers, "declared_for"):
+            raise PzError(
+                code="PZ_OBSERVABILITY_PROVIDERS_INVALID",
+                message="ObservabilityFacade providers must expose require() and declared_for().",
+                stage="observability",
+                owner="runtime.observability",
+                action="bind_observability_facade",
+            )
+        self._plan = plan
+        self._providers = providers
+        self._noop = NoopObservability()
+
+    def status(self) -> CapabilityStatus:
+        metrics = merged_capability_status(self._plan, self._providers, "metrics")
+        tracing = merged_capability_status(self._plan, self._providers, "tracing")
+        statuses = (metrics, tracing)
+        if any(status == "unavailable" for status in statuses):
+            return "unavailable"
+        if any(status == "ready" for status in statuses):
+            return "ready"
+        if any(status == "enabled" for status in statuses):
+            return "enabled"
+        return "disabled"
+
+    def _port(self) -> ObservabilityPort:
+        for capability in ("metrics", "tracing"):
+            if not self._providers.declared_for(capability):
+                continue
+            try:
+                provider = self._providers.require(capability)
+            except PzError:
+                continue
+            if isinstance(provider, ObservabilityPort):
+                return provider
+        return self._noop
+
+    def logger(self, name: str):
+        name = _require_observability_name(name, action="logger")
+        return self._port().logger(name)
+
+    def counter(
+        self,
+        name: str,
+        *,
+        unit: str | None = None,
+        description: str | None = None,
+    ):
+        name = _require_observability_name(name, action="counter")
+        return self._port().counter(name, unit=unit, description=description)
+
+    def histogram(
+        self,
+        name: str,
+        *,
+        unit: str | None = None,
+        description: str | None = None,
+    ):
+        name = _require_observability_name(name, action="histogram")
+        return self._port().histogram(name, unit=unit, description=description)
+
+    def span(
+        self,
+        name: str,
+        *,
+        attributes: Mapping[str, object] | None = None,
+    ):
+        name = _require_observability_name(name, action="span")
+        return self._port().span(name, attributes=attributes)