330 lines
12 KiB
Rust
330 lines
12 KiB
Rust
use std::{net::SocketAddr, time::Duration};
|
|
|
|
use crate::{Authentication, ClientError};
|
|
|
|
/// Protocol compatibility bound for a requested `server_fill` value, in UTF-8
|
|
/// bytes.
|
|
///
|
|
/// This is the maximum encoded server-fill string accepted by this client and
|
|
/// protocol decoder. [`SessionRequest::server_fill`] enforces the same bound
|
|
/// before opening a session.
|
|
pub use irtt_proto::MAX_SERVER_FILL_BYTES;
|
|
use irtt_proto::{Clock, ReceivedStats, StampAt};
|
|
|
|
pub(crate) const DEFAULT_PORT: u16 = 2112;
|
|
/// Largest valid DSCP codepoint accepted by client configuration.
|
|
///
|
|
/// DSCP is a six-bit value in the range `0..=63`. The client shifts it left
|
|
/// by two bits into the raw IP TOS / Traffic Class byte carried by
|
|
/// [`irtt_proto::Params::dscp`] and applied to the socket during the active
|
|
/// test phase.
|
|
pub const MAX_DSCP_CODEPOINT: u8 = 63;
|
|
/// Largest IPv4 TTL or IPv6 hop-limit value accepted by client configuration.
|
|
///
|
|
/// This is the public user-configuration bound for
|
|
/// [`SocketConfig::ttl`]. A value of zero is rejected separately because socket
|
|
/// TTL and hop-limit settings are configured as `1..=255`.
|
|
pub const MAX_TTL: u32 = 255;
|
|
/// Largest UDP payload length accepted by client configuration, in bytes.
|
|
///
|
|
/// This is the maximum UDP payload size excluding IP and UDP headers. It caps
|
|
/// [`SessionRequest::length`] before protocol packets are encoded or sent.
|
|
pub const MAX_UDP_PAYLOAD_LENGTH: u32 = 65_507;
|
|
pub(crate) const DEFAULT_DURATION: Duration = Duration::from_secs(3);
|
|
pub(crate) const DEFAULT_INTERVAL: Duration = Duration::from_secs(1);
|
|
pub(crate) const DEFAULT_OPEN_TIMEOUTS: [Duration; 4] = [
|
|
Duration::from_secs(1),
|
|
Duration::from_secs(2),
|
|
Duration::from_secs(4),
|
|
Duration::from_secs(8),
|
|
];
|
|
pub(crate) const MIN_OPEN_TIMEOUT: Duration = Duration::from_millis(200);
|
|
pub(crate) const DEFAULT_PROBE_TIMEOUT: Duration = Duration::from_secs(4);
|
|
pub(crate) const DEFAULT_MAX_PENDING: usize = 4096;
|
|
|
|
/// Configuration for opening and running an IRTT client session.
|
|
///
|
|
/// This type describes both the protocol parameters sent in the IRTT open
|
|
/// request and the local client behavior used to drive the UDP socket. Values
|
|
/// that are negotiated by the server are available after opening the session
|
|
/// through [`NegotiationResult`](crate::NegotiationResult).
|
|
///
|
|
/// # Example
|
|
///
|
|
/// Configure a finite run with larger probes and accept documented server
|
|
/// restrictions. Use `duration: None` for continuous mode, or
|
|
/// [`RunMode::NoTest`] for negotiation without probes.
|
|
///
|
|
/// ```
|
|
/// use std::time::Duration;
|
|
///
|
|
/// use irtt_client::{ClientConfig, NegotiationPolicy, OpenPolicy, SessionRequest};
|
|
///
|
|
/// let config = ClientConfig {
|
|
/// request: SessionRequest {
|
|
/// duration: Some(Duration::from_secs(10)),
|
|
/// interval: Duration::from_millis(250),
|
|
/// length: 1200,
|
|
/// ..SessionRequest::default()
|
|
/// },
|
|
/// open: OpenPolicy {
|
|
/// negotiation: NegotiationPolicy::Loose,
|
|
/// ..OpenPolicy::default()
|
|
/// },
|
|
/// ..ClientConfig::default()
|
|
/// };
|
|
///
|
|
/// assert_eq!(config.request.duration, Some(Duration::from_secs(10)));
|
|
/// assert_eq!(config.request.interval, Duration::from_millis(250));
|
|
/// assert_eq!(config.request.length, 1200);
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct ClientConfig {
|
|
/// Remote address families allowed during resolution and socket creation.
|
|
pub address_family: AddressFamily,
|
|
/// Local UDP socket properties.
|
|
pub socket: SocketConfig,
|
|
/// Protocol and session values requested from the server.
|
|
pub request: SessionRequest,
|
|
/// Open retry timeouts and negotiation policy.
|
|
pub open: OpenPolicy,
|
|
/// Concrete authentication for open, echo, and close packets.
|
|
///
|
|
/// HMAC peers must use the same key. An empty HMAC key remains authenticated.
|
|
pub auth: Authentication,
|
|
/// Time after sending a probe before the client reports it as lost.
|
|
///
|
|
/// This timeout is local client behavior; it is not negotiated with the
|
|
/// server. It must be greater than zero.
|
|
pub probe_timeout: Duration,
|
|
/// Maximum number of probes tracked as pending/timed-out/completed.
|
|
///
|
|
/// This bounds memory used for reply classification and must be greater
|
|
/// than zero. A very small value can reject sends when replies are still
|
|
/// outstanding.
|
|
pub max_pending_probes: usize,
|
|
}
|
|
|
|
impl Default for ClientConfig {
|
|
fn default() -> Self {
|
|
Self {
|
|
address_family: AddressFamily::default(),
|
|
socket: SocketConfig::default(),
|
|
request: SessionRequest::default(),
|
|
open: OpenPolicy::default(),
|
|
auth: Authentication::Unauthenticated,
|
|
probe_timeout: DEFAULT_PROBE_TIMEOUT,
|
|
max_pending_probes: DEFAULT_MAX_PENDING,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Allowed remote address families. IPv6-only selection also sets IPV6_V6ONLY.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
|
|
pub enum AddressFamily {
|
|
/// Accept IPv4 and IPv6 addresses.
|
|
#[default]
|
|
Any,
|
|
/// Accept only IPv4 addresses.
|
|
Ipv4,
|
|
/// Accept only IPv6 addresses and use IPv6-only sockets.
|
|
Ipv6,
|
|
}
|
|
|
|
/// Requested IRTT protocol and session semantics, reusable across endpoints.
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct SessionRequest {
|
|
/// Requested run duration.
|
|
///
|
|
/// `Some(duration)` requests a finite test and must be greater than zero.
|
|
/// `None` requests continuous mode and is encoded on the wire as a zero
|
|
/// duration. Use [`RunMode::NoTest`] when the caller wants negotiation only
|
|
/// without sending probes.
|
|
///
|
|
/// The managed driver stops sending after the negotiated duration.
|
|
/// Low-level adapters leave run duration to the caller.
|
|
pub duration: Option<Duration>,
|
|
/// Requested spacing between probe sends.
|
|
///
|
|
/// The interval is encoded as nanoseconds in the open request and must be
|
|
/// greater than zero. The server may return a different interval depending
|
|
/// on the negotiated policy and server restrictions.
|
|
///
|
|
/// The managed driver uses the negotiated interval for cadence.
|
|
/// Low-level adapters send whenever called.
|
|
pub interval: Duration,
|
|
/// Requested echo packet payload length, in bytes.
|
|
///
|
|
/// The value must fit within the UDP payload limit after protocol overhead.
|
|
/// A server may reduce the requested length during negotiation.
|
|
pub length: u32,
|
|
/// Requested server receive-statistics fields in echo replies.
|
|
pub received_stats: ReceivedStats,
|
|
/// Requested timestamp placement in echo replies.
|
|
pub stamp_at: StampAt,
|
|
/// Requested server clock sources for timestamp fields.
|
|
///
|
|
/// [`Clock::Unspecified`] is the wire default meaning "no clock tag was
|
|
/// sent" and is not a client mode; opening a session with it is rejected.
|
|
/// Request [`Clock::Wall`], [`Clock::Monotonic`], or [`Clock::Both`].
|
|
pub clock: Clock,
|
|
/// Requested DSCP codepoint.
|
|
///
|
|
/// This is the six-bit DSCP value, not the full traffic-class byte, and
|
|
/// must be less than or equal to [`MAX_DSCP_CODEPOINT`].
|
|
pub dscp: u8,
|
|
/// Optional server payload fill request.
|
|
///
|
|
/// `None` leaves server fill behavior unspecified. `Some(value)` requests
|
|
/// a non-empty server fill mode/value and must not exceed
|
|
/// [`MAX_SERVER_FILL_BYTES`] bytes when UTF-8 encoded.
|
|
pub server_fill: Option<String>,
|
|
/// Whether opening the session should start a probe test or perform a
|
|
/// negotiation-only no-test exchange.
|
|
pub run_mode: RunMode,
|
|
}
|
|
|
|
impl Default for SessionRequest {
|
|
fn default() -> Self {
|
|
Self {
|
|
duration: Some(DEFAULT_DURATION),
|
|
interval: DEFAULT_INTERVAL,
|
|
length: 0,
|
|
received_stats: ReceivedStats::Both,
|
|
stamp_at: StampAt::Both,
|
|
clock: Clock::Both,
|
|
dscp: 0,
|
|
server_fill: None,
|
|
run_mode: RunMode::Normal,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Opening behavior shared by blocking, async, and managed clients.
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct OpenPolicy {
|
|
/// Per-attempt receive timeouts used while opening the session.
|
|
///
|
|
/// The client sends an open request for each entry until a valid open reply
|
|
/// is received. The list must not be empty, and each timeout must be at
|
|
/// least 200 ms.
|
|
pub timeouts: Vec<Duration>,
|
|
/// Policy for server changes to negotiable protocol parameters.
|
|
pub negotiation: NegotiationPolicy,
|
|
}
|
|
|
|
impl OpenPolicy {
|
|
pub(crate) fn validate(&self) -> Result<(), ClientError> {
|
|
if self.timeouts.is_empty() {
|
|
return Err(ClientError::NoOpenTimeouts);
|
|
}
|
|
for timeout in &self.timeouts {
|
|
if *timeout < MIN_OPEN_TIMEOUT {
|
|
return Err(ClientError::OpenTimeoutTooSmall {
|
|
timeout: *timeout,
|
|
minimum: MIN_OPEN_TIMEOUT,
|
|
});
|
|
}
|
|
}
|
|
Ok(())
|
|
}
|
|
}
|
|
|
|
impl Default for OpenPolicy {
|
|
fn default() -> Self {
|
|
Self {
|
|
timeouts: DEFAULT_OPEN_TIMEOUTS.to_vec(),
|
|
negotiation: NegotiationPolicy::Strict,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Local UDP socket options used by [`ClientConfig`].
|
|
///
|
|
/// These settings affect how the client binds and sends from the socket. They
|
|
/// do not change the IRTT protocol parameters negotiated with the server.
|
|
///
|
|
/// # Example
|
|
///
|
|
/// Bind to a chosen local endpoint and set the outgoing IPv4 TTL:
|
|
///
|
|
/// ```
|
|
/// use std::net::{Ipv4Addr, SocketAddr};
|
|
///
|
|
/// use irtt_client::{AddressFamily, ClientConfig, SocketConfig};
|
|
///
|
|
/// let config = ClientConfig {
|
|
/// address_family: AddressFamily::Ipv4,
|
|
/// socket: SocketConfig {
|
|
/// bind_addr: Some(SocketAddr::from((Ipv4Addr::UNSPECIFIED, 0))),
|
|
/// ttl: Some(32),
|
|
/// ..SocketConfig::default()
|
|
/// },
|
|
/// ..ClientConfig::default()
|
|
/// };
|
|
///
|
|
/// assert_eq!(config.socket.ttl, Some(32));
|
|
/// assert_eq!(config.address_family, AddressFamily::Ipv4);
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq, Default)]
|
|
pub struct SocketConfig {
|
|
/// Local address to bind before connecting the UDP socket.
|
|
///
|
|
/// `None` binds to an unspecified address with an ephemeral port matching
|
|
/// the selected remote address family.
|
|
pub bind_addr: Option<SocketAddr>,
|
|
/// Network interface to bind this socket to (`SO_BINDTODEVICE`).
|
|
#[cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux"))]
|
|
pub bind_to_device: Option<String>,
|
|
/// Firewall mark applied to outgoing packets (`SO_MARK`).
|
|
#[cfg(any(target_os = "android", target_os = "fuchsia", target_os = "linux"))]
|
|
pub mark: Option<u32>,
|
|
/// FreeBSD FIB used for routing this socket (`SO_SETFIB`).
|
|
#[cfg(target_os = "freebsd")]
|
|
pub fib: Option<u32>,
|
|
/// Optional IPv4 TTL or IPv6 hop limit applied to sent packets.
|
|
///
|
|
/// `None` leaves the platform default unchanged. Values must fit in the
|
|
/// platform socket option range; [`MAX_TTL`] is the public configuration
|
|
/// bound used by this crate.
|
|
pub ttl: Option<u32>,
|
|
}
|
|
|
|
/// How strictly to handle server-side negotiation restrictions.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub enum NegotiationPolicy {
|
|
/// Reject any negotiated parameter that is more restrictive or different
|
|
/// than requested.
|
|
Strict,
|
|
/// Accept documented server restrictions and report them in
|
|
/// [`NegotiationResult`](crate::NegotiationResult).
|
|
Loose,
|
|
}
|
|
|
|
/// Mode requested during the IRTT open exchange.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub enum RunMode {
|
|
/// Open a probe session. The managed driver runs for the negotiated duration;
|
|
/// low-level adapters leave sending and stopping to the caller.
|
|
Normal,
|
|
/// Complete negotiation without running the echo probe test.
|
|
NoTest,
|
|
}
|
|
|
|
/// Bound for a single receive-drain operation.
|
|
///
|
|
/// This is used by lower-level callers that drive [`Client`](crate::Client)
|
|
/// directly and want to cap how many datagrams are processed before returning
|
|
/// to their own event loop.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub struct RecvBudget {
|
|
/// Maximum number of datagrams to process before returning.
|
|
pub max_packets: usize,
|
|
}
|
|
|
|
impl Default for RecvBudget {
|
|
fn default() -> Self {
|
|
Self { max_packets: 64 }
|
|
}
|
|
}
|