nomadctl 0.2.0__py3-none-any.whl

nd/__init__.py

@@ -0,0 +1,7 @@
+"""The nd package."""
+
+__version__ = "0.2.0"
+
+from nd.cli import main
+
+__all__ = ["__version__", "main"]

nd/binary/__init__.py

@@ -0,0 +1,10 @@
+"""Wrappers around the local `nomad` binary, used where the HTTP API cannot serve.
+
+`NomadBinary` is a configured handle to the binary (HCL2 compile/validate, plus
+interactive exec and log streaming), bound to one cluster via :meth:`NomadBinary.create`.
+"""
+
+from nd.binary.env import NomadBinaryError
+from nd.binary.runner import NomadBinary
+
+__all__ = ["NomadBinary", "NomadBinaryError"]

nd/binary/env.py

@@ -0,0 +1,43 @@
+"""Shared discovery and environment for the local `nomad` binary.
+
+The Nomad HTTP API cannot parse HCL2 and does not own the raw-TTY exec protocol, so
+some operations shell out to the local `nomad` binary. `NomadBinary` (in `runner.py`)
+uses these helpers to locate the binary and build the connection-env overlay that
+targets the same cluster as the API client.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from nclutils.sh import which
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from nd.nomad.config import NomadConfig
+
+
+class NomadBinaryError(Exception):
+    """Raised when the `nomad` binary is missing or a `nomad` invocation fails."""
+
+
+def ensure_nomad() -> Path:
+    """Return the path to the `nomad` binary, or raise if it is not on PATH."""
+    found = which("nomad")
+    if found is None:
+        msg = "The `nomad` binary was not found on PATH; install it to plan or run jobs."
+        raise NomadBinaryError(msg)
+    return found
+
+
+def binary_env(config: NomadConfig) -> dict[str, str]:
+    """Build the environment for a `nomad` binary invocation.
+
+    Overlays the resolved connection settings onto the current environment so the
+    spawned binary targets the same cluster, token, and namespace as the API client
+    rather than relying on the ambient env alone (which would miss nd config-file
+    overrides). Shared by every binary wrapper so they stay consistent.
+    """
+    return {**os.environ, **config.to_env()}

nd/binary/runner.py

@@ -0,0 +1,192 @@
+"""A configured handle to the local `nomad` binary, used where the HTTP API can't serve.
+
+The HTTP API cannot parse HCL2 and does not own the raw-TTY exec protocol, so some
+operations shell out to the local `nomad` binary. `NomadBinary` binds the resolved
+binary path and the connection-env overlay (which targets the same cluster as the API
+client) to one object, so a multi-file deploy or a long exec/log session resolves the
+binary and builds the env once rather than per call.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+from nclutils import pp
+from nclutils.sh import ShellCommandError, run_command
+
+from nd.binary.env import NomadBinaryError, binary_env, ensure_nomad
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from nd.nomad.config import NomadConfig
+
+
+class NomadBinary:
+    """The local `nomad` CLI, bound to one cluster's connection settings.
+
+    Build it with :meth:`create`, which resolves the binary on PATH. The job-spec
+    methods (`validate`/`plan`/`compile_to_json`) act on local HCL2 files; the
+    allocation methods (`exec_shell`/`stream_logs`) act on a running task.
+    """
+
+    def __init__(self, config: NomadConfig, path: Path) -> None:
+        self._path = str(path)
+        # Build the connection-env overlay once; it is invariant for this cluster.
+        self._env = binary_env(config)
+
+    @classmethod
+    def create(cls, config: NomadConfig) -> NomadBinary:
+        """Resolve the `nomad` binary on PATH and bind it to ``config``.
+
+        Raises:
+            NomadBinaryError: If the binary is not on PATH.
+        """
+        return cls(config, ensure_nomad())
+
+    # --- job specs (HCL2 compile/validate) -------------------------------------------
+
+    def validate(self, file: Path) -> None:
+        """Validate a job file with `nomad job validate`.
+
+        Raises:
+            NomadBinaryError: If validation fails or the binary cannot run.
+        """
+        try:
+            run_command([self._path, "job", "validate", str(file)], env=self._env)
+        except ShellCommandError as exc:
+            msg = f"`nomad job validate {file}` failed: {_stderr(exc)}"
+            raise NomadBinaryError(msg) from exc
+
+    def plan(self, file: Path) -> int:
+        """Preview a job with `nomad job plan`, streaming its output verbatim.
+
+        Returns the binary's exit code (1 means changes are present, 0 means none).
+
+        Raises:
+            NomadBinaryError: If the binary cannot be launched.
+        """
+        try:
+            result = run_command(
+                [self._path, "job", "plan", str(file)], env=self._env, stream=True, check=False
+            )
+        except ShellCommandError as exc:
+            msg = f"`nomad job plan {file}` could not run: {_stderr(exc)}"
+            raise NomadBinaryError(msg) from exc
+        return result.returncode
+
+    def compile_to_json(self, file: Path) -> bytes:
+        """Compile a job file to its JSON register payload via `nomad job run -output`.
+
+        Returns the ``{"Job": {...}}`` JSON bytes without submitting anything.
+
+        Raises:
+            NomadBinaryError: If compilation fails.
+        """
+        try:
+            result = run_command([self._path, "job", "run", "-output", str(file)], env=self._env)
+        except ShellCommandError as exc:
+            msg = f"`nomad job run -output {file}` failed: {_stderr(exc)}"
+            raise NomadBinaryError(msg) from exc
+        return result.stdout.encode("utf-8")
+
+    # --- allocations (interactive exec, log streaming) -------------------------------
+
+    def exec_shell(self, alloc_id: str, task: str, command: list[str]) -> int:
+        """Run an interactive command (a shell) inside a running task via `nomad alloc exec`.
+
+        ``command`` is the in-container argv to launch, e.g. ``["/bin/bash"]`` or the
+        ``["/bin/sh", "-c", ...]`` bash-with-fallback probe. Inherits the parent
+        terminal's stdio so the session is fully interactive. Returns the exit code.
+        """
+        argv = [self._path, "alloc", "exec", "-task", task, "-i"]
+        # Only request a pseudo-tty when stdin is a real terminal; forcing -t against a
+        # pipe (CI, `nd exec ... | cat`) makes the binary fail or hang allocating a PTY.
+        if sys.stdin.isatty():
+            argv.append("-t")
+        argv += [alloc_id, *command]
+        pp.debug("exec: " + " ".join(argv))
+        completed = subprocess.run(argv, env=self._env, check=False)  # noqa: S603
+        return completed.returncode
+
+    def stream_logs(
+        self,
+        alloc_id: str,
+        task: str,
+        *,
+        streams: tuple[str, ...] = ("stdout", "stderr"),
+        tail: int | None = None,
+        export_path: Path | None = None,
+    ) -> int:
+        """Stream, tail, or export a task's logs via `nomad alloc logs`.
+
+        ``streams`` selects which of ``stdout``/``stderr`` to read; the default reads both.
+        By default follows live until interrupted. ``tail`` shows the last N lines
+        statically. ``export_path`` writes the currently-available logs to a file instead
+        of streaming. Returns the binary's exit code; for an export, 0 on a successful write.
+
+        In follow mode both streams are read together through Nomad's native interleaving
+        (no stream flag, its `-f` default). A tail read or an export is one-shot, and Nomad
+        cannot merge streams without `-f`, so each requested stream is read in turn (stdout
+        then stderr) and concatenated.
+
+        Raises:
+            NomadBinaryError: If a read fails.
+        """
+        if tail is None and export_path is None:
+            argv = [self._path, "alloc", "logs", "-f"]
+            # One stream -> select it explicitly; both -> omit the flag so Nomad
+            # interleaves stdout and stderr (its native `-f` behavior).
+            if len(streams) == 1:
+                argv.append(f"-{streams[0]}")
+            argv += ["-task", task, alloc_id]
+            pp.debug("logs: " + " ".join(argv))
+            # Log streaming is one-way output; detach stdin so it never inherits the
+            # parent's terminal or a broken pipe.
+            completed = subprocess.run(  # noqa: S603
+                argv, env=self._env, stdin=subprocess.DEVNULL, check=False
+            )
+            return completed.returncode
+
+        # One-shot tail/export: read each requested stream in turn (Nomad cannot merge
+        # streams without -f).
+        chunks: list[bytes] = []
+        exit_code = 0
+        for stream in streams:
+            argv = [self._path, "alloc", "logs"]
+            if tail is not None:
+                argv += ["-tail", "-n", str(tail)]
+            argv += [f"-{stream}", "-task", task, alloc_id]
+            pp.debug("logs: " + " ".join(argv))
+            if export_path is not None:
+                completed = subprocess.run(  # noqa: S603
+                    argv, env=self._env, stdin=subprocess.DEVNULL, capture_output=True, check=False
+                )
+                if completed.returncode != 0:
+                    detail = completed.stderr.decode("utf-8", "replace").strip()
+                    msg = f"`nomad alloc logs` failed: {detail}"
+                    raise NomadBinaryError(msg)
+                chunks.append(completed.stdout)
+            else:
+                # Tail prints straight to the terminal; with both streams this prints
+                # stdout's tail then stderr's.
+                completed = subprocess.run(  # noqa: S603
+                    argv, env=self._env, stdin=subprocess.DEVNULL, check=False
+                )
+                exit_code = exit_code or completed.returncode
+
+        if export_path is not None:
+            export_path.write_bytes(b"".join(chunks))
+            pp.success(f"Wrote logs to {export_path}")
+            return 0
+        return exit_code
+
+
+def _stderr(exc: ShellCommandError) -> str:
+    """Extract stderr (or the message) from a shell error for a friendly report."""
+    result = getattr(exc, "result", None)
+    if result is not None and getattr(result, "stderr", ""):
+        return result.stderr.strip()
+    return str(exc)

