fix(tests): break the irtt-client/irtt-server dev-dependency cycle

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.

crates/irtt-integration-tests/tests/support/in_tree_server.rs

@@ -0,0 +1,74 @@
+use std::{
+    net::{IpAddr, Ipv4Addr, SocketAddr},
+    sync::mpsc,
+    thread::{self, JoinHandle},
+    time::Duration,
+};
+
+use irtt_server::{Server, ServerConfig};
+use tokio::sync::oneshot;
+
+const STARTUP_TIMEOUT: Duration = Duration::from_secs(2);
+
+pub struct InTreeServer {
+    pub addr: SocketAddr,
+    shutdown: Option<oneshot::Sender<()>>,
+    done: Option<JoinHandle<Result<(), irtt_server::ServerRuntimeError>>>,
+}
+
+impl InTreeServer {
+    pub fn start(config: ServerConfig) -> Self {
+        let (startup_tx, startup_rx) = mpsc::sync_channel(1);
+        let (shutdown_tx, shutdown_rx) = oneshot::channel();
+        let done = thread::spawn(move || {
+            let runtime = tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+                .expect("failed to build in-tree test server runtime");
+            runtime.block_on(async move {
+                let bind_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
+                let mut server = Server::bind(bind_addr, config).await?;
+                startup_tx
+                    .send(server.local_addr()?)
+                    .expect("test stopped waiting for in-tree server startup");
+                server
+                    .run(async {
+                        let _ = shutdown_rx.await;
+                    })
+                    .await
+            })
+        });
+
+        let addr = match startup_rx.recv_timeout(STARTUP_TIMEOUT) {
+            Ok(addr) => addr,
+            Err(error) => {
+                let _ = shutdown_tx.send(());
+                let result = done.join().expect("in-tree test server thread panicked");
+                panic!("in-tree test server failed before startup ({error}): {result:?}");
+            }
+        };
+
+        Self {
+            addr,
+            shutdown: Some(shutdown_tx),
+            done: Some(done),
+        }
+    }
+
+    fn stop_inner(&mut self) {
+        if let Some(shutdown) = self.shutdown.take() {
+            let _ = shutdown.send(());
+        }
+        if let Some(done) = self.done.take() {
+            done.join()
+                .expect("in-tree test server thread panicked")
+                .expect("in-tree test server stopped with an error");
+        }
+    }
+}
+
+impl Drop for InTreeServer {
+    fn drop(&mut self) {
+        self.stop_inner();
+    }
+}

crates/irtt-integration-tests/tests/support/mod.rs

