Each published crate (irtt-rs, irtt-client, irtt-server, irtt-stats,
irtt-proto) now points crates.io at its own README instead of
inheriting the root project README via the workspace-wide readme
default, which is removed. Each crate README is a short landing page:
what the crate is, who should use it, which sibling crate to use
instead if this isn't the right abstraction level, and links to
docs.rs and the main repository.
Add real Cargo example targets teaching irtt-client's blocking/Tokio/
managed API tiers, a basic and a multi-listener irtt-server example,
and an irtt-stats example contrasting finite vs continuous retention.
irtt-proto intentionally has none. Update each crate's top-level
rustdoc to explain its API-tier choices and point at the examples, and
enable docs.rs rustdoc example scraping for irtt-client and
irtt-server (via doc-scrape-examples on each example target, needed
because the crate has dev-dependencies).
The client examples are caller-paced against next_send_deadline()
rather than sending on every loop iteration, bound their receive wait
by the next send/timeout deadline instead of awaiting indefinitely,
poll timeouts on a short fixed cadence, and surface send/receive/close
errors instead of discarding them via unwrap_or_default()/if-let-Ok --
so they demonstrate correct pacing and terminate/report cleanly rather
than racing the server, hanging on a lost reply, or silently dropping a
failed final close.
Reduce the root README to project discovery and navigation: what
irtt-rs is, its relationship to upstream IRTT (including a factual
capability comparison checked against upstream v0.9.2), installation,
a short quick start, and links out to detailed documentation. Detailed
CLI behavior, output/measurement semantics, continuous-mode memory
guidance, and server bind/session/negotiation semantics move into new
manpage-shaped docs under docs/ (irtt-rs, irtt-client, irtt-tui,
irtt-server), rewritten as operational guidance rather than copied
verbatim from the old README sections they replace.
With no --bind, the server now binds the wildcard IRTT port on both
address families ([::]:2112 then 0.0.0.0:2112) instead of requiring an
explicit address, on platforms where wildcard reply-source selection
is already supported. Any explicit --bind fully replaces the default
pair rather than adding to it; repeated explicit binds are unaffected.
If one of the two default listeners fails because its address family
has no local support on this host at all (IPv6 disabled on an
otherwise IPv4-capable host, for example), the server falls back to
serving just the surviving family instead of failing outright. Any
other failure reason -- the port already in use, permission denied, no
safe wildcard reply-source path -- is not a family-support problem and
is not silently worked around; startup fails as it would for an
explicit --bind. This distinction is made with the new
irtt_server::address_family_available, which actually binds the
wildcard address of the failed listener's family on an ephemeral port:
a bare socket can construct successfully even when every bind for that
family fails (Linux administratively disabling IPv6 per-interface
leaves AF_INET6 sockets constructible but every bind EADDRNOTAVAIL), so
only a real bind attempt is a reliable signal.
irtt_server::ServerCore::handle_datagram is a public API that
always passes kernel_rx_timestamp = None; only the crate-private
entry point the Tokio runtime (the irtt-server applet) uses
supplies one. Say so explicitly instead of implying every use of
this crate's server gets the preference.
irtt-client can talk to any IRTT-compatible peer, not only this
repo's own irtt-server, and has no way to know what clock source
produced a peer-reported wall-clock endpoint. Restrict the
kernel-receive-timestamp-preference claim to when the peer is
this crate's own Linux irtt-server; state plainly that another
peer's reported value is used as-is otherwise.
adjusted_rtt_us/effective_rtt_us are derived in part from
server-reported processing time, which is computed from the same
server receive endpoint the client_to_server one-way-delay field
documents as kernel-preferred. Only raw RTT is guaranteed to stay
on userspace monotonic timing; say so precisely instead of
claiming RTT in general is unaffected.
RUSTFLAGS="-D warnings" cargo check -p irtt-rs --no-default-features
--features client (or --features tui) warned on dead code: some
format.rs helpers are only called from the client applet, others
only from the TUI. Narrowly #[cfg(feature = "...")]-gate each to
the applet that actually uses it instead of allowing the warning
or introducing a new feature, and split the tests that exercised
both groups to match.
ManagedClientHandle::update_targets() had a one-line rustdoc that
didn't say targets is a full desired-set replacement, that an
unchanged live target continues undisturbed, or that a changed
config or a terminal-generation resubmission starts a fresh
generation even for byte-identical config.
On Linux, one-way delay measurement best-effort prefers kernel
send/receive timestamps over userspace timing, falling back
whenever a kernel reading is unavailable or implausible. RTT is
unaffected and remains userspace-timed.
Add a user-facing README note near the measurement/output
explanation, and bring OneWayDelaySample::client_to_server's
rustdoc in line with the send-endpoint behavior, matching the
style already used for server_to_client. Also fix a stale
socket_io module doc that still claimed the captured kernel
receive timestamp went unconsumed; ServerCore has used it via
preferred_receive_wall_ns since d3f93a9.
Final per-target summaries print in the order targets were
supplied on the command line, not finish order or alphabetical
label order. This only concerns the end-of-run summary printout;
it says nothing about ordering of live/interleaved per-event
output.
The README led application users through cloning the repo and
building with cargo install --path, and led library consumers
through a local path dependency, even though irtt-rs and
irtt-client are now published. Make the registry the default
path for both and keep the local-checkout/path forms documented
as the alternative for development.
Remove the panic abort override and synchronize LTO settings across release and distribution profiles to ensure consistent binary optimization and debugging behavior.
The shared with_shutdown_flag helper, and the AtomicBool/Arc/
install_signal_handler imports it uses, only exist when at least one
applet feature (client, server, tui) is enabled. Gate them accordingly
instead of leaving them unconditionally compiled, which broke
`--no-default-features` workspace CI under -D warnings (unused
function/dead-code).
Also correct the README installation section: tui is already part of
the default feature set, so an ordinary `cargo install` already
produces irtt-tui alongside the other three binaries. Document a
lightweight `--no-default-features --features client` install instead
of the previous (incorrect) framing of tui as an opt-in extra, and fix
the same gap in the binaries/features table.
Rename the application Cargo package from irtt-cli to irtt-rs
(crates/irtt-cli -> crates/irtt-app), and hard-rename its scriptable
client binary from irtt-cli to irtt-client, now that the application
also ships a first-class server and the old name reads as an umbrella
CLI for both roles.
Give each dedicated binary (irtt-client, irtt-tui, irtt-server) its
own entry point instead of funneling through the multicall
dispatcher's argv0/subcommand logic, so a dedicated binary only links
the applet code for the role it implements and always runs that role
regardless of the name it's invoked or copied under. irtt-rs remains
the feature-selectable multicall dispatcher and is now the only binary
that inspects argv0 or subcommands.
Move future application releases to the irtt-rs/vX.Y.Z tag namespace
(regenerated via `dist generate`), and bump the application package to
0.6.0 as a breaking distribution change. Library crate versions are
unaffected.
--hmac "" silently produced an empty-byte HMAC key at the protocol
boundary, so an accidentally-empty shell expansion (--hmac "$VAR")
could look like auth was deliberately enabled while actually using a
predictable empty key. Reject a zero-length --hmac value at parse
time in the client CLI, the TUI client (via the shared
CommonClientArgs), and the server CLI. Non-empty values, including
whitespace-only ones, are accepted exactly as supplied.
TABLE output formatted every column value with format!("{value:<width$}"),
which only sets a minimum width. Target is free-form/user-controlled and
is the first default table column, so a long target label pushed every
later column out of alignment while numeric/measurement columns stayed
correct.
Add a table-only truncation for Column::Target: labels within
table_width() (18) render unchanged; longer labels keep a
character-boundary-safe prefix and end with "..." so the rendered cell
is exactly 18 characters. This is scoped to format_table_cell's Target
case only, so it cannot silently shorten any measurement/data column.
CSV, TSV, and JSONL are untouched and keep emitting the full,
untruncated target label.
Final multi-target summaries were printed by iterating the label-keyed
BTreeMap directly, so they came out in lexicographic label order
instead of the order targets were given on the command line. Iterate
setup.targets (the canonical prepared CLI order) instead, looking up
each target's stats by label, and keep the BTreeMap only for
event-time lookup.
Adds a proptest-based model test that drives generated sequences of
probe sends, valid/duplicate/late/unknown/wrong-token replies, bounded
and unbounded timeout polling, peer/local close, and u32 wire-sequence
wraparound through a real SessionMachine and an independent reference
model, asserting the observable state and every emitted event match
after each operation. This combinatorial interleaving of an open
session's operations was previously untested; existing tests are all
narrow single-scenario cases.
ServerSet's startup/bind-failure paths were already covered, but nothing
exercised a listener failing after every listener had bound and was
actively serving. Inject the failure through the crate's own established
token-source test seam (the same one core::tests already uses) via a
narrow #[cfg(test)] Server::from_socket_with_core constructor, so one
listener answers a first open like its healthy sibling before its second
draw fails deterministically. Confirms ServerSet reports the failure,
shuts the sibling down, joins both tasks and releases both sockets, with
no external shutdown ever sent.
Add proptest-based generative tests for irtt-stats's stateful rolling
windows and IPDV pairing.
The rolling_count and rolling_time bounds turn out to be two
independent VecDeques (rolling.rs), not a single window bounded by
both, so the main property test proves that independence: it drives a
StatsCollector configured with both bounds simultaneously through
generated operation streams, checking after every operation that each
window matches a from-scratch reference model applying only its own
bound (and that the cumulative snapshot matches a full-history
replay). Since both the production window and the reference replay
the same events through the same deterministic aggregation code, the
comparison is exact equality, not a tolerance.
Also add two smaller property tests for IpdvTracker's bounded FIFO
state and at-most-once adjacent-pair emission under arbitrary
(including non-monotonic and duplicate) sequence streams, complementing
the existing strictly-increasing hand test.
No discrepancies between production and the reference model were
found.
Add proptest-based property tests for irtt-proto's varint and Params
codecs, covering the full u64/i64 domains for varint/zigzag round trips
and generated valid Params for semantic round trips, presence
omission rules, repeated-tag last-wins behavior, and unknown-tag
tolerance.
Installing cargo-fuzz under a nightly directory override made rustix's
build script (a cargo-fuzz dependency) gate on `rustc_attrs`, which this
runner's nightly rejects as reserved-for-rustc. Install nightly without
overriding the directory default so `cargo install cargo-fuzz` still
builds under stable; only `fuzz build`/`fuzz run` opt into `+nightly`.
Add isolated cargo-fuzz/libFuzzer infrastructure for irtt-proto, fuzzing
decode_request, decode_open_reply, decode_echo_reply, Params::decode(_with_presence),
and the varint codec against arbitrary and structurally-derived wire input.
Each target's core invariant is that arbitrary bytes must never panic; a
small clean-room seed corpus (generated from irtt-proto's own encoders) and
a bounded nightly smoke CI workflow are included. The fuzz project is its
own isolated cargo workspace and does not affect the root workspace, its
lockfile, or any published crate's dependency graph.
cargo-deny's licenses check requires a license expression even on an
unpublished crate; add the workspace's Apache-2.0 license so the check
passes rather than treating irtt-integration-tests as unlicensed.
irtt-client and irtt-server mutually dev-depended on each other for
cross-crate integration tests. That cycle blocks `cargo publish` for
either crate whenever the other doesn't already exist on the registry
at the required version, which is exactly the situation for a crate's
first-ever release (irtt-server has never been published before).
Introduce a new `irtt-integration-tests` crate (publish = false, no
library target) to own tests whose actual subject is the interaction
between two or more irtt-* production crates:
crate-local behavior -> crate's own tests/
cross-crate/system behavior -> irtt-integration-tests
Move every test that imports both irtt_client and irtt_server there:
the client-side support harness (hmac, large_packets, protocol_options,
fill_negotiation) and the server-side real-socket tests that drive a
real AsyncClient against a real Server (async_client, negotiation_policy,
fill_wire_bytes, traffic_class, wildcard_source). server_set.rs stays in
irtt-server/tests since it only uses irtt_proto as test machinery to
drive irtt-server directly, which is a normal one-directional test
dependency, not a peer relationship.
irtt-server's dev-dependency on irtt-client is dropped entirely now
that nothing under crates/irtt-server/tests needs it, which fully
breaks the cycle from that side.
irtt-client keeps a one-directional dev-dependency on irtt-server: a
handful of white-box unit tests in src/async_client/tests.rs assert on
private AsyncClient internals (socket, remote, test_hooks) while also
needing a real in-tree server for blocking/async equivalence checks, so
they can't move to an external crate without losing that access. Their
InTreeServer helper is duplicated locally rather than shared, matching
the existing precedent of irtt-cli's own tests/support/in_tree_server.rs.
Each workspace crate now owns its own version instead of the previous
lockstep scheme; irtt-proto, irtt-client, irtt-server, irtt-stats, and
irtt-cli all become 0.5.0 as the first independently-versioned release.
Workspace dependency requirements are bumped to match.
Add a root CHANGELOG.md with a real per-crate 0.5.0 section drawn from
archaeology of every merge since v0.4.0, not just path-filtered commits.
Move cargo-dist to a crate-qualified `irtt-cli/vX.Y.Z` tag namespace so
only irtt-cli (the one dist-able application) triggers a GitHub Release;
library crate tags (irtt-proto/irtt-client/irtt-server/irtt-stats) exist
purely to pin the source for a crates.io release and no longer risk
tripping the release workflow. Regenerate the renamed
irtt-cli-release.yml via `dist generate` and update the few other files
that referenced the old release.yml path by name. Also fix a stale
`features = ["full"]` in dist-workspace.toml left over from a feature-flag
refactor that dropped the "full" feature entirely, which was silently
breaking every dist build.
Rescope semver.yml's tag trigger to the same five crate-qualified tags
so semver checks keep running under the new convention.
- Error-queue drain: an interrupted MSG_ERRQUEUE read no longer ends
the bounded drain early as if the queue were empty (which could
strand a still-queued TX timestamp past the point its probe is
looked up and removed). It now reports ErrorQueueRecord::Ignored,
consuming one attempt of the drain's existing per-call work budget
and retrying the same slot instead.
- Fake-server recv_from test helpers (client_multi_target.rs and
tests/support/mod.rs) now keep one absolute deadline across
interruptions, re-applying only the remaining time on each retry
and restoring the configured timeout afterward, mirroring the
production blocking-receive fix these tests exist to guard rather
than restarting the full timeout on every interruption.
Real signal delivery on Linux (observed via x86_64-musl workspace
testing) can interrupt blocking and nonblocking recv/recvmsg calls
with EINTR. Several production and test receive paths treated that as
a fatal error rather than a transient interruption:
- Client::open's blocking receive loop and Client::recv_once/
recv_available's blocking receive returned ClientError::Socket on
Interrupted instead of retrying within their existing timeout
budget.
- AsyncClient::poll_open and poll_recv's nonblocking recvmsg path
(Linux ancillary) failed the same way instead of retrying through
the existing readiness/work-budget machinery.
- The server's ancillary receive loop could terminate the listener on
an interrupted nonblocking recvmsg.
- The client's MSG_ERRQUEUE TX-timestamp drain turned an interrupted
read of optional metadata into a fatal ClientError::Socket.
- Fake-server test helpers panicked or misclassified EINTR as a
timeout instead of retrying it.
Interrupted is now retried transparently everywhere a receive can
observe it, while preserving each path's existing timing contract:
- Blocking Open reuses its already-absolute per-attempt deadline, so
interruptions resume within the same attempt without retransmitting
or extending the deadline.
- recv_once/recv_available compute one absolute deadline per logical
receive (when a timeout is configured) so repeated interruptions
cannot extend it past the configured timeout, and restore the
socket's configured read timeout afterward so a later call in the
same recv_available budget is unaffected.
- AsyncClient's poll_open already bounds its retry loop with
OPEN_POLL_WORK_BUDGET; poll_recv gains an equivalent
RECV_POLL_WORK_BUDGET, since unlike WouldBlock, Interrupted does not
clear Tokio's readiness state, so an unbounded retry loop was
otherwise possible under sustained signal delivery.
- The server's receive loop retries Interrupted the same way it
already retries WouldBlock, yielding to the runtime after a bounded
number of consecutive interruptions for the same reason.
- The error-queue drain treats an interrupted read as no record
obtained this drain (deferring to the next natural drain point)
rather than a socket error, matching its existing EWOULDBLOCK
handling.
Deterministic regression tests use a small test-only injection hook
(mirroring existing send-injection test hooks) rather than real signal
timing, covering: Open completing despite interruptions with no
retransmit, Open's deadline not extending under repeated
interruptions, recv_once classifying a reply normally despite
interruptions, recv_once's timeout not extending under repeated
interruptions, and the AsyncClient equivalents for open and recv.
No protocol, session, or timeout-classification behavior changes; no
new dependencies; send-side EINTR handling is unchanged and out of
scope.
Nils Andreas Svee