pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/http/app.py

@@ -0,0 +1,576 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import import_module
+import inspect
+import json
+from pathlib import Path
+from dataclasses import replace
+from typing import Any, Awaitable, Callable
+from uuid import uuid4
+
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.plan_context import active_runtime_plan
+from pz_core.core.middlewares import MiddlewareDecl
+from pz_core.runtime.adapters import RuntimeAdapter
+from pz_core.runtime.bindings import RuntimeBindings, compile_runtime_bindings
+from pz_core.runtime.facades import HealthFacade
+from pz_core.runtime.lifecycle import (
+    LifecycleState,
+    activate_runtime_plan,
+    activate_runtime_plan_async,
+    bind_runtime_plan,
+    shutdown_runtime_plan,
+    shutdown_runtime_plan_async,
+)
+from pz_core.runtime.plan import RuntimePlan, compile_runtime_plan
+from pz_core.runtime.plan_snapshot import write_runtime_plan_snapshot_if_requested
+from pz_core.runtime.settings import active_settings_project, bound_settings_snapshot
+from pz_core.runtime.http_timing import instrument_asgi_timing
+
+ASGIApp = Callable[[dict[str, Any], Any, Any], Awaitable[None]]
+
+
+def _http_error_from_exc(exc: PzError) -> dict[str, object]:
+    return _error_payload(
+        code=exc.code,
+        owner=exc.owner,
+        action=exc.action,
+        summary=exc.summary or exc.message,
+        message=exc.message,
+    )
+
+
+def _decode_header_bytes(raw: object, *, action: str) -> bytes:
+    if isinstance(raw, bytes):
+        return raw
+    raise PzError(
+        code="PZ_HTTP_REQUEST_ID_INVALID",
+        message="x-request-id header must use bytes values.",
+        stage="http",
+        owner="runtime.http",
+        action=action,
+        summary="HTTP x-request-id header is invalid.",
+    )
+
+
+def _read_headers(scope: dict[str, Any], *, action: str) -> list[tuple[bytes, bytes]]:
+    if "headers" not in scope:
+        return []
+    headers = scope.get("headers")
+    if headers is None:
+        raise PzError(
+            code="PZ_HTTP_HEADERS_INVALID",
+            message="HTTP scope headers must not be null when configured.",
+            stage="http",
+            owner="runtime.http",
+            action=action,
+            summary="HTTP headers are invalid.",
+        )
+    if not isinstance(headers, list):
+        raise PzError(
+            code="PZ_HTTP_HEADERS_INVALID",
+            message="HTTP scope headers must be declared as a list of header pairs.",
+            stage="http",
+            owner="runtime.http",
+            action=action,
+            summary="HTTP headers are invalid.",
+        )
+    normalized: list[tuple[bytes, bytes]] = []
+    for index, item in enumerate(headers):
+        if not isinstance(item, (list, tuple)) or len(item) != 2:
+            raise PzError(
+                code="PZ_HTTP_HEADERS_INVALID",
+                message=f"HTTP header entry at index {index} must be a 2-item pair.",
+                stage="http",
+                owner="runtime.http",
+                action=action,
+                summary="HTTP headers are invalid.",
+            )
+        key, value = item
+        try:
+            normalized_key = _decode_header_bytes(key, action=action)
+        except PzError as exc:
+            raise PzError(
+                code="PZ_HTTP_HEADERS_INVALID",
+                message=f"HTTP header entry at index {index} must use bytes values.",
+                stage="http",
+                owner="runtime.http",
+                action=action,
+                summary="HTTP headers are invalid.",
+            ) from exc
+        try:
+            normalized_value = _decode_header_bytes(value, action=action)
+        except PzError as exc:
+            if normalized_key.lower() == b"x-request-id":
+                raise exc
+            raise PzError(
+                code="PZ_HTTP_HEADERS_INVALID",
+                message=f"HTTP header entry at index {index} must use bytes values.",
+                stage="http",
+                owner="runtime.http",
+                action=action,
+                summary="HTTP headers are invalid.",
+            ) from exc
+        normalized.append((normalized_key, normalized_value))
+    return normalized
+
+
+def _request_id(scope: dict[str, Any]) -> str:
+    for key, value in _read_headers(scope, action="dispatch"):
+        if key.lower() == b"x-request-id":
+            raw_value = value
+            try:
+                decoded = raw_value.decode("utf-8").strip()
+            except UnicodeDecodeError as exc:
+                raise PzError(
+                    code="PZ_HTTP_REQUEST_ID_INVALID",
+                    message="x-request-id header must be valid UTF-8.",
+                    stage="http",
+                    owner="runtime.http",
+                    action="dispatch",
+                    summary="HTTP x-request-id header is invalid.",
+                ) from exc
+            if decoded:
+                return decoded
+            raise PzError(
+                code="PZ_HTTP_REQUEST_ID_INVALID",
+                message="x-request-id header must be a non-empty UTF-8 string.",
+                stage="http",
+                owner="runtime.http",
+                action="dispatch",
+                summary="HTTP x-request-id header is invalid.",
+            )
+    return uuid4().hex
+
+
+def _read_scope_path(scope: dict[str, Any]) -> str:
+    if "path" not in scope:
+        return "/"
+    raw_path = scope.get("path")
+    if not isinstance(raw_path, str) or not raw_path.strip():
+        raise PzError(
+            code="PZ_HTTP_PATH_INVALID",
+            message="HTTP scope path must be a non-empty string.",
+            stage="http",
+            owner="runtime.http",
+            action="dispatch",
+            summary="HTTP scope path is invalid.",
+        )
+    if not raw_path.startswith("/"):
+        raise PzError(
+            code="PZ_HTTP_PATH_INVALID",
+            message="HTTP scope path must start with '/'.",
+            stage="http",
+            owner="runtime.http",
+            action="dispatch",
+            summary="HTTP scope path is invalid.",
+        )
+    return raw_path
+
+
+def _read_scope_type(scope: dict[str, Any]) -> str:
+    raw_type = scope.get("type")
+    if not isinstance(raw_type, str) or not raw_type.strip():
+        raise PzError(
+            code="PZ_HTTP_SCOPE_TYPE_INVALID",
+            message="HTTP scope type must be a non-empty string.",
+            stage="http",
+            owner="runtime.http",
+            action="dispatch",
+            summary="HTTP scope type is invalid.",
+        )
+    return raw_type
+
+
+def _read_scope_method(scope: dict[str, Any]) -> str | None:
+    if "method" not in scope:
+        return None
+    raw_method = scope.get("method")
+    if not isinstance(raw_method, str) or not raw_method.strip():
+        raise PzError(
+            code="PZ_HTTP_METHOD_INVALID",
+            message="HTTP scope method must be a non-empty string when configured.",
+            stage="http",
+            owner="runtime.http",
+            action="dispatch",
+            summary="HTTP scope method is invalid.",
+        )
+    return raw_method
+
+
+async def _send_json(send: Any, status: int, payload: dict[str, Any], *, request_id: str) -> None:
+    body_payload = dict(payload)
+    body_payload.setdefault("request_id", request_id)
+    body = json.dumps(body_payload, ensure_ascii=True, sort_keys=True).encode("utf-8")
+    headers = [
+        (b"content-type", b"application/json"),
+        (b"content-length", str(len(body)).encode("ascii")),
+        (b"x-request-id", request_id.encode("utf-8")),
+    ]
+    await send({"type": "http.response.start", "status": status, "headers": headers})
+    await send({"type": "http.response.body", "body": body})
+
+
+def _error_payload(
+    *,
+    code: str,
+    owner: str,
+    action: str,
+    summary: str,
+    **extra: object,
+) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "status": "error",
+        "code": code,
+        "stage": "http",
+        "owner": owner,
+        "action": action,
+        "summary": summary,
+    }
+    payload.update(extra)
+    return payload
+
+
+def _import_middleware_factory(decl: MiddlewareDecl) -> Callable[..., ASGIApp]:
+    module_name, _, attr_name = decl.factory.partition(":")
+    try:
+        module = import_module(module_name)
+        factory = getattr(module, attr_name)
+    except Exception as exc:
+        raise PzError(
+            code="PZ_MIDDLEWARE_FACTORY_IMPORT_FAILED",
+            message=f"Failed to import middleware factory '{decl.factory}': {exc}",
+            stage="http",
+            owner=decl.owner,
+            action="create_application_runtime",
+        ) from exc
+    if not callable(factory):
+        raise PzError(
+            code="PZ_MIDDLEWARE_FACTORY_INVALID",
+            message=f"Middleware factory '{decl.factory}' is not callable.",
+            stage="http",
+            owner=decl.owner,
+            action="create_application_runtime",
+        )
+    return factory
+
+
+def apply_runtime_middlewares(
+    app: ASGIApp,
+    *,
+    plan: RuntimePlan,
+    bindings: RuntimeBindings,
+) -> ASGIApp:
+    host_app = app
+    wrapped = instrument_asgi_timing(app, label="app.core")
+    for decl in reversed(plan.middleware_manifest.middlewares):
+        factory = _import_middleware_factory(decl)
+        try:
+            runtime_params = dict(decl.params or {})
+            call_kwargs = {
+                "bindings": bindings,
+                "plan": plan,
+                "decl": decl,
+                "params": runtime_params,
+                "host_app": host_app,
+            }
+            for name, value in runtime_params.items():
+                if name not in call_kwargs:
+                    call_kwargs[name] = value
+            try:
+                signature = inspect.signature(factory)
+            except (TypeError, ValueError):
+                signature = None
+            if signature is None:
+                filtered_kwargs = call_kwargs
+            else:
+                accepts_var_kwargs = any(
+                    parameter.kind is inspect.Parameter.VAR_KEYWORD
+                    for parameter in signature.parameters.values()
+                )
+                if accepts_var_kwargs:
+                    filtered_kwargs = call_kwargs
+                else:
+                    filtered_kwargs = {
+                        name: value
+                        for name, value in call_kwargs.items()
+                        if name in signature.parameters
+                    }
+            candidate = factory(wrapped, **filtered_kwargs)
+        except PzError:
+            raise
+        except Exception as exc:
+            raise PzError(
+                code="PZ_MIDDLEWARE_FACTORY_FAILED",
+                message=f"Middleware '{decl.id}' factory execution failed: {exc}",
+                stage="http",
+                owner=decl.owner,
+                action="create_application_runtime",
+            ) from exc
+        if not callable(candidate):
+            raise PzError(
+                code="PZ_MIDDLEWARE_FACTORY_INVALID",
+                message=f"Middleware '{decl.id}' did not return an ASGI callable.",
+                stage="http",
+                owner=decl.owner,
+                action="create_application_runtime",
+            )
+        wrapped = instrument_asgi_timing(candidate, label=f"middleware:{decl.id}")
+    return instrument_asgi_timing(wrapped, label="middleware.total")
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationRuntime:
+    adapter: RuntimeAdapter
+    http_app: ASGIApp | None = None
+
+    @property
+    def pz_runtime(self) -> "ApplicationRuntime":
+        return self
+
+    @property
+    def plan(self) -> RuntimePlan:
+        return self.adapter.plan
+
+    @property
+    def state(self) -> LifecycleState:
+        return self.adapter.state
+
+    @property
+    def bindings(self) -> RuntimeBindings:
+        return self.adapter.bindings
+
+    def activate(self) -> "ApplicationRuntime":
+        if self.state.phase == "started":
+            return self
+        started_state = activate_runtime_plan(
+            self.plan,
+            self.state,
+            bindings=self.bindings,
+            host=self,
+        )
+        bindings = replace(
+            self.bindings,
+            health=HealthFacade(
+                self.plan,
+                started_state,
+                providers=self.bindings.providers,
+            ),
+        )
+        runtime = replace(
+            self,
+            adapter=replace(
+                self.adapter,
+                state=started_state,
+                bindings=bindings,
+            ),
+        )
+        return replace(runtime, http_app=_compile_http_app(runtime))
+
+    def shutdown(self) -> "ApplicationRuntime":
+        if self.state.phase == "stopped":
+            return self
+        stopped_state = shutdown_runtime_plan(
+            self.plan,
+            self.state,
+            bindings=self.bindings,
+            host=self,
+        )
+        bindings = replace(
+            self.bindings,
+            health=HealthFacade(
+                self.plan,
+                stopped_state,
+                providers=self.bindings.providers,
+            ),
+        )
+        runtime = replace(
+            self,
+            adapter=replace(
+                self.adapter,
+                state=stopped_state,
+                bindings=bindings,
+            ),
+        )
+        return replace(runtime, http_app=_compile_http_app(runtime))
+
+    async def activate_async(self) -> "ApplicationRuntime":
+        if self.state.phase == "started":
+            return self
+        started_state = await activate_runtime_plan_async(
+            self.plan,
+            self.state,
+            bindings=self.bindings,
+            host=self,
+        )
+        bindings = replace(
+            self.bindings,
+            health=HealthFacade(
+                self.plan,
+                started_state,
+                providers=self.bindings.providers,
+            ),
+        )
+        runtime = replace(
+            self,
+            adapter=replace(
+                self.adapter,
+                state=started_state,
+                bindings=bindings,
+            ),
+        )
+        return replace(runtime, http_app=_compile_http_app(runtime))
+
+    async def shutdown_async(self) -> "ApplicationRuntime":
+        if self.state.phase == "stopped":
+            return self
+        stopped_state = await shutdown_runtime_plan_async(
+            self.plan,
+            self.state,
+            bindings=self.bindings,
+            host=self,
+        )
+        bindings = replace(
+            self.bindings,
+            health=HealthFacade(
+                self.plan,
+                stopped_state,
+                providers=self.bindings.providers,
+            ),
+        )
+        runtime = replace(
+            self,
+            adapter=replace(
+                self.adapter,
+                state=stopped_state,
+                bindings=bindings,
+            ),
+        )
+        return replace(runtime, http_app=_compile_http_app(runtime))
+
+    async def _dispatch(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        request_id = uuid4().hex
+        try:
+            request_id = _request_id(scope)
+        except PzError as exc:
+            await _send_json(send, 500, _http_error_from_exc(exc), request_id=request_id)
+            return
+        try:
+            scope_type = _read_scope_type(scope)
+        except PzError as exc:
+            await _send_json(send, 500, _http_error_from_exc(exc), request_id=request_id)
+            return
+        if scope_type != "http":
+            await _send_json(
+                send,
+                500,
+                _error_payload(
+                    code="PZ_HTTP_UNSUPPORTED_SCOPE",
+                    owner="runtime.http",
+                    action="dispatch",
+                    summary="HTTP runtime only supports ASGI http scope.",
+                    scope_type=scope_type,
+                ),
+                request_id=request_id,
+            )
+            return
+        try:
+            _read_scope_method(scope)
+        except PzError as exc:
+            await _send_json(send, 500, _http_error_from_exc(exc), request_id=request_id)
+            return
+
+        try:
+            path = _read_scope_path(scope)
+        except PzError as exc:
+            await _send_json(send, 500, _http_error_from_exc(exc), request_id=request_id)
+            return
+        await _send_json(
+            send,
+            404,
+            _error_payload(
+                code="PZ_HTTP_ROUTE_NOT_FOUND",
+                owner="runtime.http",
+                action="dispatch",
+                summary="Route was not found in the formal HTTP runtime.",
+                path=path,
+            ),
+            request_id=request_id,
+        )
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if self.http_app is None:
+            raise PzError(
+                code="PZ_HTTP_APP_MISSING",
+                message="Formal HTTP runtime requires a compiled ASGI application.",
+                stage="http",
+                owner="runtime.http",
+                action="__call__",
+                summary="HTTP runtime cannot serve requests without a compiled ASGI application.",
+            )
+        await self.http_app(scope, receive, send)
+
+
+def _compile_http_app(runtime: ApplicationRuntime) -> ASGIApp:
+    project_dir = str(runtime.plan.project.project_dir)
+
+    async def _base(scope: dict[str, Any], receive: Any, send: Any) -> None:
+        with (
+            bound_settings_snapshot(runtime.plan.settings, project_dir=project_dir),
+            active_settings_project(project_dir),
+            active_runtime_plan(runtime.plan),
+        ):
+            await runtime._dispatch(scope, receive, send)
+
+    with active_settings_project(project_dir), active_runtime_plan(runtime.plan):
+        return apply_runtime_middlewares(
+            _base,
+            plan=runtime.plan,
+            bindings=runtime.bindings,
+        )
+
+
+def create_application_runtime(
+    project_dir: str | Path | None = None,
+    *,
+    installed_apps: tuple[str, ...] | None = None,
+    compile_http_app: bool = True,
+) -> ApplicationRuntime:
+    plan = compile_runtime_plan(
+        project_dir=project_dir,
+        installed_apps=installed_apps,
+        include_cli_manifest=False,
+    )
+    write_runtime_plan_snapshot_if_requested(plan)
+    state = bind_runtime_plan(plan)
+    bindings = compile_runtime_bindings(plan, state)
+    runtime = ApplicationRuntime(
+        adapter=RuntimeAdapter(kind="http", plan=plan, state=state, bindings=bindings)
+    )
+    if not compile_http_app:
+        return runtime
+    return replace(runtime, http_app=_compile_http_app(runtime))
+
+
+def create_application_runtime_from_plan(
+    plan: RuntimePlan,
+    *,
+    compile_http_app: bool = True,
+) -> ApplicationRuntime:
+    if not isinstance(plan, RuntimePlan):
+        raise PzError(
+            code="PZ_APPLICATION_RUNTIME_PLAN_INVALID",
+            message="Application runtime requires a compiled RuntimePlan.",
+            stage="http",
+            owner="runtime.http",
+            action="create_application_runtime_from_plan",
+        )
+    state = bind_runtime_plan(plan)
+    bindings = compile_runtime_bindings(plan, state)
+    runtime = ApplicationRuntime(
+        adapter=RuntimeAdapter(kind="http", plan=plan, state=state, bindings=bindings)
+    )
+    if not compile_http_app:
+        return runtime
+    return replace(runtime, http_app=_compile_http_app(runtime))