@@ -0,0 +1,638 @@
+#![allow(dead_code)]
+
+mod in_tree_server;
+mod real_irtt;
+
+use std::{
+    io::{self, ErrorKind},
+    net::{SocketAddr, UdpSocket},
+    process::Command,
+    sync::mpsc,
+    thread::{self, JoinHandle},
+    time::{Duration, Instant, SystemTime},
+};
+
+use irtt_client::{Client, ClientConfig, ClientEvent, NegotiatedParams, OpenOutcome, SocketConfig};
+use irtt_proto::{
+    compute_hmac_in_place, decode_request, echo_packet_len, encode_echo_reply, encode_open_reply,
+    flags, verify_packet_hmac, Clock, DecodedRequest, DecodedRequestKind, EchoReply, OpenReply,
+    PacketLayout, Params, ProtoError, ReceivedStats, ServerFill, StampAt, TimestampFields,
+    HMAC_SIZE, MAGIC, PROTOCOL_VERSION,
+};
+use irtt_server::ServerConfig;
+
+pub use in_tree_server::InTreeServer;
+pub use real_irtt::RealIrtServer;
+
+const HMAC_OFFSET: usize = 4;
+pub const TOKEN: u64 = 0x1234_5678_90ab_cdef;
+pub const RECV_COUNT: u32 = 42;
+pub const RECV_WINDOW: u64 = 0x07;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TestBackendKind {
+    InTree,
+    Real,
+}
+
+pub fn selected_backend() -> TestBackendKind {
+    match std::env::var("IRTT_TEST_BACKEND").as_deref() {
+        Ok("real") => {
+            let irtt_bin = std::env::var("IRTT_BIN").unwrap_or_else(|_| "irtt".to_string());
+            match Command::new(&irtt_bin).arg("version").output() {
+                Ok(output) if output.status.success() => {
+                    debug_backend("[backend] selected backend=real");
+                    TestBackendKind::Real
+                }
+                _ => panic!("IRTT_TEST_BACKEND=real but irtt binary not found at '{irtt_bin}'"),
+            }
+        }
+        Ok("in-tree") | Err(_) => {
+            debug_backend("[backend] selected backend=in-tree");
+            TestBackendKind::InTree
+        }
+        Ok(other) => panic!("unknown IRTT_TEST_BACKEND value: {other}"),
+    }
+}
+
+fn debug_backend(message: &str) {
+    if std::env::var("IRTT_TEST_BACKEND_DEBUG").as_deref() == Ok("1") {
+        eprintln!("{message}");
+    }
+}
+
+pub enum BackendPeer {
+    InTree(InTreeServer),
+    Real(RealIrtServer),
+}
+
+impl BackendPeer {
+    pub fn addr(&self) -> SocketAddr {
+        match self {
+            BackendPeer::InTree(s) => s.addr,
+            BackendPeer::Real(s) => s.addr(),
+        }
+    }
+
+    pub fn start_open_echo(hmac_key: Option<Vec<u8>>) -> Self {
+        match selected_backend() {
+            TestBackendKind::InTree => BackendPeer::InTree(InTreeServer::start(
+                hmac_key.map_or_else(ServerConfig::default, |key| {
+                    ServerConfig::default().with_hmac_key(key)
+                }),
+            )),
+            TestBackendKind::Real => {
+                BackendPeer::Real(RealIrtServer::start(hmac_key.as_deref()).unwrap())
+            }
+        }
+    }
+
+    pub fn start_hmac_required(key: Vec<u8>) -> Self {
+        match selected_backend() {
+            TestBackendKind::InTree => BackendPeer::InTree(InTreeServer::start(
+                ServerConfig::default().with_hmac_key(key),
+            )),
+            TestBackendKind::Real => BackendPeer::Real(RealIrtServer::start(Some(&key)).unwrap()),
+        }
+    }
+}
+
+pub struct FakeServer {
+    pub addr: SocketAddr,
+    rx: mpsc::Receiver<ServerObservation>,
+    done: JoinHandle<()>,
+}
+
+impl FakeServer {
+    pub fn observations(&self, count: usize) -> Vec<ServerObservation> {
+        self.rx.iter().take(count).collect()
+    }
+
+    pub fn join(self) {
+        self.done.join().unwrap();
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ServerObservation {
+    Open {
+        params: Params,
+        hmac: bool,
+    },
+    RejectedHmac {
+        hmac: bool,
+        bad_hmac: bool,
+    },
+    Echo {
+        len: usize,
+        hmac: bool,
+        token: u64,
+        sequence: u32,
+    },
+    Close {
+        hmac: bool,
+        token: u64,
+    },
+}
+
+pub struct OneProbeRun {
+    pub negotiated: NegotiatedParams,
+    pub sent: ClientEvent,
+    pub reply: ClientEvent,
+    pub observations: Vec<ServerObservation>,
+}
+
+pub fn default_params() -> Params {
+    Params {
+        protocol_version: PROTOCOL_VERSION,
+        duration_ns: 3_000_000_000,
+        interval_ns: 1_000_000_000,
+        received_stats: ReceivedStats::Both,
+        stamp_at: StampAt::Both,
+        clock: Clock::Both,
+        ..Params::default()
+    }
+}
+
+pub fn params_for_modes(received_stats: ReceivedStats, stamp_at: StampAt, clock: Clock) -> Params {
+    Params {
+        received_stats,
+        stamp_at,
+        clock,
+        ..default_params()
+    }
+}
+
+/// Builds a [`ClientConfig`] whose negotiated `Params` will match `params`.
+///
+/// `params.dscp` is the raw IP TOS / Traffic Class byte, while
+/// [`ClientConfig::dscp`] is the six-bit codepoint that produces it; shift
+/// right by two to recover the codepoint the resulting config must request.
+/// Panics if `params.dscp` has any ECN bits set, since those cannot be
+/// recovered from a codepoint and this helper's contract would silently stop
+/// holding otherwise.
+pub fn config_for_params(addr: SocketAddr, params: &Params) -> ClientConfig {
+    let traffic_class =
+        u8::try_from(params.dscp).expect("test DSCP must fit the raw traffic-class byte");
+    assert_eq!(
+        traffic_class & 0b11,
+        0,
+        "test Params::dscp must be representable by ClientConfig's DSCP codepoint"
+    );
+    ClientConfig {
+        server_addr: addr.to_string(),
+        duration: if params.duration_ns == 0 {
+            None
+        } else {
+            Some(Duration::from_nanos(
+                u64::try_from(params.duration_ns).expect("test duration must be non-negative"),
+            ))
+        },
+        interval: Duration::from_nanos(
+            u64::try_from(params.interval_ns).expect("test interval must be non-negative"),
+        ),
+        length: u32::try_from(params.length).unwrap(),
+        received_stats: params.received_stats,
+        stamp_at: params.stamp_at,
+        clock: params.clock,
+        dscp: traffic_class >> 2,
+        server_fill: params.server_fill.as_ref().map(|fill| fill.value.clone()),
+        open_timeouts: vec![Duration::from_millis(200)],
+        socket_config: SocketConfig {
+            recv_timeout: Some(Duration::from_millis(500)),
+            ..Default::default()
+        },
+        ..ClientConfig::default()
+    }
+}
+
+pub fn standard_timestamps() -> TimestampFields {
+    TimestampFields {
+        recv_wall: Some(0),
+        recv_mono: Some(5_000_000),
+        midpoint_wall: Some(0),
+        midpoint_mono: Some(5_000_000),
+        send_wall: Some(1),
+        send_mono: Some(5_000_001),
+    }
+}
+
+pub fn run_one_probe(params: Params, timestamps: TimestampFields) -> OneProbeRun {
+    let config_params = params.clone();
+    run_one_probe_with_config(params, timestamps, None, |addr| {
+        config_for_params(addr, &config_params)
+    })
+}
+
+pub fn run_one_probe_with_config<F>(
+    server_params: Params,
+    timestamps: TimestampFields,
+    hmac_key: Option<Vec<u8>>,
+    build_config: F,
+) -> OneProbeRun
+where
+    F: FnOnce(SocketAddr) -> ClientConfig,
+{
+    let server = start_one_probe_server(server_params, timestamps, hmac_key);
+    let mut client = Client::connect(build_config(server.addr)).unwrap();
+    let negotiated = assert_started(client.open().unwrap());
+
+    let sent_events = client.send_probe().unwrap();
+    assert_eq!(sent_events.len(), 1);
+
+    let reply_events = client.recv_once().unwrap();
+    assert_eq!(reply_events.len(), 1);
+
+    let observations = server.observations(2);
+    server.join();
+
+    OneProbeRun {
+        negotiated,
+        sent: sent_events.into_iter().next().unwrap(),
+        reply: reply_events.into_iter().next().unwrap(),
+        observations,
+    }
+}
+
+pub fn start_open_server(params: Params, hmac_key: Option<Vec<u8>>) -> FakeServer {
+    start_fake_server(move |socket, tx| {
+        let (request, peer) = recv_request(&socket);
+        let (open_params, hmac) = open_request_params(&request, hmac_key.as_deref());
+        tx.send(ServerObservation::Open {
+            params: open_params,
+            hmac,
+        })
+        .unwrap();
+
+        let reply = open_reply(
+            flags::FLAG_OPEN | flags::FLAG_REPLY,
+            TOKEN,
+            &params,
+            hmac_key.as_deref(),
+        );
+        socket.send_to(&reply, peer).unwrap();
+    })
+}
+
+pub fn start_hmac_required_open_drop_server(key: Vec<u8>, wait: Duration) -> FakeServer {
+    start_fake_server(move |socket, tx| {
+        socket.set_read_timeout(Some(wait)).unwrap();
+        while let Some(request) = recv_request_timeout(&socket) {
+            let hmac = decode_request(&request).is_ok_and(|request| request.hmac_present);
+            // A server with a key drops any request that fails authentication,
+            // whether it carried no HMAC field at all or a field signed with
+            // the wrong key.
+            match verify_packet_hmac(&key, &request) {
+                Ok(()) => {}
+                Err(error) => {
+                    tx.send(ServerObservation::RejectedHmac {
+                        hmac,
+                        bad_hmac: error == ProtoError::BadHmac,
+                    })
+                    .unwrap();
+                }
+            }
+        }
+    })
+}
+
+pub fn start_hmac_close_server(params: Params, key: Vec<u8>) -> FakeServer {
+    start_fake_server(move |socket, tx| {
+        let (request, peer) = recv_request(&socket);
+        let (open_params, hmac) = open_request_params(&request, Some(&key));
+        tx.send(ServerObservation::Open {
+            params: open_params,
+            hmac,
+        })
+        .unwrap();
+
+        let reply = open_reply(
+            flags::FLAG_OPEN | flags::FLAG_REPLY,
+            TOKEN,
+            &params,
+            Some(&key),
+        );
+        socket.send_to(&reply, peer).unwrap();
+
+        socket
+            .set_read_timeout(Some(Duration::from_secs(2)))
+            .unwrap();
+        let (request, peer) = recv_request(&socket);
+        let close = observe_close_request(&request, &key);
+        tx.send(close).unwrap();
+
+        let reply = close_reply(TOKEN, &key);
+        socket.send_to(&reply, peer).unwrap();
+    })
+}
+
+pub fn start_bad_hmac_echo_reply_server(params: Params, key: Vec<u8>) -> FakeServer {
+    start_fake_server(move |socket, tx| {
+        let (request, peer) = recv_request(&socket);
+        let (open_params, hmac) = open_request_params(&request, Some(&key));
+        tx.send(ServerObservation::Open {
+            params: open_params,
+            hmac,
+        })
+        .unwrap();
+
+        let reply = open_reply(
+            flags::FLAG_OPEN | flags::FLAG_REPLY,
+            TOKEN,
+            &params,
+            Some(&key),
+        );
+        socket.send_to(&reply, peer).unwrap();
+
+        socket
+            .set_read_timeout(Some(Duration::from_secs(2)))
+            .unwrap();
+        let (request, peer) = recv_request(&socket);
+        let echo = observe_echo_request(&request, Some(&key));
+        let sequence = match echo {
+            ServerObservation::Echo { sequence, .. } => sequence,
+            _ => unreachable!(),
+        };
+        tx.send(echo).unwrap();
+
+        let mut reply_packet = echo_reply_packet(
+            TOKEN,
+            sequence,
+            &params,
+            &TimestampFields::default(),
+            Some(&key),
+        );
+        reply_packet[HMAC_OFFSET] ^= 0xff;
+        socket.send_to(&reply_packet, peer).unwrap();
+    })
+}
+
+pub fn start_bad_hmac_open_reply_server(
+    params: Params,
+    request_key: Vec<u8>,
+    reply_key: Vec<u8>,
+) -> FakeServer {
+    start_fake_server(move |socket, tx| {
+        let (request, peer) = recv_request(&socket);
+        let (open_params, hmac) = open_request_params(&request, Some(&request_key));
+        tx.send(ServerObservation::Open {
+            params: open_params,
+            hmac,
+        })
+        .unwrap();
+
+        let reply = open_reply(
+            flags::FLAG_OPEN | flags::FLAG_REPLY,
+            TOKEN,
+            &params,
+            Some(&reply_key),
+        );
+        socket.send_to(&reply, peer).unwrap();
+    })
+}
+
+pub fn server_fill(value: &str) -> Option<ServerFill> {
+    Some(ServerFill {
+        value: value.to_owned(),
+    })
+}
+
+fn start_one_probe_server(
+    params: Params,
+    timestamps: TimestampFields,
+    hmac_key: Option<Vec<u8>>,
+) -> FakeServer {
+    start_fake_server(move |socket, tx| {
+        let (request, peer) = recv_request(&socket);
+        let (open_params, hmac) = open_request_params(&request, hmac_key.as_deref());
+        tx.send(ServerObservation::Open {
+            params: open_params,
+            hmac,
+        })
+        .unwrap();
+
+        let reply = open_reply(
+            flags::FLAG_OPEN | flags::FLAG_REPLY,
+            TOKEN,
+            &params,
+            hmac_key.as_deref(),
+        );
+        socket.send_to(&reply, peer).unwrap();
+
+        socket
+            .set_read_timeout(Some(Duration::from_secs(2)))
+            .unwrap();
+        let (request, peer) = recv_request(&socket);
+        let echo = observe_echo_request(&request, hmac_key.as_deref());
+        let sequence = match echo {
+            ServerObservation::Echo { sequence, .. } => sequence,
+            _ => unreachable!(),
+        };
+        tx.send(echo).unwrap();
+
+        let timestamps = materialize_wall_timestamps(timestamps);
+        let reply_packet =
+            echo_reply_packet(TOKEN, sequence, &params, &timestamps, hmac_key.as_deref());
+        socket.send_to(&reply_packet, peer).unwrap();
+    })
+}
+
+fn start_fake_server<F>(handler: F) -> FakeServer
+where
+    F: FnOnce(UdpSocket, mpsc::Sender<ServerObservation>) + Send + 'static,
+{
+    let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
+    let addr = socket.local_addr().unwrap();
+    let (tx, rx) = mpsc::channel();
+    let done = thread::spawn(move || handler(socket, tx));
+    FakeServer { addr, rx, done }
+}
+
+/// A `recv_from` that retries an interrupted syscall
+/// (`EINTR`/`ErrorKind::Interrupted`) instead of failing outright, keeping
+/// one absolute deadline across any number of interruptions exactly like the
+/// production blocking receive fix this test file exists to guard: each
+/// retry re-applies only the *remaining* time against the socket's
+/// currently configured read timeout, so a signal storm cannot turn this
+/// into an unbounded wait. The configured timeout is restored before
+/// returning so a later call is unaffected by an earlier interruption here.
+fn recv_from_retrying_interrupted(
+    socket: &UdpSocket,
+    buf: &mut [u8],
+) -> io::Result<(usize, SocketAddr)> {
+    let configured_timeout = socket.read_timeout()?;
+    let deadline = configured_timeout.and_then(|timeout| Instant::now().checked_add(timeout));
+    let mut timeout_narrowed = false;
+
+    let result = loop {
+        match socket.recv_from(buf) {
+            Ok(received) => break Ok(received),
+            Err(err) if err.kind() == ErrorKind::Interrupted => {
+                if let Some(deadline) = deadline {
+                    let Some(remaining) = deadline.checked_duration_since(Instant::now()) else {
+                        break Err(io::Error::from(ErrorKind::TimedOut));
+                    };
+                    if remaining.is_zero() {
+                        break Err(io::Error::from(ErrorKind::TimedOut));
+                    }
+                    if let Err(err) = socket.set_read_timeout(Some(remaining)) {
+                        break Err(err);
+                    }
+                    timeout_narrowed = true;
+                }
+            }
+            Err(err) => break Err(err),
+        }
+    };
+
+    if timeout_narrowed {
+        socket.set_read_timeout(configured_timeout)?;
+    }
+    result
+}
+
+fn recv_request(socket: &UdpSocket) -> (Vec<u8>, SocketAddr) {
+    let mut buf = [0_u8; 8192];
+    match recv_from_retrying_interrupted(socket, &mut buf) {
+        Ok((size, peer)) => (buf[..size].to_vec(), peer),
+        Err(err) => panic!("fake server recv_from failed: {err}"),
+    }
+}
+
+/// Like [`recv_request`], but any error, including a configured read
+/// timeout, means "nothing more to receive" rather than a failure.
+fn recv_request_timeout(socket: &UdpSocket) -> Option<Vec<u8>> {
+    let mut buf = [0_u8; 8192];
+    recv_from_retrying_interrupted(socket, &mut buf)
+        .ok()
+        .map(|(size, _)| buf[..size].to_vec())
+}
+
+fn assert_started(outcome: OpenOutcome) -> NegotiatedParams {
+    match outcome {
+        OpenOutcome::Started { negotiated, .. } => negotiated,
+        OpenOutcome::NoTestCompleted { .. } => panic!("expected started outcome"),
+    }
+}
+
+/// Admits a request the way a compliant server does: structural decode first,
+/// then HMAC presence policy, then authentication.
+fn admit_request<'a>(packet: &'a [u8], hmac_key: Option<&[u8]>) -> DecodedRequest<'a> {
+    let request = decode_request(packet).expect("fake peers only receive well-formed requests");
+    assert_eq!(request.hmac_present, hmac_key.is_some());
+    if let Some(key) = hmac_key {
+        verify_packet_hmac(key, packet).unwrap();
+    }
+    request
+}
+
+fn open_request_params(packet: &[u8], hmac_key: Option<&[u8]>) -> (Params, bool) {
+    let request = admit_request(packet, hmac_key);
+    match request.kind {
+        DecodedRequestKind::Open { params, .. } => {
+            (Params::decode(params).unwrap(), request.hmac_present)
+        }
+        other => panic!("expected an open request, got {other:?}"),
+    }
+}
+
+fn observe_echo_request(packet: &[u8], hmac_key: Option<&[u8]>) -> ServerObservation {
+    let request = admit_request(packet, hmac_key);
+    match request.kind {
+        DecodedRequestKind::Echo {
+            token, sequence, ..
+        } => ServerObservation::Echo {
+            len: packet.len(),
+            hmac: request.hmac_present,
+            token,
+            sequence,
+        },
+        other => panic!("expected an echo request, got {other:?}"),
+    }
+}
+
+fn observe_close_request(packet: &[u8], hmac_key: &[u8]) -> ServerObservation {
+    let request = admit_request(packet, Some(hmac_key));
+    match request.kind {
+        DecodedRequestKind::Close { token } => ServerObservation::Close { hmac: true, token },
+        other => panic!("expected a close request, got {other:?}"),
+    }
+}
+
+// irtt-proto has no encode_close_reply/CloseReply API yet, so this stays a
+// manual encoder. Migrate it once server-side close encoding is added.
+fn close_reply(token: u64, hmac_key: &[u8]) -> Vec<u8> {
+    let mut packet = Vec::new();
+    packet.extend_from_slice(&MAGIC);
+    packet.push(flags::FLAG_REPLY | flags::FLAG_CLOSE | flags::FLAG_HMAC);
+    packet.extend_from_slice(&[0_u8; HMAC_SIZE]);
+    packet.extend_from_slice(&token.to_le_bytes());
+    compute_hmac_in_place(hmac_key, &mut packet, HMAC_OFFSET).unwrap();
+    packet
+}
+
+fn open_reply(flags: u8, token: u64, params: &Params, hmac_key: Option<&[u8]>) -> Vec<u8> {
+    encode_open_reply(
+        &OpenReply {
+            flags,
+            token,
+            params: params.clone(),
+        },
+        hmac_key,
+    )
+    .unwrap()
+}
+
+pub(super) fn test_echo_packet_len(hmac: bool, params: &Params) -> usize {
+    echo_packet_len(hmac, params).expect("test params must have a representable length")
+}
+
+fn echo_reply_packet(
+    token: u64,
+    seq: u32,
+    params: &Params,
+    timestamps: &TimestampFields,
+    hmac_key: Option<&[u8]>,
+) -> Vec<u8> {
+    let layout = PacketLayout::echo(hmac_key.is_some(), params);
+    let reply = EchoReply {
+        flags: flags::FLAG_REPLY,
+        token,
+        sequence: seq,
+        recv_count: layout.recv_count.then_some(RECV_COUNT),
+        recv_window: layout.recv_window.then_some(RECV_WINDOW),
+        timestamps: TimestampFields {
+            recv_wall: layout.recv_wall.then(|| timestamps.recv_wall.unwrap_or(0)),
+            recv_mono: layout.recv_mono.then(|| timestamps.recv_mono.unwrap_or(0)),
+            midpoint_wall: layout
+                .midpoint_wall
+                .then(|| timestamps.midpoint_wall.unwrap_or(0)),
+            midpoint_mono: layout
+                .midpoint_mono
+                .then(|| timestamps.midpoint_mono.unwrap_or(0)),
+            send_wall: layout.send_wall.then(|| timestamps.send_wall.unwrap_or(0)),
+            send_mono: layout.send_mono.then(|| timestamps.send_mono.unwrap_or(0)),
+        },
+        payload: Vec::new(),
+    };
+    encode_echo_reply(&reply, params, hmac_key).unwrap()
+}
+
+fn materialize_wall_timestamps(mut timestamps: TimestampFields) -> TimestampFields {
+    let now_ns: i64 = SystemTime::now()
+        .duration_since(SystemTime::UNIX_EPOCH)
+        .unwrap()
+        .as_nanos()
+        .try_into()
+        .expect("current wall-clock time fits i64 nanoseconds");
+    if let Some(offset) = timestamps.recv_wall {
+        timestamps.recv_wall = Some(now_ns + offset);
+    }
+    if let Some(offset) = timestamps.midpoint_wall {
+        timestamps.midpoint_wall = Some(now_ns + offset);
+    }
+    if let Some(offset) = timestamps.send_wall {
+        timestamps.send_wall = Some(now_ns + offset);
+    }
+    timestamps
+}

