ipyrf 0.1.0__tar.gz

ipyrf-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Steinwurf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

ipyrf-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: ipyrf
+Version: 0.1.0
+Summary: A tiny iperf3-like tool with JSON output (TCP/UDP)
+Author: Steinwurf ApS
+License: MIT License
+        
+        Copyright (c) 2025 Steinwurf
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        
+        
+Project-URL: Homepage, https://github.com/steinwurf/ipyrf
+Project-URL: Repository, https://github.com/steinwurf/ipyrf
+Project-URL: Issues, https://github.com/steinwurf/ipyrf/issues
+Keywords: network,iperf,throughput,udp,tcp,benchmark
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Benchmark
+Requires-Python: >=3.8
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Dynamic: license-file
+
+ipyrf
+=====
+
+Minimal iperf3-like network throughput tool with JSON output. Supports TCP and UDP, server and client modes.
+
+Features
+--------
+- TCP and UDP tests
+- JSON or human-readable output
+- Optional bandwidth capping (TCP/UDP)
+- UDP packet loss estimation
+- Linux TCP congestion control selection (if available)
+
+Installation
+------------
+
+From PyPI (recommended):
+
+.. code-block:: bash
+
+   python3 -m pip install ipyrf
+
+From source (editable):
+
+.. code-block:: bash
+
+   python3 -m venv .venv
+   source .venv/bin/activate
+   python3 -m pip install -U pip build
+   python3 -m pip install -e .
+
+Development
+-----------
+
+For development, install with test dependencies:
+
+.. code-block:: bash
+
+   python3 -m pip install -e ".[test]"
+
+Running Tests
+~~~~~~~~~~~~~
+
+The project includes a comprehensive test suite using pytest:
+
+.. code-block:: bash
+
+   # Run all tests
+   python -m pytest tests/
+
+   # Run only unit tests (fast)
+   python -m pytest tests/ -m "not integration"
+
+   # Run only integration tests
+   python -m pytest tests/ -m "integration"
+
+   # Run with coverage
+   python -m pytest tests/ --cov=src/ipyrf --cov-report=html
+
+   # Use the test runner script
+   ./run_tests.py --type fast --verbose
+
+Test Categories
+~~~~~~~~~~~~~~~
+
+- **Unit tests**: Fast tests that don't require network access
+- **Integration tests**: Tests that require network functionality
+- **Network tests**: Tests that create actual network connections
+- **Slow tests**: Tests that take longer to run (marked with @pytest.mark.slow)
+
+Continuous Integration
+~~~~~~~~~~~~~~~~~~~~~~
+
+The project uses GitHub Actions for continuous integration, testing against Python 3.8-3.12.
+
+Usage
+-----
+
+The package installs a console script named ``ipyrf``.
+
+Quick examples
+~~~~~~~~~~~~~~
+
+TCP server:
+
+.. code-block:: bash
+
+   ipyrf tcp server 0.0.0.0 --port 12345
+
+TCP client:
+
+.. code-block:: bash
+
+   ipyrf tcp client 127.0.0.1 --port 12345 --time 5
+   ipyrf tcp client 127.0.0.1 --port 12345 --time 5 --set-mss 1400
+
+UDP server:
+
+.. code-block:: bash
+
+   ipyrf udp server 0.0.0.0 --port 12345
+
+UDP client (with bandwidth cap and optional payload size):
+
+.. code-block:: bash
+
+   ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5
+   ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5 -l 1200
+
+Interactive mode
+----------------
+
+You can run clients in an interactive mode that lets you adjust the pacing live using your keyboard. Use ``--interactive`` and optionally ``--interval`` (seconds between stats updates). When interactive is enabled, the same client logic is used underneath with a dynamic pacing controller.
+
+Controls shown in the terminal:
+
+- ``←``: -1 Mbps
+- ``→``: +1 Mbps
+- ``↓``: -10%
+- ``↑``: +10%
+- ``0``: reset to initial bandwidth (or unlimited for TCP if none was provided)
+- ``u``: unlimited (disable pacing)
+- ``q``: quit
+
+Examples:
+
+.. code-block:: bash
+
+   # TCP interactive (unlimited unless you pass --bandwidth)
+   ipyrf tcp client 127.0.0.1 --port 5201 --interactive
+
+   # TCP interactive with initial pacing and custom interval
+   ipyrf tcp client 127.0.0.1 --port 5201 --bandwidth 200M --set-mss 1400 --interactive --interval 0.5
+
+   # UDP interactive (requires initial --bandwidth)
+   ipyrf udp client 127.0.0.1 --port 5201 --bandwidth 50M -l 1200 --interactive
+
+CLI overview
+------------
+
+Top-level structure:
+
+.. code-block:: text
+
+   ipyrf [tcp|udp] [server|client] [OPTIONS]
+
+Common options (both protocols, both roles):
+
+- ``--port``: Port (default 5201)
+- ``--logfile``: Redirect output to a file
+- ``--json_log``: Emit logs in JSON (newline-delimited)
+
+TCP-specific options:
+
+- ``tcp server ADDRESS``: Start a TCP server on ``ADDRESS``
+- ``tcp client ADDRESS``: Start a TCP client to connect to ``ADDRESS``
+- ``--congestion-control``: Select Linux TCP CC algorithm if available
+- ``--time``: Test duration (seconds), default 10
+- ``--bandwidth``: Target rate (e.g., ``50M``); used for pacing, optional
+- ``--set-mss``: Set approximate MSS via ``TCP_MAXSEG``
+- ``--interactive``: Enable interactive pacing controls
+- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)
+
+UDP-specific options:
+
+- ``udp server ADDRESS``: Start a UDP server on ``ADDRESS``
+- ``udp client ADDRESS``: Start a UDP client to ``ADDRESS``
+- ``--time``: Test duration (seconds), default 10
+- ``--bandwidth``: Target rate (required for UDP client; e.g., ``50M``)
+- ``-l/--length``: UDP payload length (default 1200)
+- ``--interactive``: Enable interactive pacing controls
+- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)
+
+JSON logging
+------------
+
+Add ``--json_log`` to switch all output to newline-delimited JSON objects. This is useful for machine parsing or dashboards. Example:
+
+.. code-block:: bash
+
+   ipyrf tcp client 127.0.0.1 --time 5 --json_log | jq
+
+Notes
+-----
+
+- Output is JSON (newline-delimited for update events) when ``--json_log`` is given; otherwise, a human-readable summary is printed.
+- UDP mode sends a FIN marker at the end and the server exits after FIN (or inactivity timeout).
+- On Linux, congestion control selection is exposed if ``/proc`` entries are available.
+
+License
+-------
+
+MIT. See ``LICENSE``.

