pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/infra/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .compiler import compile_infra_context
+
+__all__ = ["compile_infra_context"]
+

pz_core/assembly/infra/compiler.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from os import PathLike
+from typing import Any
+
+from pz_core.assembly.project import ProjectContext
+from pz_core.assembly.resources.settings import read_resource_settings
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.core.extensions import (
+    ExtensionRegistry,
+    InfraPatch,
+    InfraProviderContext,
+    InfraProviderSpec,
+)
+from pz_core.infra.settings import (
+    InfraContext,
+    InfraComponent,
+    ResilienceSettings,
+)
+
+_INFRA_COMPONENTS = (
+    "database",
+    "cache",
+    "metrics",
+    "tracing",
+    "mail",
+    "storage",
+    "health",
+)
+
+_INFRA_FIELD_TYPES: dict[str, dict[str, type | tuple[type, ...]]] = {
+    "database": {
+        "enabled": bool,
+        "driver": str,
+        "migration_executor": str,
+    },
+    "cache": {
+        "enabled": bool,
+        "host": str,
+        "port": int,
+    },
+    "storage": {
+        "enabled": bool,
+        "backend": str,
+        "base_dir": (str, PathLike),
+        "subdir": str,
+    },
+    "tracing": {
+        "enabled": bool,
+        "exporter": str,
+    },
+    "mail": {
+        "enabled": bool,
+        "provider": str,
+    },
+    "health": {
+        "enabled": bool,
+        "readiness_enabled": bool,
+    },
+}
+
+def _read_dict(payload: Any, *, owner: str) -> dict[str, Any]:
+    if payload is None:
+        return {}
+    if isinstance(payload, dict):
+        return dict(payload)
+    if isinstance(payload, Mapping):
+        return dict(payload.items())
+    raise PzError(
+        code="PZ_INFRA_SECTION_INVALID",
+        message=f"{owner} settings must be declared as a table.",
+        stage="infra",
+        owner=owner,
+        action="compile_infra_context",
+    )
+
+
+def _validate_component_payload(component: str, payload: dict[str, Any], *, owner: str) -> dict[str, Any]:
+    validators = _INFRA_FIELD_TYPES.get(component, {})
+    for key, value in payload.items():
+        expected_type = validators.get(str(key))
+        if expected_type is None:
+            continue
+        if not isinstance(value, expected_type):
+            if isinstance(expected_type, tuple):
+                expected_name = " or ".join(item.__name__ for item in expected_type)
+            else:
+                expected_name = expected_type.__name__
+            raise PzError(
+                code="PZ_INFRA_FIELD_INVALID",
+                message=f"{owner}.{key} must be declared as {expected_name}.",
+                stage="infra",
+                owner=owner,
+                action="compile_infra_context",
+            )
+    return payload
+
+
+def _deep_merge_dict(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in incoming.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge_dict(dict(merged[key]), value)
+            continue
+        merged[key] = value
+    return merged
+
+
+def _normalize_infra_patch(payload: Any, *, owner: str, default_priority: int) -> tuple[InfraPatch, ...]:
+    def _coerce_patch(item: Any) -> InfraPatch:
+        if isinstance(item, InfraPatch):
+            return item
+        component = getattr(item, "component", None)
+        patch_payload = getattr(item, "payload", None)
+        source = getattr(item, "source", None)
+        priority = getattr(item, "priority", default_priority)
+        if not isinstance(component, str) or not component.strip():
+            raise PzError(
+                code="PZ_INFRA_PROVIDER_RESULT_INVALID",
+                message=f"Infra provider '{owner}' must return InfraPatch objects.",
+                stage="infra",
+                owner=owner,
+                action="compile_infra_context",
+            )
+        if component.strip() not in _INFRA_COMPONENTS:
+            raise PzError(
+                code="PZ_INFRA_PROVIDER_COMPONENT_INVALID",
+                message=(
+                    f"Infra provider '{owner}' returned unsupported component "
+                    f"'{component.strip()}'."
+                ),
+                stage="infra",
+                owner=owner,
+                action="compile_infra_context",
+            )
+        if not isinstance(patch_payload, dict):
+            raise PzError(
+                code="PZ_INFRA_PROVIDER_RESULT_INVALID",
+                message=f"Infra provider '{owner}' must return InfraPatch objects.",
+                stage="infra",
+                owner=owner,
+                action="compile_infra_context",
+            )
+        if not isinstance(source, str) or not source.strip():
+            raise PzError(
+                code="PZ_INFRA_PROVIDER_RESULT_INVALID",
+                message=f"Infra provider '{owner}' must return InfraPatch objects.",
+                stage="infra",
+                owner=owner,
+                action="compile_infra_context",
+            )
+        return InfraPatch(
+            component=component.strip(),
+            payload=dict(patch_payload),
+            source=source.strip(),
+            priority=int(priority if priority is not None else default_priority),
+        )
+
+    if payload in (None, (), []):
+        return ()
+    if not isinstance(payload, (list, tuple)):
+        return (_coerce_patch(payload),)
+    return tuple(_coerce_patch(item) for item in payload)
+
+
+def _compile_infra_payloads(
+    settings: SettingsSnapshot,
+    project: ProjectContext,
+    *,
+    extension_registry: ExtensionRegistry | None,
+) -> dict[str, dict[str, Any]]:
+    if extension_registry is None:
+        from pz_core.assembly.apps import compile_app_registry
+        from pz_core.assembly.extensions import compile_extension_registry
+
+        app_registry = compile_app_registry(settings, project_dir=project.project_dir, run_init_hooks=False)
+        extension_registry = compile_extension_registry(settings, app_registry)
+    providers = tuple(
+        spec
+        for spec in tuple(getattr(extension_registry, "extensions", ()) or ())
+        if isinstance(spec, InfraProviderSpec)
+    )
+    if not providers:
+        return {component: {} for component in _INFRA_COMPONENTS}
+
+    context = InfraProviderContext(project=project, snapshot=settings)
+    merged: dict[str, dict[str, Any]] = {component: {} for component in _INFRA_COMPONENTS}
+    ordered = sorted(
+        providers,
+        key=lambda item: (int(item.priority), str(item.owner_app), str(item.id)),
+    )
+    for spec in ordered:
+        provide = getattr(spec.provider, "provide", None)
+        if not callable(provide):
+            raise PzError(
+                code="PZ_INFRA_PROVIDER_INVALID",
+                message=f"Infra provider '{spec.id}' must declare a provider object with provide(ctx).",
+                stage="infra",
+                owner=spec.owner_app,
+                action="compile_infra_context",
+            )
+        try:
+            patches = _normalize_infra_patch(
+                provide(context),
+                owner=spec.id,
+                default_priority=int(spec.priority),
+            )
+        except PzError:
+            raise
+        except Exception as exc:
+            raise PzError(
+                code="PZ_INFRA_PROVIDER_FAILED",
+                message=f"Infra provider '{spec.id}' failed while compiling infra context: {exc}",
+                stage="infra",
+                owner=spec.owner_app,
+                action="compile_infra_context",
+            ) from exc
+        for patch in sorted(patches, key=lambda item: (int(item.priority), item.component, item.source)):
+            section = patch.component
+            payload = _validate_component_payload(
+                section,
+                _read_dict(patch.payload, owner=section),
+                owner=section,
+            )
+            merged[section] = _deep_merge_dict(merged[section], payload)
+    return merged
+
+
+def compile_infra_context(
+    settings: SettingsSnapshot,
+    project: ProjectContext,
+    extension_registry: ExtensionRegistry | None = None,
+) -> InfraContext:
+    payloads = _compile_infra_payloads(
+        settings,
+        project,
+        extension_registry=extension_registry,
+    )
+    resilience_cfg = ResilienceSettings(
+        lock_dir=project.runtime_dir / "locks",
+    )
+    resource_cfg = read_resource_settings(
+        settings,
+        project,
+        stage="infra",
+        owner="resources",
+        action="compile_infra_context",
+    )
+
+    return InfraContext(
+        project_dir=project.project_dir,
+        cache_dir=project.cache_dir,
+        runtime_dir=project.runtime_dir,
+        asset_dir=project.asset_dir,
+        database=InfraComponent("database", payloads["database"]),
+        cache=InfraComponent("cache", payloads["cache"]),
+        metrics=InfraComponent("metrics", payloads["metrics"]),
+        tracing=InfraComponent("tracing", payloads["tracing"]),
+        mail=InfraComponent("mail", payloads["mail"]),
+        storage=InfraComponent("storage", payloads["storage"]),
+        health=InfraComponent(
+            "health",
+            payloads["health"] or {"enabled": True, "state": "enabled", "readiness_enabled": True},
+        ),
+        resilience=resilience_cfg,
+        resources=resource_cfg,
+    )
+
+
+__all__ = ["compile_infra_context"]

pz_core/assembly/lifecycle/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .compiler import LifecycleManifest, compile_lifecycle_manifest
+
+__all__ = ["LifecycleManifest", "compile_lifecycle_manifest"]

pz_core/assembly/lifecycle/compiler.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pz_core.assembly.apps import AppRegistry
+from pz_core.core.errors import PzError
+from pz_core.core.extensions import ExtensionRegistry, LifecycleContributionSpec
+
+_PHASE_ORDER = {"init": 0, "startup": 1, "shutdown": 2}
+
+
+@dataclass(frozen=True, slots=True)
+class LifecycleManifest:
+    contributions: tuple[LifecycleContributionSpec, ...]
+
+    def for_phase(self, phase: str) -> tuple[LifecycleContributionSpec, ...]:
+        expected = str(phase or "").strip()
+        if not expected:
+            return ()
+        return tuple(item for item in self.contributions if item.phase == expected)
+
+
+def _app_order_index(app_registry: AppRegistry) -> dict[str, int]:
+    return {app.app_id: index for index, app in enumerate(app_registry.apps)}
+
+
+def compile_lifecycle_manifest(
+    app_registry: AppRegistry,
+    extension_registry: ExtensionRegistry,
+) -> LifecycleManifest:
+    app_order = _app_order_index(app_registry)
+    contributions: list[LifecycleContributionSpec] = []
+    seen_phase_ids: set[tuple[str, str]] = set()
+    for item in extension_registry.by_kind("lifecycle.contribution"):
+        if not isinstance(item, LifecycleContributionSpec):
+            raise PzError(
+                code="PZ_LIFECYCLE_DECL_INVALID",
+                message="Lifecycle declarations must use LifecycleContributionSpec.",
+                stage="lifecycle",
+                owner="assembly.lifecycle",
+                action="compile_lifecycle_manifest",
+            )
+        if item.owner_app not in app_order:
+            raise PzError(
+                code="PZ_LIFECYCLE_OWNER_UNKNOWN",
+                message=(
+                    f"Lifecycle contribution '{item.id}' declares unknown owner_app "
+                    f"'{item.owner_app}'."
+                ),
+                stage="lifecycle",
+                owner=item.owner_app,
+                action="compile_lifecycle_manifest",
+            )
+        if item.phase not in _PHASE_ORDER:
+            raise PzError(
+                code="PZ_LIFECYCLE_PHASE_INVALID",
+                message=(
+                    f"Lifecycle contribution '{item.id}' declares unsupported phase "
+                    f"'{item.phase}'."
+                ),
+                stage="lifecycle",
+                owner=item.owner_app,
+                action="compile_lifecycle_manifest",
+            )
+        if not callable(item.handler):
+            raise PzError(
+                code="PZ_LIFECYCLE_HANDLER_INVALID",
+                message=f"Lifecycle contribution '{item.id}' must declare a callable handler.",
+                stage="lifecycle",
+                owner=item.owner_app,
+                action="compile_lifecycle_manifest",
+            )
+        phase_key = (item.phase, item.id)
+        if phase_key in seen_phase_ids:
+            raise PzError(
+                code="PZ_LIFECYCLE_DUPLICATE_ID",
+                message=(
+                    f"Lifecycle contribution '{item.id}' is declared more than once for "
+                    f"phase '{item.phase}'."
+                ),
+                stage="lifecycle",
+                owner=item.owner_app,
+                action="compile_lifecycle_manifest",
+            )
+        seen_phase_ids.add(phase_key)
+        contributions.append(item)
+    contributions.sort(
+        key=lambda item: (
+            _PHASE_ORDER[item.phase],
+            app_order[item.owner_app],
+            int(item.priority),
+            str(item.id),
+        )
+    )
+    return LifecycleManifest(contributions=tuple(contributions))

pz_core/assembly/middlewares/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pz_core.core.middlewares import MiddlewareDecl, MiddlewareManifest
+
+from .compiler import (
+    compile_conventional_middleware_manifest,
+    compile_middleware_manifest,
+    merge_explicit_middleware_order,
+    sort_middleware_declarations,
+)
+
+__all__ = [
+    "MiddlewareDecl",
+    "MiddlewareManifest",
+    "compile_conventional_middleware_manifest",
+    "compile_middleware_manifest",
+    "merge_explicit_middleware_order",
+    "sort_middleware_declarations",
+]