docker-stack 2.2.3__tar.gz → 2.2.5__tar.gz

{docker_stack-2.2.3 → docker_stack-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.2.3
+Version: 2.2.5
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai

{docker_stack-2.2.3 → docker_stack-2.2.5}/docker_stack/cli.py

@@ -37,7 +37,6 @@ from docker_stack.shell_auth import (
     shell_session_active,
 )
 from docker_stack.manager_api import (
-    FEATURE_CLUSTER_CONTAINER_CLI,
     FEATURE_STACK_DEPLOY,
     FEATURE_STACK_QUERY,
     ManagerApiClient,
@@ -102,15 +101,23 @@ def _write_selected_node(value: Optional[str], display_name: str) -> None:
         Path(node_state).write_text(f"{display_name}\n", encoding="utf-8")
 
 
-def _manager_with_cluster_cli() -> ManagerApiClient:
-    client = discover_manager_client()
-    if client is None or not client.supports(FEATURE_CLUSTER_CONTAINER_CLI):
-        raise RuntimeError("Docker-Manager does not support cluster container CLI; upgrade the manager and all node agents")
+def _require_manager() -> ManagerApiClient:
+    """Return a client for the Docker-Manager behind this shell, or explain why not.
+
+    Only the current manager is supported, so there is no capability negotiation here -
+    either the target is a Docker-Manager or it is a plain Docker daemon.
+    """
+    client = discover_manager_client(strict=True)
+    if client is None or not client.is_manager_backend():
+        raise RuntimeError(
+            f"{client.manager_url if client else 'the current Docker endpoint'} is not a "
+            "Docker-Manager; node-local commands need one"
+        )
     return client
 
 
 def _select_node(value: str) -> str:
-    client = _manager_with_cluster_cli()
+    client = _require_manager()
     requested = value.strip()
     if requested.lower() == "cluster":
         _write_selected_node(None, "cluster")
@@ -133,6 +140,9 @@ def _select_node(value: str) -> str:
         raise RuntimeError(f"node '{requested}' is not ready")
     node_id = str(node.get("id") or "").strip()
     hostname = str(node.get("hostname") or node_id).strip()
+    # Only this node has to be usable. The health of every other node - drained, down, or
+    # missing its agent - is none of this command's business.
+    client.check_node_agent(node_id or hostname)
     _write_selected_node(node_id, hostname)
     return hostname
 
@@ -339,6 +349,13 @@ def _print_cluster_containers(payload: Dict[str, object], *, no_trunc: bool = Fa
         columns.append("SIZE")
     columns.append("NODE")
     _print_table(columns, rows)
+    skipped = payload.get("skipped_nodes") if isinstance(payload.get("skipped_nodes"), list) else []
+    for node in skipped:
+        if isinstance(node, dict):
+            print(
+                f"docker ps: skipped node {node.get('node_name') or node.get('node_id')}: {node.get('reason')}",
+                file=sys.stderr,
+            )
     errors = payload.get("node_errors") if isinstance(payload.get("node_errors"), list) else []
     for error in errors:
         if isinstance(error, dict):
@@ -350,6 +367,38 @@ def _print_cluster_containers(payload: Dict[str, object], *, no_trunc: bool = Fa
     return 1 if errors else 0
 
 
+def _exec_process(command: List[str], env: Optional[Dict[str, str]] = None) -> int:
+    """Replace this process with ``command`` so it owns the terminal, its signals, and its exit code.
+
+    Proxying through ``subprocess.run`` keeps Python in the foreground process group: Ctrl+C is
+    delivered to the proxy as well as to the child, which surfaces as a ``KeyboardInterrupt``
+    traceback, and a signal-killed child reports a negative return code that ``sys.exit`` turns into
+    a nonsense status (``-2`` becomes ``254`` instead of ``130``). ``exec`` removes the middleman.
+    Only POSIX execs: on Windows ``exec`` detaches the child and hands control straight back, which
+    would break the caller's wait semantics.
+
+    Returns only on failure; the caller keeps its ``int`` contract for that case.
+    """
+    if os.name != "posix":
+        return subprocess.run(command, check=False, env=env).returncode
+    # exec discards Python's buffers, so anything already printed has to reach the fd first.
+    sys.stdout.flush()
+    sys.stderr.flush()
+    try:
+        if env is None:
+            os.execvp(command[0], command)
+        else:
+            os.execvpe(command[0], command, env)
+    except OSError as exc:
+        print(f"docker-stack: cannot execute {command[0]}: {exc}", file=sys.stderr)
+        return 127
+
+
+def _exec_docker(values: List[str]) -> int:
+    """Hand the command to the real Docker CLI, replacing this process."""
+    return _exec_process(["docker", *values])
+
+
 def _managed_docker(arguments: List[str]) -> int:
     values = list(arguments)
     if values and values[0] == "--":
@@ -378,11 +427,11 @@ def _managed_docker(arguments: List[str]) -> int:
         value in {"-q", "--quiet", "--format"} or value.startswith("--format=")
         for value in command
     ):
-        return subprocess.run(["docker", *values], check=False).returncode
+        return _exec_docker(values)
     try:
         client = discover_manager_client()
-        if client is None or not client.supports(FEATURE_CLUSTER_CONTAINER_CLI):
-            return subprocess.run(["docker", *values], check=False).returncode
+        if client is None or not client.is_manager_backend():
+            return _exec_docker(values)
         filters = []
         all_containers = False
         latest = False
@@ -411,7 +460,7 @@ def _managed_docker(arguments: List[str]) -> int:
             elif value.startswith("--last="):
                 limit = int(value.split("=", 1)[1])
             else:
-                return subprocess.run(["docker", *values], check=False).returncode
+                return _exec_docker(values)
             index += 1
         payload = client.list_containers(
             all_containers=all_containers,
@@ -1774,7 +1823,7 @@ def open_context_shell(config_dir: Path, context_name: str) -> int:
     env["DOCKER_CONTEXT"] = context_name
     env["DOCKER_MANAGER_CONTEXT_NAME"] = context_name
     shell = env.get("SHELL", "").strip() or "/bin/bash"
-    return subprocess.run([shell, "-i"], check=False, env=env).returncode
+    return _exec_process([shell, "-i"], env=env)
 
 
 def active_shell_config_dir(context_name: str) -> Optional[Path]:
@@ -1805,6 +1854,29 @@ def _error_output(exc: subprocess.CalledProcessError) -> str:
     return "\n".join(value for value in values if value)
 
 
+_MANAGER_VERSION_PROBE_PATTERN = re.compile(r"manager request failed \(\w+ /version\)", re.IGNORECASE)
+
+
+def _humanize_manager_error(message: str) -> str:
+    """Render a manager JSON error body as prose instead of dumping the raw payload."""
+    match = re.search(r"^(.*?: HTTP \d+): (\{.*\})$", message, re.DOTALL)
+    if not match:
+        return message
+    try:
+        body = json.loads(match.group(2))
+    except json.JSONDecodeError:
+        return message
+    if not isinstance(body, dict):
+        return message
+    detail = str(body.get("message", "")).strip()
+    if not detail:
+        return message
+    incident = str(body.get("incident_id") or body.get("trace_id") or "").strip()
+    if incident:
+        return f"{match.group(1)}: {detail} (incident {incident})"
+    return f"{match.group(1)}: {detail}"
+
+
 def _manager_deploy_suggestion(message: str) -> Optional[str]:
     if GITHUB_WORKFLOW_RESTRICTED_MESSAGE in message:
         return (
@@ -1824,10 +1896,16 @@ def _manager_deploy_suggestion(message: str) -> Optional[str]:
             "by this stack. Either allow that external network in the Docker-Manager deployment rule, attach the service to "
             "a stack-owned network, or relabel/recreate the existing network with the expected stack ownership before deploying."
         )
-    if "manager request failed" in lowered and "/version" in lowered:
+    if "stack not found" in lowered:
+        return (
+            "Suggestion: the manager was reached but has no stack by that name in that namespace. "
+            "Run 'docker-stack ls' to list stacks in the current namespace, or 'docker-stack ls -A' to search every namespace."
+        )
+    if _MANAGER_VERSION_PROBE_PATTERN.search(message):
         return (
-            "Suggestion: check that the manager URL is reachable from the runner and that the setup action exported "
-            "DOCKER_MANAGER_URL and the matching Docker auth headers."
+            "Suggestion: docker-stack could not read the manager's /version endpoint. Check that DOCKER_MANAGER_URL points "
+            "at a reachable manager and that the Docker auth headers are set - in CI that means running the docker-stack "
+            "setup action before this step."
         )
     if "docker-manager is configured" in lowered and "did not advertise required feature" in lowered:
         return (
@@ -1841,7 +1919,7 @@ def _format_called_process_error(exc: subprocess.CalledProcessError) -> str:
     output = _error_output(exc)
     lines = [f"docker-stack: command failed with exit code {exc.returncode}: {_format_command(exc.cmd)}"]
     if output:
-        lines.append(output)
+        lines.append(_humanize_manager_error(output))
     suggestion = _manager_deploy_suggestion(output)
     if suggestion:
         lines.extend(["", suggestion])
@@ -1850,14 +1928,14 @@ def _format_called_process_error(exc: subprocess.CalledProcessError) -> str:
 
 def _format_runtime_error(exc: RuntimeError) -> str:
     message = str(exc).strip() or exc.__class__.__name__
-    lines = [f"docker-stack: {message}"]
+    lines = [f"docker-stack: {_humanize_manager_error(message)}"]
     suggestion = _manager_deploy_suggestion(message)
     if suggestion:
         lines.extend(["", suggestion])
     return "\n".join(lines)
 
 
-def main(args: List[str] = None):
+def _run(args: List[str] = None):
     parser = argparse.ArgumentParser(description="Deploy and manage Docker stacks.")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
@@ -2202,5 +2280,18 @@ def main(args: List[str] = None):
         sys.exit(2)
 
 
+def main(args: List[str] = None):
+    """Entry point. Ctrl+C has to look like an interrupted shell command, not a Python crash.
+
+    Commands that exec into another binary never reach this handler; it covers the paths that stay
+    in Python (cluster-rendered ``ps``, login, deploy) and any HTTP call they are blocked on.
+    """
+    try:
+        return _run(args)
+    except KeyboardInterrupt:
+        print(file=sys.stderr)
+        return 130
+
+
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

{docker_stack-2.2.3 → docker_stack-2.2.5}/docker_stack/manager_api.py

@@ -416,6 +416,22 @@ class ManagerApiClient:
         endpoint_id = self._resolve_endpoint_id()
         return f"/api/endpoints/{endpoint_id}{normalized}"
 
+    def is_manager_backend(self) -> bool:
+        """True when the target is a Docker-Manager stack API rather than a raw daemon."""
+        return self._detect_manager_backend()
+
+    def check_node_agent(self, selector: str) -> Dict[str, Any]:
+        """Report whether one node can serve node-local Docker commands.
+
+        Scoped to ``selector`` on purpose: an unrelated node that is drained, down, or
+        missing its agent must never make a usable node look unusable.
+        """
+        node = urllib.parse.quote(selector, safe="")
+        payload = self._request_json(f"/api/docker-stack/nodes/{node}/agent")
+        if not isinstance(payload, dict):
+            raise RuntimeError("Docker-Manager node agent response is invalid")
+        return payload
+
     def supports(self, feature_name: str) -> bool:
         features = self.detect_features()
         if FEATURE_MESUDIP_DOCKER_ENTERPRISE in features and feature_name in {
@@ -721,7 +737,15 @@ class ManagerApiClient:
         )
 
 
-def discover_manager_client(timeout_secs: int = 5) -> Optional[ManagerApiClient]:
+def discover_manager_client(
+    timeout_secs: int = 5, *, strict: bool = False
+) -> Optional[ManagerApiClient]:
+    """Build a client for the manager behind DOCKER_MANAGER_URL or the Docker context.
+
+    ``strict`` raises the concrete reason instead of returning ``None``. Callers that
+    fall back to the plain Docker CLI want the quiet form; callers that are about to
+    report a failure to the user must not discard why discovery failed.
+    """
     try:
         target = _manager_target_from_env()
         if target:
@@ -729,11 +753,26 @@ def discover_manager_client(timeout_secs: int = 5) -> Optional[ManagerApiClient]
         elif shutil.which("docker"):
             _, context_target = current_docker_context_target()
             if not context_target or not context_target.startswith(("tcp://", "http://", "https://")):
+                if strict:
+                    raise RuntimeError(
+                        "no Docker-Manager endpoint found: set DOCKER_MANAGER_URL, or select a "
+                        f"docker context with a tcp:// endpoint (current target: {context_target or 'none'})"
+                    )
                 return None
             config = resolve_login_config(manager_target=context_target)
         else:
+            if strict:
+                raise RuntimeError(
+                    "no Docker-Manager endpoint found: DOCKER_MANAGER_URL is unset and the docker CLI is not installed"
+                )
             return None
-    except Exception:
+    except RuntimeError:
+        if strict:
+            raise
+        return None
+    except Exception as exc:
+        if strict:
+            raise RuntimeError(f"failed resolving the Docker-Manager endpoint: {exc}") from exc
         return None
 
     return ManagerApiClient(

{docker_stack-2.2.3 → docker_stack-2.2.5}/docker_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.2.3
+Version: 2.2.5
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai

{docker_stack-2.2.3 → docker_stack-2.2.5}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="docker-stack",
-    version="2.2.3",
+    version="2.2.5",
     description="CLI for deploying and managing Docker stacks.",
     long_description=open("README.md").read(),  # You can include a README file to describe your package
     long_description_content_type="text/markdown",

{docker_stack-2.2.3 → docker_stack-2.2.5}/tests/test_docker_stack.py

@@ -12,6 +12,8 @@ import yaml
 from docker_stack.cli import (
     DOCKER_SHELL_ENDPOINT_ENV_VARS,
     Docker,
+    _format_runtime_error,
+    _exec_process,
     _managed_docker,
     _read_selected_node,
     _select_node,
@@ -36,14 +38,17 @@ def test_node_use_updates_only_managed_shell_config(monkeypatch, tmp_path):
     monkeypatch.setenv("DOCKER_STACK_SHELL_SECRET", "secret")
     monkeypatch.setenv("DOCKER_CONFIG", str(tmp_path))
     monkeypatch.setenv("DOCKER_STACK_SHELL_NODE_STATE", str(node_state))
+    checked = []
     client = SimpleNamespace(
         list_nodes=lambda: {
             "nodes": [
                 {"id": "node-worker-123", "hostname": "worker-02", "state": "Ready"},
             ]
-        }
+        },
+        check_node_agent=lambda selector: checked.append(selector)
+        or {"node_id": selector, "node_name": "worker-02", "agent": "ready"},
     )
-    monkeypatch.setattr("docker_stack.cli._manager_with_cluster_cli", lambda: client)
+    monkeypatch.setattr("docker_stack.cli._require_manager", lambda: client)
 
     assert _select_node("worker-02") == "worker-02"
     payload = json.loads(config_path.read_text(encoding="utf-8"))
@@ -52,6 +57,8 @@ def test_node_use_updates_only_managed_shell_config(monkeypatch, tmp_path):
     assert _read_selected_node() == "node-worker-123"
     assert node_state.read_text(encoding="utf-8").strip() == "worker-02"
 
+    assert checked == ["node-worker-123"]
+
     assert _select_node("cluster") == "cluster"
     payload = json.loads(config_path.read_text(encoding="utf-8"))
     assert "X-Docker-Manager-Node" not in payload["HttpHeaders"]
@@ -59,7 +66,7 @@ def test_node_use_updates_only_managed_shell_config(monkeypatch, tmp_path):
 
 def test_managed_docker_ps_renders_node_column(monkeypatch, capsys):
     client = SimpleNamespace(
-        supports=lambda feature: feature == "cluster_container_cli_v1",
+        is_manager_backend=lambda: True,
         list_containers=lambda **_kwargs: {
             "containers": [
                 {
@@ -91,7 +98,7 @@ def test_managed_docker_ps_renders_node_column(monkeypatch, capsys):
 
 def test_managed_docker_ps_matches_docker_columns(monkeypatch, capsys):
     client = SimpleNamespace(
-        supports=lambda feature: feature == "cluster_container_cli_v1",
+        is_manager_backend=lambda: True,
         list_containers=lambda **_kwargs: {
             "containers": [
                 {
@@ -154,7 +161,7 @@ def test_managed_docker_ps_matches_docker_columns(monkeypatch, capsys):
 )
 def test_managed_docker_ps_drops_pinned_digest_like_docker(monkeypatch, capsys, image, expected, expected_no_trunc):
     client = SimpleNamespace(
-        supports=lambda feature: feature == "cluster_container_cli_v1",
+        is_manager_backend=lambda: True,
         list_containers=lambda **_kwargs: {
             "containers": [
                 {
@@ -185,7 +192,7 @@ def test_managed_docker_ps_drops_pinned_digest_like_docker(monkeypatch, capsys,
 def test_managed_docker_ps_forwards_global_latest_and_limit(monkeypatch):
     calls = []
     client = SimpleNamespace(
-        supports=lambda feature: feature == "cluster_container_cli_v1",
+        is_manager_backend=lambda: True,
         list_containers=lambda **kwargs: calls.append(kwargs)
         or {"containers": [], "node_errors": []},
     )
@@ -200,11 +207,65 @@ def test_managed_docker_ps_forwards_global_latest_and_limit(monkeypatch):
     assert calls[1]["limit"] == 3
 
 
-def test_managed_docker_delegates_format_to_real_docker(monkeypatch):
+def test_exec_process_replaces_the_python_process(monkeypatch):
     calls = []
+    monkeypatch.setattr(os, "name", "posix")
+    monkeypatch.setattr("docker_stack.cli.os.execvp", lambda file, args: calls.append((file, args)))
+
+    _exec_process(["docker", "service", "logs", "-f", "svc"])
+
+    assert calls == [("docker", ["docker", "service", "logs", "-f", "svc"])]
+
+
+def test_exec_process_passes_env_when_given(monkeypatch):
+    calls = []
+    monkeypatch.setattr(os, "name", "posix")
+    monkeypatch.setattr("docker_stack.cli.os.execvpe", lambda file, args, env: calls.append((file, args, env)))
+
+    _exec_process(["/bin/test-shell", "-i"], env={"DOCKER_CONTEXT": "office"})
+
+    assert calls == [("/bin/test-shell", ["/bin/test-shell", "-i"], {"DOCKER_CONTEXT": "office"})]
+
+
+def test_exec_process_reports_missing_binary(monkeypatch, capsys):
+    monkeypatch.setattr(os, "name", "posix")
+
+    def missing(_file, _args):
+        raise FileNotFoundError(2, "No such file or directory")
+
+    monkeypatch.setattr("docker_stack.cli.os.execvp", missing)
+
+    assert _exec_process(["docker", "ps"]) == 127
+    assert "cannot execute docker" in capsys.readouterr().err
+
+
+def test_exec_process_falls_back_to_subprocess_off_posix(monkeypatch):
+    calls = []
+    monkeypatch.setattr(os, "name", "nt")
+    monkeypatch.setattr("docker_stack.cli.os.execvp", lambda *_args: pytest.fail("exec must not run off POSIX"))
     monkeypatch.setattr(
         "docker_stack.cli.subprocess.run",
-        lambda command, **_kwargs: calls.append(command) or SimpleNamespace(returncode=7),
+        lambda command, **_kwargs: calls.append(command) or SimpleNamespace(returncode=3),
+    )
+
+    assert _exec_process(["docker", "ps"]) == 3
+    assert calls == [["docker", "ps"]]
+
+
+def test_main_reports_interrupt_as_shell_exit_code(monkeypatch):
+    def interrupted(_args):
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr("docker_stack.cli._run", interrupted)
+
+    assert main(["ps"]) == 130
+
+
+def test_managed_docker_delegates_format_to_real_docker(monkeypatch):
+    calls = []
+    monkeypatch.setattr(
+        "docker_stack.cli._exec_process",
+        lambda command, **_kwargs: calls.append(command) or 7,
     )
 
     assert _managed_docker(["ps", "--format", "{{.ID}}"]) == 7
@@ -224,8 +285,8 @@ def test_managed_docker_delegates_format_to_real_docker(monkeypatch):
 def test_managed_docker_delegates_explicit_target_overrides(monkeypatch, arguments):
     calls = []
     monkeypatch.setattr(
-        "docker_stack.cli.subprocess.run",
-        lambda command, **_kwargs: calls.append(command) or SimpleNamespace(returncode=6),
+        "docker_stack.cli._exec_process",
+        lambda command, **_kwargs: calls.append(command) or 6,
     )
     monkeypatch.setattr(
         "docker_stack.cli.discover_manager_client",
@@ -236,13 +297,13 @@ def test_managed_docker_delegates_explicit_target_overrides(monkeypatch, argumen
     assert calls == [["docker", *arguments]]
 
 
-def test_managed_docker_ps_delegates_when_manager_lacks_cluster_feature(monkeypatch):
+def test_managed_docker_ps_delegates_when_target_is_not_a_manager(monkeypatch):
     calls = []
-    client = SimpleNamespace(supports=lambda _feature: False)
+    client = SimpleNamespace(is_manager_backend=lambda: False)
     monkeypatch.setattr("docker_stack.cli.discover_manager_client", lambda: client)
     monkeypatch.setattr(
-        "docker_stack.cli.subprocess.run",
-        lambda command, **_kwargs: calls.append(command) or SimpleNamespace(returncode=9),
+        "docker_stack.cli._exec_process",
+        lambda command, **_kwargs: calls.append(command) or 9,
     )
 
     assert _managed_docker(["ps"]) == 9
@@ -1477,18 +1538,16 @@ def test_open_context_shell_clears_endpoint_overrides(monkeypatch, tmp_path):
         monkeypatch.setenv(key, f"parent-{key}")
     monkeypatch.setenv("SHELL", "/bin/test-shell")
 
-    def fake_run(cmd, check, env):
+    def fake_exec(cmd, env=None):
         captured["cmd"] = cmd
-        captured["check"] = check
         captured["env"] = env
-        return SimpleNamespace(returncode=0)
+        return 0
 
-    monkeypatch.setattr("docker_stack.cli.subprocess.run", fake_run)
+    monkeypatch.setattr("docker_stack.cli._exec_process", fake_exec)
 
     assert open_context_shell(tmp_path, "office") == 0
 
     assert captured["cmd"] == ["/bin/test-shell", "-i"]
-    assert captured["check"] is False
     assert captured["env"]["DOCKER_CONFIG"] == str(tmp_path)
     assert captured["env"]["DOCKER_CONTEXT"] == "office"
     for key in DOCKER_SHELL_ENDPOINT_ENV_VARS:
@@ -1573,3 +1632,23 @@ def test_context_use_preserves_auth_when_switching_to_manager(monkeypatch, capsy
     output = capsys.readouterr().out
     assert "DOCKER_CONTEXT=office" in output
     assert "auth header preserved" in output
+
+
+def test_stack_not_found_error_does_not_suggest_ci_setup():
+    formatted = _format_runtime_error(
+        RuntimeError(
+            "Manager request failed (GET /api/docker-stack/stacks/docker-manager/versions?namespace=infra): "
+            'HTTP 404: {"message":"stack not found","incident_id":"d9d372ed","trace_id":"d9d372ed"}'
+        )
+    )
+
+    assert "HTTP 404: stack not found (incident d9d372ed)" in formatted
+    assert '{"message"' not in formatted
+    assert "has no stack by that name in that namespace" in formatted
+    assert "setup action" not in formatted
+
+
+def test_version_probe_failure_still_suggests_manager_url_check():
+    formatted = _format_runtime_error(RuntimeError("Manager request failed (GET /version): connection refused"))
+
+    assert "DOCKER_MANAGER_URL points at a reachable manager" in formatted