ipyrf-0.1.0/README.rst

@@ -0,0 +1,193 @@
+ipyrf
+=====
+
+Minimal iperf3-like network throughput tool with JSON output. Supports TCP and UDP, server and client modes.
+
+Features
+--------
+- TCP and UDP tests
+- JSON or human-readable output
+- Optional bandwidth capping (TCP/UDP)
+- UDP packet loss estimation
+- Linux TCP congestion control selection (if available)
+
+Installation
+------------
+
+From PyPI (recommended):
+
+.. code-block:: bash
+
+   python3 -m pip install ipyrf
+
+From source (editable):
+
+.. code-block:: bash
+
+   python3 -m venv .venv
+   source .venv/bin/activate
+   python3 -m pip install -U pip build
+   python3 -m pip install -e .
+
+Development
+-----------
+
+For development, install with test dependencies:
+
+.. code-block:: bash
+
+   python3 -m pip install -e ".[test]"
+
+Running Tests
+~~~~~~~~~~~~~
+
+The project includes a comprehensive test suite using pytest:
+
+.. code-block:: bash
+
+   # Run all tests
+   python -m pytest tests/
+
+   # Run only unit tests (fast)
+   python -m pytest tests/ -m "not integration"
+
+   # Run only integration tests
+   python -m pytest tests/ -m "integration"
+
+   # Run with coverage
+   python -m pytest tests/ --cov=src/ipyrf --cov-report=html
+
+   # Use the test runner script
+   ./run_tests.py --type fast --verbose
+
+Test Categories
+~~~~~~~~~~~~~~~
+
+- **Unit tests**: Fast tests that don't require network access
+- **Integration tests**: Tests that require network functionality
+- **Network tests**: Tests that create actual network connections
+- **Slow tests**: Tests that take longer to run (marked with @pytest.mark.slow)
+
+Continuous Integration
+~~~~~~~~~~~~~~~~~~~~~~
+
+The project uses GitHub Actions for continuous integration, testing against Python 3.8-3.12.
+
+Usage
+-----
+
+The package installs a console script named ``ipyrf``.
+
+Quick examples
+~~~~~~~~~~~~~~
+
+TCP server:
+
+.. code-block:: bash
+
+   ipyrf tcp server 0.0.0.0 --port 12345
+
+TCP client:
+
+.. code-block:: bash
+
+   ipyrf tcp client 127.0.0.1 --port 12345 --time 5
+   ipyrf tcp client 127.0.0.1 --port 12345 --time 5 --set-mss 1400
+
+UDP server:
+
+.. code-block:: bash
+
+   ipyrf udp server 0.0.0.0 --port 12345
+
+UDP client (with bandwidth cap and optional payload size):
+
+.. code-block:: bash
+
+   ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5
+   ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5 -l 1200
+
+Interactive mode
+----------------
+
+You can run clients in an interactive mode that lets you adjust the pacing live using your keyboard. Use ``--interactive`` and optionally ``--interval`` (seconds between stats updates). When interactive is enabled, the same client logic is used underneath with a dynamic pacing controller.
+
+Controls shown in the terminal:
+
+- ``←``: -1 Mbps
+- ``→``: +1 Mbps
+- ``↓``: -10%
+- ``↑``: +10%
+- ``0``: reset to initial bandwidth (or unlimited for TCP if none was provided)
+- ``u``: unlimited (disable pacing)
+- ``q``: quit
+
+Examples:
+
+.. code-block:: bash
+
+   # TCP interactive (unlimited unless you pass --bandwidth)
+   ipyrf tcp client 127.0.0.1 --port 5201 --interactive
+
+   # TCP interactive with initial pacing and custom interval
+   ipyrf tcp client 127.0.0.1 --port 5201 --bandwidth 200M --set-mss 1400 --interactive --interval 0.5
+
+   # UDP interactive (requires initial --bandwidth)
+   ipyrf udp client 127.0.0.1 --port 5201 --bandwidth 50M -l 1200 --interactive
+
+CLI overview
+------------
+
+Top-level structure:
+
+.. code-block:: text
+
+   ipyrf [tcp|udp] [server|client] [OPTIONS]
+
+Common options (both protocols, both roles):
+
+- ``--port``: Port (default 5201)
+- ``--logfile``: Redirect output to a file
+- ``--json_log``: Emit logs in JSON (newline-delimited)
+
+TCP-specific options:
+
+- ``tcp server ADDRESS``: Start a TCP server on ``ADDRESS``
+- ``tcp client ADDRESS``: Start a TCP client to connect to ``ADDRESS``
+- ``--congestion-control``: Select Linux TCP CC algorithm if available
+- ``--time``: Test duration (seconds), default 10
+- ``--bandwidth``: Target rate (e.g., ``50M``); used for pacing, optional
+- ``--set-mss``: Set approximate MSS via ``TCP_MAXSEG``
+- ``--interactive``: Enable interactive pacing controls
+- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)
+
+UDP-specific options:
+
+- ``udp server ADDRESS``: Start a UDP server on ``ADDRESS``
+- ``udp client ADDRESS``: Start a UDP client to ``ADDRESS``
+- ``--time``: Test duration (seconds), default 10
+- ``--bandwidth``: Target rate (required for UDP client; e.g., ``50M``)
+- ``-l/--length``: UDP payload length (default 1200)
+- ``--interactive``: Enable interactive pacing controls
+- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)
+
+JSON logging
+------------
+
+Add ``--json_log`` to switch all output to newline-delimited JSON objects. This is useful for machine parsing or dashboards. Example:
+
+.. code-block:: bash
+
+   ipyrf tcp client 127.0.0.1 --time 5 --json_log | jq
+
+Notes
+-----
+
+- Output is JSON (newline-delimited for update events) when ``--json_log`` is given; otherwise, a human-readable summary is printed.
+- UDP mode sends a FIN marker at the end and the server exits after FIN (or inactivity timeout).
+- On Linux, congestion control selection is exposed if ``/proc`` entries are available.
+
+License
+-------
+
+MIT. See ``LICENSE``.

