pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/routes/compiler.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.core.routing import RouteDecl, RouteManifest
+
+
+def _read_path_segment(part: object) -> str:
+    if not isinstance(part, str):
+        raise PzError(
+            code="PZ_ROUTE_PATH_SEGMENT_INVALID",
+            message="Route path segments must be strings.",
+            stage="routes",
+            owner="assembly.routes",
+            action="compile_route_manifest",
+        )
+    return part.strip("/")
+
+
+def _join_path(*parts: str) -> str:
+    cleaned = [segment for segment in (_read_path_segment(part) for part in parts) if segment]
+    if not cleaned:
+        return "/"
+    return "/" + "/".join(cleaned)
+
+
+def _languages(settings: SettingsSnapshot) -> tuple[str, ...]:
+    raw = settings.get("routing", "all_supported_languages", default=None)
+    if raw is None:
+        raw = settings.get("i18n", "languages", default=None)
+    if isinstance(raw, list):
+        out: list[str] = []
+        for index, item in enumerate(raw):
+            if not isinstance(item, str):
+                raise PzError(
+                    code="PZ_ROUTING_SUPPORTED_LANGUAGES_ITEM_INVALID",
+                    message=(
+                        f"routing.all_supported_languages entry at index {index} must be a non-empty string."
+                    ),
+                    stage="routes",
+                    owner="assembly.routes",
+                    action="compile_route_manifest",
+                )
+            value = item.strip()
+            if not value:
+                raise PzError(
+                    code="PZ_ROUTING_SUPPORTED_LANGUAGES_ITEM_INVALID",
+                    message=(
+                        f"routing.all_supported_languages entry at index {index} must be a non-empty string."
+                    ),
+                    stage="routes",
+                    owner="assembly.routes",
+                    action="compile_route_manifest",
+                )
+            out.append(value)
+        if out:
+            return tuple(out)
+        raise PzError(
+            code="PZ_ROUTING_SUPPORTED_LANGUAGES_INVALID",
+            message="routing.all_supported_languages must declare at least one language when configured.",
+            stage="routes",
+            owner="assembly.routes",
+            action="compile_route_manifest",
+        )
+    return ("en",)
+
+
+def _language_aliases(settings: SettingsSnapshot, languages: tuple[str, ...]) -> dict[str, str]:
+    raw = settings.get("routing", "language_aliases", default=None)
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise PzError(
+            code="PZ_ROUTING_LANGUAGE_ALIASES_INVALID",
+            message="routing.language_aliases must be an object mapping alias language segments to supported languages.",
+            stage="routes",
+            owner="assembly.routes",
+            action="compile_route_manifest",
+        )
+    supported = {item.casefold(): item for item in languages if item}
+    aliases: dict[str, str] = {}
+    for raw_alias, raw_target in raw.items():
+        if not isinstance(raw_alias, str) or not raw_alias.strip():
+            raise PzError(
+                code="PZ_ROUTING_LANGUAGE_ALIAS_INVALID",
+                message="routing.language_aliases keys must be non-empty strings.",
+                stage="routes",
+                owner="assembly.routes",
+                action="compile_route_manifest",
+            )
+        if not isinstance(raw_target, str) or not raw_target.strip():
+            raise PzError(
+                code="PZ_ROUTING_LANGUAGE_ALIAS_TARGET_INVALID",
+                message="routing.language_aliases values must be non-empty supported language strings.",
+                stage="routes",
+                owner="assembly.routes",
+                action="compile_route_manifest",
+            )
+        alias = raw_alias.strip().strip("/")
+        target = raw_target.strip().strip("/")
+        canonical_target = supported.get(target.casefold())
+        if not canonical_target:
+            raise PzError(
+                code="PZ_ROUTING_LANGUAGE_ALIAS_TARGET_UNSUPPORTED",
+                message=f"routing.language_aliases target '{target}' must be listed in routing.all_supported_languages.",
+                stage="routes",
+                owner="assembly.routes",
+                action="compile_route_manifest",
+            )
+        if alias.casefold() == canonical_target.casefold():
+            raise PzError(
+                code="PZ_ROUTING_LANGUAGE_ALIAS_REDUNDANT",
+                message=f"routing.language_aliases alias '{alias}' must not point to itself.",
+                stage="routes",
+                owner="assembly.routes",
+                action="compile_route_manifest",
+            )
+        aliases[alias] = canonical_target
+    return aliases
+
+
+def _read_required_string(
+    value: object,
+    *,
+    code: str,
+    message: str,
+    owner: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="routes",
+            owner=owner,
+            action="compile_route_manifest",
+        )
+    return value.strip()
+
+
+def _read_optional_string(
+    value: object,
+    *,
+    default: str,
+    code: str,
+    message: str,
+    owner: str,
+) -> str:
+    if value is None:
+        return default
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="routes",
+            owner=owner,
+            action="compile_route_manifest",
+    )
+    return value.strip()
+
+
+def _read_required_path(
+    value: object,
+    *,
+    code: str,
+    message: str,
+    owner: str,
+) -> str:
+    path = _read_required_string(
+        value,
+        code=code,
+        message=message,
+        owner=owner,
+    )
+    if not path.startswith("/"):
+        raise PzError(
+            code=code,
+            message=message,
+            stage="routes",
+            owner=owner,
+            action="compile_route_manifest",
+        )
+    return path
+
+
+def _read_optional_path(
+    value: object,
+    *,
+    default: str,
+    code: str,
+    message: str,
+    owner: str,
+) -> str:
+    if value is None:
+        return default
+    return _read_required_path(
+        value,
+        code=code,
+        message=message,
+        owner=owner,
+    )
+
+
+def _read_optional_bool(
+    value: object,
+    *,
+    default: bool,
+    code: str,
+    message: str,
+    owner: str,
+) -> bool:
+    if value is None:
+        return default
+    if not isinstance(value, bool):
+        raise PzError(
+            code=code,
+            message=message,
+            stage="routes",
+            owner=owner,
+            action="compile_route_manifest",
+        )
+    return value
+
+
+def _expand_route(
+    item: dict[str, Any],
+    *,
+    default_base_prefix: str,
+    api_version_prefix: str,
+    languages: tuple[str, ...],
+) -> tuple[RouteDecl, ...]:
+    owner = _read_optional_string(
+        item.get("owner"),
+        default="runtime",
+        code="PZ_ROUTE_OWNER_INVALID",
+        message="Route declarations must declare owner as a non-empty string when provided.",
+        owner="assembly.routes",
+    )
+    raw_path = item.get("path")
+    if raw_path is None:
+        raise PzError(
+            code="PZ_ROUTE_PATH_MISSING",
+            message="Route declarations must declare a non-empty path.",
+            stage="routes",
+            owner=owner,
+            action="compile_route_manifest",
+        )
+    raw_path = _read_required_path(
+        raw_path,
+        code="PZ_ROUTE_PATH_INVALID",
+        message="Route declarations must declare path as a slash-prefixed non-empty string.",
+        owner=owner,
+    )
+    source_path = raw_path
+    path = source_path
+    base_prefix = _read_optional_path(
+        item.get("base_prefix"),
+        default=default_base_prefix,
+        code="PZ_ROUTE_BASE_PREFIX_INVALID",
+        message=(
+            f"Route '{source_path}' base_prefix must be a slash-prefixed non-empty string when provided."
+        ),
+        owner=owner,
+    )
+    if _read_optional_bool(
+        item.get("api_version"),
+        default=False,
+        code="PZ_ROUTE_API_VERSION_INVALID",
+        message=f"Route '{source_path}' api_version must be a boolean when provided.",
+        owner=owner,
+    ):
+        path = _join_path(api_version_prefix, path)
+    if base_prefix:
+        path = _join_path(base_prefix, path)
+
+    method = _read_optional_string(
+        item.get("method"),
+        default="GET",
+        code="PZ_ROUTE_METHOD_INVALID",
+        message=f"Route '{source_path}' method must be a non-empty string when provided.",
+        owner=owner,
+    ).upper()
+    name = _read_optional_string(
+        item.get("name"),
+        default=f"{owner}:{path}",
+        code="PZ_ROUTE_NAME_INVALID",
+        message=f"Route '{source_path}' name must be a non-empty string when provided.",
+        owner=owner,
+    )
+    i18n_aware = _read_optional_bool(
+        item.get("i18n_aware"),
+        default=False,
+        code="PZ_ROUTE_I18N_AWARE_INVALID",
+        message=f"Route '{source_path}' i18n_aware must be a boolean when provided.",
+        owner=owner,
+    )
+    if not i18n_aware:
+        return (RouteDecl(path=path, method=method, name=name, owner=owner, source_path=source_path),)
+
+    expanded: list[RouteDecl] = [
+        RouteDecl(path=path, method=method, name=name, owner=owner, source_path=source_path)
+    ]
+    for language in languages:
+        expanded.append(
+            RouteDecl(
+                path=_join_path(language, path),
+                method=method,
+                name=f"{name}:{language}",
+                owner=owner,
+                source_path=source_path,
+            )
+        )
+    return tuple(expanded)
+
+
+def _validate_conflicts(routes: tuple[RouteDecl, ...], conflict_policy: str) -> None:
+    seen: dict[tuple[str, str], RouteDecl] = {}
+    duplicates: list[str] = []
+    for route in routes:
+        key = (route.method, route.path)
+        previous = seen.get(key)
+        if previous is not None:
+            duplicates.append(f"{route.method} {route.path} ({previous.owner}, {route.owner})")
+            continue
+        seen[key] = route
+    if duplicates and conflict_policy != "warn":
+        raise PzError(
+            code="PZ_ROUTE_CONFLICT",
+            message="Route conflict detected before runtime registration: " + ", ".join(duplicates),
+            stage="routes",
+            owner="assembly.routes",
+            action="compile_route_manifest",
+        )
+
+
+def compile_route_manifest(settings: SettingsSnapshot) -> RouteManifest:
+    routes: list[RouteDecl] = []
+    conflict_policy = _read_optional_string(
+        settings.get("routing", "conflict_policy", default=None),
+        default="fail",
+        code="PZ_ROUTE_CONFLICT_POLICY_INVALID",
+        message="routing.conflict_policy must be one of: fail, warn.",
+        owner="assembly.routes",
+    ).lower()
+    if conflict_policy not in {"fail", "warn"}:
+        raise PzError(
+            code="PZ_ROUTE_CONFLICT_POLICY_INVALID",
+            message="routing.conflict_policy must be one of: fail, warn.",
+            stage="routes",
+            owner="assembly.routes",
+            action="compile_route_manifest",
+        )
+    default_base_prefix = _read_optional_path(
+        settings.get("routing", "base_prefix", default=None),
+        default="",
+        code="PZ_ROUTE_BASE_PREFIX_INVALID",
+        message="routing.base_prefix must be a slash-prefixed non-empty string when provided.",
+        owner="assembly.routes",
+    )
+    api_version_prefix = _read_optional_path(
+        settings.get("routing", "api_version_prefix", default=None),
+        default="/api/v1",
+        code="PZ_ROUTE_API_VERSION_PREFIX_INVALID",
+        message="routing.api_version_prefix must be a slash-prefixed non-empty string when provided.",
+        owner="assembly.routes",
+    )
+    languages = _languages(settings)
+    _language_aliases(settings, languages)
+
+    raw_routes = settings.get("routes", default=[])
+    if not isinstance(raw_routes, list):
+        raise PzError(
+            code="PZ_ROUTES_CONFIG_INVALID",
+            message="Routes configuration must be declared as an array.",
+            stage="routes",
+            owner="assembly.routes",
+            action="compile_route_manifest",
+        )
+    for index, item in enumerate(raw_routes):
+        if not isinstance(item, dict):
+            raise PzError(
+                code="PZ_ROUTE_ITEM_INVALID",
+                message=f"Route entry at index {index} must be a table/object declaration.",
+                stage="routes",
+                owner="assembly.routes",
+                action="compile_route_manifest",
+            )
+        routes.extend(
+            _expand_route(
+                item,
+                default_base_prefix=default_base_prefix,
+                api_version_prefix=api_version_prefix,
+                languages=languages,
+            )
+        )
+
+    manifest = RouteManifest(routes=tuple(routes), conflict_policy="warn" if conflict_policy == "warn" else "fail")
+    _validate_conflicts(manifest.routes, manifest.conflict_policy)
+    return manifest

