#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
# Copyright (C) 2026 Adam Mercer
"""testvm: throwaway QEMU/KVM virtual machines for testing.

  testvm run [opts] -- CMD...      boot a fresh VM, run CMD as root, destroy it
  testvm up NAME [opts]            boot a VM and leave it running
  testvm ssh NAME [-- CMD...]      shell (or command) in a running VM
  testvm cp SRC... DEST            copy files with scp; write VM paths as NAME:PATH
  testvm down NAME... | --all      stop and delete VMs
  testvm ls                        list VMs
  testvm images                    list base images
  testvm pull IMAGE [--refresh]    download a base image

opts: --image debian-13 --cpus 2 --mem 2048 --disk 10G -p HOSTPORT:GUESTPORT

Each VM boots from a copy-on-write disk on top of a cached cloud image, so it
always starts clean. cloud-init installs a generated SSH key for root.
A single CMD argument is run by the remote shell ('apt update && ...');
several are quoted and run as one command (ls -l "a b").
"""
import argparse
import fcntl
import hashlib
import json
import os
import secrets
import shlex
import shutil
import signal
import socket
import subprocess
import sys
import time
import urllib.request
from pathlib import Path

IMAGES = {
    # name: (url, checksum file in the same directory, hash)
    "almalinux-10": ("https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/AlmaLinux-10-GenericCloud-latest.x86_64.qcow2", "CHECKSUM", "sha256"),
    "debian-12": ("https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2", "SHA512SUMS", "sha512"),
    "debian-13": ("https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2", "SHA512SUMS", "sha512"),
}
DEFAULT_IMAGE = "debian-13"
HOME = Path.home()
CACHE = Path(os.environ.get("TESTVM_CACHE", HOME / ".cache/testvm"))
STATE = Path(os.environ.get("TESTVM_STATE", HOME / ".local/state/testvm"))
KEY = CACHE / "id_ed25519"
SSH_OPTS = ["-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null",
            "-o", "LogLevel=ERROR", "-o", "IdentitiesOnly=yes", "-i", str(KEY)]
# Boot with UEFI: under nested KVM, BIOS GRUB has been seen to reset the VM
# the moment it jumps into the kernel, while OVMF boots the same image fine.
OVMF_CODE = Path("/usr/share/OVMF/OVMF_CODE_4M.fd")
OVMF_VARS = Path("/usr/share/OVMF/OVMF_VARS_4M.fd")
BOOT_TIMEOUT = int(os.environ.get("TESTVM_BOOT_TIMEOUT", "300"))


class Fail(Exception):
    pass


def log(msg):
    print(f"testvm: {msg}", file=sys.stderr, flush=True)


def sh(*cmd, **kw):
    return subprocess.run(cmd, check=True, **kw)


# --- images ------------------------------------------------------------------

def image_path(name):
    if name not in IMAGES:
        raise Fail(f"unknown image {name!r}; choose from: {', '.join(IMAGES)}")
    return CACHE / "images" / f"{name}.qcow2"


def pull(name, refresh=False):
    dest = image_path(name)
    dest.parent.mkdir(parents=True, exist_ok=True)
    # Lock so parallel runs don't download the same image twice.
    with open(dest.with_suffix(".lock"), "w") as lock:
        fcntl.flock(lock, fcntl.LOCK_EX)
        if dest.exists() and not refresh:
            return dest
        url, sums_name, algo = IMAGES[name]
        base, fname = url.rsplit("/", 1)
        with urllib.request.urlopen(f"{base}/{sums_name}", timeout=30) as r:
            sums = r.read().decode()
        want = next((ln.split()[0] for ln in sums.splitlines()
                     if ln.split() and ln.split()[-1].lstrip("*") == fname), None)
        if not want:
            raise Fail(f"{fname} not listed in {base}/{sums_name}")
        tmp = dest.with_suffix(".part")
        h, done, shown = hashlib.new(algo), 0, -1
        log(f"downloading {name} from {url}")
        with urllib.request.urlopen(url, timeout=60) as r, open(tmp, "wb") as f:
            total = int(r.headers.get("Content-Length") or 0)
            while chunk := r.read(1 << 20):
                f.write(chunk)
                h.update(chunk)
                done += len(chunk)
                pct = done * 100 // total if total else -1
                if pct >= 0 and pct // 10 != shown:
                    shown = pct // 10
                    log(f"  {pct}% of {total >> 20} MiB")
        if h.hexdigest() != want:
            tmp.unlink()
            raise Fail(f"checksum mismatch for {name}; download discarded")
        os.replace(tmp, dest)
        return dest


