pz-cli 5.0.0__py3-none-any.whl

pz_foundation/lazy_exports.py

@@ -0,0 +1,43 @@
+"""Formal minimal helper surface for package-level lazy exports."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import import_module
+from typing import Any
+
+LazyExportTarget = str | tuple[str, str]
+LazyExportMap = Mapping[str, LazyExportTarget]
+
+
+def resolve_lazy_export(
+    module_name: str,
+    name: str,
+    export_map: LazyExportMap,
+    namespace: dict[str, Any],
+) -> Any:
+    try:
+        target = export_map[name]
+    except KeyError as exc:
+        raise AttributeError(f"module {module_name!r} has no attribute {name!r}") from exc
+
+    if isinstance(target, tuple):
+        target_module, attr_name = target
+    else:
+        target_module, attr_name = target, name
+
+    if target_module.startswith("."):
+        imported = import_module(target_module, package=module_name)
+    else:
+        imported = import_module(target_module)
+
+    value = getattr(imported, attr_name)
+    namespace[name] = value
+    return value
+
+
+def export_dir(namespace: Mapping[str, Any], exported_names: list[str]) -> list[str]:
+    return sorted(set(namespace).union(exported_names))
+
+
+__all__ = ["LazyExportMap", "LazyExportTarget", "export_dir", "resolve_lazy_export"]

pz_foundation/lazy_imports.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib import import_module
+from typing import Any, Callable
+
+
+@lru_cache(maxsize=None)
+def _import_module(module_name: str):
+    return import_module(module_name)
+
+
+class LazyImportProxy:
+    def __init__(
+        self,
+        resolver: Callable[[], Any],
+        label: str,
+        *,
+        module_name: str = "",
+        attr_name: str = "",
+        call_factory: bool = False,
+    ) -> None:
+        self._resolver = resolver
+        self._label = label
+        self._module_name = str(module_name or "")
+        self._attr_name = str(attr_name or "")
+        self._call_factory = bool(call_factory)
+
+    def _resolve(self) -> Any:
+        if "_resolved" not in self.__dict__:
+            self.__dict__["_resolved"] = self._resolver()
+        return self.__dict__["_resolved"]
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._resolve(), name)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._resolve()(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"<LazyImportProxy {self._label}>"
+
+    def __reduce__(self):
+        if not self._module_name or not self._attr_name:
+            raise TypeError(f"{self.__class__.__name__} '{self._label}' is not serializable")
+        return (
+            _rebuild_lazy_import_proxy,
+            (self._module_name, self._attr_name, self._call_factory),
+        )
+
+
+class LazyCallableProxy:
+    __slots__ = ("_module_name", "_attr_name", "_resolved")
+
+    def __init__(self, module_name: str, attr_name: str) -> None:
+        self._module_name = str(module_name)
+        self._attr_name = str(attr_name)
+        self._resolved: Callable[..., Any] | None = None
+
+    def _resolve(self) -> Callable[..., Any]:
+        if self._resolved is not None:
+            return self._resolved
+        value = getattr(_import_module(self._module_name), self._attr_name)
+        if not callable(value):
+            raise TypeError(f"{self._module_name}.{self._attr_name} must be callable")
+        self._resolved = value
+        return value
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._resolve()(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._resolve(), name)
+
+    def __repr__(self) -> str:
+        return f"<LazyCallableProxy {self._module_name}.{self._attr_name}>"
+
+
+def lazy_import_attr(module_name: str, attr_name: str) -> LazyImportProxy:
+    return LazyImportProxy(
+        resolver=lambda: getattr(_import_module(module_name), attr_name),
+        label=f"{module_name}.{attr_name}",
+        module_name=module_name,
+        attr_name=attr_name,
+    )
+
+
+def lazy_import_factory(module_name: str, attr_name: str) -> LazyImportProxy:
+    def _resolve() -> Any:
+        factory = getattr(_import_module(module_name), attr_name)
+        return factory()
+
+    return LazyImportProxy(
+        resolver=_resolve,
+        label=f"{module_name}.{attr_name}()",
+        module_name=module_name,
+        attr_name=attr_name,
+        call_factory=True,
+    )
+
+
+def _rebuild_lazy_import_proxy(module_name: str, attr_name: str, call_factory: bool) -> LazyImportProxy:
+    if call_factory:
+        return lazy_import_factory(module_name, attr_name)
+    return lazy_import_attr(module_name, attr_name)
+
+
+def install_lazy_callables(
+    *,
+    module_name: str,
+    names: tuple[str, ...],
+    namespace: dict[str, Any],
+) -> None:
+    for name in names:
+        namespace.setdefault(name, LazyCallableProxy(module_name, name))
+
+
+__all__ = [
+    "LazyCallableProxy",
+    "LazyImportProxy",
+    "install_lazy_callables",
+    "lazy_import_attr",
+    "lazy_import_factory",
+]

pz_foundation/lifecycle.py

@@ -0,0 +1,392 @@
+"""Foundation runtime lifecycle assembly."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pz_core.core.extensions import HostBuilderSpec
+from pz_core.core.middlewares import MiddlewareDecl
+import pz_settings_center.public as settings_center
+
+from .db import FoundationDatabaseSettings, load_foundation_database_settings, probe_foundation_database_binding
+from .health import probe_foundation_health
+from .host.builder import FoundationWebHostBuilder
+from .host.lifespan import InfraContext, setup_infra, shutdown_infra
+from .kv import FoundationRedisSettings, get_required_foundation_cache, load_foundation_redis_settings
+from .notifications import describe_email_backend_binding
+from .observability import metrics, probe_observability
+from .runtime import bind_runtime_state, reset_runtime_state
+from .storage import probe_foundation_storage
+
+
+MIDDLEWARES: tuple[MiddlewareDecl, ...] = (
+    MiddlewareDecl(
+        id="pz_foundation.geo_country",
+        factory="pz_foundation.middlewares:GeoCountryMiddleware",
+        owner="pz_foundation",
+        priority=10,
+    ),
+    MiddlewareDecl(
+        id="pz_foundation.cors",
+        factory="pz_foundation.middlewares:ConfigurableCORSMiddleware",
+        owner="pz_foundation",
+        priority=20,
+    ),
+    MiddlewareDecl(
+        id="pz_foundation.route_owner",
+        factory="pz_foundation.middlewares:DefaultLanguageRouteOwnerMiddleware",
+        owner="pz_foundation",
+        priority=58,
+    ),
+    MiddlewareDecl(
+        id="pz_foundation.security_csrf",
+        factory="pz_foundation.middlewares:SecurityCSRFMiddleware",
+        owner="pz_foundation",
+        priority=120,
+    ),
+    MiddlewareDecl(
+        id="pz_foundation.cache_control",
+        factory="pz_foundation.middlewares:CacheControlMiddleware",
+        owner="pz_foundation",
+        priority=160,
+    ),
+    MiddlewareDecl(
+        id="pz_foundation.compression",
+        factory="pz_foundation.middlewares:CompressionMiddleware",
+        owner="pz_foundation",
+        priority=165,
+    ),
+    MiddlewareDecl(
+        id="pz_foundation.analytics",
+        factory="pz_foundation.middlewares:AnalyticsMiddleware",
+        owner="pz_foundation",
+        priority=170,
+    ),
+    MiddlewareDecl(
+        id="pz_foundation.csp_nonce",
+        factory="pz_foundation.middlewares.security_headers.csp_nonce:CSPNonceSecurityHeadersMiddleware",
+        owner="pz_foundation",
+        priority=180,
+    ),
+)
+
+EXTENSIONS: tuple[HostBuilderSpec, ...] = (
+    HostBuilderSpec(
+        id="pz_foundation.host.builder.web",
+        owner_app="pz_foundation",
+        title="Foundation Web Host Builder",
+        priority=100,
+        builder=FoundationWebHostBuilder(),
+    ),
+)
+
+PROVIDERS: tuple[dict[str, object], ...] = (
+    {
+        "id": "foundation-resource-builder",
+        "capability": "resources",
+        "owner": "pz_foundation",
+        "provider_path": "pz_foundation.resources.builder:build_resource_provider",
+    },
+    {
+        "id": "foundation-db-migrations",
+        "capability": "database.migrations",
+        "owner": "pz_foundation",
+        "provider_path": "pz_foundation.db.migrations:build_migration_provider",
+    },
+    {
+        "id": "foundation-storage",
+        "capability": "storage",
+        "owner": "pz_foundation",
+        "provider_path": "pz_foundation.storage.service:build_storage_provider",
+    },
+)
+
+_LIFECYCLE_INFRA_CONTEXTS: dict[str, InfraContext] = {}
+
+def _safe_assign_runtime_state(state: object | None, **values: Any) -> None:
+    if state is None:
+        return
+    for key, value in values.items():
+        try:
+            setattr(state, key, value)
+        except (AttributeError, TypeError):
+            continue
+
+
+def _host_state(host: object | None) -> object | None:
+    state = getattr(host, "state", None)
+    if state is None or state.__class__.__module__.startswith("pz_core.runtime"):
+        return None
+    return state
+
+
+def _runtime_owner_key(app_id: str, host: object | None, context: object | None) -> str:
+    if _host_state(host) is not None:
+        return f"{app_id}:host:{id(host)}"
+    plan = getattr(context, "plan", None) if context is not None else None
+    if plan is not None:
+        return f"{app_id}:plan:{id(plan)}"
+    return f"{app_id}:host:{id(host)}"
+
+
+async def _setup_lifecycle_infra(
+    *,
+    context: object,
+    project_dir: object,
+) -> InfraContext:
+    settings_snapshot = getattr(getattr(context, "plan", None), "settings", None)
+    return await setup_infra(
+        settings_snapshot,
+        project_dir=str(project_dir) if project_dir is not None else None,
+        start_background_tasks=False,
+    )
+
+
+async def _shutdown_lifecycle_infra(
+    host: object | None,
+    context: object | None,
+    *,
+    owner: str | None,
+) -> None:
+    state = _host_state(host)
+    ctx = getattr(state, "pz_foundation_lifecycle_infra_context", None) if state is not None else None
+    if ctx is None and owner is not None:
+        ctx = _LIFECYCLE_INFRA_CONTEXTS.pop(owner, None)
+    elif owner is not None:
+        _LIFECYCLE_INFRA_CONTEXTS.pop(owner, None)
+    if ctx is not None:
+        await shutdown_infra(ctx)
+
+
+def _resolve_component_capability_status(default_state: str, status: dict[str, Any] | None) -> str:
+    payload = dict(status or {})
+    if not bool(payload.get("enabled")):
+        return "disabled"
+    if bool(payload.get("probe_deferred")) and not str(payload.get("error") or "").strip():
+        return default_state if default_state in {"enabled", "ready"} else "enabled"
+    if bool(payload.get("ready")):
+        return "ready"
+    if str(payload.get("error") or "").strip() or not bool(payload.get("configured")) or bool(payload.get("enabled")):
+        return "unavailable"
+    return default_state if default_state in {"enabled", "ready"} else "enabled"
+
+
+def _resolve_cache_capability_status(default_state: str, status: dict[str, Any] | None) -> str:
+    return _resolve_component_capability_status(default_state, status)
+
+
+def _resolve_health_capability_status(default_state: str, status: dict[str, Any] | None) -> str:
+    payload = dict(status or {})
+    if not bool(payload.get("enabled", True)):
+        return "disabled"
+    if bool(payload.get("ready")):
+        return "ready"
+    if payload.get("issues") or str(payload.get("error") or "").strip() or bool(payload.get("enabled", True)):
+        return "unavailable"
+    return default_state if default_state in {"enabled", "ready"} else "enabled"
+
+
+def _database_is_configured(db_settings: Any) -> bool:
+    if not bool(getattr(db_settings, "enabled", False)):
+        return False
+    driver = str(getattr(db_settings, "driver", "") or "").strip().lower() or "sqlite"
+    urls = tuple(getattr(db_settings, "urls", ()) or ())
+    if driver == "sqlite":
+        return bool(str(getattr(db_settings, "path", "") or (urls[0] if urls else "") or "").strip())
+    return bool(urls or str(getattr(db_settings, "host", "") or "").strip())
+
+
+def _redis_is_configured(redis_settings: Any) -> bool:
+    if not bool(getattr(redis_settings, "enabled", False)):
+        return False
+    return bool(str(getattr(redis_settings, "url", "") or getattr(redis_settings, "host", "") or "").strip())
+
+
+async def startup_foundation(host: object, context: object, *, app_id: str = "foundation") -> None:
+    settings_obj = settings_center.settings.pz_foundation
+    if not settings_obj.enabled:
+        return
+    project = getattr(getattr(context, "plan", None), "project", None)
+    project_dir = getattr(project, "project_dir", None)
+    owner = _runtime_owner_key(app_id, host, context)
+    infra_ctx = await _setup_lifecycle_infra(context=context, project_dir=project_dir)
+    _LIFECYCLE_INFRA_CONTEXTS[owner] = infra_ctx
+    database_status = _bind_database(project_dir, settings_obj)
+    kv_status = _bind_kv(project_dir, settings_obj)
+    mail_status = _bind_mail(project_dir, settings_obj)
+    storage_status = _bind_storage(project_dir, settings_obj)
+    observability_status = _bind_observability(project_dir, settings_obj)
+    health_status = _bind_health(
+        project_dir,
+        settings_obj,
+        database_status=database_status,
+        kv_status=kv_status,
+        mail_status=mail_status,
+        storage_status=storage_status,
+        observability_status=observability_status,
+    )
+    capability_statuses = {
+        "cache": _resolve_cache_capability_status(settings_obj.cache.state, kv_status),
+        "database": _resolve_component_capability_status("enabled", database_status),
+        "health": _resolve_health_capability_status(settings_obj.health.state, health_status),
+        "mail": _resolve_component_capability_status(settings_obj.mail.state, mail_status),
+        "observability": _resolve_component_capability_status(
+            settings_obj.observability.state,
+            observability_status,
+        ),
+        "storage": _resolve_component_capability_status(settings_obj.storage.state, storage_status),
+    }
+    runtime_state = bind_runtime_state(
+        capability_statuses=capability_statuses,
+        database_status=database_status,
+        kv_status=kv_status,
+        mail_status=mail_status,
+        storage_status=storage_status,
+        observability_status=observability_status,
+        health_status=health_status,
+        project_dir=project_dir,
+        owner=owner,
+    )
+    metrics.foundation_runtime_ready.set(1.0 if health_status.get("ready") else 0.0)
+    state = _host_state(host)
+    _safe_assign_runtime_state(
+        state,
+        pz_foundation_owner=owner,
+        pz_foundation_lifecycle_infra_context=infra_ctx,
+        pz_foundation_runtime=runtime_state,
+        pz_foundation_database=database_status,
+        pz_foundation_kv=kv_status,
+        pz_foundation_mail=mail_status,
+        pz_foundation_storage=storage_status,
+        pz_foundation_observability=observability_status,
+        pz_foundation_health=health_status,
+    )
+
+
+async def shutdown_foundation(host: object, context: object | None = None, *, app_id: str = "foundation") -> None:
+    state = _host_state(host)
+    owner = getattr(state, "pz_foundation_owner", None) if state is not None else _runtime_owner_key(app_id, host, context)
+    await _shutdown_lifecycle_infra(host, context, owner=owner)
+    reset_runtime_state(owner=owner)
+    metrics.foundation_runtime_ready.set(0.0)
+    _safe_assign_runtime_state(
+        state,
+        pz_foundation_owner=None,
+        pz_foundation_lifecycle_infra_context=None,
+        pz_foundation_runtime=None,
+        pz_foundation_database=None,
+        pz_foundation_kv=None,
+        pz_foundation_mail=None,
+        pz_foundation_storage=None,
+        pz_foundation_observability=None,
+        pz_foundation_health=None,
+    )
+
+
+def _bind_database(project_dir: object, settings_obj: object) -> dict[str, Any]:
+    del settings_obj
+    db_settings = _database_settings(project_dir)
+    return probe_foundation_database_binding(project_dir=project_dir, settings=db_settings)
+
+
+def _bind_kv(project_dir: object, settings_obj: object) -> dict[str, Any]:
+    if not settings_obj.cache.enabled:
+        return {
+            "enabled": False,
+            "configured": False,
+            "backend": None,
+            "operational": False,
+            "degraded": False,
+            "ready": False,
+            "error": None,
+        }
+    redis_settings = _redis_settings(project_dir)
+    status: dict[str, Any] = {
+        "enabled": bool(redis_settings.enabled),
+        "configured": _redis_is_configured(redis_settings),
+        "backend": None,
+        "operational": False,
+        "degraded": False,
+        "ready": False,
+        "error": None,
+        "host": redis_settings.host or None,
+        "port": redis_settings.port,
+        "db": redis_settings.db,
+        "url": redis_settings.url or None,
+    }
+    if not redis_settings.enabled:
+        return status
+    try:
+        cache = get_required_foundation_cache(
+            project_dir=project_dir,
+            settings=redis_settings,
+            capability_name="foundation redis",
+        )
+        probe_key = "__foundation_probe__"
+        cache.set(probe_key, "1", ex=1)
+        operational = cache.get(probe_key) == "1"
+        status["backend"] = "redis"
+        status["operational"] = operational
+        status["degraded"] = False
+        status["ready"] = bool(redis_settings.enabled) and operational
+        try:
+            cache.delete(probe_key)
+        except Exception:
+            pass
+    except Exception as exc:
+        status["degraded"] = True
+        status["error"] = f"{type(exc).__name__}: {exc}"
+    return status
+
+
+def _database_settings(project_dir: object) -> FoundationDatabaseSettings:
+    return load_foundation_database_settings(
+        project_dir=str(project_dir) if project_dir is not None else None,
+    )
+
+
+def _redis_settings(project_dir: object) -> FoundationRedisSettings:
+    return load_foundation_redis_settings(
+        project_dir=str(project_dir) if project_dir is not None else None,
+    )
+
+def _read_float(value: object, default: float) -> float:
+    try:
+        return float(value if value is not None else default)
+    except Exception:
+        return default
+
+
+def _bind_mail(project_dir: object, settings_obj: object) -> dict[str, Any]:
+    if not settings_obj.mail.enabled:
+        return {"enabled": False, "configured": False, "ready": False, "error": None, "probe_deferred": False}
+    return describe_email_backend_binding(project_dir=project_dir)
+
+
+def _bind_storage(project_dir: object, settings_obj: object) -> dict[str, Any]:
+    if not settings_obj.storage.enabled:
+        return {"enabled": False, "configured": False, "ready": False, "error": None}
+    metrics.foundation_storage_probes_total.inc()
+    return probe_foundation_storage(project_dir=project_dir)
+
+
+def _bind_observability(project_dir: object, settings_obj: object) -> dict[str, Any]:
+    if not settings_obj.observability.enabled:
+        return {"enabled": False, "configured": False, "ready": False, "error": None}
+    return probe_observability(project_dir=project_dir)
+
+
+def _bind_health(project_dir: object, settings_obj: object, **statuses: Any) -> dict[str, Any]:
+    if not settings_obj.health.enabled:
+        return {"enabled": False, "configured": False, "ready": False, "error": None}
+    metrics.foundation_health_checks_total.inc()
+    return probe_foundation_health(project_dir=project_dir, **statuses)
+
+
+__all__ = [
+    "EXTENSIONS",
+    "MIDDLEWARES",
+    "PROVIDERS",
+    "shutdown_foundation",
+    "startup_foundation",
+]