ipyrf-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ipyrf"
+version = "0.1.0"
+description = "A tiny iperf3-like tool with JSON output (TCP/UDP)"
+readme = "README.rst"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Steinwurf ApS" }
+]
+keywords = ["network", "iperf", "throughput", "udp", "tcp", "benchmark"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX :: Linux",
+  "Topic :: System :: Networking",
+  "Topic :: System :: Benchmark",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "pytest-cov>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/steinwurf/ipyrf"
+Repository = "https://github.com/steinwurf/ipyrf"
+Issues = "https://github.com/steinwurf/ipyrf/issues"
+
+[project.scripts]
+ipyrf = "ipyrf.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ipyrf*"]
+exclude = []

ipyrf-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ipyrf-0.1.0/src/ipyrf/__init__.py

@@ -0,0 +1,5 @@
+"""ipyrf package: a tiny iperf3-like tool with JSON output."""
+
+__all__ = [
+    "main",
+]

ipyrf-0.1.0/src/ipyrf/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

ipyrf-0.1.0/src/ipyrf/cli.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+import argparse
+import sys
+
+from .logger import Logger
+from .utils import parse_bandwidth, parse_ip, tcp_congestion_control_info
+from . import tcp, udp
+from .interactive import InteractiveController
+from .controllers import StaticPacingController
+
+
+def main():
+    p = argparse.ArgumentParser(description="Minimal iperf3-like tool (JSON output)")
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--port", type=int, default=5201, help="Port number")
+    common.add_argument(
+        "--logfile", help="Write log messages to a file instead of stdout"
+    )
+    common.add_argument(
+        "--json_log",
+        help="Write the log messages as JSON.",
+        action="store_true",
+        default=False,
+    )
+    common.add_argument("--interval", type=float, default=1.0, help="Stats interval")
+
+    subp = p.add_subparsers(dest="protocol", required=True)
+
+    tcp_parser = subp.add_parser("tcp", help="TCP mode")
+    tcp_sub = tcp_parser.add_subparsers(dest="role", required=True)
+
+    congestion_control = tcp_congestion_control_info()
+    common_tcp = argparse.ArgumentParser(add_help=False)
+    common_tcp.add_argument(
+        "--congestion-control",
+        choices=congestion_control.get("allowed", []),
+        default=None,
+        help=(
+            argparse.SUPPRESS
+            if congestion_control == {}
+            else (
+                "TCP: set congestion control algorithm "
+                f"(default: system default '{congestion_control.get('current')}')"
+            )
+        ),
+    )
+
+    tcp_srv = tcp_sub.add_parser(
+        "server", parents=[common, common_tcp], help="Run a TCP server"
+    )
+    tcp_srv.add_argument(
+        "address", metavar="ADDRESS", type=parse_ip, help="Listen address"
+    )
+
+    tcp_cli = tcp_sub.add_parser(
+        "client", parents=[common, common_tcp], help="Run a TCP client"
+    )
+    tcp_cli.add_argument(
+        "--bandwidth", type=parse_bandwidth, help="Target bandwidth, e.g., 50M"
+    )
+    tcp_cli.add_argument("address", metavar="ADDRESS", help="Server address to connect")
+    tcp_cli.add_argument(
+        "--set-mss", dest="set_mss", type=int, help="TCP: set TCP_MAXSEG (approx MSS)"
+    )
+
+    # Time and interactive mode are mutually exclusive
+    tcp_time_group = tcp_cli.add_mutually_exclusive_group()
+    tcp_time_group.add_argument(
+        "--time", type=int, default=10, help="Test duration in seconds"
+    )
+    tcp_time_group.add_argument(
+        "--interactive", action="store_true", help="Run client in interactive mode"
+    )
+
+    udp_parser = subp.add_parser("udp", help="UDP mode")
+    udp_sub = udp_parser.add_subparsers(dest="role", required=True)
+
+    udp_srv = udp_sub.add_parser("server", parents=[common], help="Run a UDP server")
+    udp_srv.add_argument(
+        "address", metavar="ADDRESS", type=parse_ip, help="Listen address"
+    )
+
+    udp_cli = udp_sub.add_parser("client", parents=[common], help="Run a UDP client")
+    udp_cli.add_argument("address", metavar="ADDRESS", help="Server address to connect")
+    udp_cli.add_argument(
+        "--bandwidth", type=parse_bandwidth, help="Target bandwidth, e.g., 50M"
+    )
+    udp_cli.add_argument(
+        "-l", dest="length", type=int, default=1200, help="UDP payload length"
+    )
+
+    # Time and interactive mode are mutually exclusive
+    udp_time_group = udp_cli.add_mutually_exclusive_group()
+    udp_time_group.add_argument(
+        "--time", type=int, default=10, help="Test duration in seconds"
+    )
+    udp_time_group.add_argument(
+        "--interactive", action="store_true", help="Run client in interactive mode"
+    )
+
+    args = p.parse_args()
+
+    if args.role not in ("server", "client"):
+        raise ValueError(f"Invalid role: {args.role}. Must be 'server' or 'client'.")
+
+    log = Logger(args.json_log, args.protocol, args.role, args.logfile)
+
+    controller = None
+    if args.protocol == "udp":
+        if args.role == "server":
+            udp.server(log, args.address, args.port, args.interval)
+        else:
+            bw = (
+                args.bandwidth or parse_bandwidth("50M")
+                if args.interactive
+                else (args.bandwidth or 1e9)
+            )
+            if args.interactive:
+                controller = InteractiveController(bw, args.length, args.interval)
+            else:
+                controller = StaticPacingController(
+                    bw, max(args.length, udp.UDP_HDR.size), args.time, args.interval
+                )
+            udp.client(
+                log,
+                args.address,
+                args.port,
+                args.length,
+                controller,
+            )
+
+    else:
+        if args.role == "server":
+            tcp.server(
+                log, args.address, args.port, args.interval, args.congestion_control
+            )
+        else:
+            if args.interactive:
+                quantum = args.set_mss if args.set_mss else 1200
+                # If no bandwidth provided, controller will act as unlimited until adjusted
+                controller = InteractiveController(
+                    args.bandwidth, quantum, args.interval
+                )
+            else:
+                controller = StaticPacingController(
+                    args.bandwidth,
+                    args.set_mss if args.set_mss else 1200,
+                    args.time,
+                    args.interval,
+                )
+            tcp.client(
+                log,
+                args.address,
+                args.port,
+                args.congestion_control,
+                args.set_mss,
+                controller,
+            )
+
+    if controller is not None:
+        controller.stop()