docker-stack 2.2.4__py3-none-any.whl → 2.3.0__py3-none-any.whl

docker_stack/cli.py

@@ -36,12 +36,16 @@ from docker_stack.shell_auth import (
     run_managed_shell,
     shell_session_active,
 )
+from docker_stack.conflict_prompt import ForceDeployPrompt
 from docker_stack.manager_api import (
-    FEATURE_CLUSTER_CONTAINER_CLI,
+    DEPLOY_WAIT_ENV,
     FEATURE_STACK_DEPLOY,
     FEATURE_STACK_QUERY,
     ManagerApiClient,
+    describe_active_deployment,
+    describe_run,
     discover_manager_client,
+    format_deploy_error_body,
 )
 from docker_stack.registry import DockerRegistry
 from .envsubst import LineCheckResult, SubstitutionError, envsubst, envsubst_load_file
@@ -102,15 +106,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 +145,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 +354,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):
@@ -413,7 +435,7 @@ def _managed_docker(arguments: List[str]) -> int:
         return _exec_docker(values)
     try:
         client = discover_manager_client()
-        if client is None or not client.supports(FEATURE_CLUSTER_CONTAINER_CLI):
+        if client is None or not client.is_manager_backend():
             return _exec_docker(values)
         filters = []
         all_containers = False
@@ -1483,6 +1505,7 @@ class DockerStack:
                 options=options,
             )
         else:
+            prompt = ForceDeployPrompt.create()
             try:
                 payload = manager_client.deploy_stack_stream(
                     stack=stack_name,
@@ -1490,6 +1513,7 @@ class DockerStack:
                     compose=rendered_content,
                     options=options,
                     on_event=DockerStack._print_manager_deploy_event,
+                    wait_for_poll=prompt.wait if prompt else None,
                 )
             except RuntimeError as exc:
                 message = str(exc)
@@ -1554,6 +1578,51 @@ class DockerStack:
             message = data.get("message") or data.get("error") or ""
             if message:
                 print(f"[manager] {service}: {status}: {message}", flush=True)
+        elif event_name == "deployment":
+            deployment_id = data.get("deployment_id")
+            if deployment_id:
+                mode = data.get("mode") or "deployment"
+                print(f"[manager] {mode} {deployment_id}", flush=True)
+        elif event_name == "waiting":
+            DockerStack._print_manager_wait(data)
+
+    @staticmethod
+    def _print_manager_wait(active: Dict[str, object]) -> None:
+        """Narrate the wait for another run of this stack, and any attempt to force past it.
+
+        The manager will not queue an interactive deploy for us, so the CLI polls
+        and reports each phase: waiting, forcing (asking the manager to abort the
+        holder), and how that abort ended.
+        """
+        if not isinstance(active, dict):
+            active = {}
+        phase = str(active.get("phase") or "waiting")
+        run = describe_run(active)
+        if phase == "waiting":
+            budget = active.get("wait_budget_secs")
+            suffix = f" (waiting up to {budget}s, set {DEPLOY_WAIT_ENV} to change)" if isinstance(budget, int) else ""
+            message = f"waiting: {describe_active_deployment(active)}{suffix}"
+        elif phase == "forcing":
+            message = f"forcing: asking the manager to abort {run}"
+        elif phase == "aborted":
+            message = f"aborted {run}; deploying now"
+        elif phase == "aborted_other":
+            message = f"aborted a different run than shown: {run}; deploying now"
+        elif phase == "free":
+            message = "the stack is free; deploying now"
+        elif phase == "not_released":
+            message = f"asked the manager to abort {run}, but it has not released the stack yet; waiting for it to finish"
+        elif phase == "forbidden":
+            message = f"you do not have permission to abort {run}; still waiting"
+        elif phase == "still_held":
+            message = f"the stack is still held by {run}; waiting"
+        elif phase == "force_used":
+            message = "force was already used once in this run; waiting for the stack to free up"
+        elif phase == "interrupted":
+            message = "interrupted while asking the manager to abort; that request may still complete"
+        else:
+            message = f"{phase}: {run}"
+        print(f"[manager] {message}", file=sys.stderr, flush=True)
 
     @staticmethod
     def _rollback_via_manager(
@@ -1563,10 +1632,13 @@ class DockerStack:
         namespace: str,
         version: str,
     ) -> Optional[str]:
+        prompt = ForceDeployPrompt.create()
         payload = manager_client.rollback_stack(
             stack=stack_name,
             namespace=namespace,
             version=version,
+            on_wait=DockerStack._print_manager_wait,
+            wait_for_poll=prompt.wait if prompt else None,
         )
         warnings = payload.get("warnings") or []
         for warning in warnings:
