docker-stack 2.2.4__tar.gz → 2.3.0__tar.gz

{docker_stack-2.2.4 → docker_stack-2.3.0}/PKG-INFO

@@ -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 → docker_stack-2.3.0}/README.md

@@ -187,6 +187,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 → docker_stack-2.3.0}/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-2.3.0/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)