nd/cli.py

@@ -0,0 +1,97 @@
+"""Root Typer application and process entry point for the ``nd`` CLI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated
+
+import typer
+from nclutils import pp
+
+from nd import __version__
+from nd.commands import clean, exec, logs, plan, run, status, stop, volume  # noqa: A004
+from nd.commands import list as list_cmd
+from nd.nomad import (
+    NomadAuthError,
+    NomadConfigError,
+    NomadConnectionError,
+    NomadError,
+)
+
+app = typer.Typer(
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+app.add_typer(status.app, name="status")
+app.add_typer(stop.app, name="stop")
+app.add_typer(clean.app, name="clean")
+app.add_typer(list_cmd.app, name="list")
+app.add_typer(plan.app, name="plan")
+app.add_typer(run.app, name="run")
+app.add_typer(logs.app, name="logs")
+app.add_typer(exec.app, name="exec")
+app.add_typer(volume.app, name="volume")
+
+
+@dataclass
+class AppState:
+    """Shared CLI state passed to subcommands via the Typer context object."""
+
+    verbose: int = 0
+
+
+def _version_callback(value: bool) -> None:  # noqa: FBT001
+    """Print the version and exit when ``--version`` is passed."""
+    if value:
+        pp.console().print(f"nd {__version__}")
+        raise typer.Exit
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "-v", "--verbose", count=True, help="Increase verbosity (-v debug, -vv trace)."
+        ),
+    ] = 0,
+    version: Annotated[  # noqa: ARG001, FBT002
+        bool,
+        typer.Option(
+            "--version",
+            is_eager=True,
+            callback=_version_callback,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Manage Nomad jobs, allocations, and host volumes from the command line."""
+    pp.configure(verbosity=verbose)
+    ctx.obj = AppState(verbose=verbose)
+
+    # With no subcommand, default to the status dashboard rather than printing help.
+    if ctx.invoked_subcommand is None:
+        status.status(ctx, verbose=verbose)
+
+
+def main() -> None:
+    """Run the CLI, mapping Nomad client errors to clean, non-zero exits."""
+    try:
+        app()
+    except KeyboardInterrupt as exc:
+        # 130 = 128 + SIGINT(2), the conventional shell exit code for Ctrl-C.
+        pp.warning("Aborted")
+        raise SystemExit(130) from exc
+    except NomadConnectionError as exc:
+        pp.error("Could not reach the Nomad agent", details=[str(exc)])
+        raise SystemExit(1) from exc
+    except NomadAuthError as exc:
+        pp.error("Not authorized by Nomad (check NOMAD_TOKEN)", details=[str(exc)])
+        raise SystemExit(1) from exc
+    except NomadConfigError as exc:
+        pp.error("Invalid Nomad configuration", details=[str(exc)])
+        raise SystemExit(1) from exc
+    except NomadError as exc:
+        pp.error("Nomad request failed", details=[str(exc)])
+        raise SystemExit(1) from exc

