rosotacom-dev 2.5.dev52__py3-none-any.whl → 2.5.dev53__py3-none-any.whl

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/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.dist-info → rosotacom_dev-2.5.dev53.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev52
+Version: 2.5.dev53
 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.dist-info → rosotacom_dev-2.5.dev53.dist-info}/RECORD

@@ -6,7 +6,7 @@ rosotacom/benched_set.py,sha256=lBA1Rj04dbr2e-lIvYTWoL55_LdUpCAC-y7eIvJZ8lc,2721
 rosotacom/benchmark.py,sha256=3QoXJtWUGQPwvDWyQT_fOjx6K9G2pmvtnVurA21G2QY,76612
 rosotacom/benchmark_delta.py,sha256=qXzriBkbXOeJdlLKM4ziov1F-JfwlseYHE48S9hjFsQ,10005
 rosotacom/bundle_check.py,sha256=l_3BSuYk6juXQmsNU6jkxRbH8ayH2GkiW9ONKMQ1oJY,18270
-rosotacom/cli.py,sha256=P0nZ_VJFCDhaKA5-DsUJg63hnb12lVWwFwaTY2_6APY,409550
+rosotacom/cli.py,sha256=DKG6cylS_37hFe5pvIQI1y-Iq-TxmwR2zIFjuUdB-zE,412811
 rosotacom/cli_benchmark.py,sha256=0R30if8b9F4uxTX53KmUuEJ0VXcK_5RcudqR9QARV5Q,355021
 rosotacom/deployment.py,sha256=XVhB8JjxhAsglSEEPtiVSeV6fCG0rgGmDRulh14oIYQ,7318
 rosotacom/ffmpeg_packet.py,sha256=zB1BHgY1kexr5sETVMkm4bkVnRytj9k2t0uOYiHUZ6M,4267
@@ -14,6 +14,7 @@ rosotacom/forensics.py,sha256=fxpjuRq3pA1wCf2ERai4SlVnNhJBqZbDh6ETRKODNd0,53576
 rosotacom/geomap.py,sha256=_85kWI-twzS3rf9KxamnFuhlw8Rp_fRk7n7xI-rUMFc,30292
 rosotacom/image_cache.py,sha256=71wC291j8rRMgF1D5pt2gTQdplmiIwnUDXk0BZoQNNQ,7185
 rosotacom/netem_dist.py,sha256=OWtc8asx-ow1wCxDoQuuJwJsFLl7F_lthLWsp-nlK-M,4642
+rosotacom/network_preflight.py,sha256=mQsjVnHP3CPDfHyLsOdobtymcYhcvJbmJRbXm9EgGDs,5532
 rosotacom/network_profiles.py,sha256=GAyVL794zQ3HnGlr1d6GoG5_qDaF5BsXwN9WRGF7kLE,31530
 rosotacom/network_shaper.py,sha256=kjn9ZtiO1SMm8UHKIjmn92JBu_hE5TJF6vaNF1XKtNU,5463
 rosotacom/plots.py,sha256=YRGRxuGHSHDZmtL0sv1JS7cPVSL9VzjGYuvMxeHAj54,22674
@@ -197,9 +198,9 @@ rosotacom/resources/ws/session/creation/generate_session_files.py,sha256=NYdRSZT
 rosotacom/resources/ws/session/creation/run_session.py,sha256=G2hJhrmLp11gm3JZ6_C-zZcqu_reXlE_wmobB7BiCfU,16849
 rosotacom/resources/ws/session/creation/run_session_in_external_terminal.py,sha256=Ub_5f-ttUUc-rAPrZmg_Op34s8Z4C91hTyEn8fgyt-E,2633
 rosotacom/resources/ws/session/creation/strip_ansi.py,sha256=vNjpemcq4xHr0VG4x0bZqvgwEBEfOgN-b4PzbrM5nfM,851
-rosotacom_dev-2.5.dev52.dist-info/licenses/LICENSE.txt,sha256=FDB3-fao3lqZ94wsJHKAH7U88kAnfvZhZC8Hm5rN__g,1459
-rosotacom_dev-2.5.dev52.dist-info/METADATA,sha256=Rk127GLA4yN5kVy3gAYi6dxfO7VENDeGb43WZxadVrQ,54535
-rosotacom_dev-2.5.dev52.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-rosotacom_dev-2.5.dev52.dist-info/entry_points.txt,sha256=im11ZWqBbgjQUBz2Ik2RNfMu54wlMwgiVpsBKeI7dCI,49
-rosotacom_dev-2.5.dev52.dist-info/top_level.txt,sha256=BZrtQcIVDWn_pQZR3Mlssqy5SaRXHjOa6B-1D9Fy4Ao,10
-rosotacom_dev-2.5.dev52.dist-info/RECORD,,
+rosotacom_dev-2.5.dev53.dist-info/licenses/LICENSE.txt,sha256=FDB3-fao3lqZ94wsJHKAH7U88kAnfvZhZC8Hm5rN__g,1459
+rosotacom_dev-2.5.dev53.dist-info/METADATA,sha256=ydDF-JJdTFmWNx_-sNEMeFbHmg2LwQ849jwxMMYRucM,55410
+rosotacom_dev-2.5.dev53.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rosotacom_dev-2.5.dev53.dist-info/entry_points.txt,sha256=im11ZWqBbgjQUBz2Ik2RNfMu54wlMwgiVpsBKeI7dCI,49
+rosotacom_dev-2.5.dev53.dist-info/top_level.txt,sha256=BZrtQcIVDWn_pQZR3Mlssqy5SaRXHjOa6B-1D9Fy4Ao,10
+rosotacom_dev-2.5.dev53.dist-info/RECORD,,