runspec-linux-core 0.4.0__tar.gz → 0.5.0__tar.gz

{runspec_linux_core-0.4.0 → runspec_linux_core-0.5.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # runspec-linux-core Changelog
 
+## [0.5.0] — 2026-08-07
+
+The Docker container helpers now take the same per-invocation `run_as` /
+`become_method` escalation as the log/service helpers, since the Docker daemon
+socket is typically root- or `docker`-group-owned. `list_containers`,
+`container_logs`, and `restart_container` gain keyword-only `run_as` /
+`become_method` params and wrap their `docker` subprocess with `build_become`;
+a failed escalated command raises `CommandError` with the passwordless-sudo hint
+(`container_logs` no longer returns the sudo error as log lines when `run_as` is
+set). No behaviour change when `run_as` is unset.
+
+
 ## [0.4.0] — 2026-08-01
 
 New shared privilege-escalation module `runspec_linux_core.become` — the single

{runspec_linux_core-0.4.0 → runspec_linux_core-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.4.0
+Version: 0.5.0
 Summary: Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)
 Requires-Python: >=3.10
 Provides-Extra: dev

{runspec_linux_core-0.4.0 → runspec_linux_core-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.4.0"
+version = "0.5.0"
 requires-python = ">=3.10"
 description = "Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)"
 dependencies = []

runspec_linux_core-0.5.0/runspec_linux_core/containers.py

@@ -0,0 +1,102 @@
+"""Docker container helpers: list, logs, restart.
+
+The Docker daemon socket is typically root-owned (or restricted to the ``docker``
+group), so each helper takes an optional ``run_as`` user (with a
+``become_method``). When set, the ``docker`` command is escalated via
+``sudo -n -u`` / ``su`` (:func:`runspec_linux_core.become.build_become`) — a
+``--sudo`` flag on the runnable maps to ``run_as="root"``. With no ``run_as`` the
+command runs as the calling user (unchanged).
+"""
+
+import shutil
+import subprocess
+
+from runspec_linux_core.become import build_become, check_become_error
+from runspec_linux_core.errors import ToolNotFoundError
+
+
+def _docker_available() -> bool:
+    return shutil.which("docker") is not None
+
+
+def list_containers(include_all: bool = False, *, run_as: str | None = None, become_method: str = "sudo") -> list[dict]:
+    """Return Docker containers (running, or all if ``include_all``).
+
+    Raises ToolNotFoundError if docker is not installed, or CommandError if the
+    ``docker ps`` command returns a non-zero exit (with a passwordless-sudo hint
+    when ``run_as`` is set).
+    """
+    if not _docker_available():
+        raise ToolNotFoundError("docker not installed or not in PATH")
+
+    cmd = [
+        "docker",
+        "ps",
+        "--format",
+        "{{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}\t{{.Names}}",
+    ]
+    if include_all:
+        cmd.append("--all")
+
+    result = subprocess.run(build_become(cmd, run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("list containers", result.stderr, run_as)
+
+    rows = []
+    for line in result.stdout.strip().splitlines():
+        parts = line.split("\t")
+        if len(parts) < 6:
+            continue
+        rows.append(
+            {
+                "id": parts[0],
+                "image": parts[1],
+                "command": parts[2].strip('"'),
+                "created": parts[3],
+                "status": parts[4],
+                "name": parts[5],
+            }
+        )
+    return rows
+
+
+def container_logs(container: str, lines: int = 50, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Return the last ``lines`` log lines for a container.
+
+    Raises ToolNotFoundError if docker is not installed. When ``run_as`` is set
+    and the escalated command fails, raises CommandError with a passwordless-sudo
+    hint rather than returning the sudo error as log lines.
+    """
+    if not _docker_available():
+        raise ToolNotFoundError("docker not installed or not in PATH")
+
+    argv = build_become(["docker", "logs", "--tail", str(lines), container], run_as, become_method)
+    result = subprocess.run(argv, capture_output=True, text=True)
+    if run_as and result.returncode != 0:
+        check_become_error("container logs", result.stderr, run_as)
+    # docker logs writes to stderr by default
+    output = result.stderr if result.stderr else result.stdout
+    output_lines = output.strip().splitlines()
+    out = {"container": container, "lines": output_lines, "count": len(output_lines)}
+    if run_as:
+        out["run_as"] = run_as
+    return out
+
+
+def restart_container(container: str, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Restart a container. Returns ``{container, restarted: True}`` on success.
+
+    Raises ToolNotFoundError if docker is not installed, or CommandError if the
+    restart returns a non-zero exit (with a passwordless-sudo hint when
+    ``run_as`` is set).
+    """
+    if not _docker_available():
+        raise ToolNotFoundError("docker not installed or not in PATH")
+
+    result = subprocess.run(build_become(["docker", "restart", container], run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("restart container", result.stderr, run_as)
+    out = {"container": container, "restarted": True}
+    if run_as:
+        out["run_as"] = run_as
+    return out

runspec_linux_core-0.5.0/tests/test_containers_runas.py

@@ -0,0 +1,68 @@
+"""The run_as / become_method escalation on the Docker container helpers.
+
+The subprocess layer is stubbed so no real docker runs; the tests assert the
+escalated argv (the ``sudo -n -u`` / ``su`` prefix) and that no escalation
+happens when run_as is unset.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+import pytest
+
+from runspec_linux_core import containers
+
+
+def _stub(monkeypatch: pytest.MonkeyPatch, stdout: str = "", rc: int = 0, stderr: str = "") -> list[list[str]]:
+    calls: list[list[str]] = []
+
+    def fake_run(argv, capture_output=None, text=None):  # noqa: A002
+        calls.append(argv)
+        return subprocess.CompletedProcess(argv, rc, stdout=stdout, stderr=stderr)
+
+    monkeypatch.setattr(containers.subprocess, "run", fake_run)
+    monkeypatch.setattr(containers, "_docker_available", lambda: True)
+    return calls
+
+
+def test_list_containers_no_run_as(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch, stdout='abc\timg\t"/bin/sh"\tnow\tUp\tweb\n')
+    rows = containers.list_containers()
+    assert calls[0][0] == "docker"  # no escalation prefix
+    assert rows[0]["name"] == "web"
+
+
+def test_list_containers_run_as_escalates(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch, stdout="")
+    containers.list_containers(True, run_as="root")
+    assert calls[0][:4] == ["sudo", "-n", "-u", "root"]
+    assert calls[0][4:7] == ["docker", "ps", "--format"]
+    assert "--all" in calls[0]
+
+
+def test_restart_container_run_as_escalates(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch)
+    out = containers.restart_container("web", run_as="deploy")
+    assert calls[0] == ["sudo", "-n", "-u", "deploy", "docker", "restart", "web"]
+    assert out == {"container": "web", "restarted": True, "run_as": "deploy"}
+
+
+def test_container_logs_run_as_su(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch, stdout="log line 1\nlog line 2\n")
+    out = containers.container_logs("web", 10, run_as="svc", become_method="su")
+    assert calls[0] == ["su", "svc", "-c", "docker logs --tail 10 web"]
+    assert out["count"] == 2
+    assert out["run_as"] == "svc"
+
+
+def test_container_logs_run_as_passwordless_hint(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub(monkeypatch, rc=1, stderr="sudo: a password is required")
+    with pytest.raises(Exception, match="passwordless sudo is not configured for run-as 'svc'"):
+        containers.container_logs("web", run_as="svc")
+
+
+def test_restart_container_run_as_passwordless_hint(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub(monkeypatch, rc=1, stderr="sudo: a terminal is required")
+    with pytest.raises(Exception, match="passwordless sudo is not configured for run-as 'svc'"):
+        containers.restart_container("web", run_as="svc")

runspec_linux_core-0.4.0/runspec_linux_core/containers.py

@@ -1,88 +0,0 @@
-"""Docker container helpers: list, logs, restart."""
-
-import shutil
-import subprocess
-
-from runspec_linux_core.errors import CommandError, ToolNotFoundError
-
-
-def _docker_available() -> bool:
-    return shutil.which("docker") is not None
-
-
-def list_containers(include_all: bool = False) -> list[dict]:
-    """Return Docker containers (running, or all if ``include_all``).
-
-    Raises ToolNotFoundError if docker is not installed, or CommandError if the
-    ``docker ps`` command returns a non-zero exit.
-    """
-    if not _docker_available():
-        raise ToolNotFoundError("docker not installed or not in PATH")
-
-    cmd = [
-        "docker",
-        "ps",
-        "--format",
-        "{{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}\t{{.Names}}",
-    ]
-    if include_all:
-        cmd.append("--all")
-
-    result = subprocess.run(cmd, capture_output=True, text=True)
-    if result.returncode != 0:
-        raise CommandError(result.stderr.strip())
-
-    rows = []
-    for line in result.stdout.strip().splitlines():
-        parts = line.split("\t")
-        if len(parts) < 6:
-            continue
-        rows.append(
-            {
-                "id": parts[0],
-                "image": parts[1],
-                "command": parts[2].strip('"'),
-                "created": parts[3],
-                "status": parts[4],
-                "name": parts[5],
-            }
-        )
-    return rows
-
-
-def container_logs(container: str, lines: int = 50) -> dict:
-    """Return the last ``lines`` log lines for a container.
-
-    Raises ToolNotFoundError if docker is not installed.
-    """
-    if not _docker_available():
-        raise ToolNotFoundError("docker not installed or not in PATH")
-
-    result = subprocess.run(
-        ["docker", "logs", "--tail", str(lines), container],
-        capture_output=True,
-        text=True,
-    )
-    # docker logs writes to stderr by default
-    output = result.stderr if result.stderr else result.stdout
-    output_lines = output.strip().splitlines()
-    return {"container": container, "lines": output_lines, "count": len(output_lines)}
-
-
-def restart_container(container: str) -> dict:
-    """Restart a container. Returns ``{container, restarted: True}`` on success.
-
-    Raises ToolNotFoundError if docker is not installed, or CommandError if the
-    restart returns a non-zero exit (message is the captured stderr).
-    """
-    if not _docker_available():
-        raise ToolNotFoundError("docker not installed or not in PATH")
-
-    result = subprocess.run(
-        ["docker", "restart", container],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        raise CommandError(result.stderr.strip())
-    return {"container": container, "restarted": True}