nd/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI subcommands for the nd tool."""

nd/commands/_common.py

@@ -0,0 +1,101 @@
+"""Shared wiring for the ``nd`` subcommands: verbosity and progress-step helpers."""
+
+from __future__ import annotations
+
+import asyncio
+from time import perf_counter
+from typing import TYPE_CHECKING, Annotated, Any, NoReturn, Protocol
+
+import typer
+from nclutils import pp
+from nclutils.pp import Verbosity
+
+from nd.binary import NomadBinary, NomadBinaryError
+from nd.targets import resolve_target
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from nd.nomad.config import NomadConfig
+
+# Every subcommand accepts the same -v/--verbose count option; declare it once.
+VerboseOption = Annotated[
+    int,
+    typer.Option("-v", "--verbose", count=True, help="Increase verbosity (-v debug, -vv trace)."),
+]
+
+
+def configure_verbosity(ctx: typer.Context, verbose: int) -> int:
+    """Apply the effective verbosity and return it.
+
+    A subcommand accepts ``-v``/``-vv`` either before it (the root callback, which
+    stores its count on ``ctx.obj``) or after it; take the louder of the two so
+    either position works, then configure ``pp`` with the result.
+    """
+    verbose = max(getattr(ctx.obj, "verbose", 0), verbose)
+    pp.configure(verbosity=verbose)
+    return verbose
+
+
+class StepLike(Protocol):
+    """Structural type for the progress step object yielded by ``pp.step``."""
+
+    def sub(self, text: str) -> None: ...
+
+
+async def record_step(
+    coro: Awaitable[Any],
+    *,
+    step: StepLike | None,
+    verbose: int,
+    method: str,
+    path: str,
+    count_items: bool = False,
+) -> Any:  # noqa: ANN401
+    """Await one API call, recording the request on the progress step per verbosity.
+
+    The default view stays quiet; ``-v`` names the ``<method> /v1<path>`` request, and
+    ``-vv`` adds the elapsed time (plus the response item count when ``count_items`` is
+    set and the result is a list). Returns the awaited result so callers can use it.
+    """
+    start = perf_counter()
+    result = await coro
+    if step is not None:
+        if verbose >= Verbosity.TRACE:
+            count = len(result) if count_items and isinstance(result, list) else None
+            elapsed_ms = (perf_counter() - start) * 1000
+            items = f"{count} items, " if count is not None else ""
+            step.sub(f"{method} /v1{path} → {items}{elapsed_ms:.0f}ms")
+        else:
+            step.sub(f"{method} /v1{path}")
+    return result
+
+
+def run_alloc_action(
+    config: NomadConfig,
+    *,
+    job: str | None,
+    task: str | None,
+    running_only: bool,
+    action: Callable[[NomadBinary, str, str], int],
+) -> NoReturn:
+    """Resolve an exec/logs target, run a ``nomad`` binary action against it, then exit.
+
+    Shared tail of ``nd exec`` and ``nd logs``: resolve the (job, allocation, task)
+    target through the API client, exit cleanly when there is nothing to act on, then
+    build the configured ``NomadBinary`` and hand it (with the resolved alloc id and
+    task name) to ``action``. A missing binary or failed invocation becomes a friendly
+    exit 1; otherwise the command exits with the action's own return code.
+    """
+    exit_code, target = asyncio.run(
+        resolve_target(config, job_arg=job, task_arg=task, running_only=running_only)
+    )
+    if target is None:
+        raise typer.Exit(exit_code)
+    try:
+        nomad = NomadBinary.create(config)
+        code = action(nomad, target.alloc_id, target.task)
+    except NomadBinaryError as exc:
+        pp.error(str(exc))
+        raise typer.Exit(1) from exc
+    raise typer.Exit(code)

nd/commands/clean.py

@@ -0,0 +1,50 @@
+"""The ``nd clean`` command: force Nomad cluster garbage collection."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+from nclutils import pp
+
+from nd.commands._common import VerboseOption, configure_verbosity, record_step
+from nd.nomad import NomadClient, NomadConfig
+
+app = typer.Typer()
+
+
+@app.callback(invoke_without_command=True)
+def clean(ctx: typer.Context, verbose: VerboseOption = 0) -> None:
+    """Force garbage collection and reconcile job summaries on the cluster.
+
+    Runs Nomad's system garbage collection, then reconciles job summaries. Both
+    operations are safe to run anytime: they only reclaim dead objects and correct
+    summary counts, never touching running jobs.
+    """
+    verbose = configure_verbosity(ctx, verbose)
+    asyncio.run(_run(verbose=verbose))
+
+
+async def _run(*, verbose: int) -> None:
+    """Run the cluster housekeeping operations and report a friendly result.
+
+    Garbage collection and summary reconciliation run sequentially so the
+    progress sub-lines render in a stable order. Both are safe, idempotent
+    operations whose Nomad failures propagate as ``NomadError`` for ``main()``
+    to map onto a clean non-zero exit.
+    """
+    config = NomadConfig.resolve()
+    pp.debug("Resolved Nomad config", details=[f"address={config.address}"])
+    async with NomadClient.from_config(config) as client:
+        with pp.step("Cleaning up the cluster") as step:
+            await record_step(
+                client.system.gc(), step=step, verbose=verbose, method="PUT", path="/system/gc"
+            )
+            await record_step(
+                client.system.reconcile_summaries(),
+                step=step,
+                verbose=verbose,
+                method="PUT",
+                path="/system/reconcile/summaries",
+            )
+    pp.success("Cluster cleaned", details=["garbage collected", "job summaries reconciled"])

