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

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

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

{rosotacom_dev-2.5.dev70 → 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

{rosotacom_dev-2.5.dev70 → 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.dev70 → 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.dev70
+Version: 2.5.dev71
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

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

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

{rosotacom_dev-2.5.dev70 → 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
@@ -359,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