kento-core 1.6.0.dev1__py3-none-any.whl

kento/start.py

@@ -0,0 +1,65 @@
+"""Start a kento-managed instance."""
+
+import logging
+from pathlib import Path
+
+from kento import is_running, read_mode, require_root, resolve_container
+from kento.subprocess_util import run_or_die
+
+logger = logging.getLogger("kento")
+
+
+def start(name: str, *, container_dir: Path | None = None, mode: str | None = None) -> None:
+    require_root()
+
+    if container_dir is None:
+        container_dir = resolve_container(name)
+    container_id = container_dir.name
+
+    if mode is None:
+        mode = read_mode(container_dir)
+
+    # F15: idempotent start — calling start on a running instance should
+    # be a no-op that reports the current state, not a traceback from
+    # lxc-start/pct/qm complaining the container is already up.
+    if is_running(container_dir, mode):
+        logger.info("Already running: %s", name)
+        return
+
+    # Backfill the image-hold container if missing (self-heals guests created
+    # before the hold mechanism). Cheap `container exists` check; runs on every
+    # start but NOT on the already-running early-return above.
+    from kento.layers import ensure_image_hold
+    image = (container_dir / "kento-image").read_text().strip()
+    hold_name = (container_dir / "kento-name").read_text().strip() \
+        if (container_dir / "kento-name").is_file() else name
+    ensure_image_hold(image, hold_name)
+
+    if mode == "vm":
+        from kento.vm import start_vm
+        start_vm(container_dir, name)
+        return
+    elif mode == "pve-vm":
+        vmid = (container_dir / "kento-vmid").read_text().strip()
+        run_or_die(
+            ["qm", "start", vmid],
+            what="start PVE VM",
+            name=name,
+            hint=f"check /var/log/pve/tasks/ or run 'qm start {vmid}' directly.",
+        )
+    elif mode == "pve":
+        run_or_die(
+            ["pct", "start", container_id],
+            what="start PVE container",
+            name=name,
+            hint=f"run 'pct start {container_id}' directly for details.",
+        )
+    else:
+        run_or_die(
+            ["lxc-start", "-n", container_id],
+            what="start LXC container",
+            name=name,
+            hint=f"run 'lxc-start -F -n {container_id}' in the foreground for details.",
+        )
+
+    logger.info("Started: %s", name)

kento/stop.py

