rosotacom-dev 2.5.dev24__tar.gz → 2.5.dev26__tar.gz

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/CONCURRENCY.md

@@ -39,6 +39,26 @@ commands *discover* the matching containers from Docker instead of recomputing
 fixed names — they clean up every instance for the requested identity/target,
 including leftovers from crashed runs.
 
+## Opting out: fixed, human-readable names
+
+A project whose machines are read by people rather than by CI — a demo or
+operations project — can set `com_container_prefix` in its `rosotacom.yaml`:
+
+```yaml
+com_container_prefix: remote-assist
+```
+
+Session communication containers are then named
+`<prefix>_com-to-<remote-peer>` (e.g. `remote-assist_com-to-center`): stable
+across runs and legible in `docker ps`, at the price of parallelism — a second
+start of the same session on the same host is a name conflict. That conflict is
+detected in the same preflight as everything else: `--force` (the session
+default) replaces the running container, `--no-force` aborts with its name.
+Conflict discovery matches **both** naming schemes, so a leftover
+instance-scoped container is still found and replaced after a project switches
+modes. Test and CI projects should leave the key unset and keep the
+collision-free instance-scoped names.
+
 ## How conflicts are detected (fail-safe preflight)
 
 Each start command checks Docker before it allocates anything, and aborts with

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev24
+Version: 2.5.dev26
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -227,6 +227,15 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+`com_container_prefix` (optional) trades concurrency for readability: when set,
+session communication containers get the stable name
+`<prefix>_com-to-<remote-peer>` (e.g. `remote-assist_com-to-center`) instead of
+the default workspace- and instance-scoped unique name. Set it in projects whose
+machines are read by people (`docker ps` during a demo, next to colleagues'
+containers); leave it unset in test/CI projects, where concurrent instances must
+never collide on a name. [CONCURRENCY.md](CONCURRENCY.md) has the exact
+conflict semantics.
+
 ### Locating packaged resources
 
 rosotacom is installed in an isolated environment (pipx, or a project venv), so

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/README.md

@@ -182,6 +182,15 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+`com_container_prefix` (optional) trades concurrency for readability: when set,
+session communication containers get the stable name
+`<prefix>_com-to-<remote-peer>` (e.g. `remote-assist_com-to-center`) instead of
+the default workspace- and instance-scoped unique name. Set it in projects whose
+machines are read by people (`docker ps` during a demo, next to colleagues'
+containers); leave it unset in test/CI projects, where concurrent instances must
+never collide on a name. [CONCURRENCY.md](CONCURRENCY.md) has the exact
+conflict semantics.
+
 ### Locating packaged resources
 
 rosotacom is installed in an isolated environment (pipx, or a project venv), so

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/src/rosotacom/cli.py

@@ -181,6 +181,7 @@ class RuntimeConfig:
     scenario_configs_dir: tuple[Path, ...] = ()
     profiles_file: Path | None = None
     benchmarks_dir: Path | None = None
+    com_container_prefix: str | None = None
 
 
 @dataclass(frozen=True)
@@ -485,6 +486,22 @@ def _resolve_project_config_source(args: argparse.Namespace) -> tuple[str | None
     return None, None
 
 
+_DOCKER_NAME_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$")
+
+
+def _validated_com_container_prefix(raw: Any) -> str | None:
+    if raw is None:
+        return None
+    value = str(raw).strip()
+    if not value:
+        return None
+    if not _DOCKER_NAME_RE.match(value):
+        raise RuntimeError(
+            f"com_container_prefix must be a valid docker name ([a-zA-Z0-9][a-zA-Z0-9_.-]*), got: {raw!r}"
+        )
+    return value
+
+
 def _load_runtime_config(args: argparse.Namespace | None = None) -> RuntimeConfig:
     args = args or argparse.Namespace()
     rosotacom_config_raw, project_source = _resolve_project_config_source(args)
@@ -499,6 +516,7 @@ def _load_runtime_config(args: argparse.Namespace | None = None) -> RuntimeConfi
         "deployment",
         "profiles",
         "benchmarks_dir",
+        "com_container_prefix",
     }
     unknown_project_keys = sorted(set(cfg) - allowed_project_keys)
     if unknown_project_keys:
@@ -543,6 +561,10 @@ def _load_runtime_config(args: argparse.Namespace | None = None) -> RuntimeConfi
         os.environ.get("ROSOTACOM_BENCHMARKS_DIR"),
         cfg.get("benchmarks_dir"),
     )
+    com_container_prefix_raw = _first_value(
+        os.environ.get("ROSOTACOM_COM_CONTAINER_PREFIX"),
+        cfg.get("com_container_prefix"),
+    )
 
     ros2docker_config = _resolve_path(ros2docker_config_raw, config_base, must_exist=True)
     if ros2docker_config is None:
@@ -575,6 +597,7 @@ def _load_runtime_config(args: argparse.Namespace | None = None) -> RuntimeConfi
         ),
         profiles_file=_resolve_path(profiles_raw, config_base, must_exist=True),
         benchmarks_dir=_resolve_path(benchmarks_dir_raw, config_base, must_exist=False),
+        com_container_prefix=_validated_com_container_prefix(com_container_prefix_raw),
     )
 
 
@@ -663,7 +686,23 @@ def _workspace_container_prefix(runtime: RuntimeConfig) -> str:
     return f"rosotacom_{runtime.install_id}_"
 
 
+def _fixed_com_container_name(runtime: RuntimeConfig, remote_peer_name: str) -> str | None:
+    """The stable, human-readable com container name, when the project opts in.
+
+    A project sets ``com_container_prefix`` when people read ``docker ps`` on its
+    machines (demos, operations). The price is concurrency: two instances of the
+    same session cannot run side by side on one host, which is why test/CI
+    projects leave the key unset and keep the instance-scoped names.
+    """
+    if not runtime.com_container_prefix:
+        return None
+    return _sanitize_docker_name(f"{runtime.com_container_prefix}_com-to-{remote_peer_name}")
+
+
 def _container_name(remote_peer_name: str, runtime: RuntimeConfig, instance_id: str) -> str:
+    fixed = _fixed_com_container_name(runtime, remote_peer_name)
+    if fixed is not None:
+        return fixed
     return _sanitize_docker_name(
         f"rosotacom_{runtime.install_id}_{_instance_name_token(instance_id)}_com_to_{remote_peer_name}"
     )
