rosotacom-dev 2.5.dev52__tar.gz → 2.5.dev54__tar.gz

{rosotacom_dev-2.5.dev52 → rosotacom_dev-2.5.dev54}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev52
+Version: 2.5.dev54
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -309,6 +309,24 @@ rosotacom start 1_heartbeat --identity b \
   --peer-address a=10.0.0.10 --peer-address b=10.0.0.11
 ```
 
+Before `start` stops a conflicting container, writes an instance, or builds an
+image, it verifies that the selected identity's address belongs to this host and
+that the route to the other peer selects that address as its source. A missing
+VPN/data-plane interface or a route through the wrong network therefore fails
+without disturbing a working session. Run the same check on its own with
+`preflight`; deployments that require the other host to be online already can
+also make three bounded ICMP probes mandatory:
+
+```bash
+rosotacom preflight 1_heartbeat --identity a \
+  --peer-address a=10.0.0.10 --peer-address b=10.0.0.11 \
+  --require-peer-reachable
+```
+
+Peer reachability is opt-in because some valid networks block ICMP and peers may
+be started in either order. `rosotacom start` accepts the same
+`--require-peer-reachable` policy when a deployment does require it.
+
 `rosotacom` reads the static session input and creates generated files under `session-instances/<date>/<session>_<timestamp>_<id>/config/`, including per-peer plugin/session specs, topic lists, optional QoS, and optional `domain_bridge.yaml`. Catmux pane output is logged under the same instance in `logs/<peer>/catmux/`.
 
 What else a run leaves under `logs/<peer>/`, and which file to open first when a

{rosotacom_dev-2.5.dev52 → rosotacom_dev-2.5.dev54}/README.md

@@ -264,6 +264,24 @@ rosotacom start 1_heartbeat --identity b \
   --peer-address a=10.0.0.10 --peer-address b=10.0.0.11
 ```
 
+Before `start` stops a conflicting container, writes an instance, or builds an
+image, it verifies that the selected identity's address belongs to this host and
+that the route to the other peer selects that address as its source. A missing
+VPN/data-plane interface or a route through the wrong network therefore fails
+without disturbing a working session. Run the same check on its own with
+`preflight`; deployments that require the other host to be online already can
+also make three bounded ICMP probes mandatory:
+
+```bash
+rosotacom preflight 1_heartbeat --identity a \
+  --peer-address a=10.0.0.10 --peer-address b=10.0.0.11 \
+  --require-peer-reachable
+```
+
+Peer reachability is opt-in because some valid networks block ICMP and peers may
+be started in either order. `rosotacom start` accepts the same
+`--require-peer-reachable` policy when a deployment does require it.
+
 `rosotacom` reads the static session input and creates generated files under `session-instances/<date>/<session>_<timestamp>_<id>/config/`, including per-peer plugin/session specs, topic lists, optional QoS, and optional `domain_bridge.yaml`. Catmux pane output is logged under the same instance in `logs/<peer>/catmux/`.
 
 What else a run leaves under `logs/<peer>/`, and which file to open first when a

{rosotacom_dev-2.5.dev52 → rosotacom_dev-2.5.dev54}/deployment-configuration.md

@@ -85,6 +85,29 @@ Precedence is explicit:
 All logical peers must resolve to addresses before a session starts. Session
 definitions do not accept physical addresses or SSH targets.
 
+## Data-plane preflight
+
+`rosotacom start` checks the resolved bindings against the host before it stops
+or creates containers:
+
+1. The selected identity's IPv4 address must be assigned locally.
+2. `ip route get` for the other peer must select that same address as its
+   source.
+
+This makes an absent VPN/interface, a wrong identity, and a route escaping over
+another network startup errors instead of silent communication failures. Inspect
+the result without starting anything:
+
+```bash
+rosotacom preflight SESSION --identity PEER
+```
+
+Add `--require-peer-reachable` to `preflight` or `start` when this deployment
+also requires three bounded ICMP probes to succeed. Reachability is not the
+global default: ICMP can be intentionally filtered, and valid peers can be
+started in either order. Docker-isolated local smoke networks use their own
+network lifecycle and bypass this host data-plane check.
+
 ## Project selection and completion
 
 The nearest `rosotacom.yaml` is discovered upward from the current directory.