def ensure_key():
    if not KEY.exists():
        KEY.parent.mkdir(parents=True, exist_ok=True)
        sh("ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-C", "testvm", "-f", str(KEY))


# --- VM state ----------------------------------------------------------------

def vm_dir(name):
    return STATE / name


def load(name):
    try:
        return json.loads((vm_dir(name) / "vm.json").read_text())
    except FileNotFoundError:
        raise Fail(f"no VM named {name!r}") from None


def qemu_pid(name):
    """PID of the VM's QEMU process, or None if it isn't running."""
    try:
        pid = int((vm_dir(name) / "qemu.pid").read_text())
        cmdline = Path(f"/proc/{pid}/cmdline").read_bytes()
    except (FileNotFoundError, ValueError):
        return None
    # Guard against a recycled PID belonging to something else.
    return pid if str(vm_dir(name)).encode() in cmdline else None


def free_port():
    with socket.socket() as s:
        s.bind(("127.0.0.1", 0))
        return s.getsockname()[1]


def ssh_cmd(vm, tty=False):
    return ["ssh", *SSH_OPTS, "-p", str(vm["port"]), *(["-t"] if tty else []), "root@127.0.0.1"]


def remote(cmd):
    """One argument goes to the remote shell as is; several are quoted."""
    return cmd[0] if len(cmd) == 1 else shlex.join(cmd)


def console_tail(name, n=30):
    try:
        lines = (vm_dir(name) / "console.log").read_text(errors="replace").splitlines()
        return "\n".join(lines[-n:])
    except FileNotFoundError:
        return "(no console output)"


# --- commands ----------------------------------------------------------------

def up(name, image, cpus, mem, disk, forwards):
    d = vm_dir(name)
    if d.exists():
        if qemu_pid(name):
            raise Fail(f"VM {name!r} is already running")
        shutil.rmtree(d)  # leftover from a crashed VM
    base = pull(image)
    ensure_key()
    if not OVMF_CODE.exists():
        raise Fail(f"{OVMF_CODE} not found; install the ovmf package")
    d.mkdir(parents=True)
    shutil.copy(OVMF_VARS, d / "efivars.fd")
    sh("qemu-img", "create", "-q", "-f", "qcow2", "-F", "qcow2", "-b", str(base),
       str(d / "disk.qcow2"), disk)
    pubkey = KEY.with_suffix(".pub").read_text().strip()
    (d / "user-data").write_text(
        "#cloud-config\n"
        "disable_root: false\n"
        f"ssh_authorized_keys: [{json.dumps(pubkey)}]\n")
    (d / "meta-data").write_text(f"instance-id: {name}-{secrets.token_hex(4)}\nlocal-hostname: {name}\n")
    sh("genisoimage", "-quiet", "-output", str(d / "seed.iso"), "-volid", "cidata",
       "-joliet", "-rock", str(d / "user-data"), str(d / "meta-data"))

    for attempt in range(3):  # retry if another VM grabs the same port first
        port = free_port()
        fwd = [f"hostfwd=tcp:127.0.0.1:{port}-:22"]
        fwd += [f"hostfwd=tcp:127.0.0.1:{h}-:{g}" for h, g in (f.split(":") for f in forwards)]
        proc = subprocess.run([
            "qemu-system-x86_64", "-name", name, "-machine", "q35,accel=kvm", "-cpu", "host",
            "-smp", str(cpus), "-m", str(mem), "-nodefaults", "-display", "none",
            "-serial", f"file:{d / 'console.log'}",
            "-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
            "-drive", f"if=pflash,format=raw,file={d / 'efivars.fd'}",
            "-drive", f"if=virtio,file={d / 'disk.qcow2'},format=qcow2",
            "-drive", f"if=virtio,file={d / 'seed.iso'},format=raw,readonly=on",
            "-netdev", ",".join(["user,id=n0", *fwd]), "-device", "virtio-net-pci,netdev=n0",
            "-device", "virtio-rng-pci", "-daemonize", "-pidfile", str(d / "qemu.pid"),
        ], check=False, capture_output=True, text=True)
        if proc.returncode == 0:
            break
        if "hostfwd" not in proc.stderr or attempt == 2:
            raise Fail(f"QEMU failed to start:\n{proc.stderr.strip()}")
    vm = {"name": name, "image": image, "port": port, "forwards": forwards, "created": int(time.time())}
    (d / "vm.json").write_text(json.dumps(vm))

    # Wait for SSH, then for cloud-init so tests don't race its first-boot work.
    deadline = time.monotonic() + BOOT_TIMEOUT
    while True:
        if not qemu_pid(name):
            raise Fail(f"VM {name!r} died while booting. Console:\n{console_tail(name)}")
        r = subprocess.run([*ssh_cmd(vm), "-o", "ConnectTimeout=3", "-o", "BatchMode=yes",
                            "cloud-init status --wait >/dev/null 2>&1; true"],
                           check=False, stdin=subprocess.DEVNULL, capture_output=True)
        if r.returncode == 0:
            return vm
        if time.monotonic() > deadline:
            raise Fail(f"VM {name!r} not reachable over SSH after {BOOT_TIMEOUT}s. Console:\n{console_tail(name)}")
        time.sleep(1)