@@ -0,0 +1,210 @@
+"""Shut down a kento-managed instance."""
+
+import logging
+from pathlib import Path
+
+from kento import is_running, read_mode, require_root, resolve_container
+from kento.errors import SubprocessError, ValidationError
+from kento.subprocess_util import run_or_die
+
+logger = logging.getLogger("kento")
+
+DEFAULT_PVE_VM_SHUTDOWN_TIMEOUT = 30
+
+# pct/qm phrasings emitted when the target is already down. is_running()
+# ASSUMES RUNNING on a status-query timeout/non-zero (see its docstring), so a
+# stop may be issued on an instance that is actually stopped; we must treat
+# that as a benign no-op rather than a hard error.
+_NOT_RUNNING_MARKERS = (
+    "not running",        # "CT is not running", "VM is not running"
+    "no such",            # defensive: tool variants
+    "is stopped",
+)
+
+
+def _is_not_running_error(text: str) -> bool:
+    """Heuristically detect a pct/qm "already stopped" failure from its output."""
+    lowered = (text or "").lower()
+    return any(marker in lowered for marker in _NOT_RUNNING_MARKERS)
+
+
+def _pve_shutdown_or_die(cmd, *, what: str, name: str, hint: str,
+                         container_dir: Path, mode: str):
+    """Run a pct/qm stop command, tolerating the already-stopped case.
+
+    On non-zero exit we distinguish two cases:
+      - the instance is actually already down (the status query that drove us
+        here merely timed out / returned non-zero, so is_running() assumed
+        running) -> log "Already stopped" (info) and return None; OR
+      - a genuine failure -> raise SubprocessError (branded message), as before.
+
+    The non-fatal run is issued via subprocess_util.subprocess so it shares the
+    same dispatch (and test patch point) as run_or_die. On a genuine failure
+    the branded message mirrors run_or_die's format verbatim.
+
+    Returns the CompletedProcess on success, or None if the instance was
+    already stopped (caller should return without printing a stop action).
+    """
+    from kento import subprocess_util
+    cmd = list(cmd)
+    try:
+        result = subprocess_util.subprocess.run(
+            cmd, capture_output=True, text=True)
+    except (FileNotFoundError, OSError):
+        # Tool missing / not executable: defer to run_or_die for the branded
+        # FileNotFoundError/OSError message + exit (it re-runs and hits the
+        # same error deterministically).
+        run_or_die(cmd, what=what, name=name, hint=hint)
+        return None  # unreachable (run_or_die exits)
+
+    if result.returncode == 0:
+        return result
+
+    combined = (result.stdout or "") + (result.stderr or "")
+    # Re-query actual status; if the instance really is down (or its config is
+    # gone), this was the already-stopped race, not a real failure.
+    if _is_not_running_error(combined) or not is_running(container_dir, mode):
+        logger.info("Already stopped: %s", name)
+        return None
+
+    # Genuine failure: raise SubprocessError (mirrors run_or_die's contract).
+    label = f"{what} {name}" if name else what
+    stderr = (result.stderr or "").strip()
+    if len(stderr) > 500:
+        stderr = stderr[:500] + "... (truncated)"
+    msg = f"failed to {label} (exit {result.returncode})"
+    if stderr:
+        msg += f": {stderr}"
+    if hint:
+        logger.info("hint: %s", hint)
+    raise SubprocessError(msg, cmd=list(cmd), returncode=result.returncode)
+
+
+def shutdown(
+    name: str,
+    *,
+    force: bool = False,
+    container_dir: Path | None = None,
+    mode: str | None = None,
+    timeout: int | None = None,
+    graceful_only: bool = False,
+) -> None:
+    require_root()
+
+    if container_dir is None:
+        container_dir = resolve_container(name)
+    container_id = container_dir.name
+
+    if mode is None:
+        mode = read_mode(container_dir)
+
+    # Mutually exclusive guards. timeout/graceful-only only meaningful
+    # on the bounded-graceful pve-vm path; --force skips graceful entirely.
+    if graceful_only and force:
+        raise ValidationError(
+            "--graceful-only and --force are mutually exclusive "
+            "(one waits forever, the other kills now)."
+        )
+    if graceful_only and timeout is not None:
+        raise ValidationError(
+            "--timeout has no effect with --graceful-only "
+            "(graceful-only drops --forceStop, so the timeout is meaningless)."
+        )
+    if force and timeout is not None:
+        raise ValidationError(
+            "--timeout has no effect with --force "
+            "(force skips graceful shutdown entirely)."
+        )
+
+    # F15: idempotent stop — calling stop on an already-stopped instance
+    # should be a no-op, not a traceback from lxc-stop/pct/qm exiting
+    # non-zero because the target is already down.
+    if not is_running(container_dir, mode):
+        logger.info("Already stopped: %s", name)
+        return
+
+    if mode == "vm":
+        from kento.vm import stop_vm
+        stop_vm(container_dir, force=force)
+    elif mode == "pve-vm":
+        vmid = (container_dir / "kento-vmid").read_text().strip()
+        if force:
+            result = _pve_shutdown_or_die(
+                ["qm", "stop", vmid],
+                what="stop PVE VM",
+                name=name,
+                hint=f"run 'qm stop {vmid}' directly for details.",
+                container_dir=container_dir, mode=mode,
+            )
+            if result is None:
+                return  # already stopped (message already printed)
+        elif graceful_only:
+            result = _pve_shutdown_or_die(
+                ["qm", "shutdown", vmid],
+                what="shut down PVE VM",
+                name=name,
+                hint=f"run 'qm shutdown {vmid}' directly for details.",
+                container_dir=container_dir, mode=mode,
+            )
+            if result is None:
+                return  # already stopped
+        else:
+            effective_timeout = (
+                timeout if timeout is not None else DEFAULT_PVE_VM_SHUTDOWN_TIMEOUT
+            )
+            result = _pve_shutdown_or_die(
+                [
+                    "qm", "shutdown", vmid,
+                    "--timeout", str(effective_timeout),
+                    "--forceStop",
+                ],
+                what="shut down PVE VM",
+                name=name,
+                hint=f"run 'qm shutdown {vmid}' directly for details.",
+                container_dir=container_dir, mode=mode,
+            )
+            if result is None:
+                return  # already stopped
+            combined = (result.stdout or "") + (result.stderr or "")
+            lowered = combined.lower()
+            if "still running" in lowered or "terminating" in lowered:
+                logger.warning(
+                    "VM %s did not honor ACPI shutdown within %ss, hard-stopped",
+                    name, effective_timeout,
+                )
+    elif mode == "pve":
+        if force:
+            result = _pve_shutdown_or_die(
+                ["pct", "stop", container_id],
+                what="stop PVE container",
+                name=name,
+                hint=f"run 'pct stop {container_id}' directly for details.",
+                container_dir=container_dir, mode=mode,
+            )
+        else:
+            result = _pve_shutdown_or_die(
+                ["pct", "shutdown", container_id],
+                what="shut down PVE container",
+                name=name,
+                hint=f"run 'pct shutdown {container_id}' directly for details.",
+                container_dir=container_dir, mode=mode,
+            )
+        if result is None:
+            return  # already stopped (message already printed)
+    else:
+        cmd = ["lxc-stop", "-n", container_id]
+        if force:
+            cmd.append("-k")
+        run_or_die(
+            cmd,
+            what="stop LXC container",
+            name=name,
+            hint=f"run 'lxc-stop -n {container_id}' directly for details.",
+        )
+
+    action = "Stopped" if force else "Shut down"
+    logger.info("%s: %s", action, name)
+
+
+# Alias for backward compatibility
+stop = shutdown

