testoperations 0.2.0__tar.gz → 0.3.0__tar.gz

{testoperations-0.2.0/src/testoperations.egg-info → testoperations-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testoperations
-Version: 0.2.0
+Version: 0.3.0
 Summary: Framework-agnostic, assertion-free composition functions over testprotocols capabilities.
 Author-email: Alottabits <rjvisser@alottabits.com>
 Maintainer-email: Alottabits <rjvisser@alottabits.com>

{testoperations-0.2.0 → testoperations-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "testoperations"
-version = "0.2.0"
+version = "0.3.0"
 description = "Framework-agnostic, assertion-free composition functions over testprotocols capabilities."
 requires-python = ">=3.12"
 dependencies = ["testprotocols>=0.1.0"]

{testoperations-0.2.0 → testoperations-0.3.0}/src/testoperations/network_endpoint.py

@@ -38,7 +38,7 @@ def wait_for_endpoint_ready(
     while time.monotonic() < deadline:
         try:
             ip = endpoint.get_ipv4_addr()
-        except Exception as exc:  # noqa: BLE001
+        except Exception as exc:
             last_error = exc
             ip = ""
         if ip:

testoperations-0.3.0/src/testoperations/throughput.py

@@ -0,0 +1,188 @@
+"""Concurrent iperf3 throughput measurement over typed iperf capabilities.
+
+Framing owned here (the reason this is a ``testoperations`` function and not a
+step one-liner): start every receiver FIRST (one iperf3 server instance per
+flow, each on its own port), snapshot each receiver log's completed-session
+count, launch all senders together so the flows genuinely overlap, then poll
+each receiver log until a NEW completed session appears and report its
+measured rate. The RECEIVE side is read deliberately: the receiver sits behind
+the device under test, so its rate is what actually crossed that device
+(send-side rates include bytes a shaper may still be queueing or dropping).
+
+Assertion-free and stdlib-only: returns facts (per-flow Mbit/s) and raises only
+on operational failures (duplicate ports, a receiver that never produces a
+completed session). Pass/fail thresholds belong to the caller.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from testprotocols.iperf_client import IperfClient
+from testprotocols.iperf_server import IperfServer
+
+# A finished iperf3 session is flushed to the --logfile when the sender
+# disconnects; allow a grace window after the nominal duration for that flush
+# (and for clock skew between controller and endpoints).
+DEFAULT_RESULT_TIMEOUT_S = 30.0
+_POLL_INTERVAL_S = 1.0
+
+
+@dataclass(frozen=True)
+class ThroughputFlow:
+    """One measured flow: *sender* pushes TCP to *dest_host*:*port*, *receiver* listens.
+
+    ``port`` must be unique across the flows of one measurement call — each
+    flow gets its own iperf3 server instance (and per-port logfile) on the
+    receiving device.
+    """
+
+    sender: IperfClient
+    receiver: IperfServer
+    dest_host: str
+    port: int
+
+
+@dataclass(frozen=True)
+class FlowThroughput:
+    """The measured receive-side rate of one flow."""
+
+    port: int
+    mbps: float
+
+
+def iter_json_docs(text: str) -> list[Any]:
+    """Parse the top-level JSON documents concatenated in *text*, in order.
+
+    iperf3 appends one pretty-printed JSON document per session to its
+    ``--logfile``; a restarted server appends to the same per-port file, so a
+    log may hold several documents (and a trailing, still-open one while a
+    session is running). Documents are extracted with a string-aware brace
+    scanner; only complete, parseable documents are returned.
+    """
+    docs: list[Any] = []
+    depth = 0
+    start = -1
+    in_string = False
+    escaped = False
+    for i, ch in enumerate(text):
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            if depth == 0:
+                start = i
+            depth += 1
+        elif ch == "}" and depth > 0:
+            depth -= 1
+            if depth == 0 and start >= 0:
+                try:
+                    docs.append(json.loads(text[start : i + 1]))
+                except ValueError:
+                    pass
+                start = -1
+    return docs
+
+
+def count_sessions(log_text: str) -> int:
+    """The number of completed iperf3 session documents in *log_text*."""
+    return len(iter_json_docs(log_text))
+
+
+def last_session_mbps(log_text: str) -> float | None:
+    """The receive-side rate (Mbit/s) of the LAST completed session, or ``None``.
+
+    Prefers ``end.sum_received.bits_per_second`` (TCP receive-side goodput);
+    falls back to ``end.sum.bits_per_second`` (UDP sessions). Returns ``None``
+    when no completed session carries either summary.
+    """
+    docs = iter_json_docs(log_text)
+    if not docs:
+        return None
+    end = docs[-1].get("end", {}) if isinstance(docs[-1], dict) else {}
+    for key in ("sum_received", "sum"):
+        bps = end.get(key, {}).get("bits_per_second")
+        if bps is not None:
+            return float(bps) / 1e6
+    return None
+
+
+def measure_concurrent_throughput(
+    flows: Sequence[ThroughputFlow],
+    *,
+    duration_s: int = 10,
+    result_timeout_s: float = DEFAULT_RESULT_TIMEOUT_S,
+    sleep: Callable[[float], None] = time.sleep,
+    monotonic: Callable[[], float] = time.monotonic,
+) -> list[FlowThroughput]:
+    """Run all *flows* concurrently for *duration_s*; return per-flow receive rates.
+
+    Receivers are started before any sender (no connection race), every sender
+    is launched before the measurement wait (the flows overlap for the whole
+    duration), and both sides are stopped in a ``finally`` so no iperf process
+    outlives the call — also on failure. Results are ordered like *flows*.
+
+    Raises ``ValueError`` on duplicate ports (two flows would share a server
+    instance and logfile) and ``RuntimeError`` when a receiver produces no new
+    completed session within *duration_s* + *result_timeout_s*.
+    """
+    ports = [f.port for f in flows]
+    if len(set(ports)) != len(ports):
+        raise ValueError(f"flow ports must be unique per measurement, got {ports}")
+
+    started: list[tuple[ThroughputFlow, int, str, int]] = []
+    sender_pids: list[tuple[IperfClient, int]] = []
+    try:
+        for flow in flows:
+            receiver_pid, receiver_log = flow.receiver.start_traffic_receiver(flow.port)
+            prior_sessions = count_sessions(flow.receiver.get_iperf_logs(receiver_log))
+            started.append((flow, receiver_pid, receiver_log, prior_sessions))
+
+        for flow, _, _, _ in started:
+            sender_pid, _ = flow.sender.start_traffic_sender(
+                flow.dest_host, flow.port, time=duration_s
+            )
+            sender_pids.append((flow.sender, sender_pid))
+
+        sleep(float(duration_s))
+
+        results: list[FlowThroughput] = []
+        deadline = monotonic() + result_timeout_s
+        for flow, _, receiver_log, prior_sessions in started:
+            while True:
+                log_text = flow.receiver.get_iperf_logs(receiver_log)
+                if count_sessions(log_text) > prior_sessions:
+                    mbps = last_session_mbps(log_text)
+                    if mbps is not None:
+                        results.append(FlowThroughput(port=flow.port, mbps=mbps))
+                        break
+                if monotonic() >= deadline:
+                    raise RuntimeError(
+                        f"iperf receiver on port {flow.port} produced no completed "
+                        f"session within {result_timeout_s}s after the "
+                        f"{duration_s}s measurement window"
+                    )
+                sleep(_POLL_INTERVAL_S)
+        return results
+    finally:
+        for sender, sender_pid in sender_pids:
+            try:
+                sender.stop_traffic(sender_pid)
+            except Exception:
+                pass
+        for flow, receiver_pid, _, _ in started:
+            try:
+                flow.receiver.stop_traffic(receiver_pid)
+            except Exception:
+                pass

{testoperations-0.2.0 → testoperations-0.3.0/src/testoperations.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testoperations
-Version: 0.2.0
+Version: 0.3.0
 Summary: Framework-agnostic, assertion-free composition functions over testprotocols capabilities.
 Author-email: Alottabits <rjvisser@alottabits.com>
 Maintainer-email: Alottabits <rjvisser@alottabits.com>

{testoperations-0.2.0 → testoperations-0.3.0}/src/testoperations.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ src/testoperations/py.typed
 src/testoperations/sdwan.py
 src/testoperations/segmentation.py
 src/testoperations/sip_phone.py
+src/testoperations/throughput.py
 src/testoperations/tr069_server.py
 src/testoperations/wifi_client.py
 src/testoperations.egg-info/PKG-INFO
@@ -37,5 +38,6 @@ tests/test_pcap_capture.py
 tests/test_sdwan.py
 tests/test_segmentation.py
 tests/test_sip_phone.py
+tests/test_throughput.py
 tests/test_tr069_server.py
 tests/test_wifi_client.py

{testoperations-0.2.0 → testoperations-0.3.0}/tests/test_network_endpoint.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from unittest.mock import MagicMock
 
 import pytest
-
 from testoperations.network_endpoint import wait_for_endpoint_ready
 
 

{testoperations-0.2.0 → testoperations-0.3.0}/tests/test_sip_phone.py

@@ -17,7 +17,7 @@ from testoperations.sip_phone import (
 class TestCallAPhone:
     def test_calls_off_hook_and_dial(self):
         caller = MagicMock()
-        
+
         call_a_phone(caller, "2002")
 
         caller.off_hook.assert_called_once_with()

testoperations-0.3.0/tests/test_throughput.py

@@ -0,0 +1,177 @@
+"""Tests for testoperations.throughput (concurrent iperf3 measurement framing)."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+from testoperations.throughput import (
+    ThroughputFlow,
+    count_sessions,
+    iter_json_docs,
+    last_session_mbps,
+    measure_concurrent_throughput,
+)
+
+
+def _session_doc(rx_bps: float | None = None, sum_bps: float | None = None) -> str:
+    end: dict[str, dict[str, float]] = {}
+    if rx_bps is not None:
+        end["sum_received"] = {"bits_per_second": rx_bps}
+    if sum_bps is not None:
+        end["sum"] = {"bits_per_second": sum_bps}
+    return json.dumps({"start": {"test_start": {}}, "end": end}, indent=2)
+
+
+# --- JSON log parsing ---------------------------------------------------------
+
+
+class TestLogParsing:
+    def test_iter_json_docs_multiple_documents(self) -> None:
+        text = _session_doc(rx_bps=1e6) + "\n" + _session_doc(rx_bps=2e6)
+        assert len(iter_json_docs(text)) == 2
+
+    def test_iter_json_docs_ignores_trailing_incomplete_document(self) -> None:
+        text = _session_doc(rx_bps=1e6) + '\n{"start": {"test_start"'
+        assert len(iter_json_docs(text)) == 1
+
+    def test_iter_json_docs_braces_inside_strings_do_not_confuse_scanner(self) -> None:
+        text = json.dumps({"note": "brace } in { string", "end": {}})
+        docs = iter_json_docs(text)
+        assert len(docs) == 1
+        assert docs[0]["note"] == "brace } in { string"
+
+    def test_count_sessions_empty_log(self) -> None:
+        assert count_sessions("") == 0
+
+    def test_last_session_mbps_prefers_receive_side_of_last_doc(self) -> None:
+        text = _session_doc(rx_bps=100e6) + "\n" + _session_doc(rx_bps=47.5e6)
+        assert last_session_mbps(text) == pytest.approx(47.5)
+
+    def test_last_session_mbps_falls_back_to_sum(self) -> None:
+        assert last_session_mbps(_session_doc(sum_bps=9e6)) == pytest.approx(9.0)
+
+    def test_last_session_mbps_none_when_no_summary(self) -> None:
+        assert last_session_mbps("") is None
+        assert last_session_mbps(json.dumps({"end": {}})) is None
+
+
+# --- measure_concurrent_throughput ---------------------------------------------
+
+
+def _flow(
+    port: int, mbps: float, *, stale_docs: int = 0
+) -> tuple[ThroughputFlow, MagicMock, MagicMock]:
+    """A flow over mocked capabilities; returns (flow, sender_mock, receiver_mock).
+
+    The fake ``get_iperf_logs`` returns only the *stale* documents until the
+    sender has been started, then appends the fresh session — mirroring the
+    real sequencing (session completes only after the measurement window).
+    """
+    stale = "\n".join(_session_doc(rx_bps=1e6) for _ in range(stale_docs))
+    fresh = stale + "\n" + _session_doc(rx_bps=mbps * 1e6)
+
+    sender = MagicMock()
+    sender.start_traffic_sender.return_value = (4000 + port, f"/tmp/cl_{port}.log")
+
+    receiver = MagicMock()
+    receiver.start_traffic_receiver.return_value = (5000 + port, f"/tmp/rx_{port}.log")
+    receiver.get_iperf_logs.side_effect = lambda _log: (
+        fresh if sender.start_traffic_sender.called else stale
+    )
+    flow = ThroughputFlow(sender=sender, receiver=receiver, dest_host="192.168.32.3", port=port)
+    return flow, sender, receiver
+
+
+class TestMeasureConcurrentThroughput:
+    def test_single_flow_returns_receive_rate(self) -> None:
+        flow, _, _ = _flow(5301, mbps=47.5)
+        results = measure_concurrent_throughput([flow], duration_s=10, sleep=lambda _s: None)
+        assert [r.port for r in results] == [5301]
+        assert results[0].mbps == pytest.approx(47.5)
+
+    def test_receiver_started_before_sender_with_expected_args(self) -> None:
+        flow, sender, receiver = _flow(5301, mbps=10.0)
+        order: list[str] = []
+
+        def _rx(port: int) -> tuple[int, str]:
+            order.append(f"rx:{port}")
+            return (5301, "/tmp/rx.log")
+
+        def _tx(host: str, port: int, time: int) -> tuple[int, str]:
+            order.append(f"tx:{host}:{port}:t={time}")
+            return (4001, "/tmp/tx.log")
+
+        receiver.start_traffic_receiver.side_effect = _rx
+        sender.start_traffic_sender.side_effect = _tx
+        measure_concurrent_throughput([flow], duration_s=7, sleep=lambda _s: None)
+        assert order == ["rx:5301", "tx:192.168.32.3:5301:t=7"]
+
+    def test_stale_sessions_in_log_are_not_read_as_results(self) -> None:
+        # Two stale docs at 1 Mbps sit in the per-port log from an earlier run;
+        # the fresh session measures 42 Mbps and must be the one reported.
+        flow, _, _ = _flow(5301, mbps=42.0, stale_docs=2)
+        results = measure_concurrent_throughput([flow], duration_s=10, sleep=lambda _s: None)
+        assert results[0].mbps == pytest.approx(42.0)
+
+    def test_concurrent_flows_all_senders_started_before_wait_and_ordered_results(self) -> None:
+        flow_a, sender_a, _ = _flow(5301, mbps=9.5)
+        flow_b, sender_b, _ = _flow(5302, mbps=11.0)
+        sleeps: list[float] = []
+        results = measure_concurrent_throughput(
+            [flow_a, flow_b], duration_s=10, sleep=sleeps.append
+        )
+        assert [r.port for r in results] == [5301, 5302]
+        assert [r.mbps for r in results] == [pytest.approx(9.5), pytest.approx(11.0)]
+        # Both senders launched; the measurement wait happened exactly once.
+        sender_a.start_traffic_sender.assert_called_once()
+        sender_b.start_traffic_sender.assert_called_once()
+        assert sleeps.count(10.0) == 1
+
+    def test_duplicate_ports_rejected(self) -> None:
+        flow_a, _, _ = _flow(5301, mbps=1.0)
+        flow_b, _, _ = _flow(5301, mbps=2.0)
+        with pytest.raises(ValueError, match="unique"):
+            measure_concurrent_throughput([flow_a, flow_b], sleep=lambda _s: None)
+
+    def test_timeout_when_no_new_session_appears(self) -> None:
+        flow, _, receiver = _flow(5301, mbps=42.0)
+        receiver.get_iperf_logs.side_effect = lambda _log: ""  # never completes
+        clock = iter(float(t) for t in range(0, 1000, 5))
+        with pytest.raises(RuntimeError, match="port 5301"):
+            measure_concurrent_throughput(
+                [flow],
+                duration_s=10,
+                result_timeout_s=20.0,
+                sleep=lambda _s: None,
+                monotonic=lambda: next(clock),
+            )
+
+    def test_both_sides_stopped_on_success(self) -> None:
+        flow, sender, receiver = _flow(5301, mbps=5.0)
+        measure_concurrent_throughput([flow], duration_s=10, sleep=lambda _s: None)
+        sender.stop_traffic.assert_called_once_with(4000 + 5301)
+        receiver.stop_traffic.assert_called_once_with(5000 + 5301)
+
+    def test_cleanup_runs_even_when_measurement_times_out(self) -> None:
+        flow, sender, receiver = _flow(5301, mbps=5.0)
+        receiver.get_iperf_logs.side_effect = lambda _log: ""
+        clock = iter(float(t) for t in range(0, 1000, 5))
+        with pytest.raises(RuntimeError):
+            measure_concurrent_throughput(
+                [flow],
+                duration_s=10,
+                result_timeout_s=15.0,
+                sleep=lambda _s: None,
+                monotonic=lambda: next(clock),
+            )
+        sender.stop_traffic.assert_called_once()
+        receiver.stop_traffic.assert_called_once()
+
+    def test_cleanup_swallows_stop_errors(self) -> None:
+        flow, sender, receiver = _flow(5301, mbps=5.0)
+        sender.stop_traffic.side_effect = RuntimeError("already gone")
+        receiver.stop_traffic.side_effect = RuntimeError("already gone")
+        results = measure_concurrent_throughput([flow], duration_s=10, sleep=lambda _s: None)
+        assert results[0].mbps == pytest.approx(5.0)