{rosotacom_dev-2.5.dev52 → rosotacom_dev-2.5.dev54}/session-configuration.md

@@ -674,6 +674,7 @@ Declaratively, add a `playout` block to the transport:
             target_ms: 350    # fixed budget when adaptive: false
             min_ms: 100       # adaptive clamp above the observed delay floor
             max_ms: 800
+            republish: paced  # paced (default) | unpaced | both
 ```
 
 The receiving peer then runs the pacer in its own `PACE` window against the
@@ -684,6 +685,33 @@ why `playout` requires `remote_republish`: without a republish the pacer's
 The sender's own preview decode (`local_republish`) is never paced — it reads
 the local copy of what was just encoded, so there is no jitter to absorb.
 
+##### `republish`: which stream reaches the display
+
+Pacing under an unchanged topic name is what keeps applications working, and it
+is also what makes the improvement invisible — nothing shows paced and unpaced
+together. `republish` names which stream the receiver decodes:
+
+| value | decodes | publishes |
+|---|---|---|
+| `paced` (default) | `<encoded>/paced` | `<encoded>/<remote_republish>` |
+| `unpaced` | `<encoded>` | `<encoded>/<remote_republish>` |
+| `both` | both | delivered as above, comparison on `<encoded>/unpaced/<remote_republish>` |
+
+**The delivered name is the same in all three.** Only what feeds the decode
+moves, so switching modes never changes what an application subscribes to.
+
+`unpaced` still runs the pacer: `/paced` and its `budget_ms` / `queue_depth`
+debug topics are published and recordable, they just do not reach the display.
+That is the A/B control — measure a pacer on a live link without changing what
+an operator sees.
+
+`both` runs the receiver's expensive stage twice (a codec decode plus, for
+`compressed`, a JPEG encode per frame) and adds one local topic; nothing extra
+crosses the link. It also consumes one of the four reverse-transport slots. It
+is a rehearsal and diagnosis switch — the comparison stream is deliberately not
+a status pipeline stage, because it is not something the link promises to
+deliver.
+
 The node also runs standalone against any packet stream:
 
 ```bash

{rosotacom_dev-2.5.dev52 → rosotacom_dev-2.5.dev54}/src/rosotacom/cli.py

@@ -64,6 +64,7 @@ from .image_cache import (
     image_fingerprint,
     reference_tag,
 )
+from .network_preflight import NetworkPreflightResult, run_network_preflight
 
 anonymize_lib = importlib.import_module("rosotacom.anonymize")
 
@@ -1125,7 +1126,7 @@ def _get_local_ipv4s() -> list[str]:
         out = subprocess.check_output(["ip", "-o", "-4", "addr", "show"], text=True)
     except Exception:
         return []
-    return _IPV4_RE.findall(out)
+    return re.findall(r"\binet\s+(\d+\.\d+\.\d+\.\d+)/", out)
 
 
 def _default_local_ip() -> str:
@@ -1234,6 +1235,29 @@ def _auto_identity(bindings: dict[str, PeerBinding]) -> str:
     raise RuntimeError(f"Auto identity ambiguous: matched peers={matches} for local IPv4s={sorted(local_ips)}.")
 
 
