tunnelscope 0.2.1__tar.gz → 0.2.2__tar.gz

{tunnelscope-0.2.1/tunnelscope.egg-info → tunnelscope-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunnelscope
-Version: 0.2.1
+Version: 0.2.2
 Summary: Evidence-based MTU and packet-size diagnostics for Linux networks
 License-Expression: MIT
 Project-URL: Repository, https://github.com/lazypanic999/tunnelscope
@@ -22,7 +22,7 @@ Dynamic: license-file
 
 Evidence-based MTU and packet-size diagnostics for Linux networks.
 
-**Status: v0.2.1 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
+**Status: v0.2.2 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
 
 ## The problem
 
@@ -59,8 +59,8 @@ The [two-VM correlation record](https://github.com/lazypanic999/tunnelscope/blob
 The [blocked ACK return lab](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/ack-return-blocked.md) validates a receiver-observed sender timeout.
 
 Use `tunnelscope show report.json` for a short terminal table of a probe,
-bidirectional comparison, correlation, or lab report. JSON remains the
-machine-readable source of evidence.
+receiver observation, bidirectional comparison, correlation, or lab report.
+JSON remains the machine-readable source of evidence.
 
 ## Install locally
 

{tunnelscope-0.2.1 → tunnelscope-0.2.2}/README.md

@@ -6,7 +6,7 @@
 
 Evidence-based MTU and packet-size diagnostics for Linux networks.
 
-**Status: v0.2.1 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
+**Status: v0.2.2 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
 
 ## The problem
 
@@ -43,8 +43,8 @@ The [two-VM correlation record](https://github.com/lazypanic999/tunnelscope/blob
 The [blocked ACK return lab](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/ack-return-blocked.md) validates a receiver-observed sender timeout.
 
 Use `tunnelscope show report.json` for a short terminal table of a probe,
-bidirectional comparison, correlation, or lab report. JSON remains the
-machine-readable source of evidence.
+receiver observation, bidirectional comparison, correlation, or lab report.
+JSON remains the machine-readable source of evidence.
 
 ## Install locally
 

{tunnelscope-0.2.1 → tunnelscope-0.2.2}/docs/receiver-observations.md

@@ -12,6 +12,12 @@ Start the receiver on endpoint B and give it an output path:
 tunnelscope receive --bind B_IP --output receiver.json
 ```
 
+After the receiver exits, `tunnelscope show receiver.json` groups its
+observations by run ID and payload size. It shows how many probes arrived and
+how many acknowledgement sends succeeded or failed locally. An empty capture
+still displays its exit reason and a zero count. A successful send call does not
+confirm that the acknowledgement reached the sender.
+
 Run the sender on endpoint A:
 
 ```sh
@@ -38,9 +44,12 @@ filtered, sent to another endpoint or missed because capture started late.
 `unmatched_receiver_observations` counts valid probes seen by the receiver that
 were not present in the sender file. It can reveal a mixed or incorrect pairing.
 
-`pairing.run_id_check` is `matched` when the receiver observed this sender run.
-The command rejects a receiver file containing only observations from another
-run. An empty receiver file cannot establish which run it covered and is marked
+`pairing.run_id_check` is `matched` when the receiver observed only this sender
+run, or `matched_with_other_runs` when the receiver file also contains probes
+from another run. The terminal view shows unmatched receiver observations to
+make mixed captures easier to spot. The command rejects a receiver file
+containing only observations from another run. An empty receiver file cannot
+establish which run it covered and is marked
 `unverified_no_receiver_observations`. `pairing.endpoint_checks` compares the
 target port and, unless the receiver bound to `0.0.0.0`, the target IPv4 address.
 Mismatches need review; address translation can legitimately change them.

tunnelscope-0.2.2/docs/releases/v0.2.2.md

@@ -0,0 +1,19 @@
+# TunnelScope v0.2.2
+
+Small maintenance release of the Python command-line prototype.
+
+## Changes
+
+- `tunnelscope show receiver.json` summarizes receiver observations by run ID
+  and payload size, including local acknowledgement send results.
+- Empty receiver reports render without an error.
+- Correlation identifies receiver captures containing the selected sender run
+  alongside other runs and shows the number of unmatched observations.
+
+## Limits
+
+A receiver observation proves arrival at that receiver, while a successful
+acknowledgement send call only proves that its local socket accepted the reply.
+Timeouts remain inconclusive without additional evidence. The tool does not
+discover an exact end-to-end path MTU or prove a root cause on an unknown
+network. Use its unauthenticated protocol only in controlled environments.

{tunnelscope-0.2.1 → tunnelscope-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tunnelscope"
-version = "0.2.1"
+version = "0.2.2"
 description = "Evidence-based MTU and packet-size diagnostics for Linux networks"
 readme = "README.md"
 license = "MIT"

{tunnelscope-0.2.1 → tunnelscope-0.2.2}/tests/test_delivery.py

@@ -172,6 +172,14 @@ class DeliveryTests(unittest.TestCase):
                 self.assertEqual(shown.returncode, 0, shown.stderr)
                 self.assertIn("2/2 observed at receiver", shown.stdout)
                 self.assertIn("Receiver saw", shown.stdout)
+                receiver_shown = subprocess.run(
+                    [sys.executable, str(Path(tunnelscope.__file__)), "show", str(receiver_path)],
+                    capture_output=True, text=True, timeout=5,
+                )
+                self.assertEqual(receiver_shown.returncode, 0, receiver_shown.stderr)
+                self.assertIn("Receiver observations: 2 probes", receiver_shown.stdout)
+                self.assertIn(probe["run_id"], receiver_shown.stdout)
+                self.assertIn("ACK sent", receiver_shown.stdout)
                 self.assertIn("64", tunnelscope.format_report(probe))
             finally:
                 if process.poll() is None:
@@ -208,6 +216,42 @@ class DeliveryTests(unittest.TestCase):
         result = tunnelscope.correlate_reports(probe, receiver)
         self.assertEqual(result["pairing"]["run_id_check"], "unverified_no_receiver_observations")
 
+    def test_correlation_flags_receiver_capture_with_other_runs(self):
+        probe = {"schema_version": 1, "run_id": "11" * 8, "results": [
+            {"probe_id": "ab" * 16, "payload_bytes": 64, "status": "acknowledged"},
+        ]}
+        receiver = {"schema_version": 1, "kind": "receiver_observations", "observations": [
+            {"probe_id": "ab" * 16, "run_id": "11" * 8, "payload_bytes": 64},
+            {"probe_id": "cd" * 16, "run_id": "22" * 8, "payload_bytes": 1400},
+        ]}
+        result = tunnelscope.correlate_reports(probe, receiver)
+        self.assertEqual(result["pairing"]["run_id_check"], "matched_with_other_runs")
+        self.assertEqual(result["summary"]["unmatched_receiver_observations"], 1)
+        shown = tunnelscope.format_report(result)
+        self.assertIn("1 unmatched receiver observations", shown)
+        self.assertIn("matched_with_other_runs", shown)
+
+        receiver["observations"][0]["run_id"] = "22" * 8
+        receiver["observations"].append({"probe_id": "ef" * 16, "run_id": "11" * 8,
+                                          "payload_bytes": 64})
+        with self.assertRaisesRegex(ValueError, "matching probe ID has a different run ID"):
+            tunnelscope.correlate_reports(probe, receiver)
+
+    def test_receiver_view_separates_runs_and_ack_send_errors(self):
+        report = {"schema_version": 1, "kind": "receiver_observations", "exit_reason": "idle_timeout",
+                  "observations": [
+                      {"run_id": "11" * 8, "payload_bytes": 64, "ack_send_status": "sent"},
+                      {"run_id": "11" * 8, "payload_bytes": 64, "ack_send_status": "socket_error"},
+                      {"run_id": "22" * 8, "payload_bytes": 1400, "ack_send_status": "sent"},
+                  ]}
+        rendered = tunnelscope.format_report(report)
+        self.assertIn("Receiver observations: 3 probes; exit: idle_timeout", rendered)
+        self.assertIn("1111111111111111  64     2     1         1", rendered)
+        self.assertIn("2222222222222222  1400   1     1         0", rendered)
+        self.assertIn("not that it arrived", rendered)
+        report["observations"] = []
+        self.assertIn("Receiver observations: 0 probes", tunnelscope.format_report(report))
+
 
 if __name__ == "__main__":
     unittest.main()

{tunnelscope-0.2.1 → tunnelscope-0.2.2/tunnelscope.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunnelscope
-Version: 0.2.1
+Version: 0.2.2
 Summary: Evidence-based MTU and packet-size diagnostics for Linux networks
 License-Expression: MIT
 Project-URL: Repository, https://github.com/lazypanic999/tunnelscope
@@ -22,7 +22,7 @@ Dynamic: license-file
 
 Evidence-based MTU and packet-size diagnostics for Linux networks.
 
-**Status: v0.2.1 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
+**Status: v0.2.2 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
 
 ## The problem
 
@@ -59,8 +59,8 @@ The [two-VM correlation record](https://github.com/lazypanic999/tunnelscope/blob
 The [blocked ACK return lab](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/ack-return-blocked.md) validates a receiver-observed sender timeout.
 
 Use `tunnelscope show report.json` for a short terminal table of a probe,
-bidirectional comparison, correlation, or lab report. JSON remains the
-machine-readable source of evidence.
+receiver observation, bidirectional comparison, correlation, or lab report.
+JSON remains the machine-readable source of evidence.
 
 ## Install locally
 

{tunnelscope-0.2.1 → tunnelscope-0.2.2}/tunnelscope.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ docs/receiver-observations.md
 docs/v0.1-scope.md
 docs/images/two-vm-results.png
 docs/releases/v0.2.1.md
+docs/releases/v0.2.2.md
 docs/validation/ack-return-blocked.md
 docs/validation/mtu-boundary.md
 docs/validation/pmtu-blackhole.md

{tunnelscope-0.2.1 → tunnelscope-0.2.2}/tunnelscope.py

@@ -297,7 +297,7 @@ def correlate_reports(probe_report, receiver_report):
     elif run_id not in receiver_run_ids:
         raise ValueError("receiver report has observations from a different run")
     else:
-        run_id_check = "matched"
+        run_id_check = "matched_with_other_runs" if len(receiver_run_ids) > 1 else "matched"
     observations = {row["probe_id"]: row for row in received}
     sent_ids = {row["probe_id"] for row in sent}
     matched = []
@@ -305,7 +305,7 @@ def correlate_reports(probe_report, receiver_report):
         observation = observations.get(row["probe_id"])
         if observation is not None and observation["payload_bytes"] != row["payload_bytes"]:
             raise ValueError("matching probe IDs have different payload sizes")
-        if observation is not None and run_id_check == "matched" and observation["run_id"] != run_id:
+        if observation is not None and run_id_check in ("matched", "matched_with_other_runs") and observation["run_id"] != run_id:
             raise ValueError("matching probe ID has a different run ID")
         matched.append({
             "probe_id": row["probe_id"],
@@ -398,7 +398,7 @@ def combine_reports(a_to_b, b_to_a):
 
 def text_table(headers, rows):
     cells = [[str(value) for value in row] for row in rows]
-    widths = [max(len(header), *(len(row[index]) for row in cells)) for index, header in enumerate(headers)]
+    widths = [max([len(header), *(len(row[index]) for row in cells)]) for index, header in enumerate(headers)]
     def line(values):
         return "  ".join(value.ljust(width) for value, width in zip(values, widths))
     return "\n".join([line(headers), line(["-" * width for width in widths]), *(line(row) for row in cells)])
@@ -429,6 +429,28 @@ def format_report(report):
         return "Probe results (UDP payload bytes)\n" + text_table(
             ["Bytes", "Ack", "Too large", "Timeout", "Error", "Assessment"], values
         ) + "\nTimeouts are inconclusive; an ACK confirms delivery and a small reply."
+    if kind == "receiver_observations":
+        observations = report.get("observations")
+        if not isinstance(observations, list) or any(not isinstance(row, dict) for row in observations):
+            raise ValueError("receiver report has no valid observations")
+        counts = {}
+        for row in observations:
+            run_id, size = row.get("run_id") or "unknown", row.get("payload_bytes")
+            if not isinstance(run_id, str) or not isinstance(size, int):
+                raise ValueError("invalid receiver observation")
+            key = (run_id, size)
+            if key not in counts:
+                counts[key] = {"observed": 0, "ack_sent": 0, "ack_errors": 0}
+            counts[key]["observed"] += 1
+            if row.get("ack_send_status") == "sent":
+                counts[key]["ack_sent"] += 1
+            elif row.get("ack_send_status") == "socket_error":
+                counts[key]["ack_errors"] += 1
+        values = [(run_id, size, item["observed"], item["ack_sent"], item["ack_errors"])
+                  for (run_id, size), item in sorted(counts.items())]
+        return (f"Receiver observations: {len(observations)} probes; exit: {report.get('exit_reason', 'unknown')}\n"
+                + text_table(["Run ID", "Bytes", "Seen", "ACK sent", "ACK error"], values)
+                + "\nACK sent means the local socket accepted the reply, not that it arrived.")
     if kind == "bidirectional_comparison":
         comparison = report.get("comparison")
         rows = comparison.get("by_payload_size") if isinstance(comparison, dict) else None
@@ -452,7 +474,8 @@ def format_report(report):
         pairing = report.get("pairing")
         run_check = pairing.get("run_id_check", "unavailable") if isinstance(pairing, dict) else "unavailable"
         return (f"Correlation: {summary.get('receiver_observed', '?')}/{summary.get('sent_probes', '?')} observed at receiver; "
-                f"{summary.get('timed_out_but_receiver_observed', '?')} timed out after arrival; run ID: {run_check}\n"
+                f"{summary.get('timed_out_but_receiver_observed', '?')} timed out after arrival; "
+                f"{summary.get('unmatched_receiver_observations', '?')} unmatched receiver observations; run ID: {run_check}\n"
                 + text_table(["Bytes", "Sender", "Receiver saw", "ACK send"], values)
                 + "\nNo receiver observation is inconclusive without confirmed capture coverage.")
     raise ValueError(f"unsupported report kind: {kind}")