def down(name):
    pid = qemu_pid(name)
    if pid:
        os.kill(pid, signal.SIGTERM)
        for _ in range(50):
            if not qemu_pid(name):
                break
            time.sleep(0.1)
        else:
            os.kill(pid, signal.SIGKILL)
    shutil.rmtree(vm_dir(name), ignore_errors=True)


def all_vms():
    return sorted(p.name for p in STATE.iterdir() if p.is_dir()) if STATE.exists() else []


def cmd_run(a):
    name = a.name or f"run-{secrets.token_hex(3)}"
    try:
        log(f"booting {name} ({a.image})")
        vm = up(name, a.image, a.cpus, a.mem, a.disk, a.forward)
        cmd = a.cmd or ["bash", "-l"]
        tty = not a.cmd and sys.stdin.isatty()
        return subprocess.run([*ssh_cmd(vm, tty), remote(cmd)], check=False).returncode
    finally:
        if a.keep:
            log(f"kept VM {name}; remove it with: testvm down {name}")
        else:
            down(name)


def cmd_up(a):
    vm = up(a.name, a.image, a.cpus, a.mem, a.disk, a.forward)
    log(f"{a.name} is up (ssh port {vm['port']}); connect with: testvm ssh {a.name}")


def cmd_ssh(a):
    vm = load(a.name)
    if not qemu_pid(a.name):
        raise Fail(f"VM {a.name!r} is not running")
    tty = not a.cmd and sys.stdin.isatty()
    return subprocess.run([*ssh_cmd(vm, tty), *([remote(a.cmd)] if a.cmd else [])],
                          check=False).returncode


def cmd_cp(a):
    port, args = None, []
    for p in a.paths:
        head, sep, tail = p.partition(":")
        if sep and "/" not in head and vm_dir(head).exists():
            vm = load(head)
            if port not in (None, vm["port"]):
                raise Fail("cp works with one VM at a time")
            port = vm["port"]
            args.append(f"root@127.0.0.1:{tail}")
        else:
            args.append(p)
    if port is None:
        raise Fail("no VM path given; write VM paths as NAME:PATH")
    return subprocess.run(["scp", *SSH_OPTS, "-P", str(port), "-r", *args], check=False).returncode


def cmd_down(a):
    names = all_vms() if a.all else a.names
    if not names:
        raise Fail("give VM names or --all")
    for n in names:
        if not vm_dir(n).exists():
            raise Fail(f"no VM named {n!r}")
        down(n)


