pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/host.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pz_core.core.extensions import HostBuildContext, HostBuildResult, HostBuilderSpec
+from pz_core.runtime.errors import PzError
+from pz_core.runtime import create_application_runtime, create_application_runtime_from_plan
+from pz_core.runtime.plan import RuntimePlan, compile_runtime_plan
+from pz_core.runtime.plan_context import active_runtime_plan
+from pz_core.runtime.plan_snapshot import (
+    bind_runtime_plan_snapshot_env,
+    bind_runtime_plan_snapshot_invocation_env,
+    load_runtime_plan_snapshot,
+    runtime_plan_snapshot_path,
+    write_runtime_plan_snapshot,
+)
+from pz_core.runtime.settings import active_settings_project
+
+_PRECOMPILED_RUNTIME: Any | None = None
+_PRECOMPILED_RUNTIME_PROJECT_DIR: str | None = None
+
+
+def _store_precompiled_runtime(runtime: Any) -> None:
+    global _PRECOMPILED_RUNTIME, _PRECOMPILED_RUNTIME_PROJECT_DIR
+    _PRECOMPILED_RUNTIME = runtime
+    _PRECOMPILED_RUNTIME_PROJECT_DIR = str(Path(runtime.plan.project.project_dir).resolve())
+
+
+def _take_precompiled_runtime(project_dir: Path) -> Any | None:
+    global _PRECOMPILED_RUNTIME, _PRECOMPILED_RUNTIME_PROJECT_DIR
+    resolved_project_dir = str(Path(project_dir).resolve())
+    if _PRECOMPILED_RUNTIME is None or _PRECOMPILED_RUNTIME_PROJECT_DIR != resolved_project_dir:
+        return None
+    runtime = _PRECOMPILED_RUNTIME
+    _PRECOMPILED_RUNTIME = None
+    _PRECOMPILED_RUNTIME_PROJECT_DIR = None
+    return runtime
+
+
+def prepare_host_runtime(
+    *,
+    project_dir: str | Path,
+    reload_enabled: bool,
+    workers: int,
+    invocation_id: str = "",
+) -> RuntimePlan | None:
+    if reload_enabled:
+        bind_runtime_plan_snapshot_env(None)
+        bind_runtime_plan_snapshot_invocation_env(None)
+        return None
+    if workers > 1:
+        snapshot_path = None
+        if str(invocation_id or "").strip():
+            resolved_project_dir = Path(project_dir).resolve()
+            snapshot_path = runtime_plan_snapshot_path(project_dir=resolved_project_dir, invocation_id=invocation_id)
+            if not snapshot_path.is_file():
+                plan = compile_runtime_plan(project_dir=resolved_project_dir)
+                snapshot_path = write_runtime_plan_snapshot(plan, invocation_id=invocation_id)
+        bind_runtime_plan_snapshot_env(snapshot_path)
+        bind_runtime_plan_snapshot_invocation_env(invocation_id)
+        return None
+    bind_runtime_plan_snapshot_env(None)
+    bind_runtime_plan_snapshot_invocation_env(None)
+    runtime = create_application_runtime(
+        project_dir=str(Path(project_dir).resolve()),
+        compile_http_app=False,
+    )
+    _store_precompiled_runtime(runtime)
+    return runtime.plan
+
+
+def _iter_host_builders(
+    *,
+    project_dir: Path | None = None,
+    plan: RuntimePlan | None = None,
+) -> tuple[HostBuilderSpec, ...]:
+    runtime_plan = plan if plan is not None else compile_runtime_plan(project_dir=project_dir)
+    return tuple(getattr(runtime_plan, "host_builders", ()) or ())
+
+
+def resolve_host_builder(
+    *,
+    project_dir: Path,
+    plan: RuntimePlan | None = None,
+) -> HostBuilderSpec:
+    matches: list[HostBuilderSpec] = []
+    for spec in _iter_host_builders(project_dir=project_dir, plan=plan):
+        build = getattr(spec.builder, "build", None)
+        if not callable(build):
+            raise PzError(
+                code="PZ_HOST_BUILDER_INVALID",
+                message=f"Host builder '{spec.id}' from '{spec.owner_app}' must declare a builder object with build(ctx).",
+                stage="runtime",
+                owner=spec.owner_app,
+                action="create_host_app",
+            )
+        matches.append(spec)
+    if not matches:
+        raise PzError(
+            code="PZ_HOST_BUILDER_UNAVAILABLE",
+            message="No installed app declared a host.builder extension.",
+            stage="runtime",
+            owner="pz_core.runtime.host",
+            action="create_host_app",
+        )
+    matches.sort(key=lambda item: (-int(item.priority), str(item.owner_app), str(item.id)))
+    selected = matches[0]
+    if len(matches) > 1 and int(matches[1].priority) == int(selected.priority):
+        raise PzError(
+            code="PZ_HOST_BUILDER_AMBIGUOUS",
+            message=(
+                "Multiple installed apps declared host.builder extensions at the same priority. "
+                "Adjust extension priority so one builder wins."
+            ),
+            stage="runtime",
+            owner="pz_core.runtime.host",
+            action="create_host_app",
+        )
+    return selected
+
+
+def create_host_app(
+    project_dir: str | Path | None = None,
+    *,
+    runtime: Any | None = None,
+):
+    """Create the formal host ASGI app using the installed host.builder convention."""
+
+    runtime_project = getattr(getattr(getattr(runtime, "plan", None), "project", None), "project_dir", None)
+    resolved_project_dir = Path(runtime_project or project_dir or ".").resolve()
+    resolved_runtime = runtime or _take_precompiled_runtime(resolved_project_dir)
+    if resolved_runtime is None:
+        snapshot_plan = load_runtime_plan_snapshot()
+        if snapshot_plan is not None:
+            snapshot_project_dir = Path(snapshot_plan.project.project_dir).resolve()
+            if snapshot_project_dir != resolved_project_dir:
+                raise PzError(
+                    code="PZ_RUNTIME_PLAN_SNAPSHOT_PROJECT_MISMATCH",
+                    message=(
+                        "Runtime plan snapshot project_dir does not match requested host project_dir: "
+                        f"{snapshot_project_dir} != {resolved_project_dir}"
+                    ),
+                    stage="runtime",
+                    owner="pz_core.runtime.host",
+                    action="create_host_app",
+                )
+            resolved_runtime = create_application_runtime_from_plan(
+                snapshot_plan,
+                compile_http_app=False,
+            )
+        else:
+            resolved_runtime = create_application_runtime(
+                project_dir=str(resolved_project_dir),
+                compile_http_app=False,
+            )
+    with (
+        active_settings_project(resolved_project_dir),
+        active_runtime_plan(resolved_runtime.plan),
+    ):
+        host_builder_spec = resolve_host_builder(
+            project_dir=resolved_project_dir,
+            plan=resolved_runtime.plan,
+        )
+        build = getattr(host_builder_spec.builder, "build", None)
+        result = build(
+            HostBuildContext(
+                project=resolved_runtime.plan.project,
+                plan=resolved_runtime.plan,
+                settings=resolved_runtime.plan.settings,
+                bindings=resolved_runtime.bindings,
+                lifecycle_state=resolved_runtime.state,
+            )
+        )
+    if not isinstance(result, HostBuildResult):
+        raise PzError(
+            code="PZ_HOST_BUILDER_RESULT_INVALID",
+            message=(
+                f"Host builder '{host_builder_spec.id}' from '{host_builder_spec.owner_app}' must return HostBuildResult."
+            ),
+            stage="runtime",
+            owner=host_builder_spec.owner_app,
+            action="create_host_app",
+        )
+    return result.app
+
+
+__all__ = ["create_host_app", "prepare_host_runtime", "resolve_host_builder"]

