rostainer-deploy 0.0.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,242 @@
1
+ """What other plugins may use of deploy: its targets, and running things on them.
2
+
3
+ A plugin that works with the robots ``[plugins.deploy]`` lists - fetching
4
+ their logs, say - builds on this rather than its own list of hosts. It
5
+ lists deploy in its ``requires`` (and ``rostainer-deploy`` in its package's
6
+ dependencies), and uses this module; nothing else in ``rostainer_deploy``
7
+ is a promise::
8
+
9
+ from rostainer_deploy import api
10
+
11
+ class Fetch(Command):
12
+ def add_arguments(self, parser):
13
+ api.add_target_arguments(parser) # TARGET_OR_GROUP ..., or all
14
+
15
+ def run(self, args, ctx):
16
+ def fetch(conn: api.Connection) -> int:
17
+ name = conn.package_container()
18
+ ...
19
+ return 0 if conn.copy_from("logs/today.tar", Path("today.tar")) else 1
20
+
21
+ targets = api.targets(ctx, args.targets) # groups, 'enabled', as deploy does
22
+ return api.report(api.for_each(ctx, targets, fetch, title="Fetching"), "Fetching")
23
+
24
+ Targets are reached as deploy reaches them: ssh with the workspace's
25
+ ``ssh_options``, never prompting, connecting with ``connect_attempts``
26
+ retries; several at once (``parallel``), each line of output prefixed
27
+ with the target's name (or, with a ``title``, a board of how each is doing). A target that can't be reached fails alone.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import argparse
33
+ import os
34
+ import shlex
35
+ import subprocess
36
+ from pathlib import Path
37
+ from typing import Callable, List, NamedTuple, Optional, Sequence
38
+
39
+ from rostainer_cli.plugin_api import Context
40
+ from rostainer_deploy import remote
41
+ from rostainer_deploy.remote import Destination, Outcome
42
+
43
+ __all__ = [
44
+ "Connection",
45
+ "DeployTarget",
46
+ "Outcome",
47
+ "Result",
48
+ "add_target_arguments",
49
+ "for_each",
50
+ "report",
51
+ "targets",
52
+ ]
53
+
54
+ #: A target, as :func:`targets` returns it: ``name``, ``host``, ``user``,
55
+ #: ``port`` (``None``: ssh's), and ``install_dir`` (where its package is
56
+ #: installed; relative to the ssh user's home unless absolute).
57
+ DeployTarget = Destination
58
+
59
+
60
+ class Result(NamedTuple):
61
+ """How a command on a target went."""
62
+
63
+ returncode: int
64
+ output: str
65
+ """Its standard output, with ``capture``; else ``""`` (it was shown)."""
66
+
67
+
68
+ def _deploy(ctx: Context) -> Context:
69
+ """Deploy's context, from the calling plugin's (which must require it)."""
70
+ return ctx if ctx.plugin.name == "deploy" else ctx.plugin_context("deploy")
71
+
72
+
73
+ def add_target_arguments(parser: argparse.ArgumentParser, *, required: bool = False) -> None:
74
+ """Add the targets argument deploy's own commands take, as ``targets``:
75
+ target names, group names, or ``all`` (the default, unless ``required``)."""
76
+ from rostainer_deploy import ALL
77
+
78
+ parser.add_argument(
79
+ "targets",
80
+ nargs="+" if required else "*",
81
+ metavar="TARGET_OR_GROUP",
82
+ help=f"Targets, groups, or '{ALL}' (every enabled target)"
83
+ + ("" if required else f"; default: {ALL}"),
84
+ )
85
+
86
+
87
+ def targets(ctx: Context, selectors: Sequence[str] = ()) -> List[DeployTarget]:
88
+ """The targets ``selectors`` pick, as ``rostainer deploy`` picks them:
89
+ by name or group, ``all`` (or none) for every enabled one; in the
90
+ order they're listed in ``[plugins.deploy.targets]``.
91
+
92
+ Args:
93
+ ctx: The calling plugin's context. It must list ``"deploy"`` in its
94
+ ``requires``.
95
+
96
+ Raises:
97
+ ConfigError: If there are no targets, a selector is none of them,
98
+ or none is left (shown as an error, like deploy's own).
99
+ ValueError: If the calling plugin doesn't require deploy.
100
+ """
101
+ from rostainer_deploy import destinations
102
+
103
+ return destinations(_deploy(ctx), selectors)
104
+
105
+
106
+ class Connection:
107
+ """An open ssh connection to one target, for :func:`for_each`'s function."""
108
+
109
+ def __init__(self, target: DeployTarget, via: Sequence[str]) -> None:
110
+ self.target = target
111
+ """The target: ``.name``, ``.host``, ``.install_dir``, ..."""
112
+ self._via = list(via)
113
+
114
+ def say(self, line: str) -> None:
115
+ """Print a line of output for the target, prefixed with its name."""
116
+ remote.say(self.target.name, line)
117
+
118
+ def run(self, script: str, *, stdin: bytes = b"", capture: bool = False) -> Result:
119
+ """Run ``script`` (``sh``) on the target, from the ssh user's home.
120
+
121
+ Without ``capture``, its output is shown as it comes, prefixed with
122
+ the target's name. With it, its standard output is returned; its
123
+ errors are still shown.
124
+ """
125
+ if not capture:
126
+ outcome = remote.run_on(self.target, script, stdin=stdin, ssh_extra=self._via)
127
+ return Result(outcome.returncode, "")
128
+ process = subprocess.run(
129
+ self.target.ssh(*self._via) + ["sh", "-c", shlex.quote(script)],
130
+ input=stdin,
131
+ stdout=subprocess.PIPE,
132
+ stderr=subprocess.PIPE,
133
+ check=False,
134
+ )
135
+ for line in process.stderr.decode(errors="replace").splitlines():
136
+ self.say(line)
137
+ return Result(process.returncode, process.stdout.decode(errors="replace"))
138
+
139
+ def _manage(self, *arguments: str) -> str:
140
+ """The script running the installed package's ``./rostainer``."""
141
+ return remote.manage_script(self.target.install_dir, " ".join(map(shlex.quote, arguments)))
142
+
143
+ def in_package(self, command: Sequence[str], *, capture: bool = False) -> Result:
144
+ """Run ``command`` in the target's package container, with ROS and
145
+ the workspace sourced (``./rostainer shell -- command``) - e.g. a
146
+ script of the plugin's ``container_files``, under
147
+ ``CONTAINER_PLUGINS_DIR``. Exits 3, saying so, without a package."""
148
+ return self.run(self._manage("shell", "--", *command), capture=capture)
149
+
150
+ def run_command(
151
+ self, plugin: str, command: str, args: Sequence[str] = (), *, capture: bool = False
152
+ ) -> Result:
153
+ """Run ``plugin``'s container command ``command`` (a
154
+ ``ContainerCommand``) in the target's package, as ``./rostainer
155
+ <plugin> <command> ARGS`` there: with the settings that package
156
+ was made with. Exits 2, saying so, if the package has no such
157
+ command (e.g. one made before the plugin had it); 3 without a
158
+ package."""
159
+ return self.run(self._manage(plugin, command, *args), capture=capture)
160
+
161
+ def package_container(self) -> Optional[str]:
162
+ """The name of the target's package container (``./rostainer
163
+ container``), e.g. for ``docker inspect``; ``None`` without a
164
+ package (or one from before rostainer-package had the command)."""
165
+ result = self.run(self._manage("container"), capture=True)
166
+ name = result.output.strip()
167
+ return name if result.returncode == 0 and name else None
168
+
169
+ def copy_from(self, path: str, destination: Path) -> bool:
170
+ """Copy the file ``path`` on the target (relative to the ssh user's
171
+ home, or absolute) to ``destination`` here. Written to a ``.part``
172
+ file first, and renamed only once complete: ``destination`` is
173
+ never left half-written. Returns whether it worked (if not, the
174
+ reason was shown)."""
175
+ destination.parent.mkdir(parents=True, exist_ok=True)
176
+ partial = destination.with_name(destination.name + ".part")
177
+ try:
178
+ with partial.open("wb") as out:
179
+ process = subprocess.run(
180
+ self.target.ssh(*self._via) + ["cat", "--", shlex.quote(path)],
181
+ stdin=subprocess.DEVNULL,
182
+ stdout=out,
183
+ stderr=subprocess.PIPE,
184
+ check=False,
185
+ )
186
+ for line in process.stderr.decode(errors="replace").splitlines():
187
+ self.say(line)
188
+ if process.returncode != 0:
189
+ return False
190
+ os.replace(str(partial), str(destination))
191
+ return True
192
+ finally:
193
+ if partial.exists():
194
+ partial.unlink()
195
+
196
+ def copy_to(self, source: Path, path: str) -> bool:
197
+ """Copy the file ``source`` here to ``path`` on the target (relative
198
+ to the ssh user's home, or absolute), through a temporary file
199
+ there renamed once complete. Returns whether it worked."""
200
+ quoted = shlex.quote(path)
201
+ script = f'tmp={quoted}.part.$$ && cat > "$tmp" && mv -f "$tmp" {quoted} || {{ rm -f "$tmp"; exit 1; }}'
202
+ return self.run(script, stdin=source.read_bytes()).returncode == 0
203
+
204
+
205
+ def for_each(
206
+ ctx: Context,
207
+ targets: Sequence[DeployTarget],
208
+ run: Callable[[Connection], int],
209
+ *,
210
+ title: Optional[str] = None,
211
+ ) -> List[Outcome]:
212
+ """Connect to each target and call ``run`` with the connection,
213
+ ``parallel`` at a time (deploy's setting); its return value is the
214
+ target's exit code. A target that can't be connected to (after
215
+ deploy's retries) fails with 255, saying why, without ``run``; one
216
+ whose ``run`` raises fails with 1, showing the error. In ``targets``'
217
+ order.
218
+
219
+ With a ``title`` (e.g. ``"Fetching the archives"``), in a terminal,
220
+ it's shown as a board of how each target is doing, docker compose
221
+ style: each one's latest line of output, then the whole output of
222
+ those that failed. Without one, every line is shown as it comes."""
223
+ settings = _deploy(ctx).config
224
+
225
+ def one(target: DeployTarget) -> Outcome:
226
+ try:
227
+ with remote.connection(target) as via:
228
+ return Outcome(target.name, run(Connection(target, via)))
229
+ except remote.ConnectError as error:
230
+ remote.say(target.name, str(error))
231
+ return Outcome(target.name, 255)
232
+ except Exception as error: # noqa: BLE001 - one target's failure only.
233
+ remote.say(target.name, f"{type(error).__name__}: {error}")
234
+ return Outcome(target.name, 1)
235
+
236
+ return remote.run_on_all(list(targets), one, settings.parallel, title)
237
+
238
+
239
+ def report(outcomes: Sequence[Outcome], what: str) -> int:
240
+ """Summarize ``outcomes`` as deploy does ("``what`` failed on robot2 (1
241
+ of 2 succeeded)"); the exit code: 0 only if every target succeeded."""
242
+ return remote.report(outcomes, what)
@@ -0,0 +1,129 @@
1
+ """A live board of how each target is doing, docker compose style.
2
+
3
+ While something runs on several targets in a terminal, each gets a row
4
+ with its latest line of output, instead of every line streamed::
5
+
6
+ [+] Deploying '20261102-111227' 2/4
7
+ ✔ diver81 [OK] Install complete. 34.2s
8
+ ⠸ diver82 [INFO] Checking it keeps running for 20s... 21.0s
9
+ ✘ diver83 [ERROR] No package was installed here before... 30.1s
10
+ · diver84 Waiting
11
+
12
+ Once all are done, the whole output of those that failed is printed (as
13
+ lines prefixed with the target's name), and the warnings of the others.
14
+ Without a terminal (or rich), there's no board: every line is printed as
15
+ it comes, prefixed with the target's name.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import os
21
+ import re
22
+ import sys
23
+ import threading
24
+ import time
25
+ from typing import Any, Dict, List, Optional, Sequence
26
+
27
+ #: A line of a target that succeeded still shown after the board.
28
+ _WARNING = re.compile(r"warn", re.IGNORECASE)
29
+
30
+
31
+ class _Row:
32
+ """One target's progress."""
33
+
34
+ def __init__(self) -> None:
35
+ self.lines: List[str] = []
36
+ self.started: Optional[float] = None
37
+ self.finished: Optional[float] = None
38
+ self.returncode: Optional[int] = None
39
+
40
+
41
+ class Board:
42
+ """The rows of :func:`board`'s targets, rendered by rich's ``Live``."""
43
+
44
+ def __init__(self, title: str, names: Sequence[str], console: Any = None) -> None:
45
+ from rich.console import Console
46
+ from rich.spinner import Spinner
47
+
48
+ self.title = title
49
+ self.rows: Dict[str, _Row] = {name: _Row() for name in names}
50
+ self.console = console or Console()
51
+ self._spinners = {name: Spinner("dots", style="cyan") for name in names}
52
+ self._lock = threading.Lock()
53
+
54
+ def start(self, name: str) -> None:
55
+ with self._lock:
56
+ self.rows[name].started = time.monotonic()
57
+
58
+ def add(self, name: str, line: str) -> None:
59
+ with self._lock:
60
+ self.rows[name].lines.append(line)
61
+
62
+ def finish(self, name: str, returncode: int) -> None:
63
+ with self._lock:
64
+ row = self.rows[name]
65
+ row.finished = time.monotonic()
66
+ row.returncode = returncode
67
+
68
+ def live(self) -> Any:
69
+ """The ``with`` block showing the board, updated as it goes."""
70
+ from rich.live import Live
71
+
72
+ return Live(self, console=self.console, refresh_per_second=10)
73
+
74
+ def __rich__(self) -> Any:
75
+ from rich.console import Group
76
+ from rich.table import Table
77
+ from rich.text import Text
78
+
79
+ with self._lock:
80
+ done = sum(row.returncode is not None for row in self.rows.values())
81
+ table = Table.grid(padding=(0, 1), expand=True)
82
+ table.add_column(no_wrap=True)
83
+ table.add_column(no_wrap=True, style="bold")
84
+ table.add_column(no_wrap=True, overflow="ellipsis", ratio=1)
85
+ table.add_column(no_wrap=True, justify="right", style="dim")
86
+ now = time.monotonic()
87
+ for name, row in self.rows.items():
88
+ latest = next((line for line in reversed(row.lines) if line.strip()), "")
89
+ status = Text.from_ansi(latest.strip())
90
+ if row.started is None:
91
+ mark: Any = Text("·", style="dim")
92
+ status = Text("Waiting", style="dim")
93
+ elif row.returncode is None:
94
+ mark = self._spinners[name]
95
+ elif row.returncode == 0:
96
+ mark = Text("✔", style="green")
97
+ else:
98
+ mark = Text("✘", style="red")
99
+ if not latest:
100
+ status = Text(f"Failed (exit code {row.returncode})", style="red")
101
+ elapsed = (
102
+ f"{(row.finished or now) - row.started:.1f}s" if row.started is not None else ""
103
+ )
104
+ table.add_row(mark, name, status, elapsed)
105
+ return Group(Text(f"[+] {self.title} {done}/{len(self.rows)}", style="bold"), table)
106
+
107
+ def print_details(self) -> None:
108
+ """After the board: the whole output of the targets that failed,
109
+ and the warnings of those that didn't."""
110
+ shown = []
111
+ for name, row in self.rows.items():
112
+ failed = row.returncode != 0
113
+ for line in row.lines:
114
+ if failed or _WARNING.search(line):
115
+ shown.append(f"[{name}] {line}")
116
+ if shown:
117
+ print()
118
+ print("\n".join(shown), flush=True)
119
+
120
+
121
+ def board(title: Optional[str], names: Sequence[str]) -> Optional[Board]:
122
+ """A :class:`Board` for ``names`` if there's a terminal to show it in
123
+ (and a ``title``, and rich); else ``None``: stream the lines."""
124
+ if not title or not sys.stdout.isatty() or os.environ.get("TERM") == "dumb":
125
+ return None
126
+ try:
127
+ return Board(title, names)
128
+ except ImportError:
129
+ return None