@mriekki/lean 0.0.0-stage → 0.1.1

package/assets/generated/deployment/distribution/lean-poc-deploy.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from lean_poc_deployment.entrypoint import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,3 @@
+"""Lean POC Deployment Kit."""
+
+__version__ = "0.1.0.dev0"

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

@@ -0,0 +1,3 @@
+from .entrypoint import main
+
+raise SystemExit(main())

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

@@ -0,0 +1,140 @@
+"""CLI for generic immutable application runtime deployment."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .app_runtime import (
+    APP_DEPLOY_WRITE_PHRASE,
+    PRODUCTION_APP_DEPLOY_WRITE_PHRASE,
+    app_inventory,
+    apply_app_deploy,
+    deploy_write_phrase,
+    normalize_app_spec,
+    plan_app_deploy,
+)
+from .errors import DeploymentKitError
+from .sqlite_adapter import assert_app_spec_matches_persistence
+
+
+def _print(value: Any, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(value, indent=2, sort_keys=True))
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                print(f"{key}: {json.dumps(item, sort_keys=True)}")
+            else:
+                print(f"{key}: {item}")
+        return
+    print(value)
+
+
+def _parse_env(items: list[str]) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    for item in items:
+        if "=" not in item:
+            raise DeploymentKitError("--env entries must use NAME=value form.")
+        key, value = item.split("=", 1)
+        result.append((key, value))
+    return result
+
+
+def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
+    if args.yes:
+        return
+    entered = input(f"Type {phrase} to {action}: ").strip()
+    if entered != phrase:
+        raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="lean-poc-deploy app")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inventory = sub.add_parser(
+        "inventory",
+        help="Read Kit-managed application runtime ownership/readiness without writes",
+    )
+    inventory.add_argument("name")
+    inventory.add_argument("--json", action="store_true")
+
+    deploy = sub.add_parser(
+        "deploy",
+        help="Deploy one immutable application runtime without modifying routes",
+    )
+    deploy.add_argument("name")
+    deploy.add_argument("--owner-repo", required=True)
+    deploy.add_argument("--environment", required=True)
+    deploy.add_argument("--app-slug", required=True)
+    deploy.add_argument("--container-name", required=True)
+    deploy.add_argument("--image", required=True)
+    deploy.add_argument("--runtime-port", type=int, required=True)
+    deploy.add_argument("--health-path", required=True)
+    deploy.add_argument("--run-as", required=True)
+    deploy.add_argument(
+        "--persistence-mode",
+        choices=("none", "directory"),
+        required=True,
+    )
+    deploy.add_argument("--data-container-path")
+    deploy.add_argument(
+        "--env",
+        action="append",
+        default=[],
+        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
+    )
+    deploy.add_argument("--json", action="store_true")
+    deploy.add_argument("--yes", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "inventory":
+            _print(app_inventory(args.name), as_json=args.json)
+            return 0
+
+        spec = normalize_app_spec(
+            owner_repo=args.owner_repo,
+            environment=args.environment,
+            app_slug=args.app_slug,
+            container_name=args.container_name,
+            image=args.image,
+            runtime_port=args.runtime_port,
+            health_path=args.health_path,
+            run_as=args.run_as,
+            persistence_mode=args.persistence_mode,
+            data_container_path=args.data_container_path,
+            environment_variables=_parse_env(args.env),
+        )
+        assert_app_spec_matches_persistence(args.name, spec)
+        plan = plan_app_deploy(args.name, spec)
+        _print(
+            {key: value for key, value in plan.items() if key != "spec"},
+            as_json=False,
+        )
+        phrase = deploy_write_phrase(plan)
+        _confirm(
+            args,
+            phrase,
+            f"deploy {plan['appSlug']} ({plan['environment']}) on target {args.name}",
+        )
+        _print(apply_app_deploy(plan), as_json=args.json)
+        return 0
+    except DeploymentKitError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 2
+
+
+__all__ = [
+    "APP_DEPLOY_WRITE_PHRASE",
+    "PRODUCTION_APP_DEPLOY_WRITE_PHRASE",
+    "build_parser",
+    "main",
+]

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

@@ -0,0 +1,455 @@
+"""Generic immutable application-runtime deployment for Kit-managed hosts."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+import subprocess
+from typing import Any, Iterable
+
+from .box_platform import platform_status
+from .box_platform_assets import CADDY_CONTAINER, NETWORK_NAME
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .ssh import ssh_args, verify_access
+from .app_runtime_remote import REMOTE_SCRIPT
+
+APP_ROOT = "/srv/lean-poc-apps"
+APP_SCHEMA_VERSION = 1
+APP_DEPLOY_WRITE_PHRASE = "[APP DEPLOY WRITE]"
+PRODUCTION_APP_DEPLOY_WRITE_PHRASE = "[PRODUCTION APP DEPLOY]"
+
+_SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_CONTAINER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+_IMAGE_RE = re.compile(
+    r"^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$"
+)
+_RUN_AS_RE = re.compile(r"^[0-9]+(?::[0-9]+)?$")
+_ENV_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_HEALTH_PATH_RE = re.compile(r"^/[A-Za-z0-9._~!$&'()*+,;=:@%/\-]*$")
+_CONTAINER_PATH_RE = re.compile(r"^/[A-Za-z0-9._~+:/\-]*$")
+
+
+def _slug(value: str, field: str) -> str:
+    if not isinstance(value, str) or _SLUG_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, and internal hyphens.")
+    return value
+
+
+def _owner_repo(value: str) -> str:
+    if not isinstance(value, str) or _REPO_RE.fullmatch(value) is None:
+        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
+    return value
+
+
+def _container_name(value: str) -> str:
+    if not isinstance(value, str) or _CONTAINER_RE.fullmatch(value) is None:
+        raise DeploymentKitError("containerName contains unsupported characters.")
+    return value
+
+
+def _image(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_RE.fullmatch(value) is None:
+        raise DeploymentKitError("image must be an immutable image reference ending in @sha256:<64 lowercase hex>.")
+    return value
+
+
+def _runtime_port(value: int) -> int:
+    if type(value) is not int or not 1 <= value <= 65535:
+        raise DeploymentKitError("runtimePort must be an integer from 1 through 65535.")
+    return value
+
+
+def _health_path(value: str) -> str:
+    if not isinstance(value, str) or _HEALTH_PATH_RE.fullmatch(value) is None:
+        raise DeploymentKitError("healthPath must be a safe absolute HTTP path.")
+    return value
+
+
+def _run_as(value: str) -> str:
+    if not isinstance(value, str) or _RUN_AS_RE.fullmatch(value) is None:
+        raise DeploymentKitError("runAs must be a numeric UID or UID:GID.")
+    return value
+
+
+def _container_path(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or _CONTAINER_PATH_RE.fullmatch(value) is None or "/../" in f"{value}/":
+        raise DeploymentKitError("dataContainerPath must be a safe absolute container path.")
+    return value.rstrip("/") or "/"
+
+
+def _normalize_environment_variables(items: dict[str, str] | Iterable[tuple[str, str]]) -> dict[str, str]:
+    pairs = items.items() if isinstance(items, dict) else items
+    result: dict[str, str] = {}
+    for key, value in pairs:
+        if not isinstance(key, str) or _ENV_KEY_RE.fullmatch(key) is None:
+            raise DeploymentKitError(f"Invalid environment variable name: {key!r}")
+        if key in result:
+            raise DeploymentKitError(f"Duplicate environment variable: {key}")
+        if not isinstance(value, str) or "\x00" in value or "\n" in value or "\r" in value:
+            raise DeploymentKitError(f"Environment variable {key} contains unsupported control characters.")
+        result[key] = value
+    return dict(sorted(result.items()))
+
+
+def normalize_app_spec(
+    *,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    container_name: str,
+    image: str,
+    runtime_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]:
+    if persistence_mode not in {"none", "directory"}:
+        raise DeploymentKitError("persistenceMode must be 'none' or 'directory'.")
+    data_path = _container_path(data_container_path)
+    if persistence_mode == "directory" and data_path is None:
+        raise DeploymentKitError("directory persistence requires dataContainerPath.")
+    if persistence_mode == "none" and data_path is not None:
+        raise DeploymentKitError("dataContainerPath must be omitted when persistenceMode is 'none'.")
+    spec = {
+        "schemaVersion": APP_SCHEMA_VERSION,
+        "ownerRepo": _owner_repo(owner_repo),
+        "environment": _slug(environment, "environment"),
+        "appSlug": _slug(app_slug, "appSlug"),
+        "containerName": _container_name(container_name),
+        "image": _image(image),
+        "runtimePort": _runtime_port(runtime_port),
+        "healthPath": _health_path(health_path),
+        "runAs": _run_as(run_as),
+        "persistence": {
+            "mode": persistence_mode,
+            "dataContainerPath": data_path,
+        },
+        "environmentVariables": _normalize_environment_variables(environment_variables),
+    }
+    spec["specSha256"] = _spec_sha(spec)
+    return spec
+
+
+def _spec_sha(spec: dict[str, Any]) -> str:
+    value = {key: spec[key] for key in spec if key != "specSha256"}
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _b64(value: str) -> str:
+    return base64.b64encode(value.encode("utf-8")).decode("ascii")
+
+
+def build_remote_script(spec: dict[str, Any] | None = None) -> str:
+    env_keys: list[str] = []
+    env_values: list[str] = []
+    desired = {
+        "ownerRepo": "",
+        "environment": "",
+        "appSlug": "",
+        "containerName": "",
+        "image": "",
+        "runtimePort": "",
+        "healthPath": "",
+        "runAs": "",
+        "persistenceMode": "",
+        "dataContainerPath": "",
+        "specSha256": "",
+    }
+    if spec is not None:
+        desired.update(
+            ownerRepo=spec["ownerRepo"],
+            environment=spec["environment"],
+            appSlug=spec["appSlug"],
+            containerName=spec["containerName"],
+            image=spec["image"],
+            runtimePort=str(spec["runtimePort"]),
+            healthPath=spec["healthPath"],
+            runAs=spec["runAs"],
+            persistenceMode=spec["persistence"]["mode"],
+            dataContainerPath=spec["persistence"]["dataContainerPath"] or "",
+            specSha256=spec["specSha256"],
+        )
+        for key, value in spec["environmentVariables"].items():
+            env_keys.append(_b64(key))
+            env_values.append(_b64(value))
+
+    replacements = {
+        "__APP_ROOT__": APP_ROOT,
+        "__APP_SCHEMA_VERSION__": str(APP_SCHEMA_VERSION),
+        "__NETWORK_NAME__": NETWORK_NAME,
+        "__CADDY_CONTAINER__": CADDY_CONTAINER,
+        "__DESIRED_PRESENT__": "true" if spec is not None else "false",
+        "__D_OWNER_B64__": _b64(desired["ownerRepo"]),
+        "__D_ENV_B64__": _b64(desired["environment"]),
+        "__D_APP_B64__": _b64(desired["appSlug"]),
+        "__D_CONTAINER_B64__": _b64(desired["containerName"]),
+        "__D_IMAGE_B64__": _b64(desired["image"]),
+        "__D_PORT__": desired["runtimePort"],
+        "__D_HEALTH_B64__": _b64(desired["healthPath"]),
+        "__D_RUN_AS_B64__": _b64(desired["runAs"]),
+        "__D_PERSISTENCE__": desired["persistenceMode"],
+        "__D_DATA_TARGET_B64__": _b64(desired["dataContainerPath"]),
+        "__D_SPEC_SHA__": desired["specSha256"],
+        "__D_ENV_KEYS__": " ".join(f"'{item}'" for item in env_keys),
+        "__D_ENV_VALUES__": " ".join(f"'{item}'" for item in env_values),
+    }
+    script = REMOTE_SCRIPT
+    for placeholder, value in replacements.items():
+        script = script.replace(placeholder, value)
+    if "__" in script:
+        raise DeploymentKitError("Internal application-runtime script contains an unresolved placeholder.")
+    return script
+
+
+def _parse_inventory(output: str) -> dict[str, Any]:
+    apps: list[dict[str, Any]] = []
+    summary: dict[str, str] = {}
+    for raw in output.splitlines():
+        if not raw:
+            continue
+        parts = raw.split("\t")
+        if parts[0] == "SUMMARY":
+            if len(parts) != 3 or parts[1] in summary:
+                raise DeploymentKitError("Malformed or duplicate application inventory summary.")
+            summary[parts[1]] = parts[2]
+            continue
+        if parts[0] != "APP" or len(parts) != 15:
+            raise DeploymentKitError("Malformed application inventory record.")
+        try:
+            port = int(parts[7])
+        except ValueError as error:
+            raise DeploymentKitError("Malformed application inventory runtime port.") from error
+        if parts[12] not in {"true", "false"} or parts[13] not in {"true", "false"}:
+            raise DeploymentKitError("Malformed application inventory boolean value.")
+        owner = _owner_repo(parts[1])
+        environment = _slug(parts[2], "environment")
+        app_slug = _slug(parts[3], "appSlug")
+        container = _container_name(parts[4])
+        image = _image(parts[5])
+        if re.fullmatch(r"[0-9a-f]{64}", parts[6]) is None:
+            raise DeploymentKitError("Malformed application inventory spec fingerprint.")
+        health_path = _health_path(parts[8])
+        if parts[9] not in {"none", "directory"}:
+            raise DeploymentKitError("Malformed application inventory persistence mode.")
+        app = {
+            "ownerRepo": owner,
+            "environment": environment,
+            "appSlug": app_slug,
+            "containerName": container,
+            "image": image,
+            "specSha256": parts[6],
+            "runtimePort": port,
+            "healthPath": health_path,
+            "persistenceMode": parts[9],
+            "currentRelease": parts[10] or None,
+            "previousRelease": parts[11] or None,
+            "containerRunning": parts[12] == "true",
+            "connectedToSharedNetwork": parts[13] == "true",
+            "httpHealthy": parts[14] == "true",
+        }
+        apps.append(app)
+    if set(summary) != {"appCount"}:
+        raise DeploymentKitError("Application inventory omitted appCount.")
+    try:
+        count = int(summary["appCount"])
+    except ValueError as error:
+        raise DeploymentKitError("Malformed application inventory count.") from error
+    if count != len(apps):
+        raise DeploymentKitError("Application inventory count does not match records.")
+    keys = [(item["appSlug"], item["environment"]) for item in apps]
+    if len(keys) != len(set(keys)):
+        raise DeploymentKitError("Duplicate application/environment ownership records were reported.")
+    return {"applications": sorted(apps, key=lambda item: (item["appSlug"], item["environment"]))}
+
+
+def _run_remote(
+    profile: dict[str, Any],
+    address: str,
+    action: str,
+    *,
+    spec: dict[str, Any] | None = None,
+    expected_spec_sha: str = "",
+) -> str:
+    if action not in {"inventory", "deploy"}:
+        raise DeploymentKitError(f"Unsupported application-runtime action: {action}")
+    args = [action]
+    if action == "deploy":
+        args.extend([expected_spec_sha or "NONE", profile["user"]])
+    command = ssh_args(
+        profile,
+        address,
+        command="sudo -n bash -s -- " + " ".join(args),
+    )
+    completed = subprocess.run(
+        command,
+        input=build_remote_script(spec).encode("utf-8"),
+        check=False,
+        capture_output=True,
+    )
+    stdout = completed.stdout.decode("utf-8", errors="replace")
+    stderr = completed.stderr.decode("utf-8", errors="replace")
+    if completed.returncode != 0:
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Remote application-runtime {action} failed: {detail}")
+    return stdout
+
+
+def app_inventory(name: str) -> dict[str, Any]:
+    profile = load_profile(name)
+    evidence = verify_access(profile)
+    inventory = _parse_inventory(
+        _run_remote(profile, evidence["address"], "inventory")
+    )
+    inventory["targetName"] = name
+    inventory["verifiedAddress"] = evidence["address"]
+    inventory["mutated"] = False
+    return inventory
+
+
+def _inventory_snapshot(inventory: dict[str, Any]) -> str:
+    value = {"applications": inventory["applications"]}
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _find_app(inventory: dict[str, Any], app_slug: str, environment: str) -> dict[str, Any] | None:
+    return next(
+        (
+            item
+            for item in inventory["applications"]
+            if item["appSlug"] == app_slug and item["environment"] == environment
+        ),
+        None,
+    )
+
+
+def plan_app_deploy(name: str, spec: dict[str, Any]) -> dict[str, Any]:
+    platform = platform_status(name)
+    if platform["state"] != "ready":
+        raise DeploymentKitError(
+            f"Application deployment requires a ready shared platform; target '{name}' is '{platform['state']}'."
+        )
+    inventory = app_inventory(name)
+    existing = _find_app(inventory, spec["appSlug"], spec["environment"])
+    if existing is not None and existing["ownerRepo"] != spec["ownerRepo"]:
+        raise DeploymentKitError("Application/environment ownership does not match the requested repository.")
+    for item in inventory["applications"]:
+        if (
+            item["containerName"] == spec["containerName"]
+            and (item["appSlug"], item["environment"])
+            != (spec["appSlug"], spec["environment"])
+        ):
+            raise DeploymentKitError(
+                f"Container name collision with managed app {item['appSlug']}--{item['environment']}."
+            )
+    if (
+        existing is not None
+        and existing["specSha256"] == spec["specSha256"]
+        and existing["containerRunning"]
+        and existing["connectedToSharedNetwork"]
+        and existing["httpHealthy"]
+    ):
+        raise DeploymentKitError("The exact application runtime spec is already deployed and healthy.")
+    return {
+        "targetName": name,
+        "action": "deploy",
+        "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 is not None else "create",
+        "previousImage": existing["image"] if existing is not None else None,
+        "previousRelease": existing["currentRelease"] if existing is not None else None,
+        "retainsPreviousRelease": existing is not None,
+        "publishesHostPort": False,
+        "attachesSharedNetwork": NETWORK_NAME,
+        "modifiesRoutes": False,
+        "persistentDataDeletion": False,
+        "inventorySnapshot": _inventory_snapshot(inventory),
+        "expectedSpecSha256": existing["specSha256"] if existing is not None else None,
+        "spec": spec,
+    }
+
+
+def deploy_write_phrase(plan: dict[str, Any]) -> str:
+    return (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE
+        if plan["environment"] == "production"
+        else APP_DEPLOY_WRITE_PHRASE
+    )
+
+
+def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "targetName",
+        "action",
+        "environment",
+        "appSlug",
+        "ownerRepo",
+        "containerName",
+        "image",
+        "runtimePort",
+        "healthPath",
+        "persistenceMode",
+        "changeType",
+        "previousImage",
+        "previousRelease",
+        "retainsPreviousRelease",
+        "publishesHostPort",
+        "attachesSharedNetwork",
+        "modifiesRoutes",
+        "persistentDataDeletion",
+        "inventorySnapshot",
+        "expectedSpecSha256",
+        "spec",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+        raise DeploymentKitError("Malformed application deployment plan.")
+
+    current = app_inventory(plan["targetName"])
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Application inventory changed after the plan was reviewed; create and authorize a fresh plan."
+        )
+    platform = platform_status(plan["targetName"])
+    if platform["state"] != "ready":
+        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
+
+    profile = load_profile(plan["targetName"])
+    evidence = verify_access(profile)
+    _run_remote(
+        profile,
+        evidence["address"],
+        "deploy",
+        spec=plan["spec"],
+        expected_spec_sha=plan["expectedSpecSha256"] or "",
+    )
+    final = app_inventory(plan["targetName"])
+    deployed = _find_app(final, plan["appSlug"], plan["environment"])
+    if deployed is None:
+        raise DeploymentKitError("Application deployment returned without managed runtime state.")
+    if deployed["specSha256"] != plan["spec"]["specSha256"]:
+        raise DeploymentKitError("Application deployment returned with a different runtime spec.")
+    if not (
+        deployed["containerRunning"]
+        and deployed["connectedToSharedNetwork"]
+        and deployed["httpHealthy"]
+    ):
+        raise DeploymentKitError("Application deployment completed but runtime readiness is not healthy.")
+    final["mutated"] = True
+    return final