rostainer-instances 0.0.3__tar.gz

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,213 @@
1
+ # Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode,python,emacs
2
+ # Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode,python,emacs
3
+
4
+ # Docker ROS Tools - This is a tool repository, not a workspace
5
+ # Ignore any test workspaces or temporary files created during development
6
+ .compose_starter_info
7
+ .docker-compose.override.yml
8
+ .direnv/
9
+ builds/
10
+ # Generated from git tags by hatch-vcs at build/install time
11
+ scripts/cli/rostainer_cli/_version.py
12
+ ### Emacs ###
13
+ # -*- mode: gitignore; -*-
14
+ *~
15
+ \#*\#
16
+ /.emacs.desktop
17
+ /.emacs.desktop.lock
18
+ *.elc
19
+ auto-save-list
20
+ tramp
21
+ .\#*
22
+
23
+ # Org-mode
24
+ .org-id-locations
25
+ *_archive
26
+
27
+ # flymake-mode
28
+ *_flymake.*
29
+
30
+ # eshell files
31
+ /eshell/history
32
+ /eshell/lastdir
33
+
34
+ # elpa packages
35
+ /elpa/
36
+
37
+ # reftex files
38
+ *.rel
39
+
40
+ # AUCTeX auto folder
41
+ /auto/
42
+
43
+ # cask packages
44
+ .cask/
45
+ dist/
46
+
47
+ # Flycheck
48
+ flycheck_*.el
49
+
50
+ # server auth directory
51
+ /server/
52
+
53
+ # projectiles files
54
+ .projectile
55
+
56
+ # directory configuration
57
+ .dir-locals.el
58
+
59
+ # network security
60
+ /network-security.data
61
+
62
+
63
+ ### Python ###
64
+ # Byte-compiled / optimized / DLL files
65
+ __pycache__/
66
+ *.py[cod]
67
+ *$py.class
68
+
69
+ # C extensions
70
+ *.so
71
+
72
+ # Distribution / packaging
73
+ .Python
74
+ build/
75
+ develop-eggs/
76
+ downloads/
77
+ eggs/
78
+ .eggs/
79
+ lib/
80
+ lib64/
81
+ parts/
82
+ sdist/
83
+ var/
84
+ wheels/
85
+ share/python-wheels/
86
+ *.egg-info/
87
+ .installed.cfg
88
+ *.egg
89
+ MANIFEST
90
+
91
+ # PyInstaller
92
+ # Usually these files are written by a python script from a template
93
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
94
+ *.manifest
95
+ *.spec
96
+
97
+ # Installer logs
98
+ pip-log.txt
99
+ pip-delete-this-directory.txt
100
+
101
+ # Unit test / coverage reports
102
+ htmlcov/
103
+ .tox/
104
+ .nox/
105
+ .coverage
106
+ .coverage.*
107
+ .cache
108
+ nosetests.xml
109
+ coverage.xml
110
+ *.cover
111
+ *.py,cover
112
+ .hypothesis/
113
+ .pytest_cache/
114
+ cover/
115
+
116
+ # Translations
117
+ *.mo
118
+ *.pot
119
+
120
+ # Django stuff:
121
+ *.log
122
+ local_settings.py
123
+ db.sqlite3
124
+ db.sqlite3-journal
125
+
126
+ # Flask stuff:
127
+ instance/
128
+ .webassets-cache
129
+
130
+ # Scrapy stuff:
131
+ .scrapy
132
+
133
+ # Sphinx documentation
134
+ docs/_build/
135
+
136
+ # PyBuilder
137
+ .pybuilder/
138
+ target/
139
+
140
+ # Jupyter Notebook
141
+ .ipynb_checkpoints
142
+
143
+ # IPython
144
+ profile_default/
145
+ ipython_config.py
146
+
147
+ # pyenv
148
+ # For a library or package, you might want to ignore these files since the code is
149
+ # intended to run in multiple environments; otherwise, check them in:
150
+ # .python-version
151
+
152
+ # pipenv
153
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
154
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
155
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
156
+ # install all needed dependencies.
157
+ #Pipfile.lock
158
+
159
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow
160
+ __pypackages__/
161
+
162
+ # Celery stuff
163
+ celerybeat-schedule
164
+ celerybeat.pid
165
+
166
+ # SageMath parsed files
167
+ *.sage.py
168
+
169
+ # Environments
170
+ .env
171
+ .venv
172
+ env/
173
+ venv/
174
+ ENV/
175
+ env.bak/
176
+ venv.bak/
177
+
178
+ # Spyder project settings
179
+ .spyderproject
180
+ .spyproject
181
+
182
+ # Rope project settings
183
+ .ropeproject
184
+
185
+ # mkdocs documentation
186
+ /site
187
+
188
+ # mypy
189
+ .mypy_cache/
190
+ .dmypy.json
191
+ dmypy.json
192
+
193
+ # Pyre type checker
194
+ .pyre/
195
+
196
+ # pytype static type analyzer
197
+ .pytype/
198
+
199
+ # Cython debug symbols
200
+ cython_debug/
201
+
202
+ ### VisualStudioCode ###
203
+ .vscode/
204
+
205
+ # Local History for Visual Studio Code
206
+ .history/
207
+
208
+ ### VisualStudioCode Patch ###
209
+ # Ignore all local history of files
210
+ .history
211
+ .ionide
212
+
213
+ # End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,python,emacs
@@ -0,0 +1,43 @@
1
+ Metadata-Version: 2.5
2
+ Name: rostainer-instances
3
+ Version: 0.0.3
4
+ Summary: rostainer plugin: run several copies of a ROS environment, for simulation and testing
5
+ Project-URL: Homepage, https://git.whoi.edu/bmillerklugman/rostainer
6
+ Project-URL: Documentation, https://bmillerklugman.pages.whoi.edu/rostainer/
7
+ Author: rostainer contributors
8
+ License-Expression: MIT
9
+ Keywords: docker,ros,ros2,rostainer,simulation
10
+ Requires-Python: >=3.7
11
+ Requires-Dist: rostainer
12
+ Description-Content-Type: text/markdown
13
+
14
+ # rostainer-instances
15
+
16
+ A [rostainer](https://bmillerklugman.pages.whoi.edu/rostainer/) plugin that runs
17
+ several copies ("instances") of a ROS environment next to its dev container, for
18
+ simulation or parallel tests. Each runs the dev container's last build.
19
+
20
+ ```bash
21
+ pip install rostainer[instances] # or: pip install rostainer-instances
22
+ rostainer init --with instances # adds [plugins.instances] to .rostainer.toml
23
+ rostainer start # the dev container builds the workspace
24
+ rostainer instances start # then the instances run that build
25
+ ```
26
+
27
+ ```toml
28
+ [plugins.instances]
29
+ count = 3 # how many
30
+ connected = true # one ROS graph for them all and the dev container (false: one each)
31
+ ```
32
+
33
+ | Command | What it does |
34
+ |---|---|
35
+ | `rostainer instances start [DISTRO]` | Start the target's instances. When none runs, they're (re)created from a new snapshot of the dev container. |
36
+ | `rostainer instances restart [DISTRO]` | Replace them with the dev container's current build. |
37
+ | `rostainer instances stop [N] [--rm]` | Stop them (or instance N); `--rm` removes them. |
38
+ | `rostainer instances status` | List them. |
39
+ | `rostainer instances shell N` / `logs N` | A shell in instance N, or its logs. |
40
+
41
+ Each instance gets `$ROSTAINER_INSTANCE` (0, 1, ...) to tell them apart, e.g. in
42
+ `command`. ROS 1 and Zenoh need `network_mode = "host"` for connected instances,
43
+ and a Docker network (`"bridge"`) for independent ones.
@@ -0,0 +1,30 @@
1
+ # rostainer-instances
2
+
3
+ A [rostainer](https://bmillerklugman.pages.whoi.edu/rostainer/) plugin that runs
4
+ several copies ("instances") of a ROS environment next to its dev container, for
5
+ simulation or parallel tests. Each runs the dev container's last build.
6
+
7
+ ```bash
8
+ pip install rostainer[instances] # or: pip install rostainer-instances
9
+ rostainer init --with instances # adds [plugins.instances] to .rostainer.toml
10
+ rostainer start # the dev container builds the workspace
11
+ rostainer instances start # then the instances run that build
12
+ ```
13
+
14
+ ```toml
15
+ [plugins.instances]
16
+ count = 3 # how many
17
+ connected = true # one ROS graph for them all and the dev container (false: one each)
18
+ ```
19
+
20
+ | Command | What it does |
21
+ |---|---|
22
+ | `rostainer instances start [DISTRO]` | Start the target's instances. When none runs, they're (re)created from a new snapshot of the dev container. |
23
+ | `rostainer instances restart [DISTRO]` | Replace them with the dev container's current build. |
24
+ | `rostainer instances stop [N] [--rm]` | Stop them (or instance N); `--rm` removes them. |
25
+ | `rostainer instances status` | List them. |
26
+ | `rostainer instances shell N` / `logs N` | A shell in instance N, or its logs. |
27
+
28
+ Each instance gets `$ROSTAINER_INSTANCE` (0, 1, ...) to tell them apart, e.g. in
29
+ `command`. ROS 1 and Zenoh need `network_mode = "host"` for connected instances,
30
+ and a Docker network (`"bridge"`) for independent ones.
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["hatchling", "hatch-vcs"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "rostainer-instances"
7
+ dynamic = ["version"]
8
+ description = "rostainer plugin: run several copies of a ROS environment, for simulation and testing"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.7"
12
+ authors = [{ name = "rostainer contributors" }]
13
+ keywords = ["ros", "ros2", "docker", "rostainer", "simulation"]
14
+ # Compatibility with rostainer itself is the plugin API version
15
+ # (InstancesPlugin.api_version), which rostainer checks when it loads it.
16
+ dependencies = ["rostainer"]
17
+
18
+ [project.entry-points."rostainer.plugins"]
19
+ instances = "rostainer_instances:InstancesPlugin"
20
+
21
+ [project.urls]
22
+ Homepage = "https://git.whoi.edu/bmillerklugman/rostainer"
23
+ Documentation = "https://bmillerklugman.pages.whoi.edu/rostainer/"
24
+
25
+ # Versioned with rostainer, from the same repository's tags.
26
+ [tool.hatch.version]
27
+ source = "vcs"
28
+ fallback-version = "0.0.0.dev0"
29
+ raw-options = { root = "../.." }
30
+
31
+ [tool.hatch.build.targets.wheel]
32
+ packages = ["rostainer_instances"]
@@ -0,0 +1,367 @@
1
+ """Instances: several copies of a target, for simulation and testing.
2
+
3
+ ``[plugins.instances] count = N`` in ``.rostainer.toml`` lets ``rostainer
4
+ instances start`` run N copies of a target next to its dev container,
5
+ named ``<container>-0`` .. ``<container>-<N-1>`` (see :func:`instance_name`).
6
+ Each gets ``ROSTAINER_INSTANCE`` (its number) in its environment, e.g. to
7
+ namespace a launch in ``command``.
8
+
9
+ Instances run what the dev container last built, and never build
10
+ themselves: starting them when none is running takes a *snapshot* -- the
11
+ dev container committed to an image (with what the pre-build script and
12
+ rosdep installed in it), and its build-state volumes copied into each
13
+ instance's own. So a rebuild in the dev container never changes running
14
+ instances; ``rostainer instances restart`` takes a new snapshot.
15
+
16
+ ``connected`` says whether they share a ROS graph (with each other and
17
+ the dev container) or each has its own. With DDS that's the domain ID
18
+ (one per instance when not connected). ROS 1 and Zenoh nodes use the
19
+ master/router on their container's ``localhost``, so the network
20
+ decides: under host networking they always share one, on a Docker
21
+ network each container has its own (see :func:`network_problem`).
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import argparse
27
+ import re
28
+ import subprocess
29
+ from typing import Dict, List, Optional, Sequence
30
+
31
+ from pydantic import Field
32
+
33
+ from rostainer_cli.plugin_api import (
34
+ MAX_ROS_DOMAIN_ID,
35
+ Command,
36
+ Context,
37
+ DevContainer,
38
+ Plugin,
39
+ PluginConfig,
40
+ RostainerConfig,
41
+ Target,
42
+ bring_up_container,
43
+ core_command,
44
+ is_running,
45
+ log,
46
+ plugin_containers,
47
+ snapshot_dev_container,
48
+ stop_container,
49
+ targets,
50
+ wait_until_healthy,
51
+ warn_about_shared_graph,
52
+ )
53
+
54
+ #: The most instances ``count`` allows.
55
+ MAX_INSTANCES = 64
56
+
57
+ #: Holds an instance's number in its environment.
58
+ INSTANCE_ENV_VAR = "ROSTAINER_INSTANCE"
59
+
60
+
61
+ class InstancesConfig(PluginConfig):
62
+ """The ``[plugins.instances]`` table."""
63
+
64
+ count: int = Field(
65
+ 3,
66
+ ge=1,
67
+ le=MAX_INSTANCES,
68
+ description="How many instances of a target 'rostainer instances start' runs.",
69
+ )
70
+ connected: bool = Field(
71
+ True,
72
+ description=(
73
+ "true: one ROS graph for them all and the dev container; false: one each.\n"
74
+ 'ROS 1 and Zenoh need network_mode = "host" for true, "bridge" for false.'
75
+ ),
76
+ )
77
+
78
+
79
+ def instance_name(cfg: RostainerConfig, target: Target, index: int) -> str:
80
+ """The name of a target's instance ``index``, e.g. ``jazzy-zenoh_my_ws-3``."""
81
+ return f"{cfg.container_name(target)}-{index}"
82
+
83
+
84
+ def snapshot_image(cfg: RostainerConfig, target: Target) -> str:
85
+ """The image a target's instances run: a snapshot of its dev container."""
86
+ repository = re.sub(r"[^a-z0-9._-]+", "-", cfg.container_name(target).lower())
87
+ return f"rostainer-instances/{repository.strip('-._') or 'workspace'}:latest"
88
+
89
+
90
+ def domain_id(ctx: Context, index: int) -> int:
91
+ """An instance's ``ROS_DOMAIN_ID``: the workspace's if instances are
92
+ connected, else one of its own after it (the dev container keeps
93
+ ``ros_domain_id``)."""
94
+ settings = ctx.config
95
+ if settings.connected:
96
+ return ctx.cfg.ros_domain_id
97
+ return ctx.cfg.ros_domain_id + 1 + index
98
+
99
+
100
+ def network_problem(ctx: Context, target: Target) -> Optional[str]:
101
+ """Why instances can't work as configured for ``target``, if they can't."""
102
+ cfg, settings = ctx.cfg, ctx.config
103
+ core_on_localhost = target.profile == "ros1" or target.middleware == "rmw_zenoh_cpp"
104
+ core = "roscore" if target.profile == "ros1" else "Zenoh router"
105
+ host = cfg.network_mode == "host"
106
+ if core_on_localhost and settings.connected and not host:
107
+ return (
108
+ f"Connected {target.describe()} instances need network_mode = \"host\": "
109
+ f"on a Docker network each container runs its own {core}, so they can't "
110
+ "share one. Use host networking, or [plugins.instances] connected = false."
111
+ )
112
+ if core_on_localhost and not settings.connected and host:
113
+ return (
114
+ f"Independent {target.describe()} instances need a Docker network "
115
+ f"(network_mode = \"bridge\"): under host networking they all use the "
116
+ f"first {core} on the host's localhost. Use bridge, or "
117
+ "[plugins.instances] connected = true."
118
+ )
119
+ last = domain_id(ctx, settings.count - 1)
120
+ if last > MAX_ROS_DOMAIN_ID:
121
+ return (
122
+ f"Independent instances use ROS_DOMAIN_ID {cfg.ros_domain_id + 1} to {last}, "
123
+ f"past ROS 2's limit of {MAX_ROS_DOMAIN_ID}: lower ros_domain_id or "
124
+ "[plugins.instances] count."
125
+ )
126
+ return None
127
+
128
+
129
+ def instances_of(
130
+ ctx: Context, target: Target, *, all_states: bool = True
131
+ ) -> Dict[int, DevContainer]:
132
+ """The target's instances, by number."""
133
+ return {
134
+ int(container.role): container
135
+ for container in plugin_containers(ctx, target, all_states=all_states)
136
+ }
137
+
138
+
139
+ def start_instances(ctx: Context, target: Target, *, verbose: bool) -> int:
140
+ """Start the target's ``count`` instances; its dev container must run.
141
+
142
+ When none of them is running, they're all (re)created from a new
143
+ snapshot of the dev container. Otherwise the missing or stopped ones
144
+ are started next to them, from the snapshot they run.
145
+ """
146
+ cfg, settings = ctx.cfg, ctx.config
147
+ dev = cfg.container_name(target)
148
+ if not is_running(dev):
149
+ log.error(
150
+ f"'{dev}' isn't running: instances run its build. Start it first with "
151
+ "'rostainer start'."
152
+ )
153
+ return 1
154
+ existing = instances_of(ctx, target)
155
+ running = {i for i, c in existing.items() if is_running(c.name)}
156
+ image = snapshot_image(cfg, target)
157
+ if not running:
158
+ for container in existing.values():
159
+ stop_container(ctx, container, remove=True)
160
+ existing = {}
161
+ log.info(f"Waiting for '{dev}' to finish starting...")
162
+ if not wait_until_healthy(dev):
163
+ log.error(f"'{dev}' isn't healthy, so there's no build to run in instances.")
164
+ return 1
165
+ if not snapshot_dev_container(ctx, target, image):
166
+ return 1
167
+
168
+ names = [instance_name(cfg, target, i) for i in range(settings.count)]
169
+ if settings.connected:
170
+ warn_about_shared_graph(
171
+ ctx,
172
+ target,
173
+ name=names[0],
174
+ domain_hint="give this workspace another ros_domain_id",
175
+ isolate_hint="use [plugins.instances] connected = false with a Docker network",
176
+ expected=[dev, *names],
177
+ )
178
+
179
+ for index in range(settings.count):
180
+ if index in running:
181
+ log.info(f"Instance {index} ({names[index]}) is already running.")
182
+ continue
183
+ create = index not in existing
184
+ log.info(
185
+ f"{'Creating' if create else 'Resuming'} instance {index} ({names[index]})..."
186
+ )
187
+ exit_code = bring_up_container(
188
+ ctx,
189
+ target,
190
+ role=str(index),
191
+ name=names[index],
192
+ image=image,
193
+ create=create,
194
+ environment={INSTANCE_ENV_VAR: str(index)},
195
+ ros_domain_id=domain_id(ctx, index),
196
+ verbose=verbose,
197
+ )
198
+ if exit_code:
199
+ return exit_code
200
+
201
+ extra = sorted(i for i in existing if i >= settings.count)
202
+ if extra:
203
+ log.warning(
204
+ f"Instances {', '.join(map(str, extra))} are past [plugins.instances] count = "
205
+ f"{settings.count}; 'rostainer instances stop' stops them."
206
+ )
207
+ how = (
208
+ "sharing a ROS graph with the dev container"
209
+ if settings.connected
210
+ else "each on a ROS graph of its own"
211
+ )
212
+ log.ok(f"{settings.count} instances of {target.describe()} are running, {how}.")
213
+ print(
214
+ " 'rostainer instances shell N' opens a shell in instance N; 'rostainer "
215
+ "instances restart' replaces them with the dev container's current build."
216
+ )
217
+ return 0
218
+
219
+
220
+ def remove_instances(ctx: Context, target: Target) -> None:
221
+ """Remove all of the target's instances, with their copies of the build."""
222
+ for container in instances_of(ctx, target).values():
223
+ stop_container(ctx, container, remove=True)
224
+
225
+
226
+ class InstancesCommand(Command):
227
+ """``rostainer instances <start|restart|stop|status|shell|logs>``."""
228
+
229
+ name = "instances"
230
+ summary = "Run copies of a ROS environment next to it, for simulation and tests"
231
+
232
+ def add_arguments(self, parser: argparse.ArgumentParser) -> None:
233
+ actions = parser.add_subparsers(dest="action", metavar="ACTION")
234
+ actions.required = True
235
+ for action, help_text in (
236
+ ("start", "Start the target's instances (from a new snapshot if none runs)"),
237
+ ("restart", "Replace the target's instances with the dev container's current build"),
238
+ ):
239
+ sub = actions.add_parser(action, help=help_text)
240
+ targets.add_arguments(sub)
241
+ sub.add_argument(
242
+ "-v", "--verbose", action="store_true", help="Stream container output"
243
+ )
244
+ stop = actions.add_parser("stop", help="Stop instances (all, or instance N)")
245
+ stop.add_argument("index", nargs="?", type=int, metavar="N")
246
+ stop.add_argument(
247
+ "--rm", action="store_true", help="Remove them, with their copies of the build"
248
+ )
249
+ actions.add_parser("status", help="List the workspace's instances")
250
+ for action in ("shell", "logs"):
251
+ sub = actions.add_parser(
252
+ action, help=f"{'A shell in' if action == 'shell' else 'The logs of'} instance N"
253
+ )
254
+ sub.add_argument("index", type=int, metavar="N")
255
+ sub.add_argument("rest", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
256
+
257
+ def run(self, args: argparse.Namespace, ctx: Optional[Context]) -> int:
258
+ assert ctx is not None
259
+ if args.action in ("start", "restart"):
260
+ return self._start(args, ctx, replace=args.action == "restart")
261
+ if args.action == "stop":
262
+ return self._stop(args, ctx)
263
+ if args.action == "status":
264
+ return self._status(ctx)
265
+ return self._enter(args, ctx)
266
+
267
+ def _start(self, args: argparse.Namespace, ctx: Context, *, replace: bool) -> int:
268
+ target = targets.select_target(ctx.cfg, args.distro, args.middleware)
269
+ if target is None:
270
+ return 1
271
+ problem = network_problem(ctx, target)
272
+ if problem:
273
+ log.error(problem)
274
+ return 1
275
+ if replace:
276
+ remove_instances(ctx, target)
277
+ return start_instances(ctx, target, verbose=args.verbose)
278
+
279
+ def _stop(self, args: argparse.Namespace, ctx: Context) -> int:
280
+ pool = [
281
+ container
282
+ for container in plugin_containers(ctx, all_states=args.rm)
283
+ if args.index is None or container.role == str(args.index)
284
+ ]
285
+ if not pool:
286
+ what = "No instances" if args.index is None else f"No instance {args.index}"
287
+ print(f"{what} {'exist' if args.rm else 'running'}.")
288
+ return 0
289
+ for container in pool:
290
+ stop_container(ctx, container, remove=args.rm)
291
+ return 0
292
+
293
+ def _status(self, ctx: Context) -> int:
294
+ containers = plugin_containers(ctx)
295
+ if not containers:
296
+ print("No instances exist. 'rostainer instances start' starts them.")
297
+ return 0
298
+ for container in containers:
299
+ state = "running" if is_running(container.name) else "stopped"
300
+ log.info(f"{container.describe()}: {state}")
301
+ return 0
302
+
303
+ def _enter(self, args: argparse.Namespace, ctx: Context) -> int:
304
+ matches = [
305
+ container
306
+ for container in plugin_containers(ctx, all_states=False)
307
+ if container.role == str(args.index)
308
+ ]
309
+ if not matches:
310
+ log.error(f"No instance {args.index} is running.")
311
+ return 1
312
+ if len(matches) > 1:
313
+ log.error(
314
+ f"Instance {args.index} of several targets is running: "
315
+ f"'rostainer {args.action}' asks which."
316
+ )
317
+ return 1
318
+ return core_command(args.action, [matches[0].name, *args.rest])
319
+
320
+
321
+ class InstancesPlugin(Plugin):
322
+ """Several copies of a target next to its dev container."""
323
+
324
+ name = "instances"
325
+ api_version = 1
326
+ summary = "Several copies of a ROS environment, for simulation and testing"
327
+ config_model = InstancesConfig
328
+
329
+ def commands(self) -> Sequence[Command]:
330
+ return [InstancesCommand()]
331
+
332
+ def owns_container(self, ctx: Context, container: DevContainer) -> bool:
333
+ """Only under the name its instance has now (not, e.g., from before a
334
+ ``ros_container_suffix`` change)."""
335
+ return (
336
+ container.target is not None
337
+ and container.role.isdigit()
338
+ and container.name == instance_name(ctx.cfg, container.target, int(container.role))
339
+ )
340
+
341
+ def prunable_images(self, ctx: Context, removed: Sequence[str]) -> List[str]:
342
+ """Snapshots no container uses: starting instances when none runs
343
+ takes a new one anyway."""
344
+ snapshots = _lines(
345
+ [
346
+ "docker",
347
+ "image",
348
+ "ls",
349
+ "--filter",
350
+ "reference=rostainer-instances/*",
351
+ "--format",
352
+ "{{.Repository}}:{{.Tag}}",
353
+ ]
354
+ )
355
+ if not snapshots:
356
+ return []
357
+ used = {
358
+ line.split("\t")[1]
359
+ for line in _lines(["docker", "ps", "-a", "--format", "{{.Names}}\t{{.Image}}"])
360
+ if "\t" in line and line.split("\t")[0] not in removed
361
+ }
362
+ return [image for image in snapshots if image not in used]
363
+
364
+
365
+ def _lines(args: List[str]) -> List[str]:
366
+ proc = subprocess.run(args, capture_output=True, text=True, check=False)
367
+ return [line for line in proc.stdout.splitlines() if line.strip()]
@@ -0,0 +1,15 @@
1
+ """Test package bootstrap: make ``rostainer_instances`` and ``rostainer_cli``
2
+ importable from a plain checkout, without installing either.
3
+
4
+ Run from the plugin's directory: ``python -m unittest discover -s tests -t .``
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import sys
10
+ from pathlib import Path
11
+
12
+ _PLUGIN_DIR = Path(__file__).resolve().parent.parent
13
+ for _path in (_PLUGIN_DIR, _PLUGIN_DIR.parent.parent / "scripts" / "cli"):
14
+ if str(_path) not in sys.path:
15
+ sys.path.insert(0, str(_path))
@@ -0,0 +1,299 @@
1
+ """Unit tests for the instances plugin: ``[plugins.instances]``, starting
2
+ and stopping instances, and how rostainer sees their containers.
3
+
4
+ Docker is mocked. What matters most: instances only start from a new
5
+ snapshot when none is running (so a running fleet never changes under
6
+ itself), ``connected`` is refused where the network can't do it, and an
7
+ instance is never mistaken for a stale container.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import contextlib
14
+ import io
15
+ import os
16
+ import unittest
17
+ from pathlib import Path
18
+ from tempfile import TemporaryDirectory
19
+ from typing import Any, Dict
20
+ from unittest import mock
21
+
22
+ import rostainer_instances as instances
23
+ from rostainer_cli import config, plugins
24
+ from rostainer_cli.config import RostainerConfig, Target
25
+ from rostainer_cli.docker_utils import DevContainer
26
+ from rostainer_cli.plugin_api import Context
27
+
28
+ ZENOH = Target("ros2", "jazzy", "rmw_zenoh_cpp")
29
+ CYCLONE = Target("ros2", "jazzy", "rmw_cyclonedds_cpp")
30
+ NOETIC = Target("ros1", "noetic", "")
31
+
32
+
33
+ def _cfg(table: Dict[str, Any] = None, **overrides: Any) -> RostainerConfig:
34
+ """A config with ``[plugins.instances]`` set to ``table``, built directly."""
35
+ values: Dict[str, Any] = dict(
36
+ config_file=Path("/tmp/ws/.rostainer.toml"),
37
+ workspace_root=Path("/tmp/ws"),
38
+ global_dir=Path("/tmp/global"),
39
+ workspace_src_dir=Path("/tmp/ws/src"),
40
+ docker_compose_file=Path("/tmp/global/docker-compose.yml"),
41
+ shell_setup_script=Path("/tmp/global/dummy_shell_setup.sh"),
42
+ pre_build_script=Path("/tmp/global/dummy_pre_build.sh"),
43
+ post_build_script=Path("/tmp/global/dummy_post_build.sh"),
44
+ ros_container_suffix="_container",
45
+ user_uid=1000,
46
+ user_gid=1000,
47
+ username="rosuser",
48
+ gpu_vendor="none",
49
+ network_mode="host",
50
+ rt_preempt=False,
51
+ device_mappings=[],
52
+ port_mappings=[],
53
+ volume_mappings=[],
54
+ ros1_mappings=[],
55
+ ros2_mappings=[],
56
+ )
57
+ values.update(overrides)
58
+ if table is not None:
59
+ values["plugins"] = {"instances": instances.InstancesConfig.model_validate(table)}
60
+ return RostainerConfig(**values)
61
+
62
+
63
+ def _ctx(table: Dict[str, Any] = None, **overrides: Any) -> Context:
64
+ return Context(instances.InstancesPlugin(), _cfg(table, **overrides))
65
+
66
+
67
+ def _instance(cfg: RostainerConfig, target: Target, index: int) -> DevContainer:
68
+ return DevContainer(instances.instance_name(cfg, target, index), target, "instances", str(index))
69
+
70
+
71
+ class InstancesConfigTest(unittest.TestCase):
72
+ def setUp(self) -> None:
73
+ plugins._cache.clear()
74
+ self.addCleanup(plugins._cache.clear)
75
+
76
+ def _load(self, text: str) -> RostainerConfig:
77
+ with TemporaryDirectory() as tmp:
78
+ root = Path(tmp)
79
+ global_dir = root / "global"
80
+ global_dir.mkdir()
81
+ (global_dir / "docker-compose.yml").write_text("services: {}\n")
82
+ for name in ("dummy_shell_setup.sh", "dummy_pre_build.sh", "dummy_post_build.sh"):
83
+ (global_dir / name).write_text("#!/bin/bash\n")
84
+ workspace = root / "ws"
85
+ (workspace / "src").mkdir(parents=True)
86
+ (workspace / ".rostainer.toml").write_text(text)
87
+ with mock.patch.object(
88
+ plugins,
89
+ "discover",
90
+ return_value={"instances": instances.InstancesPlugin()},
91
+ ), contextlib.redirect_stdout(io.StringIO()):
92
+ return config.load_config(
93
+ explicit_config=str(workspace / ".rostainer.toml"),
94
+ global_dir_override=str(global_dir),
95
+ )
96
+
97
+ def test_count_and_connected(self) -> None:
98
+ cfg = self._load("[plugins.instances]\ncount = 4\nconnected = false\n")
99
+ settings = cfg.plugins["instances"]
100
+ self.assertEqual((settings.count, settings.connected), (4, False))
101
+
102
+ def test_defaults_without_a_table(self) -> None:
103
+ ctx = Context(instances.InstancesPlugin(), self._load(""))
104
+ self.assertEqual((ctx.config.count, ctx.config.connected), (3, True))
105
+
106
+ def test_invalid_tables_are_refused(self) -> None:
107
+ for text in (
108
+ "[plugins.instances]\ncount = 0\n",
109
+ "[plugins.instances]\ncount = 65\n",
110
+ "[plugins.instances]\ncount = true\n",
111
+ '[plugins.instances]\ncount = "3"\n',
112
+ "[plugins.instances]\ncount = 2\nconnected = 1\n",
113
+ "[plugins.instances]\ncount = 2\nseparate_networks = true\n",
114
+ ):
115
+ with self.subTest(text=text), self.assertRaises(config.ConfigError):
116
+ self._load(text)
117
+
118
+ def test_template_for_init_with(self) -> None:
119
+ text = plugins.template(instances.InstancesPlugin())
120
+ self.assertIn("# [plugins.instances]\n", text)
121
+ self.assertIn("# count = 3\n", text)
122
+ self.assertIn("# connected = true\n", text)
123
+
124
+
125
+ class NetworkProblemTest(unittest.TestCase):
126
+ def _problem(self, target: Target, connected: bool = True, **overrides: Any):
127
+ ctx = _ctx({"count": 3, "connected": connected}, **overrides)
128
+ return instances.network_problem(ctx, target)
129
+
130
+ def test_ros1_and_zenoh_follow_the_network(self) -> None:
131
+ for target in (ZENOH, NOETIC):
132
+ with self.subTest(target=target):
133
+ self.assertIsNone(self._problem(target, network_mode="host"))
134
+ self.assertIn("host", self._problem(target, network_mode="bridge"))
135
+ self.assertIn(
136
+ "bridge", self._problem(target, connected=False, network_mode="host")
137
+ )
138
+ self.assertIsNone(
139
+ self._problem(target, connected=False, network_mode="bridge")
140
+ )
141
+
142
+ def test_dds_works_either_way(self) -> None:
143
+ for network_mode in ("host", "bridge"):
144
+ for connected in (True, False):
145
+ with self.subTest(network_mode=network_mode, connected=connected):
146
+ self.assertIsNone(
147
+ self._problem(CYCLONE, connected=connected, network_mode=network_mode)
148
+ )
149
+
150
+ def test_independent_domain_ids_must_fit(self) -> None:
151
+ self.assertIn("232", self._problem(CYCLONE, connected=False, ros_domain_id=230))
152
+
153
+
154
+ class DomainIdTest(unittest.TestCase):
155
+ def test_independent_instances_get_their_own(self) -> None:
156
+ ctx = _ctx({"count": 2, "connected": False}, ros_domain_id=4)
157
+ self.assertEqual([instances.domain_id(ctx, i) for i in range(2)], [5, 6])
158
+
159
+ def test_connected_instances_keep_the_workspaces(self) -> None:
160
+ ctx = _ctx({"count": 2}, ros_domain_id=4)
161
+ self.assertEqual(instances.domain_id(ctx, 1), 4)
162
+
163
+
164
+ class OwnershipTest(unittest.TestCase):
165
+ def test_instances_are_current_not_stale(self) -> None:
166
+ ctx = _ctx()
167
+ plugin = instances.InstancesPlugin()
168
+ self.assertTrue(plugin.owns_container(ctx, _instance(ctx.cfg, ZENOH, 2)))
169
+ renamed = DevContainer("jazzy-zenoh_old-2", ZENOH, "instances", "2")
170
+ self.assertFalse(plugin.owns_container(ctx, renamed))
171
+ self.assertIn("[instances 2]", _instance(ctx.cfg, ZENOH, 2).describe())
172
+
173
+ def test_snapshot_image_is_per_target(self) -> None:
174
+ self.assertEqual(
175
+ instances.snapshot_image(_cfg(), ZENOH),
176
+ "rostainer-instances/jazzy-zenoh_container:latest",
177
+ )
178
+
179
+
180
+ class StartInstancesTest(unittest.TestCase):
181
+ def _start(self, existing, running, dev_running=True):
182
+ ctx = _ctx({"count": 3})
183
+ cfg = ctx.cfg
184
+ containers = {i: _instance(cfg, ZENOH, i) for i in existing}
185
+ running_names = {instances.instance_name(cfg, ZENOH, i) for i in running}
186
+ if dev_running:
187
+ running_names.add(cfg.container_name(ZENOH))
188
+ with mock.patch.object(
189
+ instances, "instances_of", return_value=containers
190
+ ), mock.patch.object(
191
+ instances, "is_running", side_effect=lambda name: name in running_names
192
+ ), mock.patch.object(
193
+ instances, "wait_until_healthy", return_value=True
194
+ ), mock.patch.object(
195
+ instances, "stop_container"
196
+ ) as stop_container, mock.patch.object(
197
+ instances, "warn_about_shared_graph"
198
+ ), mock.patch.object(
199
+ instances, "snapshot_dev_container", return_value=True
200
+ ) as snapshot, mock.patch.object(
201
+ instances, "bring_up_container", return_value=0
202
+ ) as bring_up, contextlib.redirect_stdout(
203
+ io.StringIO()
204
+ ), contextlib.redirect_stderr(
205
+ io.StringIO()
206
+ ):
207
+ code = instances.start_instances(ctx, ZENOH, verbose=False)
208
+ created = {
209
+ int(call[1]["role"]): call[1]["create"] for call in bring_up.call_args_list
210
+ }
211
+ environments = [call[1]["environment"] for call in bring_up.call_args_list]
212
+ return code, snapshot.called, stop_container.call_count, created, environments
213
+
214
+ def test_none_running_recreates_all_from_a_new_snapshot(self) -> None:
215
+ code, snapshot, removed, created, environments = self._start(
216
+ existing=[0, 1], running=[]
217
+ )
218
+ self.assertEqual(code, 0)
219
+ self.assertTrue(snapshot)
220
+ self.assertEqual(removed, 2)
221
+ self.assertEqual(created, {0: True, 1: True, 2: True})
222
+ self.assertEqual(environments[2], {"ROSTAINER_INSTANCE": "2"})
223
+
224
+ def test_some_running_keeps_the_snapshot(self) -> None:
225
+ code, snapshot, removed, created, _ = self._start(existing=[0, 1], running=[0])
226
+ self.assertEqual(code, 0)
227
+ self.assertFalse(snapshot)
228
+ self.assertEqual(removed, 0)
229
+ self.assertEqual(created, {1: False, 2: True})
230
+
231
+ def test_dev_container_must_run(self) -> None:
232
+ code, snapshot, _, created, _ = self._start(existing=[], running=[], dev_running=False)
233
+ self.assertEqual(code, 1)
234
+ self.assertFalse(snapshot)
235
+ self.assertEqual(created, {})
236
+
237
+
238
+ class CommandTest(unittest.TestCase):
239
+ def _parse(self, argv):
240
+ parser = argparse.ArgumentParser(prog="rostainer instances")
241
+ instances.InstancesCommand().add_arguments(parser)
242
+ return parser.parse_args(argv)
243
+
244
+ def _run(self, argv, containers):
245
+ ctx = _ctx({"count": 3})
246
+ with mock.patch.object(
247
+ instances, "plugin_containers", return_value=containers
248
+ ), mock.patch.object(instances, "stop_container") as stop_container, mock.patch.object(
249
+ instances, "core_command", return_value=0
250
+ ) as core_command, contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(
251
+ io.StringIO()
252
+ ):
253
+ code = instances.InstancesCommand().run(self._parse(argv), ctx)
254
+ return code, stop_container, core_command
255
+
256
+ def test_stop_n_stops_that_instance(self) -> None:
257
+ cfg = _cfg()
258
+ fleet = [_instance(cfg, ZENOH, i) for i in range(3)]
259
+ code, stop_container, _ = self._run(["stop", "2"], fleet)
260
+ self.assertEqual(code, 0)
261
+ self.assertEqual([call[0][1] for call in stop_container.call_args_list], [fleet[2]])
262
+
263
+ def test_stop_stops_them_all(self) -> None:
264
+ cfg = _cfg()
265
+ fleet = [_instance(cfg, ZENOH, i) for i in range(2)]
266
+ _, stop_container, _ = self._run(["stop", "--rm"], fleet)
267
+ self.assertEqual(len(stop_container.call_args_list), 2)
268
+ self.assertTrue(all(call[1]["remove"] for call in stop_container.call_args_list))
269
+
270
+ def test_shell_n_opens_rostainers_shell_in_it(self) -> None:
271
+ cfg = _cfg()
272
+ fleet = [_instance(cfg, ZENOH, i) for i in range(2)]
273
+ code, _, core_command = self._run(["shell", "1", "-c", "ls"], fleet)
274
+ self.assertEqual(code, 0)
275
+ core_command.assert_called_once_with(
276
+ "shell", ["jazzy-zenoh_container-1", "-c", "ls"]
277
+ )
278
+
279
+ def test_shell_n_with_none_running(self) -> None:
280
+ code, _, core_command = self._run(["shell", "5"], [])
281
+ self.assertEqual(code, 1)
282
+ core_command.assert_not_called()
283
+
284
+
285
+ class PrunableImagesTest(unittest.TestCase):
286
+ def test_snapshots_no_container_uses(self) -> None:
287
+ listings = {
288
+ "image": ["rostainer-instances/a:latest", "rostainer-instances/b:latest"],
289
+ "ps": ["a-0\trostainer-instances/a:latest", "b-0\trostainer-instances/b:latest"],
290
+ }
291
+ with mock.patch.object(
292
+ instances, "_lines", side_effect=lambda args: listings[args[1]]
293
+ ):
294
+ images = instances.InstancesPlugin().prunable_images(_ctx(), removed=["b-0"])
295
+ self.assertEqual(images, ["rostainer-instances/b:latest"])
296
+
297
+
298
+ if __name__ == "__main__":
299
+ unittest.main()