@@ -697,10 +736,19 @@ def _list_docker_containers(*, all_states: bool = False) -> list[tuple[str, list
 
 
 def _matching_com_containers(runtime: RuntimeConfig, remote_peer_name: str, *, all_states: bool = False) -> list[str]:
-    """Workspace communication containers for `remote_peer_name`, any instance."""
+    """Workspace communication containers for `remote_peer_name`, any instance.
+
+    Matches both naming schemes — the instance-scoped default and the fixed
+    ``com_container_prefix`` name — so a leftover container from the other mode
+    is still found after a project toggles the key.
+    """
     suffix = _sanitize_docker_name(f"com_to_{remote_peer_name}")
+    fixed = _fixed_com_container_name(runtime, remote_peer_name)
     names = []
     for name, _networks in _list_docker_containers(all_states=all_states):
+        if fixed is not None and name == fixed:
+            names.append(name)
+            continue
         parts = _split_workspace_container(name, runtime)
         if parts is not None and parts[1] == suffix:
             names.append(name)
@@ -4350,7 +4398,13 @@ def _load_scenario_definition(resolved: ResolvedScenario) -> ScenarioDefinition:
             assert config_path is not None
             if not config_path.is_file():
                 raise RuntimeError(f"{context}.ros2docker_config must resolve to a file: {config_path}")
-            load_config(config_path)
+            # Structural validation only. A definition names applications for
+            # every peer, and a `-v` host path (a staged replay bag, a local
+            # workspace) is only required to exist on the machine that starts
+            # that application — which validates it in `_run-application`.
+            # Resolving run args here would make every peer demand every other
+            # peer's machine-local artifacts (#249).
+            load_config(config_path, resolve_run_args=False)
             seen_names.add(name)
             parsed_entries.append(ScenarioApplication(name=name, ros2docker_config=config_path))
         applications[identity] = tuple(parsed_entries)
@@ -4900,7 +4954,13 @@ def start_session(args: argparse.Namespace) -> str:
     container_name = _container_name(remote_name, runtime, instance.instance_id)
     network_isolated = bool(getattr(args, "network_name", None))
     if not network_isolated and not getattr(args, "skip_conflict_check", False):
-        conflicts = [name for name in _matching_com_containers(runtime, remote_name) if name != container_name]
+        matching = _matching_com_containers(runtime, remote_name)
+        if _fixed_com_container_name(runtime, remote_name) is not None:
+            # A fixed name cannot coexist with itself: a running container with
+            # this exact name is a conflict too, not a rejoinable instance.
+            conflicts = matching
+        else:
+            conflicts = [name for name in matching if name != container_name]
         if conflicts and args.force:
             for conflict in conflicts:
                 _stop_container_name(conflict, runtime, quiet_missing=True)
@@ -5616,15 +5676,20 @@ def ps_command(args: argparse.Namespace) -> int:
     """Answer "can I start something?" by classifying active rosotacom containers."""
     runtime = _load_runtime_config(args)
     prefix = _workspace_container_prefix(runtime)
+    fixed_com_prefix = (
+        f"{_sanitize_docker_name(runtime.com_container_prefix)}_com-to-" if runtime.com_container_prefix else None
+    )
     smoke_isolated: list[tuple[str, str]] = []
     host_shared: list[str] = []
     other_workspaces: list[str] = []
     for name, networks in _list_docker_containers():
-        if not name.startswith("rosotacom_"):
-            continue
-        if not name.startswith(prefix):
-            other_workspaces.append(name)
-            continue
+        fixed_named = fixed_com_prefix is not None and name.startswith(fixed_com_prefix)
+        if not fixed_named:
+            if not name.startswith("rosotacom_"):
+                continue
+            if not name.startswith(prefix):
+                other_workspaces.append(name)
+                continue
         smoke_nets = [net for net in networks if net.startswith("rosotacom_smoke_") or net == SMOKE_NETWORK_NAME]
         if smoke_nets:
             smoke_isolated.append((name, smoke_nets[0]))

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev24
+Version: 2.5.dev26
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -227,6 +227,15 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+`com_container_prefix` (optional) trades concurrency for readability: when set,
+session communication containers get the stable name
+`<prefix>_com-to-<remote-peer>` (e.g. `remote-assist_com-to-center`) instead of
+the default workspace- and instance-scoped unique name. Set it in projects whose
+machines are read by people (`docker ps` during a demo, next to colleagues'
+containers); leave it unset in test/CI projects, where concurrent instances must
+never collide on a name. [CONCURRENCY.md](CONCURRENCY.md) has the exact
+conflict semantics.
+
 ### Locating packaged resources
 
 rosotacom is installed in an isolated environment (pipx, or a project venv), so

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 24,
-  "node": "g74a8a6227adefec12dd07aeed5d58ce67d5ad2c2",
+  "distance": 26,
+  "node": "g78896a3820ecc07358d123fd0b0df6710b2d15fe",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-13"

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/tests/unit/test_cli.py

@@ -158,6 +158,31 @@ def test_rosotacom_yaml_rejects_removed_data_dict_key(tmp_path: Path) -> None:
         rosotacom._load_runtime_config(argparse.Namespace(rosotacom_config=str(config)))
 
 
+def test_rosotacom_yaml_accepts_com_container_prefix(tmp_path: Path) -> None:
+    (tmp_path / "ros2docker.json").write_text('{"image_name": "test"}\n', encoding="utf-8")
+    config = tmp_path / "rosotacom.yaml"
+    config.write_text(
+        "ros2docker_config: ros2docker.json\ncom_container_prefix: remote-assist\n",
+        encoding="utf-8",
+    )
+
+    runtime = rosotacom._load_runtime_config(argparse.Namespace(rosotacom_config=str(config)))
+
+    assert runtime.com_container_prefix == "remote-assist"
+
+
+def test_rosotacom_yaml_rejects_invalid_com_container_prefix(tmp_path: Path) -> None:
+    (tmp_path / "ros2docker.json").write_text('{"image_name": "test"}\n', encoding="utf-8")
+    config = tmp_path / "rosotacom.yaml"
+    config.write_text(
+        "ros2docker_config: ros2docker.json\ncom_container_prefix: 'has space'\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(RuntimeError, match="com_container_prefix must be a valid docker name"):
+        rosotacom._load_runtime_config(argparse.Namespace(rosotacom_config=str(config)))
+
+
 def test_session_definition_rejects_physical_address_field() -> None:
     with pytest.raises(RuntimeError, match="Unsupported keys in peers.a.*address"):
         rosotacom.session_gen._validate_session_template_cfg({"peers": {"a": {"address": "10.0.0.1"}, "b": {}}})
@@ -411,6 +436,40 @@ def test_scenario_definition_resolves_and_validates_strictly(tmp_path: Path) ->
         rosotacom._load_scenario_definition(resolved)
 
 
+def test_scenario_definition_ignores_foreign_peers_host_paths(tmp_path: Path) -> None:
+    """Loading a definition must not require other peers' machine-local mounts.
+
+    Application b mounts a host path that exists only on b's machine (a staged
+    replay bag). Peer a still has to be able to parse the definition and start
+    its own applications; the mount is validated where b actually starts
+    (#249).
+    """
+    runtime, resolved = _write_test_scenario_project(tmp_path)
+    foreign_config = tmp_path / "apps" / "b.json"
+    foreign_config.write_text(
+        "\n".join(
+            [
+                "{",
+                '  "container_name": "b_app",',
+                '  "run_type": "command",',
+                '  "command": ["true"],',
+                '  "run_args": ["-v", "./only-on-machine-b:/bag:ro"]',
+                "}",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    definition = rosotacom._load_scenario_definition(resolved)
+    assert definition.applications["b"][0].name == "local_app"
+
+    # The start path still refuses the missing mount on the machine that runs
+    # the application: full resolution stays where it is meaningful.
+    with pytest.raises(FileNotFoundError, match="Host path does not exist"):
+        rosotacom.load_config(foreign_config)
+
+
 def test_scenario_name_completion_uses_active_project(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev26}/tests/unit/test_concurrency.py

@@ -17,8 +17,20 @@ import rosotacom.cli as rosotacom
 from rosotacom import cli_benchmark
 
 
-def _runtime(tmp_path: Path, install_id: str = "abc") -> rosotacom.RuntimeConfig:
-    return rosotacom.RuntimeConfig(None, tmp_path / "ros2docker.json", (), None, install_id, tmp_path / "instances")
+def _runtime(
+    tmp_path: Path,
+    install_id: str = "abc",
+    com_container_prefix: str | None = None,
+) -> rosotacom.RuntimeConfig:
+    return rosotacom.RuntimeConfig(
+        None,
+        tmp_path / "ros2docker.json",
+        (),
+        None,
+        install_id,
+        tmp_path / "instances",
+        com_container_prefix=com_container_prefix,
+    )
 
 
 def test_container_name_is_instance_scoped(tmp_path: Path) -> None:
@@ -34,6 +46,42 @@ def test_container_name_is_instance_scoped(tmp_path: Path) -> None:
     assert rosotacom._container_name("remote", runtime, "my_run") == "rosotacom_abc_my-run_com_to_remote"
 
 
+def test_container_name_is_fixed_with_com_container_prefix(tmp_path: Path) -> None:
+    runtime = _runtime(tmp_path, com_container_prefix="remote-assist")
+    first = rosotacom._container_name("center", runtime, "run1")
+    second = rosotacom._container_name("center", runtime, "run2")
+
+    # No install id, no instance token: the name is stable across runs and
+    # readable next to colleagues' containers in `docker ps`.
+    assert first == "remote-assist_com-to-center"
+    assert second == first
+    assert rosotacom._container_name("ella", runtime, "run1") == "remote-assist_com-to-ella"
+
+
+def test_matching_com_containers_includes_fixed_names(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runtime = _runtime(tmp_path, com_container_prefix="remote-assist")
+    monkeypatch.setattr(
+        rosotacom,
+        "_list_docker_containers",
+        lambda all_states=False: [
+            ("remote-assist_com-to-remote", ["bridge"]),
+            ("remote-assist_com-to-other", ["bridge"]),
+            ("rosotacom_abc_run1_com_to_remote", ["bridge"]),
+            ("unrelated", ["bridge"]),
+        ],
+    )
+
+    # Both schemes match, so a leftover instance-scoped container is still
+    # found after the project switched to fixed names (and vice versa).
+    assert rosotacom._matching_com_containers(runtime, "remote") == [
+        "remote-assist_com-to-remote",
+        "rosotacom_abc_run1_com_to_remote",
+    ]
+
+
 def test_scenario_container_name_is_instance_scoped(tmp_path: Path) -> None:
     runtime = _runtime(tmp_path)
     first = rosotacom._scenario_container_name(runtime, "demo", "a", "app", "run1")
@@ -209,6 +257,58 @@ def test_start_session_force_replaces_conflicting_identity_container(
     assert [name for name, _ in calls] == ["build", "run", "exec"]
 
 
+def test_start_session_fixed_name_conflicts_with_itself_without_force(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runtime = _runtime(tmp_path, install_id="id", com_container_prefix="remote-assist")
+    session = rosotacom.ResolvedSession(tmp_path, "/session/current", "absolute")
+    cfg = {"peers": {"a": {}, "b": {"com-name": "remote"}}}
+    calls: list[tuple[str, dict[str, object]]] = []
+    _patch_start_session_collaborators(monkeypatch, runtime, session, cfg, calls)
+    monkeypatch.setattr(
+        rosotacom,
+        "_list_docker_containers",
+        lambda all_states=False: [("remote-assist_com-to-remote", ["bridge"])],
+    )
+
+    with pytest.raises(RuntimeError) as excinfo:
+        rosotacom.start_session(_start_session_args())
+
+    # A fixed name cannot coexist with itself, so the running container is a
+    # conflict rather than a rejoinable instance.
+    assert "remote-assist_com-to-remote" in str(excinfo.value)
+    assert calls == []
+
+
+def test_start_session_fixed_name_force_replaces_running_container(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runtime = _runtime(tmp_path, install_id="id", com_container_prefix="remote-assist")
+    session = rosotacom.ResolvedSession(tmp_path, "/session/current", "absolute")
+    cfg = {"peers": {"a": {}, "b": {"com-name": "remote"}}}
+    calls: list[tuple[str, dict[str, object]]] = []
+    stopped: list[str] = []
+    _patch_start_session_collaborators(monkeypatch, runtime, session, cfg, calls)
+    monkeypatch.setattr(
+        rosotacom,
+        "_list_docker_containers",
+        lambda all_states=False: [("remote-assist_com-to-remote", ["bridge"])],
+    )
+    monkeypatch.setattr(
+        rosotacom,
+        "_stop_container_name",
+        lambda name, runtime, **kwargs: stopped.append(name) or True,
+    )
+
+    container = rosotacom.start_session(_start_session_args(force=True))
+
+    assert container == "remote-assist_com-to-remote"
+    assert stopped[0] == "remote-assist_com-to-remote"
+    assert [name for name, _ in calls] == ["build", "run", "exec"]
+
+
 def test_start_session_skips_identity_conflicts_on_isolated_networks(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -318,6 +418,32 @@ def test_ps_command_classifies_active_containers(
     assert "onedrive" not in output
 
 
+def test_ps_command_lists_fixed_named_com_containers(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    runtime = _runtime(tmp_path, com_container_prefix="remote-assist")
+    monkeypatch.setattr(rosotacom, "_load_runtime_config", lambda args: runtime)
+    monkeypatch.setattr(
+        rosotacom,
+        "_list_docker_containers",
+        lambda all_states=False: [
+            ("remote-assist_com-to-center", ["bridge"]),
+            ("rosotacom_abc_run2_com_to_b", ["bridge"]),
+            ("onedrive", ["bridge"]),
+        ],
+    )
+
+    assert rosotacom.ps_command(argparse.Namespace()) == 0
+    output = capsys.readouterr().out
+
+    assert "Host-shared" in output
+    assert "remote-assist_com-to-center" in output
+    assert "rosotacom_abc_run2_com_to_b" in output
+    assert "onedrive" not in output
+
+
 def test_ps_command_reports_empty_workspace(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,