+def _network_preflight(
+    bindings: dict[str, PeerBinding],
+    identity: str,
+    *,
+    require_peer_reachable: bool = False,
+) -> NetworkPreflightResult:
+    return run_network_preflight(
+        bindings,
+        identity,
+        local_addresses=_get_local_ipv4s(),
+        require_peer_reachable=require_peer_reachable,
+    )
+
+
+def _print_network_preflight(result: NetworkPreflightResult) -> None:
+    reachability = "peer reachable" if result.peer_reachable else "route verified"
+    print(
+        f"Network preflight OK: {result.identity} ({result.local_address}) -> "
+        f"{result.remote_identity} ({result.remote_address}) via {result.interface} "
+        f"src {result.source_address}; {reachability}."
+    )
+
+
 def _peer_com_name(peers: dict[str, Any], peer_key: str) -> str:
     value = (peers.get(peer_key) or {}).get("com-name")
     if value is None:
@@ -5123,10 +5147,18 @@ def start_session(args: argparse.Namespace) -> str:
     identity = args.identity or _auto_identity(bindings)
     if not args.identity:
         print(f"Auto-selected identity: {identity}")
+    network_isolated = bool(getattr(args, "network_name", None))
+    if not network_isolated:
+        _print_network_preflight(
+            _network_preflight(
+                bindings,
+                identity,
+                require_peer_reachable=getattr(args, "require_peer_reachable", False),
+            )
+        )
     remote_name = _remote_peer_name(cfg, identity)
     instance = _resolve_session_instance(runtime, session, getattr(args, "instance_id", None))
     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):
         matching = _matching_com_containers(runtime, remote_name)
         if _fixed_com_container_name(runtime, remote_name) is not None:
@@ -5235,6 +5267,30 @@ def start_session(args: argparse.Namespace) -> str:
     return container_name
 
 
+def preflight_session(args: argparse.Namespace) -> NetworkPreflightResult:
+    runtime = _load_runtime_config(args)
+    session = _resolve_session(args.session_dir, runtime)
+    cfg = _effective_session_config(session.host_dir, runtime)
+    bindings = _resolve_bindings(
+        cfg,
+        runtime,
+        peer=getattr(args, "peer", None),
+        peer_address=getattr(args, "peer_address", None),
+    )
+    if not args.identity and not getattr(args, "auto_identity", True):
+        raise RuntimeError("Missing --identity. Provide --identity <peer> or allow auto identity.")
+    identity = args.identity or _auto_identity(bindings)
+    if not args.identity:
+        print(f"Auto-selected identity: {identity}")
+    result = _network_preflight(
+        bindings,
+        identity,
+        require_peer_reachable=getattr(args, "require_peer_reachable", False),
+    )
+    _print_network_preflight(result)
+    return result
+
+
 def stop_session(args: argparse.Namespace) -> None:
     runtime = _load_runtime_config(args)
     session = _resolve_session(args.session_dir, runtime)
@@ -8668,6 +8724,11 @@ def _add_start_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--rewrite-formatting", action="store_true")
     _add_peer_arg(parser)
     _add_peer_address_arg(parser)