nd/commands/exec.py

@@ -0,0 +1,67 @@
+"""The ``nd exec`` command: open an interactive shell inside a running task."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from nd.commands._common import VerboseOption, configure_verbosity, run_alloc_action
+from nd.constants import DEFAULT_EXEC_SHELL, EXEC_SHELL_PROBE
+from nd.nomad import NomadConfig
+
+# allow_interspersed_args lets options follow the positional JOB (e.g. `nd exec web -s sh`).
+app = typer.Typer(context_settings={"allow_interspersed_args": True})
+
+
+def _container_command(shell: str | None) -> list[str]:
+    """Build the in-container argv: an explicit shell, or bash-with-sh fallback.
+
+    An explicit ``--shell`` is run verbatim. With no flag, probe for bash inside the
+    container and fall back to sh so the nicer shell is used when present without
+    failing on minimal images that ship only sh.
+    """
+    if shell is not None:
+        return [shell]
+    return [DEFAULT_EXEC_SHELL, "-c", EXEC_SHELL_PROBE]
+
+
+@app.callback(invoke_without_command=True)
+def exec_(
+    ctx: typer.Context,
+    job: Annotated[
+        str | None,
+        typer.Argument(
+            help="Running job to enter; matches any job whose name starts with this. "
+            "Omit to pick from a list."
+        ),
+    ] = None,
+    task: Annotated[
+        str | None,
+        typer.Option("--task", "-t", help="Target task; skips the task prompt."),
+    ] = None,
+    shell: Annotated[
+        str | None,
+        typer.Option(
+            "--shell", "-s", help="Shell to launch (default: bash, or sh if bash is absent)."
+        ),
+    ] = None,
+    verbose: VerboseOption = 0,
+) -> None:
+    """Open an interactive shell inside a running task's allocation.
+
+    Resolves a running job, allocation, and task, prompting only where the choice is
+    ambiguous, then opens a shell over nomad alloc exec. With no --shell it prefers
+    bash and falls back to sh, so it works on minimal images. Requires an interactive
+    terminal.
+    """
+    configure_verbosity(ctx, verbose)
+    config = NomadConfig.resolve()
+    command = _container_command(shell)
+    run_alloc_action(
+        config,
+        job=job,
+        task=task,
+        running_only=True,
+        action=lambda nomad, alloc_id, task_name: nomad.exec_shell(alloc_id, task_name, command),
+    )