def cmd_ls(a):
    print(f"{'NAME':16} {'STATE':8} {'IMAGE':14} {'SSH':6} {'AGE':>6}  FORWARDS")
    for n in all_vms():
        try:
            vm = load(n)
        except (Fail, ValueError):
            print(f"{n:16} broken")
            continue
        age = int(time.time() - vm["created"])
        age_s = f"{age // 3600}h" if age >= 3600 else f"{age // 60}m"
        state = "running" if qemu_pid(n) else "dead"
        print(f"{n:16} {state:8} {vm['image']:14} {vm['port']:<6} {age_s:>6}  {' '.join(vm['forwards'])}")


def cmd_images(a):
    for name in IMAGES:
        p = image_path(name)
        size = f"{p.stat().st_size >> 20} MiB cached" if p.exists() else "not downloaded"
        print(f"{name:14} {size}{'  (default)' if name == DEFAULT_IMAGE else ''}")


def cmd_pull(a):
    log(f"{a.image} ready at {pull(a.image, a.refresh)}")


def main():
    p = argparse.ArgumentParser(prog="testvm", description=__doc__.split("\n")[0],
                                epilog=__doc__.split("\n", 2)[2], formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = p.add_subparsers(dest="command", required=True)

    def vm_opts(sp):
        sp.add_argument("--image", default=DEFAULT_IMAGE, choices=IMAGES)
        sp.add_argument("--cpus", type=int, default=2)
        sp.add_argument("--mem", type=int, default=2048, help="MiB")
        sp.add_argument("--disk", default="10G")
        sp.add_argument("-p", "--forward", action="append", default=[], metavar="HOST:GUEST",
                        help="forward 127.0.0.1:HOST to the VM's TCP port GUEST")

    sp = sub.add_parser("run", help="boot a fresh VM, run a command, destroy it")
    vm_opts(sp)
    sp.add_argument("--name")
    sp.add_argument("--keep", action="store_true", help="leave the VM running afterwards")
    sp.add_argument("cmd", nargs=argparse.REMAINDER)
    sp.set_defaults(fn=cmd_run)

    sp = sub.add_parser("up", help="boot a VM and leave it running")
    sp.add_argument("name")
    vm_opts(sp)
    sp.set_defaults(fn=cmd_up)

    sp = sub.add_parser("ssh", help="shell or command in a running VM")
    sp.add_argument("name")
    sp.add_argument("cmd", nargs=argparse.REMAINDER)
    sp.set_defaults(fn=cmd_ssh)

    sp = sub.add_parser("cp", help="copy files to or from a VM (NAME:PATH)")
    sp.add_argument("paths", nargs="+")
    sp.set_defaults(fn=cmd_cp)

    sp = sub.add_parser("down", help="stop and delete VMs")
    sp.add_argument("names", nargs="*")
    sp.add_argument("--all", action="store_true")
    sp.set_defaults(fn=cmd_down)

    sub.add_parser("ls", help="list VMs").set_defaults(fn=cmd_ls)
    sub.add_parser("images", help="list base images").set_defaults(fn=cmd_images)
    sp = sub.add_parser("pull", help="download a base image")
    sp.add_argument("image", choices=IMAGES)
    sp.add_argument("--refresh", action="store_true")
    sp.set_defaults(fn=cmd_pull)

    a = p.parse_args()
    if getattr(a, "cmd", None) and a.cmd[0] == "--":
        a.cmd = a.cmd[1:]
    if getattr(a, "name", None) and ("/" in a.name or a.name.startswith(".")):
        raise Fail("VM names can't contain '/' or start with '.'")
    # Turn SIGTERM into a normal exit so `finally` blocks clean up VMs.
    signal.signal(signal.SIGTERM, lambda *_: sys.exit(143))
    return a.fn(a) or 0


if __name__ == "__main__":
    try:
        sys.exit(main())
    except Fail as e:
        log(str(e))
        sys.exit(1)
    except subprocess.CalledProcessError as e:
        log(f"command failed ({e.returncode}): {shlex.join(map(str, e.cmd))}")
        sys.exit(1)
    except KeyboardInterrupt:
        sys.exit(130)
