@mriekki/lean 0.4.4 → 0.4.5

package/assets/generated/deployment/src/lean_poc_deployment/local_runtime.py

@@ -0,0 +1,523 @@
+"""Loopback-only immutable application deployment on the developer workstation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Iterable
+
+from .app_runtime import PRODUCTION_APP_DEPLOY_WRITE_PHRASE, normalize_app_spec
+from .errors import DeploymentKitError
+from .profiles import config_root
+
+LOCAL_RUNTIME_SCHEMA_VERSION = 1
+LOCAL_APP_DEPLOY_WRITE_PHRASE = "[LOCAL APP DEPLOY]"
+LOOPBACK_ADDRESS = "127.0.0.1"
+
+_LABEL_PREFIX = "com.mriekki.lean-poc"
+_LABEL_OWNER = f"{_LABEL_PREFIX}.owner-repo"
+_LABEL_APP = f"{_LABEL_PREFIX}.app-slug"
+_LABEL_ENV = f"{_LABEL_PREFIX}.environment"
+_LABEL_SPEC = f"{_LABEL_PREFIX}.spec-sha256"
+_LABEL_PLACEMENT = f"{_LABEL_PREFIX}.placement"
+
+
+def _docker() -> str:
+    executable = shutil.which("docker")
+    if not executable:
+        raise DeploymentKitError(
+            "Docker is unavailable. Workstation-container deployment requires a working Docker CLI/engine."
+        )
+    completed = subprocess.run(
+        [executable, "info", "--format", "{{.ServerVersion}}"],
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout).strip()
+        raise DeploymentKitError("Docker engine is not ready" + (f": {detail}" if detail else "."))
+    return executable
+
+
+def _run(docker: str, args: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(
+        [docker, *args],
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+    )
+    if check and completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout).strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Local Docker command failed: {detail}")
+    return completed
+
+
+def _host_port(value: int) -> int:
+    if type(value) is not int or not 1 <= value <= 65535:
+        raise DeploymentKitError("hostPort must be an integer from 1 through 65535.")
+    return value
+
+
+def _state_root(app_slug: str, environment: str) -> Path:
+    return config_root() / "local-apps" / app_slug / environment
+
+
+def _state_file(app_slug: str, environment: str) -> Path:
+    return _state_root(app_slug, environment) / "deployment.json"
+
+
+def _evidence_file(app_slug: str, environment: str) -> Path:
+    return _state_root(app_slug, environment) / "deployment-evidence.jsonl"
+
+
+def _data_dir(app_slug: str, environment: str) -> Path:
+    return _state_root(app_slug, environment) / "data"
+
+
+def _safe_state_write(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def _append_evidence(app_slug: str, environment: str, value: dict[str, Any]) -> None:
+    path = _evidence_file(app_slug, environment)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as target:
+        target.write(json.dumps(value, sort_keys=True, separators=(",", ":")) + "\n")
+
+
+def _load_state(app_slug: str, environment: str) -> dict[str, Any] | None:
+    path = _state_file(app_slug, environment)
+    if not path.is_file():
+        return None
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Cannot read local deployment state {path}: {error}") from error
+    if not isinstance(value, dict) or value.get("schemaVersion") != LOCAL_RUNTIME_SCHEMA_VERSION:
+        raise DeploymentKitError(f"Unsupported local deployment state: {path}")
+    return value
+
+
+def normalize_local_spec(
+    *,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    container_name: str,
+    image: str,
+    runtime_port: int,
+    host_port: int,
+    health_path: str,
+    run_as: str,
+    persistence_mode: str,
+    data_container_path: str | None,
+    environment_variables: dict[str, str] | Iterable[tuple[str, str]],
+) -> dict[str, Any]:
+    base = normalize_app_spec(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        container_name=container_name,
+        image=image,
+        runtime_port=runtime_port,
+        health_path=health_path,
+        run_as=run_as,
+        persistence_mode=persistence_mode,
+        data_container_path=data_container_path,
+        environment_variables=environment_variables,
+    )
+    base.pop("specSha256", None)
+    base.update(
+        {
+            "schemaVersion": LOCAL_RUNTIME_SCHEMA_VERSION,
+            "placement": "workstation",
+            "isolation": "container",
+            "exposure": "loopback",
+            "hostAddress": LOOPBACK_ADDRESS,
+            "hostPort": _host_port(host_port),
+        }
+    )
+    base["specSha256"] = hashlib.sha256(
+        json.dumps(base, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+    return base
+
+
+def _inspect_owned_container(docker: str, container_name: str) -> dict[str, Any] | None:
+    inspected = _run(
+        docker,
+        [
+            "inspect",
+            "--format",
+            "{{json .Config.Labels}}\t{{json .NetworkSettings.Ports}}\t{{.State.Running}}",
+            container_name,
+        ],
+        check=False,
+    )
+    if inspected.returncode != 0:
+        detail = (inspected.stderr or "").lower()
+        if "no such" in detail or "not found" in detail:
+            return None
+        raise DeploymentKitError(
+            f"Unable to inspect local container {container_name}: {(inspected.stderr or inspected.stdout).strip()}"
+        )
+    parts = inspected.stdout.strip().split("\t")
+    if len(parts) != 3:
+        raise DeploymentKitError("Local Docker inspect returned malformed container evidence.")
+    try:
+        labels = json.loads(parts[0]) if parts[0] else {}
+        ports = json.loads(parts[1]) if parts[1] else {}
+    except json.JSONDecodeError as error:
+        raise DeploymentKitError("Local Docker inspect returned malformed JSON evidence.") from error
+    if not isinstance(labels, dict):
+        labels = {}
+    return {
+        "labels": labels,
+        "ports": ports if isinstance(ports, dict) else {},
+        "running": parts[2].strip().lower() == "true",
+    }
+
+
+def _assert_owned_or_absent(
+    docker: str,
+    *,
+    container_name: str,
+    owner_repo: str,
+    app_slug: str,
+    environment: str,
+) -> dict[str, Any] | None:
+    existing = _inspect_owned_container(docker, container_name)
+    if existing is None:
+        return None
+    labels = existing["labels"]
+    identity = (labels.get(_LABEL_OWNER), labels.get(_LABEL_APP), labels.get(_LABEL_ENV))
+    expected = (owner_repo, app_slug, environment)
+    if identity != expected:
+        raise DeploymentKitError(
+            f"Container name '{container_name}' already exists but is not owned by "
+            f"{owner_repo} / {app_slug} / {environment}; refusing replacement."
+        )
+    return existing
+
+
+def _managed_containers(docker: str) -> list[dict[str, Any]]:
+    listed = _run(
+        docker,
+        ["ps", "-a", "--filter", f"label={_LABEL_PLACEMENT}=workstation", "--format", "{{.Names}}"],
+    )
+    result: list[dict[str, Any]] = []
+    for name in sorted(line.strip() for line in listed.stdout.splitlines() if line.strip()):
+        info = _inspect_owned_container(docker, name)
+        if info is None:
+            continue
+        labels = info["labels"]
+        if not all(labels.get(key) for key in (_LABEL_OWNER, _LABEL_APP, _LABEL_ENV, _LABEL_SPEC)):
+            continue
+        result.append(
+            {
+                "containerName": name,
+                "ownerRepo": labels[_LABEL_OWNER],
+                "appSlug": labels[_LABEL_APP],
+                "environment": labels[_LABEL_ENV],
+                "specSha256": labels[_LABEL_SPEC],
+                "running": info["running"],
+            }
+        )
+    return result
+
+
+def _http_healthy(spec: dict[str, Any], *, timeout: float = 2.0) -> bool:
+    url = f"http://{LOOPBACK_ADDRESS}:{spec['hostPort']}{spec['healthPath']}"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            return 200 <= response.status < 400
+    except (OSError, urllib.error.URLError):
+        return False
+
+
+def local_inventory() -> dict[str, Any]:
+    docker = _docker()
+    applications: list[dict[str, Any]] = []
+    for container in _managed_containers(docker):
+        state = _load_state(container["appSlug"], container["environment"])
+        item = dict(container)
+        item.update(
+            {
+                "placement": "workstation",
+                "isolation": "container",
+                "exposure": "loopback",
+                "hostAddress": LOOPBACK_ADDRESS,
+                "hostPort": state.get("hostPort") if state else None,
+                "image": state.get("image") if state else None,
+                "runtimePort": state.get("runtimePort") if state else None,
+                "healthPath": state.get("healthPath") if state else None,
+                "httpHealthy": bool(state and container["running"] and _http_healthy(state)),
+            }
+        )
+        applications.append(item)
+    return {
+        "schemaVersion": LOCAL_RUNTIME_SCHEMA_VERSION,
+        "placement": "workstation",
+        "isolation": "container",
+        "exposure": "loopback",
+        "applications": applications,
+        "mutated": False,
+    }
+
+
+def _inventory_snapshot(inventory: dict[str, Any]) -> str:
+    value = {
+        "applications": [
+            {
+                key: item.get(key)
+                for key in (
+                    "containerName",
+                    "ownerRepo",
+                    "appSlug",
+                    "environment",
+                    "specSha256",
+                    "running",
+                    "hostPort",
+                )
+            }
+            for item in inventory["applications"]
+        ]
+    }
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _assert_port_available(
+    inventory: dict[str, Any], *, host_port: int, app_slug: str, environment: str
+) -> None:
+    for item in inventory["applications"]:
+        if item.get("hostPort") == host_port and (item["appSlug"], item["environment"]) != (
+            app_slug,
+            environment,
+        ):
+            raise DeploymentKitError(
+                f"Loopback host port {host_port} is already owned by "
+                f"{item['appSlug']} / {item['environment']}."
+            )
+
+
+def plan_local_deploy(spec: dict[str, Any]) -> dict[str, Any]:
+    docker = _docker()
+    _assert_owned_or_absent(
+        docker,
+        container_name=spec["containerName"],
+        owner_repo=spec["ownerRepo"],
+        app_slug=spec["appSlug"],
+        environment=spec["environment"],
+    )
+    inventory = local_inventory()
+    _assert_port_available(
+        inventory,
+        host_port=spec["hostPort"],
+        app_slug=spec["appSlug"],
+        environment=spec["environment"],
+    )
+    existing = next(
+        (
+            item
+            for item in inventory["applications"]
+            if item["appSlug"] == spec["appSlug"] and item["environment"] == spec["environment"]
+        ),
+        None,
+    )
+    if existing and existing["specSha256"] == spec["specSha256"] and existing["running"] and existing["httpHealthy"]:
+        raise DeploymentKitError("The exact local application runtime is already deployed and healthy.")
+    return {
+        "action": "deploy",
+        "placement": "workstation",
+        "isolation": "container",
+        "exposure": "loopback",
+        "publicExposure": False,
+        "hostAddress": LOOPBACK_ADDRESS,
+        "hostPort": spec["hostPort"],
+        "environment": spec["environment"],
+        "appSlug": spec["appSlug"],
+        "ownerRepo": spec["ownerRepo"],
+        "containerName": spec["containerName"],
+        "image": spec["image"],
+        "runtimePort": spec["runtimePort"],
+        "healthPath": spec["healthPath"],
+        "persistenceMode": spec["persistence"]["mode"],
+        "changeType": "update" if existing else "create",
+        "previousImage": existing.get("image") if existing else None,
+        "inventorySnapshot": _inventory_snapshot(inventory),
+        "spec": spec,
+    }
+
+
+def local_deploy_write_phrase(plan: dict[str, Any]) -> str:
+    return PRODUCTION_APP_DEPLOY_WRITE_PHRASE if plan["environment"] == "production" else LOCAL_APP_DEPLOY_WRITE_PHRASE
+
+
+def _container_args(spec: dict[str, Any]) -> list[str]:
+    args = [
+        "run",
+        "-d",
+        "--name",
+        spec["containerName"],
+        "--restart",
+        "unless-stopped",
+        "--user",
+        spec["runAs"],
+        "-p",
+        f"{LOOPBACK_ADDRESS}:{spec['hostPort']}:{spec['runtimePort']}",
+        "--label",
+        f"{_LABEL_OWNER}={spec['ownerRepo']}",
+        "--label",
+        f"{_LABEL_APP}={spec['appSlug']}",
+        "--label",
+        f"{_LABEL_ENV}={spec['environment']}",
+        "--label",
+        f"{_LABEL_SPEC}={spec['specSha256']}",
+        "--label",
+        f"{_LABEL_PLACEMENT}=workstation",
+    ]
+    if spec["persistence"]["mode"] == "directory":
+        data_dir = _data_dir(spec["appSlug"], spec["environment"]).resolve()
+        data_dir.mkdir(parents=True, exist_ok=True)
+        args.extend(["-v", f"{data_dir}:{spec['persistence']['dataContainerPath']}"])
+    for key, value in spec["environmentVariables"].items():
+        args.extend(["-e", f"{key}={value}"])
+    args.append(spec["image"])
+    return args
+
+
+def _wait_for_health(spec: dict[str, Any], *, timeout_seconds: float = 120.0) -> None:
+    deadline = time.monotonic() + timeout_seconds
+    while time.monotonic() < deadline:
+        if _http_healthy(spec):
+            return
+        time.sleep(1.0)
+    raise DeploymentKitError(
+        f"Local application failed loopback health check at "
+        f"http://{LOOPBACK_ADDRESS}:{spec['hostPort']}{spec['healthPath']}."
+    )
+
+
+def _persist_state(spec: dict[str, Any]) -> None:
+    value = {
+        "schemaVersion": LOCAL_RUNTIME_SCHEMA_VERSION,
+        "ownerRepo": spec["ownerRepo"],
+        "appSlug": spec["appSlug"],
+        "environment": spec["environment"],
+        "containerName": spec["containerName"],
+        "image": spec["image"],
+        "specSha256": spec["specSha256"],
+        "runtimePort": spec["runtimePort"],
+        "hostPort": spec["hostPort"],
+        "hostAddress": LOOPBACK_ADDRESS,
+        "healthPath": spec["healthPath"],
+        "runAs": spec["runAs"],
+        "persistence": spec["persistence"],
+        "placement": "workstation",
+        "isolation": "container",
+        "exposure": "loopback",
+        "environmentVariableNames": sorted(spec["environmentVariables"]),
+    }
+    _safe_state_write(_state_file(spec["appSlug"], spec["environment"]), value)
+
+
+def apply_local_deploy(plan: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "action",
+        "placement",
+        "isolation",
+        "exposure",
+        "publicExposure",
+        "hostAddress",
+        "hostPort",
+        "environment",
+        "appSlug",
+        "ownerRepo",
+        "containerName",
+        "image",
+        "runtimePort",
+        "healthPath",
+        "persistenceMode",
+        "changeType",
+        "previousImage",
+        "inventorySnapshot",
+        "spec",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+        raise DeploymentKitError("Malformed local application deployment plan.")
+    current = local_inventory()
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Local application inventory changed after plan review; create and authorize a fresh plan."
+        )
+    spec = plan["spec"]
+    docker = _docker()
+    existing = _assert_owned_or_absent(
+        docker,
+        container_name=spec["containerName"],
+        owner_repo=spec["ownerRepo"],
+        app_slug=spec["appSlug"],
+        environment=spec["environment"],
+    )
+    evidence_base = {
+        "schemaVersion": LOCAL_RUNTIME_SCHEMA_VERSION,
+        "ownerRepo": spec["ownerRepo"],
+        "appSlug": spec["appSlug"],
+        "environment": spec["environment"],
+        "containerName": spec["containerName"],
+        "image": spec["image"],
+        "specSha256": spec["specSha256"],
+        "placement": "workstation",
+        "exposure": "loopback",
+    }
+    try:
+        if existing is not None:
+            _run(docker, ["rm", "-f", spec["containerName"]])
+        _run(docker, ["pull", spec["image"]])
+        _run(docker, _container_args(spec))
+        _wait_for_health(spec)
+    except DeploymentKitError:
+        _append_evidence(spec["appSlug"], spec["environment"], {**evidence_base, "outcome": "failed"})
+        raise
+    _persist_state(spec)
+    _append_evidence(spec["appSlug"], spec["environment"], {**evidence_base, "outcome": "ready"})
+    final = local_inventory()
+    deployed = next(
+        (
+            item
+            for item in final["applications"]
+            if item["appSlug"] == spec["appSlug"] and item["environment"] == spec["environment"]
+        ),
+        None,
+    )
+    if not deployed or deployed["specSha256"] != spec["specSha256"] or not deployed["httpHealthy"]:
+        raise DeploymentKitError("Local deployment completed but readiness evidence is not healthy.")
+    final["mutated"] = True
+    return final
+
+
+__all__ = [
+    "LOCAL_APP_DEPLOY_WRITE_PHRASE",
+    "LOOPBACK_ADDRESS",
+    "apply_local_deploy",
+    "local_deploy_write_phrase",
+    "local_inventory",
+    "normalize_local_spec",
+    "plan_local_deploy",
+]