@@ -1851,7 +1923,7 @@ def _humanize_manager_error(message: str) -> str:
         return message
     if not isinstance(body, dict):
         return message
-    detail = str(body.get("message", "")).strip()
+    detail = format_deploy_error_body(body) if body.get("code") else str(body.get("message", "")).strip()
     if not detail:
         return message
     incident = str(body.get("incident_id") or body.get("trace_id") or "").strip()
@@ -1879,6 +1951,17 @@ 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 "is still running" in lowered and ("gave up after waiting" in lowered or "http 409" in lowered):
+        return (
+            "Suggestion: another run holds this stack's deploy lock. Rerun and let it wait, raise "
+            f"{DEPLOY_WAIT_ENV} to queue longer, press Enter twice while waiting at a terminal to abort that run "
+            "and force your deploy, or abort it from the Docker-Manager stack page."
+        )
+    if "failed services:" in lowered:
+        return (
+            "Suggestion: every service operation has finished; the failed ones are listed above with their incident ids. "
+            "Fix the cause and redeploy, or use the rollback offered on the Docker-Manager stack page to restore the previous specs."
+        )
     if "stack not found" in lowered:
         return (
             "Suggestion: the manager was reached but has no stack by that name in that namespace. "
@@ -1901,9 +1984,10 @@ def _manager_deploy_suggestion(message: str) -> Optional[str]:
 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(_humanize_manager_error(output))
-    suggestion = _manager_deploy_suggestion(output)
+    humanized = _humanize_manager_error(output) if output else ""
+    if humanized:
+        lines.append(humanized)
+    suggestion = _manager_deploy_suggestion(humanized or output)
     if suggestion:
         lines.extend(["", suggestion])
     return "\n".join(lines)
@@ -1911,8 +1995,9 @@ 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: {_humanize_manager_error(message)}"]
-    suggestion = _manager_deploy_suggestion(message)
+    humanized = _humanize_manager_error(message)
+    lines = [f"docker-stack: {humanized}"]
+    suggestion = _manager_deploy_suggestion(humanized)
     if suggestion:
         lines.extend(["", suggestion])
     return "\n".join(lines)

docker_stack/conflict_prompt.py

@@ -0,0 +1,134 @@
+"""Terminal prompt shown while a deploy waits for another run of the same stack.
+
+Docker-Manager refuses to queue interactive applies: it answers ``409
+deployment_in_progress`` and leaves the choice between waiting and aborting to
+whoever is on the other end. On a CLI that is the person at the terminal, so
+while the client polls for the stack to free up this prompt listens for two
+Enter presses in quick succession and reports ``"force"``; the caller then asks
+the manager to abort the running deployment. Ctrl+C is left alone and keeps
+exiting the CLI.
+
+Enter is line-oriented, so no terminal mode is changed and there is nothing to
+restore on the way out. The prompt is only created when both stdin and stderr
+are terminals and the process is in the foreground; anywhere else (CI, pipes,
+the GitHub Action's heredoc) the caller simply sleeps between polls.
+"""
+
+import io
+import os
+import select
+import sys
+import time
+from typing import Any, Optional
+
+DOUBLE_ENTER_SECS = 3.0
+WINDOWS_POLL_SECS = 0.1
+HINT = "[manager] press Enter twice to force your deploy (aborts that run; changes it already made to the daemon stay), Ctrl+C to quit"
+SECOND_ENTER_HINT = f"[manager] press Enter again within {int(DOUBLE_ENTER_SECS)}s to force the deploy"
+
+ENTER = "enter"
+OTHER = "other"
+TIMEOUT = "timeout"
+EOF = "eof"
+
+
+class _PosixEnterReader:
+    def __init__(self, stdin, fd: int):
+        self._stdin = stdin
+        self._fd = fd
+
+    def wait_for_enter(self, timeout: float) -> str:
+        try:
+            readable, _, _ = select.select([self._fd], [], [], max(0.0, timeout))
+        except (OSError, ValueError):
+            return EOF
+        if not readable:
+            return TIMEOUT
+        line = self._stdin.readline()
+        if line == "":
+            return EOF
+        return ENTER if line.strip() == "" else OTHER
+
+
+class _WindowsEnterReader:
+    def __init__(self, msvcrt_module):
+        self._msvcrt = msvcrt_module
+
+    def wait_for_enter(self, timeout: float) -> str:
+        deadline = time.monotonic() + max(0.0, timeout)
+        while True:
+            if self._msvcrt.kbhit():
+                char = self._msvcrt.getwch()
+                return ENTER if char in ("\r", "\n") else OTHER
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return TIMEOUT
+            time.sleep(min(WINDOWS_POLL_SECS, remaining))
+
+
+class ForceDeployPrompt:
+    """Listens for a double Enter between polls; see the module docstring."""
+
+    def __init__(self, stderr, reader):
+        self._stderr = stderr
+        self._reader = reader
+        self._hinted = False
+        self._dead = False
+        self._first_enter_at: Optional[float] = None
+
+    @classmethod
+    def create(cls) -> Optional["ForceDeployPrompt"]:
+        """Build a prompt when a person can see and answer it, else ``None``."""
+        stdin, stderr = sys.stdin, sys.stderr
+        if stdin is None or stderr is None:
+            return None
+        try:
+            if not stdin.isatty() or not stderr.isatty():
+                return None
+            fd = stdin.fileno()
+        except (AttributeError, ValueError, OSError, io.UnsupportedOperation):
+            return None
+        if os.name == "nt":
+            try:
+                import msvcrt  # type: ignore[import-not-found]
+            except ImportError:
+                return None
+            return cls(stderr, _WindowsEnterReader(msvcrt))
+        try:
+            # Reading a terminal from a background job stops the process (SIGTTIN).
+            if os.tcgetpgrp(fd) != os.getpgrp():
+                return None
+        except (AttributeError, OSError):
+            return None
+        return cls(stderr, _PosixEnterReader(stdin, fd))
+
+    def _say(self, message: str) -> None:
+        print(message, file=self._stderr, flush=True)
+
+    def wait(self, active: Any, seconds: float) -> Optional[str]:
+        """Wait up to ``seconds`` for the next poll; ``"force"`` if Enter was pressed twice."""
+        deadline = time.monotonic() + max(0.0, seconds)
+        if not self._hinted:
+            self._say(HINT)
+            self._hinted = True
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            if self._dead:
+                time.sleep(remaining)
+                return None
+            result = self._reader.wait_for_enter(remaining)
+            if result == TIMEOUT:
+                return None
+            if result == EOF:
+                self._dead = True
+                continue
+            if result != ENTER:
+                continue
+            now = time.monotonic()
+            if self._first_enter_at is not None and now - self._first_enter_at <= DOUBLE_ENTER_SECS:
+                self._first_enter_at = None
+                return "force"
+            self._first_enter_at = now
+            self._say(SECOND_ENTER_HINT)

docker_stack/manager_api.py

@@ -4,6 +4,8 @@ import shutil
 import socket
 import ssl
 import subprocess
+import sys
+import time
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -215,6 +217,208 @@ def _manager_deploy_timeout_secs(default: int) -> int:
     )
 
 