pz_core/runtime/host_runner.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import socket
+import subprocess
+import sys
+
+from pz_core.assembly.settings.host_runtime_endpoint import HostRuntimeEndpoint, HostRuntimeEndpointResolver
+from pz_core.cli_options import add_cli_option
+from pz_core.project_runtime_cli import build_project_pz_child_env, resolve_project_pz_executable
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.cli._args import PzArgumentParser, normalize_cli_argv
+from pz_core.runtime.host import create_host_app, prepare_host_runtime
+from pz_core.runtime.invocation import RUNTIME_INVOCATION_ID_ENV, configure_runtime_invocation_id
+from pz_core.runtime.settings import current_pz_env
+from pz_core.utils import read_env_bool, read_env_int, read_env_string, resolve_host_project_shortcuts
+
+
+HOST_PROJECT_DIR_ENV = "PZ_HOST_PROJECT_DIR"
+_HOST_RUNTIME_STATE_RELATIVE_PATH = Path(".runtime/run/host.state.json")
+
+
+def _managed_worker_autostart_command(
+    project_dir: Path,
+    *,
+    owner_pid: int | None = None,
+) -> tuple[str, ...]:
+    command = [
+        resolve_project_pz_executable(project_dir),
+        "workers",
+        "run",
+        "--project-dir",
+        str(project_dir.resolve()),
+        "--detach",
+    ]
+    if owner_pid is not None and int(owner_pid) > 0:
+        command.extend(["--owner-pid", str(int(owner_pid))])
+    return tuple(command)
+
+
+def _managed_worker_host_env(
+    *,
+    host: str,
+    port: int,
+    reload_enabled: bool,
+    workers: int,
+) -> dict[str, str]:
+    resolution = HostRuntimeEndpointResolver(
+        current_app_host=host,
+        current_app_port=port,
+    ).resolve()
+    if resolution is None:
+        endpoint = HostRuntimeEndpoint(host=_normalize_connect_host(host), port=int(port))
+        resolution = HostRuntimeEndpointResolver(
+            current_base_url=endpoint.connect_base_url,
+            current_app_host=endpoint.host,
+            current_app_port=endpoint.port,
+        ).resolve()
+    if resolution is None:
+        return {
+            "APP_HOST": str(host),
+            "APP_PORT": str(int(port)),
+            "APP_RELOAD": "true" if bool(reload_enabled) else "false",
+            "APP_WORKERS": str(int(workers)),
+        }
+    return resolution.env(reload_enabled=reload_enabled, workers=workers)
+
+
+def _auto_start_managed_workers(
+    project_dir: Path,
+    *,
+    host: str,
+    port: int,
+    reload_enabled: bool,
+    workers: int,
+) -> None:
+    completed = subprocess.run(
+        _managed_worker_autostart_command(project_dir, owner_pid=os.getpid()),
+        cwd=str(project_dir.resolve()),
+        env=build_project_pz_child_env(
+            project_dir,
+            pz_env=current_pz_env(project_dir=project_dir),
+            env_overrides=_managed_worker_host_env(
+                host=host,
+                port=port,
+                reload_enabled=reload_enabled,
+                workers=workers,
+            ),
+        ),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    if completed.returncode == 0:
+        return
+    detail = (completed.stderr or "").strip() or f"exit code {completed.returncode}"
+    sys.stderr.write(f"[pz-host] managed worker auto-start failed: {detail}\n")
+
+
+def _normalize_connect_host(host: str) -> str:
+    normalized = str(host or "").strip()
+    if not normalized or normalized in {"0.0.0.0", "::"}:
+        return "127.0.0.1"
+    return normalized
+
+
+def _host_runtime_state_path(project_dir: Path) -> Path:
+    return project_dir.resolve() / _HOST_RUNTIME_STATE_RELATIVE_PATH
+
+
+def _write_host_runtime_state(
+    *,
+    project_dir: Path,
+    host: str,
+    port: int,
+    reload_enabled: bool,
+    workers: int,
+) -> Path:
+    state_path = _host_runtime_state_path(project_dir)
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    endpoint = HostRuntimeEndpoint.from_host_port(host=host, port=port)
+    base_url = endpoint.connect_base_url if endpoint is not None else f"http://{_normalize_connect_host(host)}:{int(port)}"
+    payload = {
+        "project_dir": str(project_dir.resolve()),
+        "pid": os.getpid(),
+        "host": str(host),
+        "connect_host": _normalize_connect_host(host),
+        "port": int(port),
+        "base_url": base_url,
+        "reload": bool(reload_enabled),
+        "workers": int(workers),
+        "pz_env": current_pz_env(project_dir=project_dir),
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+    }
+    temp_path = state_path.with_suffix(".tmp")
+    temp_path.write_text(json.dumps(payload, ensure_ascii=True, sort_keys=True) + "\n", encoding="utf-8")
+    temp_path.replace(state_path)
+    return state_path
+
+
+def _clear_host_runtime_state(project_dir: Path) -> None:
+    state_path = _host_runtime_state_path(project_dir)
+    try:
+        state_path.unlink()
+    except FileNotFoundError:
+        return
+
+
+def _assert_host_bind_available(*, host: str, port: int) -> None:
+    bind_host = str(host or "127.0.0.1")
+    bind_port = int(port)
+    family = socket.AF_INET6 if ":" in bind_host else socket.AF_INET
+    try:
+        with socket.socket(family, socket.SOCK_STREAM) as probe:
+            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            probe.bind((bind_host, bind_port))
+    except OSError as exc:
+        raise PzError(
+            code="PZ_HOST_BIND_UNAVAILABLE",
+            message=f"Host address is unavailable before worker startup: {bind_host}:{bind_port} ({exc}).",
+            stage="runtime",
+            owner="pz_core.runtime.host_runner",
+            action="run_host_main",
+        ) from exc
+
+
+def _build_host_parser(*, project_dir: str | Path | None = None) -> PzArgumentParser:
+    shortcuts = resolve_host_project_shortcuts(project_dir=project_dir)
+    parser = PzArgumentParser(
+        prog="pz-host",
+        description="Run the pz host application.",
+        error_code="PZ_HOST_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner="pz_core.runtime.host_runner",
+        error_action="run_host_main",
+    )
+    add_cli_option(parser, "--host", default=read_env_string(shortcuts.app_host, "APP_HOST"))
+    add_cli_option(parser, "--port", type=int, default=read_env_int(shortcuts.app_port, "APP_PORT"))
+    add_cli_option(
+        parser,
+        "--reload",
+        action="store_true",
+        default=read_env_bool(shortcuts.app_reload, "APP_RELOAD"),
+    )
+    add_cli_option(
+        parser,
+        "--workers",
+        type=int,
+        default=max(1, read_env_int(shortcuts.app_workers, "APP_WORKERS")),
+    )
+    return parser
+
+
+def load_host_app_from_env():
+    project_dir = os.getenv(HOST_PROJECT_DIR_ENV)
+    if not isinstance(project_dir, str) or not project_dir.strip():
+        raise PzError(
+            code="PZ_HOST_PROJECT_DIR_MISSING",
+            message=f"{HOST_PROJECT_DIR_ENV} is required to resolve the host project directory.",
+            stage="runtime",
+            owner="pz_core.runtime.host_runner",
+            action="load_host_app_from_env",
+        )
+    return create_host_app(project_dir=project_dir.strip())
+
+
+def run_host_main(
+    project_dir: str | Path | None = None,
+    argv: Sequence[str] | None = None,
+) -> int:
+    resolved_project_dir = Path(project_dir or ".").resolve()
+    effective_argv = list(sys.argv[1:] if argv is None else argv)
+    normalized = normalize_cli_argv(
+        effective_argv,
+        code="PZ_HOST_ARGV_INVALID",
+        stage="cli",
+        owner="pz_core.runtime.host_runner",
+        action="run_host_main",
+    )
+    args = _build_host_parser(project_dir=resolved_project_dir).parse_args(normalized)
+    workers = 1 if args.reload else max(1, int(args.workers))
+    use_import_string = bool(args.reload) or workers > 1
+    os.environ[HOST_PROJECT_DIR_ENV] = str(resolved_project_dir)
+    invocation_id = configure_runtime_invocation_id(enabled=not args.reload and workers > 1)
+    prepare_host_runtime(
+        project_dir=resolved_project_dir,
+        reload_enabled=bool(args.reload),
+        workers=workers,
+        invocation_id=invocation_id,
+    )
+    _assert_host_bind_available(host=str(args.host), port=int(args.port))
+    _auto_start_managed_workers(
+        resolved_project_dir,
+        host=str(args.host),
+        port=int(args.port),
+        reload_enabled=bool(args.reload),
+        workers=workers,
+    )
+    _write_host_runtime_state(
+        project_dir=resolved_project_dir,
+        host=str(args.host),
+        port=int(args.port),
+        reload_enabled=bool(args.reload),
+        workers=workers,
+    )
+    try:
+        import uvicorn
+    except Exception as exc:
+        _clear_host_runtime_state(resolved_project_dir)
+        raise PzError(
+            code="PZ_HOST_RUNNER_DEPENDENCY_MISSING",
+            message="Host startup requires uvicorn to be installed in the active runtime.",
+            stage="runtime",
+            owner="pz_core.runtime.host_runner",
+            action="run_host_main",
+        ) from exc
+    try:
+        uvicorn.run(
+            "pz_core.runtime.host_runner:load_host_app_from_env" if use_import_string else load_host_app_from_env,
+            host=str(args.host),
+            port=int(args.port),
+            reload=bool(args.reload),
+            workers=workers,
+            factory=True,
+        )
+    finally:
+        _clear_host_runtime_state(resolved_project_dir)
+    return 0
+
+
+__all__ = [
+    "HOST_PROJECT_DIR_ENV",
+    "RUNTIME_INVOCATION_ID_ENV",
+    "_managed_worker_autostart_command",
+    "load_host_app_from_env",
+    "run_host_main",
+]

pz_core/runtime/http/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .app import (
+    ApplicationRuntime,
+    apply_runtime_middlewares,
+    create_application_runtime,
+    create_application_runtime_from_plan,
+)
+from ..http_timing import current_http_timing_meta, http_timing_enabled, instrument_asgi_timing, log_http_timing
+
+__all__ = [
+    "ApplicationRuntime",
+    "apply_runtime_middlewares",
+    "create_application_runtime",
+    "create_application_runtime_from_plan",
+    "current_http_timing_meta",
+    "http_timing_enabled",
+    "instrument_asgi_timing",
+    "log_http_timing",
+]