kento/subprocess_util.py

@@ -0,0 +1,76 @@
+"""Subprocess wrapper that converts CalledProcessError/FileNotFoundError into
+kento-branded error messages, not Python tracebacks."""
+
+import logging
+import subprocess
+from typing import Sequence
+
+from kento.errors import SubprocessError
+
+logger = logging.getLogger("kento")
+
+
+def run_or_die(
+    cmd: Sequence[str],
+    what: str,
+    *,
+    name: str | None = None,
+    hint: str | None = None,
+    env: dict | None = None,
+    cwd: str | None = None,
+) -> subprocess.CompletedProcess:
+    """Run cmd and raise SubprocessError on failure.
+
+    Args:
+        cmd: Command + args (first element is the executable).
+        what: Human-readable operation description, e.g. "start LXC container".
+              Used in the error message: "failed to {what}..."
+        name: Optional instance name for the message.
+        hint: Optional follow-on line suggesting what to do next.
+        env, cwd: Passed to subprocess.run.
+
+    Returns the CompletedProcess on success. On failure raises SubprocessError
+    with a message of the form:
+        failed to {what}[ {name}] (exit {rc})[: {stderr_snippet}]
+    carrying cmd and returncode. FileNotFoundError / PermissionError / OSError
+    raise SubprocessError with returncode=None.
+    """
+    try:
+        result = subprocess.run(
+            list(cmd),
+            capture_output=True,
+            text=True,
+            env=env,
+            cwd=cwd,
+        )
+    except FileNotFoundError:
+        tool = cmd[0] if cmd else "(empty cmd)"
+        msg = f"'{tool}' not found on PATH. Install it or check your PATH."
+        if hint:
+            logger.info("hint: %s", hint)
+        raise SubprocessError(msg, cmd=list(cmd))
+    except OSError as e:
+        # PermissionError (binary lacks +x, or is a directory) and other OSError
+        # (ENOEXEC / wrong-arch) — surface a branded message, not a traceback.
+        tool = cmd[0] if cmd else "(empty cmd)"
+        msg = f"cannot execute '{tool}': {e.strerror} (check permissions/arch)"
+        if hint:
+            logger.info("hint: %s", hint)
+        raise SubprocessError(msg, cmd=list(cmd))
+
+    if result.returncode != 0:
+        label = f"{what} {name}" if name else what
+        stderr = (result.stderr or "").strip()
+        # Keep the stderr snippet short so it's still scannable. Full output
+        # from the external tool already went to the user's terminal if the
+        # caller didn't capture it.
+        if len(stderr) > 500:
+            stderr = stderr[:500] + "... (truncated)"
+        msg = f"failed to {label} (exit {result.returncode})"
+        if stderr:
+            msg += f": {stderr}"
+        if hint:
+            logger.info("hint: %s", hint)
+        raise SubprocessError(msg, cmd=list(cmd), returncode=result.returncode)
+
+    return result

