ipyrf 1.5.1

Features

• TCP and UDP tests

• JSON or human-readable output

• Optional bandwidth capping (TCP/UDP)

• UDP packet loss estimation

• Optional per-datagram UDP packet recording

• Linux TCP congestion control selection (if available)

Installation

From PyPI (recommended):

python3 -m pip install ipyrf

From source (editable):

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -U pip build
python3 -m pip install -e .

from ipyrf.test import IPyrfBuilder, CheckCriteria

def test_my_network(testdirectory):
    builder = IPyrfBuilder(testdirectory)
    port = 12345

    server = builder.build()
    client = builder.build()

    server.run_tcp_server("127.0.0.1", port)
    client.run_tcp_client("127.0.0.1", port, duration=2)

    # Check with custom criteria
    builder.check(
        (server, client),
        timeout=5,
        criteria={"min_bps": 1000000}
    )

# Run all tests
python3 waf --run_tests

Usage

The package installs a console script named ipyrf.

ipyrf tcp server 0.0.0.0 --port 12345

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

ipyrf udp server 0.0.0.0 --port 12345
ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv

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:

# 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:

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)

• --packet-record PATH: UDP server: write received packet traces to a CSV file after the test

• --interactive: Enable interactive pacing controls

• --interval: Stats interval in seconds for interactive mode (default 1.0)

UDP packet recording

Pass --packet-record PATH to a UDP server to record one trace entry per received datagram (sequence number, sender timestamp, receiver timestamp, packet size). Records are packed into fixed-size in-memory chunks during the test so the receive path stays free of CSV I/O. Chunks are allocated before the test starts (about 20 s of 1 Gbit/s traffic by default) so rotation does not stall the receive loop. When the test ends, the CSV file (columns sequence, size_bytes, transmitted_ns, received_ns) is written to PATH. Per-packet latency in nanoseconds is received_ns - transmitted_ns.

Quick local test (two terminals):

# Terminal 1 — server with recording
ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv

# Terminal 2 — short paced client
ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 2 -l 1200

When the client finishes, the server exits and packets.csv contains the trace. Use --enable-latency on the client if you also want latency stats in the server summary.

JSON logging

Add --json_log to switch all output to newline-delimited JSON objects. This is useful for machine parsing or dashboards. Example:

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.