+    parser.add_argument(
+        "--require-peer-reachable",
+        action="store_true",
+        help="Require three bounded ICMP probes to the peer to succeed before starting.",
+    )
     parser.add_argument("--instance-id", help="Join or create a named runtime session instance.")
     parser.add_argument(
         "--skip-conflict-check",
@@ -8681,6 +8742,22 @@ def _add_start_args(parser: argparse.ArgumentParser) -> None:
     parser.set_defaults(force=True, auto_identity=True)
 
 
+def _add_preflight_args(parser: argparse.ArgumentParser) -> None:
+    _add_common_config_args(parser)
+    _add_session_arg(parser, "session_dir_positional", nargs="?")
+    _add_session_arg(parser, "-s", "--session-dir", dest="session_dir")
+    _add_identity_arg(parser)
+    parser.add_argument("--no-auto-identity", dest="auto_identity", action="store_false")
+    _add_peer_arg(parser)
+    _add_peer_address_arg(parser)
+    parser.add_argument(
+        "--require-peer-reachable",
+        action="store_true",
+        help="Require three bounded ICMP probes to the peer to succeed.",
+    )
+    parser.set_defaults(auto_identity=True)
+
+
 def _normalize_session_arg(args: argparse.Namespace) -> None:
     positional = getattr(args, "session_dir_positional", None)
     explicit = getattr(args, "session_dir", None)
@@ -8697,6 +8774,12 @@ def start_command(args: argparse.Namespace) -> int:
     return 0
 
 
+def preflight_command(args: argparse.Namespace) -> int:
+    _normalize_session_arg(args)
+    preflight_session(args)
+    return 0
+
+
 def stop_command(args: argparse.Namespace) -> int:
     _normalize_session_arg(args)
     stop_session(args)
@@ -9052,6 +9135,7 @@ def videoquality_command(args: argparse.Namespace) -> int:
 # turn into `rosotacom start foo` — so a contract test keeps the two in sync.
 TOP_LEVEL_COMMANDS = {
     "start",
+    "preflight",
     "stop",
     "doctor",
     "ps",
@@ -9127,6 +9211,13 @@ def main(argv: list[str] | None = None) -> int:
     _add_start_args(start_parser)
     start_parser.set_defaults(func=start_command)
 
+    preflight_parser = subparsers.add_parser(
+        "preflight",
+        help="Validate the resolved local address, peer route, and optional peer reachability.",
+    )
+    _add_preflight_args(preflight_parser)
+    preflight_parser.set_defaults(func=preflight_command)
+
     stop_parser = subparsers.add_parser("stop", help="Stop rosotacom containers for a session.")
     _add_common_config_args(stop_parser)
     _add_session_arg(stop_parser, "session_dir_positional", nargs="?")

rosotacom_dev-2.5.dev54/src/rosotacom/network_preflight.py

@@ -0,0 +1,134 @@
+"""Host data-plane validation for resolved communication peers."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import subprocess
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from .deployment import PeerBinding
+
+
+@dataclass(frozen=True)
+class NetworkPreflightResult:
+    identity: str
+    local_address: str
+    remote_identity: str
+    remote_address: str
+    interface: str
+    source_address: str
+    peer_reachable: bool | None
+
+
+def _binding_ipv4(binding: PeerBinding, *, role: str) -> str:
+    try:
+        return str(ipaddress.IPv4Address(binding.address))
+    except ipaddress.AddressValueError as exc:
+        raise RuntimeError(
+            f"Network preflight failed: {role} peer {binding.peer!r} has non-IPv4 address "
+            f"{binding.address!r}. Communication peer addresses must be concrete IPv4 addresses."
+        ) from exc
+
+
+def run_network_preflight(
+    bindings: dict[str, PeerBinding],
+    identity: str,
+    *,
+    local_addresses: Iterable[str],
+    require_peer_reachable: bool = False,
+) -> NetworkPreflightResult:
+    """Validate the selected local binding and kernel path to its peer."""
+    if identity not in bindings:
+        raise RuntimeError(f"Network preflight failed: identity {identity!r} is not one of peers={sorted(bindings)}.")
+    if len(bindings) != 2:
+        raise RuntimeError(f"Network preflight failed: expected exactly 2 peers, got peers={sorted(bindings)}.")
+
+    local = bindings[identity]
+    remote_identity = next(peer for peer in bindings if peer != identity)
+    remote = bindings[remote_identity]
+    local_address = _binding_ipv4(local, role="local")
+    remote_address = _binding_ipv4(remote, role="remote")
+
+    known_local_addresses = sorted(set(local_addresses))
+    if not known_local_addresses:
+        raise RuntimeError(
+            "Network preflight failed: could not determine any local IPv4 addresses. "
+            "Verify that the `ip` command is installed and the required data-plane interface is up."
+        )
+    if local_address not in known_local_addresses:
+        raise RuntimeError(
+            f"Network preflight failed for identity {identity!r}: configured local address {local_address} "
+            f"is not assigned to this host (local IPv4s: {known_local_addresses}). "
+            "Verify --identity and the peer bindings; if the address belongs to a VPN or other data-plane "
+            "interface, bring that interface up before starting communication."
+        )
+
+    try:
+        route = subprocess.run(
+            ["ip", "-4", "route", "get", remote_address],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError("Network preflight failed: required command `ip` was not found.") from exc
+    route_output = (route.stdout or "").strip()
+    if route.returncode != 0 or not route_output:
+        detail = (route.stderr or route.stdout or "no route returned").strip()
+        raise RuntimeError(
+            f"Network preflight failed: no usable IPv4 route from {identity!r} ({local_address}) "
+            f"to {remote_identity!r} ({remote_address}): {detail}"
+        )
+    route_line = route_output.splitlines()[0]
+    source_match = re.search(r"\bsrc\s+(\d+\.\d+\.\d+\.\d+)\b", route_line)
+    interface_match = re.search(r"\bdev\s+(\S+)", route_line)
+    if source_match is None or interface_match is None:
+        raise RuntimeError(
+            f"Network preflight failed: could not determine source address and interface from route: {route_line}"
+        )
+    source_address = source_match.group(1)
+    interface = interface_match.group(1)
+    if source_address != local_address:
+        raise RuntimeError(
+            f"Network preflight failed: route to {remote_identity!r} ({remote_address}) uses source "
+            f"{source_address} on {interface}, but identity {identity!r} is bound to {local_address}. "
+            "Fix the route or peer binding before starting communication."
+        )
+
+    peer_reachable: bool | None = None
+    if require_peer_reachable:
+        try:
+            ping = subprocess.run(
+                ["ping", "-4", "-n", "-c", "3", "-W", "2", "-I", local_address, remote_address],
+                text=True,
+                capture_output=True,
+                check=False,
+                timeout=10,
+            )
+        except FileNotFoundError as exc:
+            raise RuntimeError(
+                "Network preflight failed: strict peer reachability was requested, but `ping` was not found."
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(
+                f"Network preflight failed: ICMP check from {local_address} to {remote_address} exceeded 10 seconds."
+            ) from exc
+        if ping.returncode != 0:
+            raise RuntimeError(
+                f"Network preflight failed: peer {remote_identity!r} ({remote_address}) did not answer "
+                f"3 ICMP echo requests sent from {local_address} via {interface}. This start requires an "
+                "already-reachable peer; verify the data plane, VPN, and firewall."
+            )
+        peer_reachable = True
+
+    return NetworkPreflightResult(
+        identity=identity,
+        local_address=local_address,
+        remote_identity=remote_identity,
+        remote_address=remote_address,
+        interface=interface,
+        source_address=source_address,
+        peer_reachable=peer_reachable,
+    )

{rosotacom_dev-2.5.dev52 → rosotacom_dev-2.5.dev54}/src/rosotacom/resources/ws/session/content/base/session_plugin_base.yaml

@@ -230,22 +230,32 @@ parameters:
   it_4_foxglove_qmax: -1
   it_4_outgoing_suffix: # e.g. compressed (defaults to it_4_transport if not set)
 
+  # `irt_N_out_topic` overrides where a decode publishes. It exists so two slots
+  # can decode the *same* stream — the paced one under the name applications
+  # already subscribe to, an unpaced copy next to it for comparison
+  # (transport.playout.republish: both). Left unset, a decode publishes on
+  # ${irt_N_topic}/${irt_N_out_transport}, which is the only shape any session
+  # had before and the one every unpaced link still has.
   irt: false
   irt_1_topic: # e.g. /sensors/camera/front_wide/image_color
   irt_1_transport: # e.g. raw
   irt_1_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_1_out_topic: # overrides the output remap; defaults to ${irt_1_topic}/${irt_1_out_transport}
   irt_1_paced: # "true" -> decode reads ${irt_1_topic}/paced (playout pacer, PACE window)
   irt_2_topic: # e.g. /sensors/front_camera/image_raw/compressed
   irt_2_transport: # e.g. raw
   irt_2_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_2_out_topic: # overrides the output remap; defaults to ${irt_2_topic}/${irt_2_out_transport}
   irt_2_paced: # "true" -> decode reads ${irt_2_topic}/paced
   irt_3_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_3_transport: # e.g. raw
   irt_3_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_3_out_topic: # overrides the output remap; defaults to ${irt_3_topic}/${irt_3_out_transport}
   irt_3_paced: # "true" -> decode reads ${irt_3_topic}/paced
   irt_4_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_4_transport: # e.g. raw
   irt_4_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_4_out_topic: # overrides the output remap; defaults to ${irt_4_topic}/${irt_4_out_transport}
   irt_4_paced: # "true" -> decode reads ${irt_4_topic}/paced
 
   # Receiver-side playout pacing (transport.playout in the session definition):
@@ -707,31 +717,35 @@ windows:
         - if [ '${irt_1_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_1_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_1_out_transport}"; fi
         - if [[ "${irt_1_paced}" != "None" ]]; then irt_in_topic="${irt_1_topic}/paced"; else irt_in_topic="${irt_1_topic}"; fi
+        - if [[ "${irt_1_out_topic}" != "None" ]]; then irt_out_topic="${irt_1_out_topic}"; else irt_out_topic="${irt_1_topic}/${irt_1_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish1 -p in_transport:=${irt_1_transport} -p out_transport:=${irt_1_out_transport}
-            --remap in/${irt_1_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_1_topic}/${irt_1_out_transport})
+            --remap in/${irt_1_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_2_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_2_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_2_out_transport}"; fi
         - if [[ "${irt_2_paced}" != "None" ]]; then irt_in_topic="${irt_2_topic}/paced"; else irt_in_topic="${irt_2_topic}"; fi
+        - if [[ "${irt_2_out_topic}" != "None" ]]; then irt_out_topic="${irt_2_out_topic}"; else irt_out_topic="${irt_2_topic}/${irt_2_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish2 -p in_transport:=${irt_2_transport} -p out_transport:=${irt_2_out_transport}
-            --remap in/${irt_2_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_2_topic}/${irt_2_out_transport})
+            --remap in/${irt_2_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_3_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_3_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_3_out_transport}"; fi
         - if [[ "${irt_3_paced}" != "None" ]]; then irt_in_topic="${irt_3_topic}/paced"; else irt_in_topic="${irt_3_topic}"; fi
+        - if [[ "${irt_3_out_topic}" != "None" ]]; then irt_out_topic="${irt_3_out_topic}"; else irt_out_topic="${irt_3_topic}/${irt_3_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish3 -p in_transport:=${irt_3_transport} -p out_transport:=${irt_3_out_transport}
-            --remap in/${irt_3_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_3_topic}/${irt_3_out_transport})
+            --remap in/${irt_3_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_4_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_4_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_4_out_transport}"; fi
         - if [[ "${irt_4_paced}" != "None" ]]; then irt_in_topic="${irt_4_topic}/paced"; else irt_in_topic="${irt_4_topic}"; fi
+        - if [[ "${irt_4_out_topic}" != "None" ]]; then irt_out_topic="${irt_4_out_topic}"; else irt_out_topic="${irt_4_topic}/${irt_4_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish4 -p in_transport:=${irt_4_transport} -p out_transport:=${irt_4_out_transport}
-            --remap in/${irt_4_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_4_topic}/${irt_4_out_transport})
+            --remap in/${irt_4_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}

{rosotacom_dev-2.5.dev52 → rosotacom_dev-2.5.dev54}/src/rosotacom/resources/ws/session/creation/generate_session_files.py

@@ -101,6 +101,44 @@ class TransportSpec:
     playout: Optional[Dict[str, Any]] = None
 
 
+#: What `transport.playout.republish` may say, and what each answer decodes.
+#: The delivered topic name is the same in all three -- only what feeds the
+#: decode moves, and `both` adds a second decode under a name of its own.
+PLAYOUT_REPUBLISH_MODES = ("paced", "unpaced", "both")
+PLAYOUT_REPUBLISH_DEFAULT = "paced"
+
+
+def playout_republish(playout: Dict[str, Any]) -> str:
+    """Which stream the receiver decodes, for a link that declares `playout`.
+
+    Only meaningful where a pacer runs. A link without `playout` has no paced
+    copy to read, so callers decide that case before asking -- passing None here
+    would answer 'paced' for a stream nothing paces.
+    """
+    return str((playout or {}).get("republish", PLAYOUT_REPUBLISH_DEFAULT))
+
+
+@dataclass
+class IrtSlot:
+    """One reverse-transport decode: what it reads, and where it publishes.
+
+    Four of these fit in the base plugin. Most links use one per direction, but
+    a comparison decode (`playout.republish: both`) is a second slot on the same
+    topic -- which is the only reason `out_topic` exists, since two decodes of
+    one stream would otherwise remap onto the same output name.
+    """
+
+    topic: str
+    ttype: str
+    out_transport: str
+    #: Set only for the slot that a pacer feeds; the pacer is configured from it.
+    playout: Optional[Dict[str, Any]] = None
+    #: Read '<topic>/paced' rather than '<topic>'.
+    reads_paced: bool = False
+    #: Override the output remap; None means '<topic>/<out_transport>'.
+    out_topic: Optional[str] = None
+
+
 @dataclass
 class TopicEntry:
     base: str
@@ -1746,7 +1784,7 @@ def _compute_pipeline(
         if playout_cfg is not None:
             if not isinstance(playout_cfg, dict):
                 raise ValueError(f"transport.playout must be a mapping for topic '{entry.base}'")
-            allowed = {"adaptive", "target_ms", "min_ms", "max_ms"}
+            allowed = {"adaptive", "target_ms", "min_ms", "max_ms", "republish"}
             unknown = sorted(set(playout_cfg) - allowed)
             if unknown:
                 raise ValueError(
@@ -1769,6 +1807,15 @@ def _compute_pipeline(
                 raise ValueError(f"transport.playout.max_ms must be >= min_ms for topic '{entry.base}'")
             if "adaptive" in playout_cfg and not isinstance(playout_cfg["adaptive"], bool):
                 raise ValueError(f"transport.playout.adaptive must be a boolean for topic '{entry.base}'")
+            if "republish" in playout_cfg and playout_cfg["republish"] not in PLAYOUT_REPUBLISH_MODES:
+                raise ValueError(
+                    f"transport.playout.republish for topic '{entry.base}' is "
+                    f"{playout_cfg['republish']!r}; allowed: {list(PLAYOUT_REPUBLISH_MODES)}. "
+                    "'paced' decodes the paced copy (the default), 'unpaced' runs the pacer "
+                    "without putting it on the display path, and 'both' adds a second decode "
+                    "on '<encoded>/unpaced/<transport>' for comparison. The delivered topic "
+                    "name is the same in all three."
+                )
             playout = dict(playout_cfg)
 
         params = {k: v for k, v in t.items() if k not in ("type", "playout", *republish_keys)}
@@ -2781,11 +2828,12 @@ def func(
             nor_items.append((base, suffix))
 
         # Hard limits from session_plugin_base.yaml.
-        def _assert_max(label: str, items: List[Any], limit: int) -> None:
+        def _assert_max(label: str, items: List[Any], limit: int, note: str = "") -> None:
             if len(items) > limit:
                 raise RuntimeError(
                     f"peer '{local}': too many '{label}' entries ({len(items)}). "
                     f"The base session plugin supports at most {limit}."
+                    + (f" Note: {note}." if note else "")
                 )
 
         _assert_max("drp", drp_items, 8)
@@ -3319,31 +3367,58 @@ def func(
         # The sender's own preview decode is never paced: it reads the local
         # copy of what it just encoded, so there is no network jitter to
         # absorb. Playout pacing exists on the receiving side only.
-        irt_all: List[Tuple[str, str, str, Optional[Dict[str, Any]]]] = []
+        irt_all: List[IrtSlot] = []
         for t, tspec in irt_items_local:
             assert tspec is not None
-            irt_all.append((t, tspec.type, str(tspec.local_republish), None))
-        irt_all.extend(
-            (topic, tspec.type, str(tspec.remote_republish), tspec.playout) for topic, tspec in irt_items_remote
+            irt_all.append(IrtSlot(t, tspec.type, str(tspec.local_republish)))
+        for topic, tspec in irt_items_remote:
+            out_transport = str(tspec.remote_republish)
+            if tspec.playout is None:
+                # No pacer on this link: the decode reads what arrived. Asking
+                # it for '<topic>/paced' would give it a name nothing publishes,
+                # which advertises an output and then never fills it.
+                irt_all.append(IrtSlot(topic, tspec.type, out_transport))
+                continue
+            mode = playout_republish(tspec.playout)
+            # The decode an application reads keeps its name in every mode; only
+            # what feeds it moves. `unpaced` still runs the pacer -- it publishes
+            # '<topic>/paced' and its debug topics for measurement -- and simply
+            # does not put it on the display path.
+            irt_all.append(
+                IrtSlot(topic, tspec.type, out_transport, playout=tspec.playout, reads_paced=mode != "unpaced")
+            )
+            if mode == "both":
+                # The comparison branch: same stream, undelayed, under a name of
+                # its own. `<topic>/unpaced` is a valid image_transport base, so
+                # a viewer subscribes to it exactly like the delivered one.
+                irt_all.append(
+                    IrtSlot(topic, tspec.type, out_transport, out_topic=f"{topic}/unpaced/{out_transport}")
+                )
+        _assert_max(
+            "irt",
+            irt_all,
+            4,
+            note="a `playout.republish: both` comparison decode consumes a slot of its own",
         )
-        _assert_max("irt", irt_all, 4)
         if irt_all:
             items2 = [("irt", True)]
-            for i, (topic, _ttype, _out_transport, _playout) in enumerate(irt_all, 1):
-                items2.append((f"irt_{i}_topic", topic))
-            for i, (_topic, ttype, out_transport, playout) in enumerate(irt_all, 1):
-                items2.append((f"irt_{i}_transport", ttype))
-                items2.append((f"irt_{i}_out_transport", out_transport))
-                if playout is not None:
+            for i, slot in enumerate(irt_all, 1):
+                items2.append((f"irt_{i}_topic", slot.topic))
+            for i, slot in enumerate(irt_all, 1):
+                items2.append((f"irt_{i}_transport", slot.ttype))
+                items2.append((f"irt_{i}_out_transport", slot.out_transport))
+                if slot.out_topic is not None:
+                    items2.append((f"irt_{i}_out_topic", slot.out_topic))
+                if slot.reads_paced:
                     # Points the decode's input remap at '<topic>/paced'; the
                     # pacer itself runs in the PACE window below.
                     items2.append((f"irt_{i}_paced", "true"))
             blocks.append(PluginBlock("irt", items2))
 
         paced_entries = [
-            (i, topic, ttype, playout)
-            for i, (topic, ttype, _out_transport, playout) in enumerate(irt_all, 1)
-            if playout is not None
+            (i, slot.topic, slot.ttype, slot.playout)
+            for i, slot in enumerate(irt_all, 1)
+            if slot.playout is not None
         ]
         if paced_entries:
             items_pace: List[Tuple[str, Any]] = [("pace", True)]