irtt-rs/crates/irtt-client/README.md

irtt-client

Reusable client/session library for IRTT-compatible round-trip-time probing: socket lifecycle, open negotiation, probe send/receive, loss/duplicate/late classification, and a typed event stream.

Looking for the CLI?

If you just want to run probes from the command line, use the irtt-rs application package instead, which installs the irtt-client binary. This crate is the library the binaries are built on.

API tiers

• Client — runtime-free blocking adapter. No Tokio dependency; this is the default build.
• AsyncClient (feature tokio) — low-level Tokio adapter for callers that own a runtime and drive readiness directly.
• managed (feature tokio) — a unified managed driver: ManagedClientTask / ManagedClientHandle for multi-target orchestration under a Tokio runtime, and BlockingManagedClient for synchronous callers, which owns its own dedicated current-thread runtime.

Client and AsyncClient send one probe whenever called. They expose the negotiated parameters, pending-probe status, and timeout deadlines; callers own cadence and run duration. The managed driver provides fixed cadence, missed-slot handling, finite runs, and staggered or burst pacing. Low-level sends return Result<SendReceipt, SendProbeError> instead of event lists. A SendReceipt carries the committed sequence, remote, post-send timestamp, accepted bytes, and send-call duration. NotCommitted(ClientError) guarantees no accepted datagram or committed probe; AfterCommit { receipt, source } preserves the accepted send when subsequent validation or TX processing fails. Use ClientEvent::from(receipt) for an EchoSent event with scheduled_at and timer_error absent; the managed driver supplies those schedule measurements and publishes committed sends even when post-send processing fails.

Tokio stays optional: the default build has no runtime and no Tokio dependency at all.

See examples/ in the repository for runnable examples of each tier.

Reusable configuration

ClientConfig contains no endpoint. The low-level APIs take it separately: Client::connect(endpoint, config) and AsyncClient::connect(endpoint, config).await, accepting String or &str endpoints. An omitted port defaults to 2112.

Configuration is grouped by ownership:

• address_family: AddressFamily::{Any, Ipv4, Ipv6}, defaulting to Any. It filters remote resolution; Ipv6 also sets IPV6_V6ONLY.
• socket: SocketConfig for local bind, device/routing options, and TTL.
• request: SessionRequest for duration, interval, length, received stats, timestamps, clock, DSCP, server fill, and run mode.
• open: OpenPolicy for attempt timeouts and negotiation policy.
• auth, probe_timeout, and max_pending_probes: authentication and local probe tracking policy.

Clone one config to connect to multiple endpoints. Managed targets retain their own ID, endpoint, address-family override, and authentication inheritance/override; shared ManagedClientConfig.client is reusable without endpoint mutation.

ManagedTargetConfig.address_family defaults to None, inheriting the shared family policy. Some(AddressFamily::Ipv4), Some(AddressFamily::Ipv6), or Some(AddressFamily::Any) overrides it for that target. Every new generation resolves the original endpoint again; callers can constrain a hostname without replacing it with a resolved IP. Changing the family specification replaces that target's generation, including switching between inheritance and an equal explicit override. Hostname expansion and discovery are frontend policies.

Blocking receive policy belongs to Client: client.set_recv_timeout(Some(duration))? sets it before or after opening, and client.set_recv_timeout(None)? restores the default indefinite wait. Open attempts use only open.timeouts, restoring the adapter setting afterward. Async and managed clients have no blocking receive-timeout setting.

This breaks the former flat config, endpoint-in-config, socket family flags, and SocketConfig.recv_timeout APIs. Use the grouped fields and adapter method directly; defaults and protocol/runtime behavior are preserved.

Authentication

ClientConfig.auth is concrete: Authentication::Unauthenticated or Authentication::Hmac(HmacKey::new(bytes)). Keys share their bytes across clones and print only HmacKey([REDACTED]) through Debug. Borrowing key material requires an explicit as_bytes() call. An empty key still selects HMAC authentication; textual key syntax belongs to the application.

For managed targets, ManagedTargetConfig.auth defaults to TargetAuth::Inherit. TargetAuth::Override(Authentication::Unauthenticated) disables shared authentication, and TargetAuth::Override(Authentication::Hmac(key)) replaces the shared key. Initial construction and update planning resolve inheritance into concrete session authentication before execution. Switching between inheritance and an override replaces the target generation even when their resolved authentication is equal.

This replaces the former ClientConfig.hmac_key and ClientAuthConfig API; there are no compatibility aliases.

Documentation

Full API documentation is on docs.rs/irtt-client.

Project

Part of irtt-rs, an independent Rust implementation of an IRTT-compatible protocol stack.