+# How long a deploy/rollback waits for another run of the same stack to finish
+# before giving up. ``0`` fails immediately. Defaults to the deploy timeout.
+DEPLOY_WAIT_ENV = "DOCKER_MANAGER_DEPLOY_WAIT_SECS"
+DEPLOY_WAIT_POLL_SECS = 5
+DEPLOY_WAIT_NOTICE_SECS = 30
+# The manager's abort handler itself waits up to 30s for the holder to let go
+# of the stack, so the client must give it comfortably more than that.
+ABORT_REQUEST_TIMEOUT_SECS = 45
+
+
+def _manager_deploy_wait_secs(default: int) -> int:
+    raw = os.getenv(DEPLOY_WAIT_ENV, "").strip()
+    if not raw:
+        return _manager_deploy_timeout_secs(default)
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return _manager_deploy_timeout_secs(default)
+
+
+class ManagerDeploymentInProgressError(RuntimeError):
+    """The manager refused an apply because another run holds this stack's deploy guard.
+
+    Docker-Manager answers interactive apply paths (``deploy/stream``, version
+    rollback) with ``409 deployment_in_progress`` instead of queueing. The
+    ``active_deployment`` payload names the run: ``operation``, ``actor``,
+    ``deployment_id``, ``started_at_ms``.
+    """
+
+    def __init__(self, message: str, *, active_deployment: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.active_deployment = active_deployment if isinstance(active_deployment, dict) else {}
+
+
+class ManagerAbortForbiddenError(RuntimeError):
+    """The caller may deploy this stack but lacks the permission to abort another run of it."""
+
+
+class ManagerNoActiveDeploymentError(RuntimeError):
+    """An abort found nothing running: the holder finished on its own."""
+
+
+class ManagerDeployFailedError(RuntimeError):
+    """A manager deploy stream ended with an ``error`` event.
+
+    ``services`` carries the per-service outcome when the manager reports a
+    partial failure (``code`` = ``deployment_partial_failure``); every parallel
+    service operation has completed by then, so this is the full picture.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        deployment_id: Optional[str] = None,
+        rollback_available: bool = False,
+        services: Optional[list] = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.deployment_id = deployment_id
+        self.rollback_available = rollback_available
+        self.services = services or []
+
+
+def describe_run(active: Any) -> str:
+    """Name a deploy run: who started what, when, and its deployment id if known."""
+    if not isinstance(active, dict):
+        return "another deployment of this stack"
+    operation = str(active.get("operation") or "deployment").strip() or "deployment"
+    actor = str(active.get("actor") or "").strip() or "another caller"
+    parts = [f"a {operation} started by {actor}"]
+    started_at_ms = active.get("started_at_ms")
+    if isinstance(started_at_ms, (int, float)) and started_at_ms > 0:
+        elapsed = max(0, int(time.time() - started_at_ms / 1000))
+        parts.append(f"{elapsed}s ago")
+    deployment_id = str(active.get("deployment_id") or "").strip()
+    if deployment_id:
+        parts.append(f"(deployment {deployment_id})")
+    return " ".join(parts)
+
+
+def describe_active_deployment(active: Any) -> str:
+    """One line naming the run that holds a stack: who, what, since when."""
+    return describe_run(active) + " is still running"
+
+
+def same_deploy_run(shown: Any, aborted: Any) -> bool:
+    """Whether the run the manager aborted is the one the user was looking at.
+
+    ``deployment_id`` is authoritative when both sides have one; it is ``null``
+    for a run that has not persisted its row yet and for non-stream deploys, so
+    fall back to who started what and when.
+    """
+    if not isinstance(shown, dict) or not isinstance(aborted, dict):
+        return True
+    shown_id = str(shown.get("deployment_id") or "").strip()
+    aborted_id = str(aborted.get("deployment_id") or "").strip()
+    if shown_id and aborted_id:
+        return shown_id == aborted_id
+    keys = ("operation", "actor", "started_at_ms")
+    return all(shown.get(key) == aborted.get(key) for key in keys)
+
+
+def format_failed_services(services: Any) -> list:
+    """Render the manager's per-service results as one line per failed service."""
+    lines = []
+    if not isinstance(services, list):
+        return lines
+    for item in services:
+        if not isinstance(item, dict):
+            continue
+        if str(item.get("status") or "").strip() not in {"failed", "error"}:
+            continue
+        service = str(item.get("service") or item.get("logical_name") or "service").strip()
+        action = str(item.get("action") or "").strip()
+        label = f"{service} ({action})" if action else service
+        error = str(item.get("error") or "").strip() or "failed without an error message"
+        incident = str(item.get("incident_id") or "").strip()
+        suffix = f" (incident {incident})" if incident else ""
+        lines.append(f"  - {label}: {error}{suffix}")
+    return lines
+
+
+def format_deploy_error_body(body: Dict[str, Any]) -> str:
+    """Expand a manager deploy error body into prose, keeping every reported cause."""
+    message = str(body.get("message") or "").strip()
+    code = str(body.get("code") or "").strip()
+    if code == "deployment_in_progress":
+        return describe_active_deployment(body.get("active_deployment")) if body.get("active_deployment") else message
+    lines = [message] if message else []
+    failed = format_failed_services(body.get("services"))
+    if failed:
+        lines.append("failed services:")
+        lines.extend(failed)
+    deployment_id = str(body.get("deployment_id") or "").strip()
+    if body.get("rollback_available") and deployment_id:
+        lines.append(f"rollback is available from the Docker-Manager stack page (deployment {deployment_id})")
+    elif deployment_id:
+        lines.append(f"deployment {deployment_id}")
+    return "\n".join(lines)
+
+
+def _wait_notifier(on_event):
+    """Surface deploy-guard waits through the same event callback as the stream."""
+    if on_event is None:
+        return None
+    return lambda active: on_event({"event": "waiting", "data": active})
+
+
+ABORT_DEPLOYMENT_PATH = "/api/stacks/deploy/abort"
+
+
+def _decode_http_error_body(exc: urllib.error.HTTPError) -> str:
+    try:
+        return exc.read().decode("utf-8", errors="replace").strip()
+    except Exception:
+        return ""
+
+
+def _manager_http_error(method: str, path: str, exc: urllib.error.HTTPError) -> RuntimeError:
+    """Map an HTTP failure to the most specific error the caller can act on."""
+    payload = _decode_http_error_body(exc)
+    body: Any = None
+    if payload:
+        try:
+            body = json.loads(payload)
+        except json.JSONDecodeError:
+            body = None
+    if exc.code == 409 and isinstance(body, dict) and body.get("code") == "deployment_in_progress":
+        active = body.get("active_deployment")
+        return ManagerDeploymentInProgressError(
+            f"Manager request failed ({method} {path}): HTTP 409: {describe_active_deployment(active)}",
+            active_deployment=active if isinstance(active, dict) else {},
+        )
+    if exc.code == 404 and isinstance(body, dict) and body.get("code") == "no_active_deployment":
+        return ManagerNoActiveDeploymentError(f"Manager request failed ({method} {path}): HTTP 404: no deployment is running")
+    if exc.code == 403 and path == ABORT_DEPLOYMENT_PATH:
+        detail = str(body.get("message") or "").strip() if isinstance(body, dict) else ""
+        return ManagerAbortForbiddenError(
+            f"Manager request failed ({method} {path}): HTTP 403: {detail or 'stack deploy permission required'}"
+        )
+    suffix = f": {payload}" if payload else ""
+    return RuntimeError(f"Manager request failed ({method} {path}): HTTP {exc.code}{suffix}")
+
+
+def _stream_error(data: Any, default: str) -> ManagerDeployFailedError:
+    if not isinstance(data, dict):
+        message = str(data).strip() if data is not None else ""
+        return ManagerDeployFailedError(message or default)
+    message = format_deploy_error_body(data) or default
+    services = data.get("services")
+    return ManagerDeployFailedError(
+        message,
+        code=str(data.get("code") or "").strip() or None,
+        deployment_id=str(data.get("deployment_id") or "").strip() or None,
+        rollback_available=bool(data.get("rollback_available")),
+        services=services if isinstance(services, list) else [],
+    )
+
+
 def _manager_target_from_env() -> Optional[str]:
     manager_url = os.getenv("DOCKER_MANAGER_URL", "").strip()
     if manager_url:
@@ -293,14 +497,7 @@ class ManagerApiClient:
             with urllib.request.urlopen(request, timeout=timeout, context=context) as response:
                 return json.loads(response.read().decode("utf-8"))
         except urllib.error.HTTPError as exc:
-            body = ""
-            try:
-                payload = exc.read().decode("utf-8", errors="replace").strip()
-                if payload:
-                    body = f": {payload}"
-            except Exception:
-                body = ""
-            raise RuntimeError(f"Manager request failed ({method} {path}): HTTP {exc.code}{body}") from exc
+            raise _manager_http_error(method, path, exc) from exc
         except urllib.error.URLError as exc:
             raise RuntimeError(f"Manager request failed ({method} {path}): {exc.reason}") from exc
         except (TimeoutError, socket.timeout) as exc:
@@ -361,14 +558,7 @@ class ManagerApiClient:
                         event_data = {"raw": raw_data}
                     yield {"event": event_name, "data": event_data}
         except urllib.error.HTTPError as exc:
-            body = ""
-            try:
-                payload = exc.read().decode("utf-8", errors="replace").strip()
-                if payload:
-                    body = f": {payload}"
-            except Exception:
-                body = ""
-            raise RuntimeError(f"Manager request failed ({method} {path}): HTTP {exc.code}{body}") from exc
+            raise _manager_http_error(method, path, exc) from exc
         except urllib.error.URLError as exc:
             raise RuntimeError(f"Manager request failed ({method} {path}): {exc.reason}") from exc
         except (TimeoutError, socket.timeout) as exc:
@@ -416,6 +606,144 @@ 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 abort_active_deployment(self, *, stack: str, namespace: str) -> Optional[Dict[str, Any]]:
+        """Ask the manager to abort whatever holds this stack's deploy guard.
+
+        Returns the manager's ``{"aborted": <run>, "released": bool}`` payload, or
+        ``None`` when nothing was running any more. The manager waits up to 30s
+        for the holder to release before answering, hence the long timeout.
+        """
+        try:
+            payload = self._request_json(
+                ABORT_DEPLOYMENT_PATH,
+                method="POST",
+                payload={"namespace": namespace, "stack": stack},
+                timeout_secs=max(ABORT_REQUEST_TIMEOUT_SECS, int(self.timeout_secs or 0)),
+            )
+        except ManagerNoActiveDeploymentError:
+            return None
+        if not isinstance(payload, dict):
+            raise RuntimeError("Docker-Manager abort response is invalid")
+        return payload
+
+    def _force_takeover(self, *, stack: str, namespace: str, shown: Dict[str, Any], notify) -> str:
+        """Abort the run holding the stack so ours can go. Returns ``"retry"`` or ``"wait"``.
+
+        A daemon request the aborted run already made still completes; abort stops
+        its orchestration, and our deploy then applies over whatever state that left.
+        """
+        notify("forcing", shown)
+        try:
+            outcome = self.abort_active_deployment(stack=stack, namespace=namespace)
+        except ManagerAbortForbiddenError:
+            notify("forbidden", shown)
+            return "wait"
+        except ManagerDeploymentInProgressError as exc:
+            notify("still_held", exc.active_deployment or shown)
+            return "wait"
+        except KeyboardInterrupt:
+            notify("interrupted", shown)
+            raise
+        if outcome is None:
+            notify("free", shown)
+            return "retry"
+        aborted = outcome.get("aborted")
+        aborted = aborted if isinstance(aborted, dict) else shown
+        if not outcome.get("released"):
+            notify("not_released", aborted)
+            return "wait"
+        notify("aborted" if same_deploy_run(shown, aborted) else "aborted_other", aborted)
+        return "retry"
+
+    def _run_when_stack_is_free(
+        self,
+        operation,
+        *,
+        stack: Optional[str] = None,
+        namespace: Optional[str] = None,
+        on_wait=None,
+        wait_for_poll=None,
+    ):
+        """Run ``operation``, waiting out another deploy of the same stack.
+
+        The manager's interactive apply paths answer ``409 deployment_in_progress``
+        rather than queueing, because a person in the UI can choose to wait or
+        abort. Nobody is there to choose on a CLI or CI run, so queue here: retry
+        until the guard frees or ``DOCKER_MANAGER_DEPLOY_WAIT_SECS`` runs out,
+        and tell the caller what is being waited on. A budget of ``0`` fails
+        on the first collision.
+
+        ``wait_for_poll(active, seconds)`` replaces the sleep between polls for a
+        caller that can listen to a person; returning ``"force"`` aborts the
+        running deployment (once per run) so this one can take the stack.
+        ``on_wait`` receives the active run plus a ``phase`` for every notice.
+        """
+        budget = _manager_deploy_wait_secs(self.timeout_secs)
+        started = time.monotonic()
+        last_notice: Optional[float] = None
+        force_used = False
+        force_used_notified = False
+        skip_budget_check = False
+
+        def notify(phase: str, active: Any) -> None:
+            if on_wait:
+                base = active if isinstance(active, dict) else {}
+                on_wait({**base, "phase": phase})
+
+        while True:
+            try:
+                return operation()
+            except ManagerDeploymentInProgressError as exc:
+                waited = int(time.monotonic() - started)
+                if skip_budget_check:
+                    skip_budget_check = False
+                elif waited + DEPLOY_WAIT_POLL_SECS > budget:
+                    if budget > 0:
+                        raise ManagerDeploymentInProgressError(
+                            f"{exc}; gave up after waiting {waited}s "
+                            f"(raise {DEPLOY_WAIT_ENV} to wait longer, or abort it from the Docker-Manager stack page)",
+                            active_deployment=exc.active_deployment,
+                        ) from exc
+                    raise
+                now = time.monotonic()
+                if on_wait and (last_notice is None or now - last_notice >= DEPLOY_WAIT_NOTICE_SECS):
+                    on_wait(
+                        {**exc.active_deployment, "phase": "waiting", "waited_secs": waited, "wait_budget_secs": budget}
+                    )
+                    last_notice = now
+                if wait_for_poll is None:
+                    time.sleep(DEPLOY_WAIT_POLL_SECS)
+                    continue
+                decision = wait_for_poll(exc.active_deployment, DEPLOY_WAIT_POLL_SECS)
+                if decision != "force":
+                    continue
+                if force_used:
+                    if not force_used_notified:
+                        notify("force_used", exc.active_deployment)
+                        force_used_notified = True
+                    continue
+                force_used = True
+                if stack is None or namespace is None:
+                    raise RuntimeError("cannot force a deploy without knowing its stack and namespace")
+                if self._force_takeover(stack=stack, namespace=namespace, shown=exc.active_deployment, notify=notify) == "retry":
+                    skip_budget_check = True
+
+    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 {
@@ -633,6 +961,7 @@ class ManagerApiClient:
         images: Dict[str, str],
         options: Optional[Dict[str, Any]] = None,
         on_event=None,
+        wait_for_poll=None,
     ) -> Dict[str, Any]:
         payload: Dict[str, Any] = {
             "stack": stack,
@@ -643,23 +972,18 @@ class ManagerApiClient:
         if prepared_options:
             payload["options"] = prepared_options
 
-        done: Optional[Dict[str, Any]] = None
-        for event in self._request_sse_events(
-            "/api/stacks/deploy/images",
-            method="POST",
-            payload=payload,
-            timeout_secs=_manager_deploy_timeout_secs(self.timeout_secs),
-        ):
-            if on_event:
-                on_event(event)
-            event_name = event.get("event")
-            data = event.get("data")
-            if event_name == "error":
-                message = data.get("message") if isinstance(data, dict) else str(data)
-                raise RuntimeError(message or "manager image deploy stream failed")
-            if event_name == "done" and isinstance(data, dict):
-                done = data
-        return done or {"warnings": [], "stdout": "", "stderr": ""}
+        return self._run_when_stack_is_free(
+            lambda: self._consume_deploy_stream(
+                "/api/stacks/deploy/images",
+                payload,
+                on_event=on_event,
+                default_error="manager image deploy stream failed",
+            ),
+            stack=stack,
+            namespace=namespace,
+            on_wait=_wait_notifier(on_event),
+            wait_for_poll=wait_for_poll,
+        )
 
     def deploy_stack_stream(
         self,
@@ -669,15 +993,37 @@ class ManagerApiClient:
         compose: str,
         options: Optional[Dict[str, Any]] = None,
         on_event=None,
+        wait_for_poll=None,
     ) -> Dict[str, Any]:
         payload: Dict[str, Any] = {"stack": stack, "namespace": namespace, "compose": compose}
         prepared_options = _public_deploy_options(options, compose)
         if prepared_options:
             payload["options"] = prepared_options
 
+        return self._run_when_stack_is_free(
+            lambda: self._consume_deploy_stream(
+                "/api/stacks/deploy/stream",
+                payload,
+                on_event=on_event,
+                default_error="manager deploy stream failed",
+            ),
+            stack=stack,
+            namespace=namespace,
+            on_wait=_wait_notifier(on_event),
+            wait_for_poll=wait_for_poll,
+        )
+
+    def _consume_deploy_stream(
+        self,
+        path: str,
+        payload: Dict[str, Any],
+        *,
+        on_event,
+        default_error: str,
+    ) -> Dict[str, Any]:
         done: Optional[Dict[str, Any]] = None
         for event in self._request_sse_events(
-            "/api/stacks/deploy/stream",
+            path,
             method="POST",
             payload=payload,
             timeout_secs=_manager_deploy_timeout_secs(self.timeout_secs),
@@ -687,19 +1033,32 @@ class ManagerApiClient:
             event_name = event.get("event")
             data = event.get("data")
             if event_name == "error":
-                message = data.get("message") if isinstance(data, dict) else str(data)
-                raise RuntimeError(message or "manager deploy stream failed")
+                raise _stream_error(data, default_error)
             if event_name == "done" and isinstance(data, dict):
                 done = data
         return done or {"warnings": [], "stdout": "", "stderr": ""}
 
-    def rollback_stack(self, *, stack: str, namespace: str, version: str) -> Dict[str, Any]:
+    def rollback_stack(
+        self,
+        *,
+        stack: str,
+        namespace: str,
+        version: str,
+        on_wait=None,
+        wait_for_poll=None,
+    ) -> Dict[str, Any]:
         quoted_stack = urllib.parse.quote(stack, safe="")
         if self._detect_manager_backend():
-            return self._request_json(
-                f"/api/stacks/{quoted_stack}/rollback",
-                method="POST",
-                payload={"namespace": namespace, "version": version},
+            return self._run_when_stack_is_free(
+                lambda: self._request_json(
+                    f"/api/stacks/{quoted_stack}/rollback",
+                    method="POST",
+                    payload={"namespace": namespace, "version": version},
+                ),
+                stack=stack,
+                namespace=namespace,
+                on_wait=on_wait,
+                wait_for_poll=wait_for_poll,
             )
         return self._request_json(
             self._endpoint_path(f"/inventory/stacks/{quoted_stack}/rollback"),
@@ -721,7 +1080,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 +1096,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.4.dist-info → docker_stack-2.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.2.4
+Version: 2.3.0
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai
@@ -213,6 +213,18 @@ are sent unchanged to the Docker CLI.
 -   **Docker Stack Versioning and Config Backup for Rollback:**
     The utility automatically versions your Docker configs and secrets, allowing for easy tracking of changes and seamless rollbacks to previous states. This provides a safety net for your deployments, ensuring you can always revert to a stable configuration.
 
+-   **Waiting for another deploy of the same stack (Docker-Manager):**
+    Docker-Manager runs one apply per stack at a time. When `docker-stack deploy` or `docker-stack checkout` finds another run in progress (a UI deploy, a CI image bump, another operator), it waits and prints who started it:
+
+    ```
+    [manager] waiting: a deploy started by alice 42s ago is still running (waiting up to 300s, set DOCKER_MANAGER_DEPLOY_WAIT_SECS to change)
+    [manager] press Enter twice to force your deploy (aborts that run; changes it already made to the daemon stay), Ctrl+C to quit
+    ```
+
+    - It retries every 5 seconds until the stack is free or `DOCKER_MANAGER_DEPLOY_WAIT_SECS` runs out (default: the deploy timeout; `0` fails immediately). CI runs wait the same way, without the prompt.
+    - At a terminal, pressing Enter twice within 3 seconds asks the manager to abort the running deployment and deploys as soon as the stack is released. This needs stack deploy permission and is offered once per run. The aborted run stops orchestrating, but daemon requests it already made still complete; your deploy then applies over that state.
+    - Ctrl+C exits without touching the other run.
+
 ## Why Use It?
 
 Vanilla Docker Stack deployments can sometimes lack the flexibility needed for dynamic environments or robust secret management. This utility bridges those gaps by:

{docker_stack-2.2.4.dist-info → docker_stack-2.3.0.dist-info}/RECORD

@@ -1,20 +1,21 @@
 docker_stack/__init__.py,sha256=qgHdW8ZDBlyk6FzIf8Mld_cJD1SjOfqo2dELg4pK668,880
-docker_stack/cli.py,sha256=_IWypxyKZ4reUaB4qb7WpRt24WtUVWLlmrr3ALY8riM,96017
+docker_stack/cli.py,sha256=rEIjauHe9Cz0k-2j6guaeThQR2aaVrFeEW16qG1y8QI,100468
 docker_stack/command_runner.py,sha256=mNaUAVKtrJbji_5ARVPLKhc92avqllNKrVQj1A6S0dA,1252
 docker_stack/compose.py,sha256=_fAVesjyW5ecid46sYYhcu02yF1vqknDSCFYflJPDOE,534
+docker_stack/conflict_prompt.py,sha256=1pmsyJZyZbzKYAtLJ8kYNVSC0LJb6fsu8Qz2zWvyqBE,4911
 docker_stack/docker_objects.py,sha256=U6szytv5gKrmBYKqThSeMMXdiJ2u4STIQLkeqQ-Fn4Q,12103
 docker_stack/envsubst.py,sha256=gdEUpsjWJeNbbahySk56vUdQh1nns85o3LbU6SUBo3I,8337
 docker_stack/envsubst_merge.py,sha256=TwOu8BducG0rWnSreJGwesNi-VghCetljcf-aWceE8M,4971
 docker_stack/helpers.py,sha256=nJHaIS1vtFyPYclXVl3-Qd-1h55jnSy1LwdATDrF4hk,5953
 docker_stack/login.py,sha256=jnrmrDh79Brlzj89YdZ1sGpg-ex16yb3ZN47eFpcW5g,41754
-docker_stack/manager_api.py,sha256=xb8RwY4LEn1usg9qhG9AfiCvBJ2tpQawVMLRwF3vYHY,28361
+docker_stack/manager_api.py,sha256=9AnVzsbYDllo1NeQM5vq7zTlQfPXXEYX24vXeuQCj74,44403
 docker_stack/markers.py,sha256=gqStnr0tNWZ1kzqvREc2jVQVQrevheShgJtL5QzSx4g,2388
 docker_stack/merge_conf.py,sha256=Pmsabcgf3SDyaWvf2OLsBPodzEqsvOIjj9xzn_qWXH0,1917
 docker_stack/registry.py,sha256=sWC1J9JDIrcYyhei1POYCZHJ0xUCKC2pveisSHMgYsQ,9036
 docker_stack/shell_auth.py,sha256=UUu9y4wMFKfc_j86yGcasvS_TLZ2uV4kv0T4XKTMQBQ,33424
 docker_stack/url_parser.py,sha256=Sk8GQE0nEiwCkijp1OltP2AfgtKEmM2hybcH_rBhfiI,6824
-docker_stack-2.2.4.dist-info/METADATA,sha256=__Y1aknQuctP1Nuf2zhuinUnlyYDu-qGY54rUma8alM,13821
-docker_stack-2.2.4.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
-docker_stack-2.2.4.dist-info/entry_points.txt,sha256=mpe2RwIguARsosXIUBQEN2pKU53URqZCh2S4ATwDFL4,55
-docker_stack-2.2.4.dist-info/top_level.txt,sha256=zT6TPL54cLrt9LO_MNkhEpGGOmsoe2HV6Na5Ohy3_2c,13
-docker_stack-2.2.4.dist-info/RECORD,,
+docker_stack-2.3.0.dist-info/METADATA,sha256=AOgiK8qI7kxr18yUxvOqEDrbOhpLMR_vRCi9zhuKCcU,15013
+docker_stack-2.3.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+docker_stack-2.3.0.dist-info/entry_points.txt,sha256=mpe2RwIguARsosXIUBQEN2pKU53URqZCh2S4ATwDFL4,55
+docker_stack-2.3.0.dist-info/top_level.txt,sha256=zT6TPL54cLrt9LO_MNkhEpGGOmsoe2HV6Na5Ohy3_2c,13
+docker_stack-2.3.0.dist-info/RECORD,,