kento/suspend.py

@@ -0,0 +1,196 @@
+"""Suspend / resume a kento-managed VM instance (vCPU pause, not a stop).
+
+`kento suspend` pauses a running VM's vCPUs; `kento resume` un-pauses them.
+This is a *pause to RAM* — the VM process keeps running and its memory is
+retained — NOT a shutdown. It is therefore VM-modes-only:
+
+- plain vm : QMP ``stop`` / ``cont`` over ``<container_dir>/qmp.sock`` (the
+             QMP unix socket exposed by start_vm). See qmp_command below.
+- pve-vm   : ``qm suspend <vmid>`` / ``qm resume <vmid>``.
+- lxc / pve-lxc : unsupported — there is no vCPU to pause; use
+             ``kento stop`` / ``kento start`` instead.
+
+Registered (like attach/exec/logs/set) at the bare + lxc + vm CLI scopes; an
+LXC-scoped invocation just hits the unsupported-mode error.
+"""
+
+import json
+import logging
+import socket
+import subprocess
+from pathlib import Path
+
+from kento import is_running, read_mode, require_root, resolve_any
+from kento.errors import ModeError, StateError, SubprocessError
+
+logger = logging.getLogger("kento")
+
+_LXC_UNSUPPORTED = (
+    "suspend/resume is not supported for LXC instances; "
+    "use 'kento stop' / 'kento start'."
+)
+
+
+def qmp_command(sock_path, *commands, timeout: float = 10):
+    """Connect to a QEMU QMP unix socket, negotiate, run commands, return responses.
+
+    Opens ``sock_path`` (AF_UNIX, SOCK_STREAM), reads the server's greeting
+    line (``{"QMP": {...}}``), leaves capabilities-negotiation mode by issuing
+    ``qmp_capabilities``, then sends each command dict in ``commands`` and
+    collects its reply.
+
+    QMP framing: every message is a newline-terminated JSON object. The server
+    may interleave asynchronous ``{"event": ...}`` messages with command
+    replies, so when waiting for a command's reply we read lines until we get a
+    dict that is NOT an event (i.e. carries ``return`` or ``error``).
+
+    Returns the list of reply dicts (one per command in ``commands``), each
+    either ``{"return": ...}`` or ``{"error": ...}``. Raises OSError on socket
+    failure and ValueError on a malformed/empty stream.
+    """
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(timeout)
+    try:
+        sock.connect(str(sock_path))
+        reader = _LineReader(sock)
+
+        # 1. Greeting: the server speaks first with {"QMP": {...}}.
+        greeting = reader.next_json()
+        if "QMP" not in greeting:
+            raise ValueError(f"unexpected QMP greeting: {greeting!r}")
+
+        # 2. Leave negotiation mode. The reply is {"return": {}}.
+        _send(sock, {"execute": "qmp_capabilities"})
+        reader.next_reply()
+
+        # 3. Run each requested command, collecting its reply.
+        replies = []
+        for cmd in commands:
+            _send(sock, cmd)
+            replies.append(reader.next_reply())
+        return replies
+    finally:
+        try:
+            sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        sock.close()
+
+
+def _send(sock, obj) -> None:
+    """Serialize ``obj`` as a newline-terminated UTF-8 JSON line and send it."""
+    sock.sendall((json.dumps(obj) + "\n").encode("utf-8"))
+
+
+class _LineReader:
+    """Buffered newline-delimited JSON reader over a blocking socket."""
+
+    def __init__(self, sock) -> None:
+        self._sock = sock
+        self._buf = b""
+
+    def _next_line(self) -> bytes:
+        while b"\n" not in self._buf:
+            chunk = self._sock.recv(65536)
+            if not chunk:
+                if self._buf.strip():
+                    line, self._buf = self._buf, b""
+                    return line
+                raise ValueError("QMP socket closed before a complete message")
+            self._buf += chunk
+        line, _, self._buf = self._buf.partition(b"\n")
+        return line
+
+    def next_json(self) -> dict:
+        """Return the next non-empty JSON object from the stream."""
+        while True:
+            line = self._next_line().strip()
+            if not line:
+                continue
+            return json.loads(line.decode("utf-8"))
+
+    def next_reply(self) -> dict:
+        """Return the next reply, skipping interleaved async events."""
+        while True:
+            msg = self.next_json()
+            if "event" in msg:
+                continue  # async event; keep waiting for the command reply
+            return msg
+
+
+def _vm_qmp(name: str, container_dir: Path, command: str, label: str) -> None:
+    """Run a single QMP command on a plain VM. command is 'stop' or 'cont'."""
+    sock_path = container_dir / "qmp.sock"
+    if not sock_path.exists():
+        raise SubprocessError(
+            f"QMP socket not found for '{name}' ({sock_path}). The "
+            f"instance is not running, or it was started by an older kento "
+            f"without QMP support. Start it with 'kento start {name}' and retry."
+        )
+    try:
+        (reply,) = qmp_command(sock_path, {"execute": command})
+    except (OSError, ValueError) as exc:
+        raise SubprocessError(
+            f"QMP {command} failed for '{name}': {exc}. Is it running?"
+        ) from exc
+    if "error" in reply:
+        err = reply["error"]
+        desc = err.get("desc", err) if isinstance(err, dict) else err
+        raise SubprocessError(f"QMP {command} rejected for '{name}': {desc}")
+    logger.info("%s: %s", label, name)
+
+
+def _pve_vm_qm(name: str, container_dir: Path, verb: str, label: str) -> None:
+    """Run 'qm suspend|resume <vmid>' for a pve-vm. verb is 'suspend'/'resume'."""
+    vmid = (container_dir / "kento-vmid").read_text().strip()
+    result = subprocess.run(
+        ["qm", verb, vmid], capture_output=True, text=True)
+    if result.returncode != 0:
+        stderr = (result.stderr or "").strip()
+        raise SubprocessError(
+            f"'qm {verb} {vmid}' failed for '{name}'"
+            + (f": {stderr}" if stderr else "")
+            + f". Run 'qm {verb} {vmid}' directly for details.",
+            cmd=["qm", verb, vmid],
+            returncode=result.returncode,
+        )
+    logger.info("%s: %s", label, name)
+
+
+def _dispatch(name: str, *, vm_qmp_command: str, qm_verb: str,
+              label: str, namespace: str | None = None) -> None:
+    """Shared body for suspend/resume."""
+    require_root()
+
+    container_dir, mode = resolve_any(name, namespace)
+    if mode is None:
+        mode = read_mode(container_dir)
+
+    if mode in ("lxc", "pve"):
+        raise ModeError(_LXC_UNSUPPORTED)
+
+    if not is_running(container_dir, mode):
+        raise StateError(
+            f"instance is not running: {name}. "
+            f"Start it first: kento start {name}"
+        )
+
+    if mode == "vm":
+        return _vm_qmp(name, container_dir, vm_qmp_command, label)
+    if mode == "pve-vm":
+        return _pve_vm_qm(name, container_dir, qm_verb, label)
+
+    # Unknown mode (shouldn't happen — resolve_any returns a known mode).
+    raise ModeError(f"unsupported mode {mode!r} for suspend/resume.")
+
+
+def suspend(name: str, namespace: str | None = None) -> None:
+    """Pause a running VM's vCPUs (QMP stop / qm suspend)."""
+    _dispatch(name, vm_qmp_command="stop", qm_verb="suspend",
+              label="Suspended", namespace=namespace)
+
+
+def resume(name: str, namespace: str | None = None) -> None:
+    """Resume a suspended VM's vCPUs (QMP cont / qm resume)."""
+    _dispatch(name, vm_qmp_command="cont", qm_verb="resume",
+              label="Resumed", namespace=namespace)