crates/irtt-integration-tests/tests/support/real_irtt.rs

@@ -0,0 +1,277 @@
+#![allow(dead_code)]
+
+use std::io::{BufRead, BufReader, Read};
+use std::net::{SocketAddr, UdpSocket};
+use std::process::{Child, Command, Stdio};
+use std::sync::{mpsc, Arc, Mutex};
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+
+const STARTUP_ATTEMPTS: usize = 5;
+const STARTUP_TIMEOUT: Duration = Duration::from_secs(5);
+
+pub struct RealIrtServer {
+    addr: SocketAddr,
+    child: Child,
+    keepalive_ms: Option<u64>,
+    stdout_thread: Option<JoinHandle<()>>,
+    stderr_thread: Option<JoinHandle<()>>,
+}
+
+impl RealIrtServer {
+    pub fn start(hmac_key: Option<&[u8]>) -> Result<Self, String> {
+        let irtt_bin = std::env::var("IRTT_BIN").unwrap_or_else(|_| "irtt".to_string());
+        let keepalive_ms = std::env::var("IRTT_TEST_KEEP_SERVER_MS")
+            .ok()
+            .and_then(|v| v.parse::<u64>().ok());
+
+        let mut failures = Vec::new();
+
+        for attempt in 1..=STARTUP_ATTEMPTS {
+            let port = Self::find_free_port()?;
+            let addr = SocketAddr::from(([127, 0, 0, 1], port));
+            let bind = format!("127.0.0.1:{port}");
+
+            debug_eprintln!(
+                "[real_irtt] selected backend=real irtt_bin={irtt_bin} bind={bind} attempt={attempt}/{STARTUP_ATTEMPTS}"
+            );
+
+            match Self::start_attempt(&irtt_bin, keepalive_ms, hmac_key, addr, &bind) {
+                Ok(server) => return Ok(server),
+                Err(failure) => {
+                    debug_eprintln!(
+                        "[real_irtt] startup attempt {attempt}/{STARTUP_ATTEMPTS} failed for {bind}:\n{}",
+                        failure.details()
+                    );
+                    failures.push(failure);
+                }
+            }
+        }
+
+        Err(format_startup_failures(&irtt_bin, &failures))
+    }
+
+    fn start_attempt(
+        irtt_bin: &str,
+        keepalive_ms: Option<u64>,
+        hmac_key: Option<&[u8]>,
+        addr: SocketAddr,
+        bind: &str,
+    ) -> Result<Self, StartupFailure> {
+        let mut cmd = Command::new(irtt_bin);
+        cmd.arg("server")
+            .arg("-b")
+            .arg(bind)
+            .arg("--tstamp=dual")
+            .stderr(Stdio::piped())
+            .stdout(Stdio::piped());
+
+        if let Some(key) = hmac_key {
+            let hex_key: String = key.iter().map(|b| format!("{:02x}", b)).collect();
+            cmd.arg(format!("--hmac=0x{hex_key}"));
+        }
+
+        let full_cmd = format!("{cmd:?}");
+        debug_eprintln!("[real_irtt] spawning: {full_cmd}");
+
+        let mut child = cmd.spawn().map_err(|e| StartupFailure {
+            bind: bind.to_owned(),
+            command: full_cmd.clone(),
+            output: String::new(),
+            exit_status: None,
+            error: Some(format!("failed to spawn irtt server: {e}")),
+        })?;
+
+        let pid = child.id();
+        debug_eprintln!("[real_irtt] child pid={pid}");
+
+        let stdout = child.stdout.take().ok_or_else(|| StartupFailure {
+            bind: bind.to_owned(),
+            command: full_cmd.clone(),
+            output: String::new(),
+            exit_status: None,
+            error: Some("failed to capture stdout".to_owned()),
+        })?;
+        let stderr = child.stderr.take().ok_or_else(|| StartupFailure {
+            bind: bind.to_owned(),
+            command: full_cmd.clone(),
+            output: String::new(),
+            exit_status: None,
+            error: Some("failed to capture stderr".to_owned()),
+        })?;
+
+        let captured = Arc::new(Mutex::new(Vec::new()));
+        let (line_tx, line_rx) = mpsc::channel();
+
+        let stdout_thread = {
+            let line_tx = line_tx.clone();
+            let captured = Arc::clone(&captured);
+            thread::spawn(move || drain_stream("stdout", stdout, line_tx, captured))
+        };
+
+        let stderr_thread = {
+            let captured = Arc::clone(&captured);
+            thread::spawn(move || drain_stream("stderr", stderr, line_tx, captured))
+        };
+
+        let ready = wait_for_ready(&line_rx, STARTUP_TIMEOUT);
+
+        if !ready {
+            let exit_status = child.try_wait().ok().flatten();
+            debug_eprintln!("[real_irtt] readiness result=false exit_status={exit_status:?}");
+            child.kill().ok();
+            child.wait().ok();
+            stdout_thread.join().ok();
+            stderr_thread.join().ok();
+
+            let output = captured.lock().unwrap().join("\n");
+            return Err(StartupFailure {
+                bind: bind.to_owned(),
+                command: full_cmd,
+                output,
+                exit_status,
+                error: Some("readiness timed out or server exited before ready".to_owned()),
+            });
+        }
+
+        debug_eprintln!("[real_irtt] readiness result=true addr={addr}");
+
+        Ok(Self {
+            addr,
+            child,
+            keepalive_ms,
+            stdout_thread: Some(stdout_thread),
+            stderr_thread: Some(stderr_thread),
+        })
+    }
+
+    pub fn addr(&self) -> SocketAddr {
+        self.addr
+    }
+
+    fn find_free_port() -> Result<u16, String> {
+        let socket =
+            UdpSocket::bind("127.0.0.1:0").map_err(|e| format!("failed to find free port: {e}"))?;
+        let port = socket
+            .local_addr()
+            .map_err(|e| format!("failed to get local addr: {e}"))?
+            .port();
+        drop(socket);
+        Ok(port)
+    }
+}
+
+struct StartupFailure {
+    bind: String,
+    command: String,
+    output: String,
+    exit_status: Option<std::process::ExitStatus>,
+    error: Option<String>,
+}
+
+impl StartupFailure {
+    fn details(&self) -> String {
+        let mut details = format!("bind: {}\ncommand: {}", self.bind, self.command);
+        if let Some(error) = &self.error {
+            details.push_str(&format!("\nerror: {error}"));
+        }
+        if let Some(status) = self.exit_status {
+            details.push_str(&format!("\nexit status: {status}"));
+        }
+        if !self.output.is_empty() {
+            details.push_str(&format!("\noutput:\n{}", self.output));
+        }
+        details
+    }
+}
+
+fn format_startup_failures(irtt_bin: &str, failures: &[StartupFailure]) -> String {
+    let mut message = format!(
+        "irtt server failed to start after {} attempt(s) with binary '{irtt_bin}'",
+        failures.len()
+    );
+
+    for (index, failure) in failures.iter().enumerate() {
+        message.push_str(&format!(
+            "\n\nattempt {}/{}:\n{}",
+            index + 1,
+            failures.len(),
+            failure.details()
+        ));
+    }
+
+    message
+}
+
+impl Drop for RealIrtServer {
+    fn drop(&mut self) {
+        if let Some(ms) = self.keepalive_ms {
+            debug_eprintln!(
+                "[real_irtt] keepalive: sleeping {ms}ms before kill (pid={})",
+                self.child.id()
+            );
+            thread::sleep(Duration::from_millis(ms));
+        }
+        debug_eprintln!("[real_irtt] killing child pid={}", self.child.id());
+        self.child.kill().ok();
+        self.child.wait().ok();
+        if let Some(thread) = self.stdout_thread.take() {
+            thread.join().ok();
+        }
+        if let Some(thread) = self.stderr_thread.take() {
+            thread.join().ok();
+        }
+    }
+}
+
+fn wait_for_ready(line_rx: &mpsc::Receiver<(&'static str, String)>, timeout: Duration) -> bool {
+    let start = Instant::now();
+    loop {
+        let remaining = timeout
+            .checked_sub(start.elapsed())
+            .unwrap_or(Duration::ZERO);
+
+        match line_rx.recv_timeout(remaining) {
+            Ok((stream, text)) => {
+                debug_eprintln!("[real_irtt] {stream}: {text}");
+                if text.contains("[ListenerStart]") {
+                    return true;
+                }
+                if (text.contains("[ListenerStop]") || text.contains("[ServerStop]"))
+                    && (text.contains("error") || text.contains("Error"))
+                {
+                    return false;
+                }
+            }
+            Err(_) => return false,
+        }
+    }
+}
+
+fn drain_stream(
+    stream: &'static str,
+    pipe: impl Read,
+    tx: mpsc::Sender<(&'static str, String)>,
+    captured: Arc<Mutex<Vec<String>>>,
+) {
+    let reader = BufReader::new(pipe);
+    for line in reader.lines() {
+        match line {
+            Ok(text) => {
+                captured.lock().unwrap().push(format!("{stream}: {text}"));
+                let _ = tx.send((stream, text));
+            }
+            Err(_) => break,
+        }
+    }
+}
+
+macro_rules! debug_eprintln {
+    ($($arg:tt)*) => {
+        if std::env::var("IRTT_TEST_BACKEND_DEBUG").as_deref() == Ok("1") {
+            eprintln!($($arg)*);
+        }
+    };
+}
+
+use debug_eprintln;