pz_core/assembly/runtime_manifests/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from .compiler import (
+    RuntimeManifestContributionContext,
+    RuntimeManifestMap,
+    compile_runtime_manifests,
+)
+
+__all__ = [
+    "RuntimeManifestContributionContext",
+    "RuntimeManifestMap",
+    "compile_runtime_manifests",
+]

pz_core/assembly/runtime_manifests/compiler.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import import_module
+from typing import Any
+
+from pz_core.assembly.apps import AppRegistry
+from pz_core.assembly.project import ProjectContext
+from pz_core.assembly.resources import ResourceManifest
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.core.extensions import ExtensionRegistry, RuntimeManifestContributionSpec
+
+
+RuntimeManifestMap = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeManifestContributionContext:
+    project: ProjectContext
+    settings: SettingsSnapshot
+    app_registry: AppRegistry
+    extension_registry: ExtensionRegistry
+    resource_manifest: ResourceManifest
+    runtime_manifests: Mapping[str, Any]
+
+
+def _resolve_dotted(target: str) -> Any:
+    if ":" in target:
+        module_name, attr_name = target.split(":", 1)
+    else:
+        module_name, attr_name = target.rsplit(".", 1)
+    module = import_module(module_name)
+    return getattr(module, attr_name)
+
+
+def _resolve_provider(provider: Any) -> Any:
+    if isinstance(provider, str):
+        provider = _resolve_dotted(provider)
+    if isinstance(provider, type):
+        return provider()
+    return provider
+
+
+def _normalize_provider_result(payload: Any, *, owner: str) -> tuple[tuple[str, Any], ...]:
+    if payload in (None, (), []):
+        return ()
+    if isinstance(payload, tuple) and len(payload) == 2 and isinstance(payload[0], str):
+        return ((payload[0], payload[1]),)
+    if isinstance(payload, Mapping):
+        return tuple((str(key), value) for key, value in dict(payload).items())
+    if isinstance(payload, (list, tuple)):
+        out: list[tuple[str, Any]] = []
+        for item in payload:
+            if not isinstance(item, tuple) or len(item) != 2 or not isinstance(item[0], str):
+                raise PzError(
+                    code="PZ_RUNTIME_MANIFEST_PROVIDER_RESULT_INVALID",
+                    message=(
+                        f"Runtime manifest provider '{owner}' must return a mapping or "
+                        "(manifest_key, manifest) pairs."
+                    ),
+                    stage="runtime_manifests",
+                    owner=owner,
+                    action="compile_runtime_manifests",
+                )
+            out.append((item[0], item[1]))
+        return tuple(out)
+    manifest_key = str(getattr(payload, "manifest_key", "") or "").strip()
+    if manifest_key:
+        return ((manifest_key, payload),)
+    raise PzError(
+        code="PZ_RUNTIME_MANIFEST_PROVIDER_RESULT_INVALID",
+        message=(
+            f"Runtime manifest provider '{owner}' must return a mapping, a manifest object with "
+            "manifest_key, or (manifest_key, manifest) pairs."
+        ),
+        stage="runtime_manifests",
+        owner=owner,
+        action="compile_runtime_manifests",
+    )
+
+
+def compile_runtime_manifests(
+    *,
+    project: ProjectContext,
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry,
+    extension_registry: ExtensionRegistry,
+    resource_manifest: ResourceManifest,
+) -> RuntimeManifestMap:
+    manifests: RuntimeManifestMap = {}
+    providers = tuple(
+        spec
+        for spec in tuple(getattr(extension_registry, "extensions", ()) or ())
+        if isinstance(spec, RuntimeManifestContributionSpec)
+    )
+    ordered = sorted(
+        providers,
+        key=lambda item: (int(item.priority), str(item.owner_app), str(item.id)),
+    )
+    for spec in ordered:
+        provider = _resolve_provider(spec.provider)
+        compile_method = getattr(provider, "compile", None)
+        if not callable(compile_method):
+            raise PzError(
+                code="PZ_RUNTIME_MANIFEST_PROVIDER_INVALID",
+                message=f"Runtime manifest provider '{spec.id}' must declare compile(ctx).",
+                stage="runtime_manifests",
+                owner=spec.owner_app,
+                action="compile_runtime_manifests",
+            )
+        ctx = RuntimeManifestContributionContext(
+            project=project,
+            settings=settings,
+            app_registry=app_registry,
+            extension_registry=extension_registry,
+            resource_manifest=resource_manifest,
+            runtime_manifests=dict(manifests),
+        )
+        try:
+            items = _normalize_provider_result(compile_method(ctx), owner=spec.id)
+        except PzError:
+            raise
+        except Exception as exc:
+            raise PzError(
+                code="PZ_RUNTIME_MANIFEST_PROVIDER_FAILED",
+                message=f"Runtime manifest provider '{spec.id}' failed while compiling runtime manifests: {exc}",
+                stage="runtime_manifests",
+                owner=spec.owner_app,
+                action="compile_runtime_manifests",
+            ) from exc
+        for manifest_key, manifest in items:
+            key = str(manifest_key or "").strip()
+            if not key:
+                raise PzError(
+                    code="PZ_RUNTIME_MANIFEST_KEY_INVALID",
+                    message=f"Runtime manifest provider '{spec.id}' returned an empty manifest key.",
+                    stage="runtime_manifests",
+                    owner=spec.owner_app,
+                    action="compile_runtime_manifests",
+                )
+            if key in manifests:
+                raise PzError(
+                    code="PZ_RUNTIME_MANIFEST_DUPLICATE_KEY",
+                    message=f"Runtime manifest key '{key}' is already compiled.",
+                    stage="runtime_manifests",
+                    owner=spec.owner_app,
+                    action="compile_runtime_manifests",
+                )
+            manifests[key] = manifest
+    return manifests
+
+
+__all__ = [
+    "RuntimeManifestContributionContext",
+    "RuntimeManifestMap",
+    "compile_runtime_manifests",
+]

pz_core/assembly/settings/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .compiler import (
+    SettingsSnapshot,
+    compile_settings_snapshot,
+    compile_settings_snapshot_from_payload,
+    load_project_env_file,
+)
+from .host_project_overrides import apply_host_project_env_overrides
+
+__all__ = [
+    "SettingsSnapshot",
+    "apply_host_project_env_overrides",
+    "compile_settings_snapshot",
+    "compile_settings_snapshot_from_payload",
+    "load_project_env_file",
+]