rosotacom-dev 2.5.dev69__tar.gz → 2.5.dev71__tar.gz

{rosotacom_dev-2.5.dev69 → rosotacom_dev-2.5.dev71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev69
+Version: 2.5.dev71
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev69 → rosotacom_dev-2.5.dev71}/docs/ota-pcap.md

@@ -87,6 +87,16 @@ reached the packet.
 }
 ```
 
+`stopped_because` reads `running` until something stops the capture, and that
+is deliberate: **neither file depends on a clean shutdown.** A session usually
+ends by its container being stopped, which does not reach this process as a
+signal it can act on — the first bench run ended exactly that way and left a
+pcap truncated at a buffer boundary and no sidecar at all. The pcap is flushed
+once a second and the sidecar is written at the start and rewritten on the same
+interval, so a killed capture still leaves a readable file and a description of
+it. Verified by `SIGKILL`ing a running capture: `capinfos` reads the pcap and
+the sidecar reports the packets up to the last checkpoint.
+
 **`kernel_drops` is a gap in the file, not on the link.** A capture that fell
 behind looks exactly like radio loss to anyone reading the pcap months later,
 so subtract it before reading any loss out of the capture. Zero is the normal
@@ -140,6 +150,13 @@ thread, so a capture that misbehaves cannot reach the snapshot an operator is
 watching. It is stopped with `SIGINT` and waited for, because that is what
 writes the sidecar JSON.
 
+It is launched by **file path**, not as `python3 -m com_py.ota_pcap`. sudo
+resets the environment, so `PYTHONPATH` does not survive it and the package is
+not importable on the other side — which is what a two-host run answered,
+`No module named 'com_py'`, once the permission problem was out of the way.
+`ota_pcap.py` imports nothing but the standard library, so a path needs no
+package at all, and a test pins that it stays that way.
+
 ## Cost
 
 Header-only at 96 bytes: about 6 MB per minute at 500 packets/s, so a two-hour

{rosotacom_dev-2.5.dev69 → rosotacom_dev-2.5.dev71}/src/rosotacom/resources/ws/ros2src/com_py/com_py/ota_pcap.py

@@ -79,6 +79,15 @@ A capture that quietly drops packets is worse than none: the analysis would
 read the gap as radio loss. So `PACKET_STATISTICS` is read from the kernel and
 the sidecar `.json` reports `kernel_drops` next to `packets`. A non-zero drop
 count means this process fell behind, not that the link did.
+
+Neither file depends on a clean shutdown, and that is deliberate. A session
+usually ends by the container being stopped, which does not reach this process
+as a signal it can act on — the first bench run ended exactly that way and left
+a pcap truncated at a buffer boundary and no sidecar at all. So the pcap is
+flushed on an interval and the sidecar is written at the *start* and rewritten
+on the same interval, with `stopped_because: "running"` until something stops
+it. A killed capture therefore still leaves a readable pcap and a sidecar that
+says what it was and how much it had seen, rather than an unexplained file.
 """
 
 from __future__ import annotations
@@ -135,6 +144,12 @@ DEFAULT_MAX_MB = 2000
 #: is where `kernel_drops` comes from on a burst.
 RCVBUF_BYTES = 4 << 20
 
+#: How often the pcap is flushed and the sidecar rewritten. A session that ends
+#: by having its container stopped never reaches this process, so what is on
+#: disk at any moment is what the run will be read from. One second costs a
+#: ~300-byte write and bounds the loss to the packets of that second.
+CHECKPOINT_S = 1.0
+
 
 def log(message: str) -> None:
     print(f"[ota_pcap] {message}", flush=True)
@@ -326,7 +341,7 @@ class Capture:
         self.kernel_seen = 0
         self.first_ts: float | None = None
         self.last_ts: float | None = None
-        self.stopped_because = "signal"
+        self.stopped_because = "running"
 
     def sidecar(self) -> dict:
         """What the file is, and what it is missing. Written next to the pcap."""
@@ -348,6 +363,14 @@ class Capture:
             "stopped_because": self.stopped_because,
         }
 
+    def write_sidecar(self) -> None:
+        """The sidecar as of now. Cheap enough to call on every checkpoint."""
+        try:
+            self.out.with_suffix(".json").write_text(
+                json.dumps(self.sidecar(), indent=2) + "\n", encoding="utf-8")
+        except OSError as error:
+            log(f"WARN could not write the sidecar: {error}")
+
     def run(self, stop: list) -> None:
         sock = open_socket(self.iface)
         # Root was needed for that one call and for nothing after it.
@@ -360,8 +383,22 @@ class Capture:
         with open(self.out, "wb", buffering=1 << 20) as handle:
             handle.write(pcap_header(self.snaplen))
             self.bytes_written = 24
+            handle.flush()
+            # Written before a single packet arrives, so a capture that is
+            # killed with its container still explains itself.
+            self.write_sidecar()
+            next_checkpoint = time.monotonic() + CHECKPOINT_S
             sock.settimeout(0.5)
             while not stop:
+                # `tick`, not `now`: the timestamp fallback below rebinds `now`
+                # to wall-clock time, and comparing that against a monotonic
+                # deadline would checkpoint on every single packet.
+                tick = time.monotonic()
+                if tick >= next_checkpoint:
+                    next_checkpoint = tick + CHECKPOINT_S
+                    self._collect(sock)
+                    handle.flush()
+                    self.write_sidecar()
                 try:
                     packet, ancdata, _flags, address = sock.recvmsg(65535, ancillary)
                 except socket.timeout:
@@ -395,8 +432,9 @@ class Capture:
                         f"after {self.packets} packets — the recording is untouched")
                     self.stopped_because = "size ceiling"
                     break
-                if self.packets % 20000 == 0:
-                    self._collect(sock)
+            handle.flush()
+        if self.stopped_because == "running":
+            self.stopped_because = "signal"
         self._collect(sock)
         sock.close()
 
@@ -445,9 +483,8 @@ def main(argv: list[str] | None = None) -> int:
         log(f"FAIL {error}")
         return 3
 
+    capture.write_sidecar()
     sidecar = capture.sidecar()
-    args.out.with_suffix(".json").write_text(
-        json.dumps(sidecar, indent=2) + "\n", encoding="utf-8")
     log(f"{sidecar['packets']} packets, {sidecar['bytes'] / 1e6:.1f} MB, "
         f"{sidecar['kernel_drops']} dropped by the kernel")
     if sidecar["kernel_drops"]:

{rosotacom_dev-2.5.dev69 → rosotacom_dev-2.5.dev71}/src/rosotacom/resources/ws/ros2src/com_py/com_py/status_overview.py

@@ -58,6 +58,7 @@ import signal
 import subprocess
 import sys
 import threading
+from pathlib import Path
 from typing import Dict, Optional
 
 import yaml
@@ -558,8 +559,21 @@ class StatusOverview(Node):
             return
 
         path = os.path.join(output_dir, "ota.pcap")
+        # By file path, not `-m com_py.ota_pcap`. sudo resets the environment,
+        # so PYTHONPATH does not survive and the package is not importable on
+        # the other side of it — a two-host run answered exactly that,
+        # "No module named 'com_py'", after the permission problem was fixed.
+        # `ota_pcap.py` imports nothing but the standard library (a test pins
+        # that), so a path needs no package at all.
+        script = Path(__file__).resolve().with_name("ota_pcap.py")
+        if not script.is_file():
+            self.get_logger().warning(
+                f"status_overview: ota_pcap is enabled but {script} is not here; "
+                "capturing nothing"
+            )
+            return
         argv = [
-            sys.executable, "-m", "com_py.ota_pcap",
+            sys.executable, str(script),
             "--iface", interface,
             "--out", path,
             "--snaplen", str(int(self.get_parameter("ota_pcap_snaplen").value)),

{rosotacom_dev-2.5.dev69 → rosotacom_dev-2.5.dev71}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev69
+Version: 2.5.dev71
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev69 → rosotacom_dev-2.5.dev71}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 69,
-  "node": "g429a2536fa56d96c76f3c306809f3dc6864f051e",
+  "distance": 71,
+  "node": "gbdc19f9281e1d18fdd99cbb852a3a652d45f9de3",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{rosotacom_dev-2.5.dev69 → rosotacom_dev-2.5.dev71}/tests/unit/test_ota_pcap.py

@@ -11,6 +11,7 @@ Three layers, like the status overview it is started beside:
 from __future__ import annotations
 
 import importlib.util
+import json
 import socket
 import struct
 import sys
@@ -345,6 +346,10 @@ def test_the_node_launches_it_through_sudo_and_hands_root_straight_back() -> Non
     source because the node needs rclpy, which the host suite does not have."""
     source = (WS_PY / "com_py" / "status_overview.py").read_text(encoding="utf-8")
     assert 'argv = ["sudo", "-n", *argv]' in source
+    # By path, never `-m`: sudo resets the environment, so PYTHONPATH does not
+    # reach the other side of it and the package is not importable there.
+    assert '"-m", "com_py.ota_pcap"' not in source
+    assert 'Path(__file__).resolve().with_name("ota_pcap.py")' in source
     assert '"--drop-to", f"{os.getuid()}:{os.getgid()}"' in source
     # And the stop goes the same way: the child is root, so an ordinary kill
     # would be refused — and it must be SIGINT, which is what writes ota.json.
@@ -355,3 +360,44 @@ def test_the_capture_is_a_process_not_a_thread_in_the_status_node() -> None:
     """A capture that misbehaves must not reach the snapshot an operator watches."""
     source = (WS_PY / "com_py" / "status_overview.py").read_text(encoding="utf-8")
     assert "subprocess.Popen(argv, start_new_session=True)" in source
+
+
+# ---------------------------------------------------------------------------
+# neither file depends on a clean shutdown
+# ---------------------------------------------------------------------------
+
+
+def test_the_sidecar_says_running_until_something_stops_the_capture() -> None:
+    """A session usually ends by its container being stopped, which never
+    reaches this process. So the sidecar exists from the first moment and says
+    what it is, rather than appearing only if the capture is asked nicely."""
+    capture = ota_pcap.Capture("tun0", Path("/tmp/x.pcap"))
+    assert capture.sidecar()["stopped_because"] == "running"
+
+
+def test_the_sidecar_is_written_before_a_single_packet_arrives(tmp_path: Path) -> None:
+    capture = ota_pcap.Capture("tun0", tmp_path / "ota.pcap")
+    capture.write_sidecar()
+    written = json.loads((tmp_path / "ota.json").read_text(encoding="utf-8"))
+    assert written["interface"] == "tun0"
+    assert written["packets"] == 0
+    assert written["stopped_because"] == "running"
+
+
+def test_a_sidecar_that_cannot_be_written_is_a_warning_not_a_crash(tmp_path: Path, capsys) -> None:
+    """The capture is the artifact; its description is not worth losing it for."""
+    capture = ota_pcap.Capture("tun0", tmp_path / "no" / "such" / "dir" / "ota.pcap")
+    capture.write_sidecar()
+    assert "WARN" in capsys.readouterr().out
+
+
+def test_the_capture_checkpoints_rather_than_trusting_the_shutdown() -> None:
+    source = (WS_PY / "com_py" / "ota_pcap.py").read_text(encoding="utf-8")
+    assert "CHECKPOINT_S" in source
+    body = source[source.index("def run(self, stop") : source.index("def _collect")]
+    assert "handle.flush()" in body
+    assert "self.write_sidecar()" in body
+    # And the deadline is monotonic, compared against a name the timestamp
+    # fallback cannot rebind — that collision would checkpoint every packet.
+    assert "tick = time.monotonic()" in body
+    assert "if tick >= next_checkpoint:" in body