refactor(app): clarify application and binary roles

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.

crates/irtt-app/src/shared/client/args.rs

@@ -0,0 +1,230 @@
+use std::time::Duration;
+
+use clap::ValueEnum;
+use irtt_client::{MAX_DSCP_CODEPOINT, MAX_SERVER_FILL_BYTES, MAX_TTL, MAX_UDP_PAYLOAD_LENGTH};
+use irtt_proto::{Clock, ReceivedStats, StampAt};
+
+#[derive(Debug, Clone, clap::Args)]
+pub struct CommonClientArgs {
+    /// Probe interval.
+    #[arg(long, default_value = "1s", value_parser = parse_duration)]
+    pub interval: Duration,
+
+    /// UDP payload length.
+    #[arg(long, default_value_t = 0, value_parser = parse_length)]
+    pub length: u32,
+
+    /// HMAC key.
+    #[arg(long, value_parser = parse_hmac_key)]
+    pub hmac: Option<String>,
+
+    /// Clock mode to request.
+    #[arg(long, value_enum, default_value_t = ClockArg::Both)]
+    pub clock: ClockArg,
+
+    /// Timestamp mode to request.
+    #[arg(
+        long = "tstamp",
+        visible_alias = "timestamps",
+        value_enum,
+        value_name = "MODE",
+        default_value_t = TimestampArg::Both
+    )]
+    pub tstamp: TimestampArg,
+
+    /// Received-stats mode to request.
+    #[arg(
+        long = "stats",
+        value_enum,
+        default_value_t = ReceivedStatsArg::Both,
+        help = "Server received-stats negotiation mode"
+    )]
+    pub stats: ReceivedStatsArg,
+
+    /// Server payload fill string to request, up to 32 bytes.
+    #[arg(
+        long = "sfill",
+        visible_alias = "server-fill",
+        value_name = "STRING",
+        value_parser = parse_server_fill
+    )]
+    pub server_fill: Option<String>,
+
+    /// DSCP codepoint to request; this is not a raw TOS or Traffic Class byte.
+    #[arg(long, default_value_t = 0, value_name = "0..=63", value_parser = parse_dscp)]
+    pub dscp: u8,
+
+    /// Local outgoing IPv4 TTL or IPv6 unicast hop limit; not negotiated.
+    #[arg(long, value_name = "1..=255", value_parser = parse_ttl)]
+    pub ttl: Option<u32>,
+
+    /// Accept safe server restrictions during negotiation.
+    #[arg(long)]
+    pub loose: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum ClockArg {
+    Wall,
+    Monotonic,
+    Both,
+}
+
+impl From<ClockArg> for Clock {
+    fn from(value: ClockArg) -> Self {
+        match value {
+            ClockArg::Wall => Self::Wall,
+            ClockArg::Monotonic => Self::Monotonic,
+            ClockArg::Both => Self::Both,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum TimestampArg {
+    None,
+    Send,
+    Receive,
+    Both,
+    Midpoint,
+}
+
+impl From<TimestampArg> for StampAt {
+    fn from(value: TimestampArg) -> Self {
+        match value {
+            TimestampArg::None => Self::None,
+            TimestampArg::Send => Self::Send,
+            TimestampArg::Receive => Self::Receive,
+            TimestampArg::Both => Self::Both,
+            TimestampArg::Midpoint => Self::Midpoint,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum ReceivedStatsArg {
+    None,
+    Count,
+    Window,
+    Both,
+}
+
+impl From<ReceivedStatsArg> for ReceivedStats {
+    fn from(value: ReceivedStatsArg) -> Self {
+        match value {
+            ReceivedStatsArg::None => Self::None,
+            ReceivedStatsArg::Count => Self::Count,
+            ReceivedStatsArg::Window => Self::Window,
+            ReceivedStatsArg::Both => Self::Both,
+        }
+    }
+}
+
+pub fn parse_duration(input: &str) -> Result<Duration, String> {
+    let (number, unit) = split_duration(input)?;
+    let value: u64 = number
+        .parse()
+        .map_err(|_| format!("invalid duration value {input:?}"))?;
+    if value == 0 {
+        return Err("duration must be greater than zero".to_owned());
+    }
+    match unit {
+        "ms" => Ok(Duration::from_millis(value)),
+        "s" => Ok(Duration::from_secs(value)),
+        "m" => value
+            .checked_mul(60)
+            .map(Duration::from_secs)
+            .ok_or_else(|| "duration is too large".to_owned()),
+        _ => Err(format!(
+            "unsupported duration unit {unit:?}; use ms, s, or m"
+        )),
+    }
+}
+
+pub fn parse_test_duration(input: &str) -> Result<Duration, String> {
+    if input == "0" {
+        return Ok(Duration::ZERO);
+    }
+    let (number, unit) = split_duration(input)?;
+    let value: u64 = number
+        .parse()
+        .map_err(|_| format!("invalid duration value {input:?}"))?;
+    if value == 0 {
+        return Ok(Duration::ZERO);
+    }
+    match unit {
+        "ms" => Ok(Duration::from_millis(value)),
+        "s" => Ok(Duration::from_secs(value)),
+        "m" => value
+            .checked_mul(60)
+            .map(Duration::from_secs)
+            .ok_or_else(|| "duration is too large".to_owned()),
+        _ => Err(format!(
+            "unsupported duration unit {unit:?}; use ms, s, or m"
+        )),
+    }
+}
+
+fn split_duration(input: &str) -> Result<(&str, &str), String> {
+    let split = input
+        .find(|ch: char| !ch.is_ascii_digit())
+        .ok_or_else(|| "duration must include a unit: ms, s, or m".to_owned())?;
+    let (number, unit) = input.split_at(split);
+    if number.is_empty() || unit.is_empty() {
+        return Err("duration must include a positive value and unit".to_owned());
+    }
+    if number.starts_with('-') {
+        return Err("duration must be greater than zero".to_owned());
+    }
+    Ok((number, unit))
+}
+
+pub fn parse_length(input: &str) -> Result<u32, String> {
+    let length: u32 = input
+        .parse()
+        .map_err(|_| format!("invalid packet length {input:?}"))?;
+    if length > MAX_UDP_PAYLOAD_LENGTH {
+        return Err(format!("packet length must be <= {MAX_UDP_PAYLOAD_LENGTH}"));
+    }
+    Ok(length)
+}
+
+pub fn parse_hmac_key(input: &str) -> Result<String, String> {
+    if input.is_empty() {
+        return Err("HMAC key must not be empty".to_owned());
+    }
+    Ok(input.to_owned())
+}
+
+pub fn parse_server_fill(input: &str) -> Result<String, String> {
+    if input.is_empty() {
+        return Err("server fill must not be empty".to_owned());
+    }
+    let len = input.len();
+    if len > MAX_SERVER_FILL_BYTES {
+        return Err(format!(
+            "server fill must be <= {MAX_SERVER_FILL_BYTES} bytes, got {len}"
+        ));
+    }
+    Ok(input.to_owned())
+}
+
+pub fn parse_dscp(input: &str) -> Result<u8, String> {
+    let value: u8 = input
+        .parse()
+        .map_err(|_| format!("invalid DSCP codepoint {input:?}"))?;
+    if value > MAX_DSCP_CODEPOINT {
+        return Err(format!("DSCP codepoint must be <= {MAX_DSCP_CODEPOINT}"));
+    }
+    Ok(value)
+}
+
+pub fn parse_ttl(input: &str) -> Result<u32, String> {
+    let value: u32 = input
+        .parse()
+        .map_err(|_| format!("invalid TTL/hop limit {input:?}"))?;
+    if value == 0 || value > MAX_TTL {
+        return Err(format!("TTL/hop limit must be in range 1..={MAX_TTL}"));
+    }
+    Ok(value)
+}

crates/irtt-app/src/shared/client/config.rs

@@ -0,0 +1,52 @@
+use std::time::Duration;
+
+use irtt_client::{ClientConfig, NegotiationPolicy, SocketConfig};
+
+use super::args::CommonClientArgs;
+
+pub const DEFAULT_RECV_TIMEOUT: Duration = Duration::from_millis(20);
+
+impl CommonClientArgs {
+    /// Build the shared client configuration template for a managed run.
+    ///
+    /// The template carries no server address: the managed driver replaces it
+    /// per target from that target's configuration, so deriving one here from
+    /// an arbitrary target would be dead data.
+    pub fn to_client_config(&self, duration: Duration) -> ClientConfig {
+        ClientConfig {
+            duration: (!duration.is_zero()).then_some(duration),
+            interval: self.interval,
+            length: self.length,
+            received_stats: self.stats.into(),
+            stamp_at: self.tstamp.into(),
+            clock: self.clock.into(),
+            dscp: self.dscp,
+            hmac_key: self.hmac.as_ref().map(|key| key.as_bytes().to_vec()),
+            server_fill: self.server_fill.clone(),
+            negotiation_policy: if self.loose {
+                NegotiationPolicy::Loose
+            } else {
+                NegotiationPolicy::Strict
+            },
+            socket_config: SocketConfig {
+                ttl: self.ttl,
+                recv_timeout: Some(DEFAULT_RECV_TIMEOUT),
+                ..SocketConfig::default()
+            },
+            ..ClientConfig::default()
+        }
+    }
+}
+
+pub fn expected_probe_count(duration: Duration, interval: Duration) -> u64 {
+    let interval_nanos = interval.as_nanos();
+    if interval_nanos == 0 {
+        return u64::MAX;
+    }
+
+    let expected = duration
+        .as_nanos()
+        .saturating_add(interval_nanos.saturating_sub(1))
+        / interval_nanos;
+    expected.min(u128::from(u64::MAX)) as u64
+}

crates/irtt-app/src/shared/client/mod.rs

@@ -0,0 +1,17 @@
+pub mod args;
+pub mod config;
+pub mod prepare;
+pub mod session;
+pub mod targets;
+
+pub use args::{
+    parse_dscp, parse_duration, parse_length, parse_server_fill, parse_test_duration, parse_ttl,
+    ClockArg, CommonClientArgs, ReceivedStatsArg, TimestampArg,
+};
+pub use config::{expected_probe_count, DEFAULT_RECV_TIMEOUT};
+pub use prepare::{prepare_managed_run, ManagedRunSetup, TargetSelection, MANAGED_EVENT_CAPACITY};
+pub use session::is_shutdown_requested;
+pub use targets::{
+    parse_target, prepare_managed_targets, target_specs, GroupPacingArg, PreparedTarget, TargetArg,
+    TargetSpec,
+};

crates/irtt-app/src/shared/client/prepare.rs

@@ -0,0 +1,251 @@
+//! One preparation step from parsed arguments to a runnable managed setup.
+//!
+//! Both client applets accept the same target and pacing arguments and then
+//! have to turn them into the same three things: a validated target set, one
+//! shared [`ClientConfig`] template, and a [`ManagedPacing`]. Doing that
+//! separately in each applet is how the CLI ended up deriving its client
+//! configuration from an arbitrary "primary" target whose address the managed
+//! driver immediately replaced per target.
+
+use std::time::Duration;
+
+use irtt_client::{
+    managed::{ManagedClientConfig, ManagedCompletionPolicy, ManagedPacing},
+    ClientConfig,
+};
+
+use super::{
+    args::CommonClientArgs,
+    targets::{prepare_managed_targets, target_specs, GroupPacingArg, TargetArg},
+    PreparedTarget,
+};
+
+/// Capacity of the lossy managed presentation event channel.
+pub const MANAGED_EVENT_CAPACITY: usize = 16_384;
+
+/// Target and pacing arguments common to the client applets.
+///
+/// Duration is deliberately absent: the applets disagree about what a duration
+/// means and what its default is, so each keeps its own.
+#[derive(Debug, Clone, Copy)]
+pub struct TargetSelection<'a> {
+    pub targets: &'a [TargetArg],
+    pub pacing: GroupPacingArg,
+}
+
+/// Everything a managed run needs, prepared and validated together.
+#[derive(Debug, Clone)]
+pub struct ManagedRunSetup {
+    /// Validated targets, in the order the user gave them.
+    pub targets: Vec<PreparedTarget>,
+    /// Shared client configuration template.
+    ///
+    /// The managed driver supplies each target's address and authentication
+    /// from its [`ManagedTargetConfig`](irtt_client::managed::ManagedTargetConfig),
+    /// so this template carries no target of its own.
+    pub client: ClientConfig,
+    /// Send coordination across active targets.
+    pub pacing: ManagedPacing,
+}
+
+impl ManagedRunSetup {
+    /// Number of validated targets.
+    pub fn target_count(&self) -> usize {
+        self.targets.len()
+    }
+
+    /// Whether this run drives more than one target.
+    pub fn is_multi_target(&self) -> bool {
+        self.targets.len() > 1
+    }
+
+    /// Managed target configurations, in argument order.
+    pub fn managed_targets(&self) -> Vec<irtt_client::managed::ManagedTargetConfig> {
+        self.targets
+            .iter()
+            .map(|target| target.managed.clone())
+            .collect()
+    }
+
+    /// Managed driver configuration for this run.
+    pub fn managed_config(&self) -> ManagedClientConfig {
+        let target_count = self.target_count();
+        ManagedClientConfig {
+            client: self.client.clone(),
+            pacing: self.pacing,
+            completion: ManagedCompletionPolicy::FinishWhenQuiescent,
+            event_capacity: MANAGED_EVENT_CAPACITY,
+            outcome_history_limit: target_count,
+            max_live_target_generations: target_count,
+            ..ManagedClientConfig::default()
+        }
+    }
+}
+
+/// Validate the selected targets and build the shared run setup.
+///
+/// Targets are validated before any configuration is built, so a bad target set
+/// fails before the caller can act on a half-prepared run.
+pub fn prepare_managed_run(
+    common: &CommonClientArgs,
+    duration: Duration,
+    selection: TargetSelection<'_>,
+) -> Result<ManagedRunSetup, String> {
+    let specs = target_specs(selection.targets)?;
+    let targets = prepare_managed_targets(specs)?;
+    Ok(ManagedRunSetup {
+        targets,
+        client: common.to_client_config(duration),
+        pacing: selection.pacing.into(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use clap::Parser;
+
+    use super::*;
+
+    #[derive(Parser)]
+    struct CommonOnlyArgs {
+        #[command(flatten)]
+        common: CommonClientArgs,
+    }
+
+    fn common(args: &[&str]) -> CommonClientArgs {
+        let mut argv = vec!["common-only"];
+        argv.extend_from_slice(args);
+        CommonOnlyArgs::try_parse_from(argv).unwrap().common
+    }
+
+    fn unlabeled(addr: &str) -> TargetArg {
+        TargetArg {
+            label: None,
+            addr: addr.to_owned(),
+        }
+    }
+
+    fn labeled(label: &str, addr: &str) -> TargetArg {
+        TargetArg {
+            label: Some(label.to_owned()),
+            addr: addr.to_owned(),
+        }
+    }
+
+    fn prepare(
+        targets: &[TargetArg],
+        pacing: GroupPacingArg,
+        duration: Duration,
+    ) -> Result<ManagedRunSetup, String> {
+        prepare_managed_run(&common(&[]), duration, TargetSelection { targets, pacing })
+    }
+
+    #[test]
+    fn a_single_target_prepares_one_managed_target_and_a_finite_duration() {
+        let setup = prepare(
+            &[unlabeled("127.0.0.1:2112")],
+            GroupPacingArg::Staggered,
+            Duration::from_secs(30),
+        )
+        .unwrap();
+
+        assert_eq!(setup.target_count(), 1);
+        assert!(!setup.is_multi_target());
+        assert_eq!(setup.targets[0].label, "127.0.0.1:2112");
+        assert_eq!(setup.targets[0].managed.server_addr, "127.0.0.1:2112");
+        assert_eq!(setup.client.duration, Some(Duration::from_secs(30)));
+        assert_eq!(setup.pacing, ManagedPacing::Staggered);
+    }
+
+    #[test]
+    fn a_zero_duration_prepares_a_continuous_client_config() {
+        let setup = prepare(
+            &[unlabeled("127.0.0.1:2112")],
+            GroupPacingArg::Staggered,
+            Duration::ZERO,
+        )
+        .unwrap();
+
+        assert_eq!(setup.client.duration, None);
+    }
+
+    #[test]
+    fn multiple_targets_keep_argument_order_and_share_one_client_config() {
+        let setup = prepare(
+            &[
+                unlabeled("host-a:2112"),
+                unlabeled("host-b:2112"),
+                labeled("sg", "sg.example.test:2112"),
+            ],
+            GroupPacingArg::Burst,
+            Duration::from_secs(10),
+        )
+        .unwrap();
+
+        assert!(setup.is_multi_target());
+        let labels: Vec<_> = setup
+            .targets
+            .iter()
+            .map(|target| target.label.as_str())
+            .collect();
+        assert_eq!(labels, ["host-a:2112", "host-b:2112", "sg"]);
+        assert_eq!(setup.targets[2].managed.server_addr, "sg.example.test:2112");
+        assert_eq!(setup.pacing, ManagedPacing::Burst);
+
+        let config = setup.managed_config();
+        assert_eq!(config.outcome_history_limit, 3);
+        assert_eq!(config.max_live_target_generations, 3);
+        assert_eq!(config.event_capacity, MANAGED_EVENT_CAPACITY);
+        assert_eq!(config.pacing, ManagedPacing::Burst);
+        assert_eq!(config.client, setup.client);
+        assert_eq!(setup.managed_targets().len(), 3);
+    }
+
+    #[test]
+    fn the_shared_client_config_carries_no_target_of_its_own() {
+        // The managed driver replaces the address, and the CLI's key, per
+        // target, so the template must not pin either to one target.
+        let targets = vec![unlabeled("host-a:2112"), unlabeled("host-b:2112")];
+        let setup = prepare_managed_run(
+            &common(&["--hmac", "secret"]),
+            Duration::from_secs(10),
+            TargetSelection {
+                targets: &targets,
+                pacing: GroupPacingArg::Staggered,
+            },
+        )
+        .unwrap();
+
+        assert_eq!(
+            setup.client.server_addr,
+            ClientConfig::default().server_addr
+        );
+        assert_eq!(setup.client.hmac_key, Some(b"secret".to_vec()));
+        // Per-target authentication is not exposed on the command line, so no
+        // target carries an override of the shared key.
+        assert!(setup
+            .targets
+            .iter()
+            .all(|target| target.managed.auth.is_none()));
+    }
+
+    #[test]
+    fn an_empty_target_set_is_rejected_with_the_list_columns_hint() {
+        let err = prepare(&[], GroupPacingArg::Staggered, Duration::from_secs(10)).unwrap_err();
+
+        assert!(err.contains("at least one target is required"));
+        assert!(err.contains("--list-columns"));
+    }
+
+    #[test]
+    fn a_duplicate_label_is_rejected_before_any_configuration_is_built() {
+        let targets = vec![
+            unlabeled("host-a:2112"),
+            labeled("host-a:2112", "host-b:2112"),
+        ];
+        let err =
+            prepare(&targets, GroupPacingArg::Staggered, Duration::from_secs(10)).unwrap_err();
+
+        assert!(err.contains("duplicate target label"));
+    }
+}

crates/irtt-app/src/shared/client/session.rs

@@ -0,0 +1,141 @@
+use std::sync::atomic::{AtomicBool, Ordering};
+
+#[cfg(any(feature = "client", feature = "tui"))]
+use irtt_client::managed::{ManagedEvent, ManagedEventSubscription, ManagedEventTryRecvError};
+
+#[cfg(any(feature = "client", feature = "tui"))]
+pub(crate) const MANAGED_EVENT_WORK_BUDGET: usize = 128;
+
+#[cfg(any(feature = "client", feature = "tui"))]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum ManagedDrainState {
+    Empty,
+    Closed,
+    BudgetExhausted,
+}
+
+/// Drain a bounded amount of lossy presentation work before returning to the
+/// frontend control loop.
+#[cfg(any(feature = "client", feature = "tui"))]
+pub(crate) fn drain_managed_events<E>(
+    events: &mut ManagedEventSubscription,
+    dropped_events: &mut u64,
+    mut process: impl FnMut(ManagedEvent) -> Result<(), E>,
+) -> Result<ManagedDrainState, E> {
+    for _ in 0..MANAGED_EVENT_WORK_BUDGET {
+        match events.try_recv() {
+            Ok(event) => process(event)?,
+            Err(ManagedEventTryRecvError::Lagged(count)) => {
+                *dropped_events = dropped_events.saturating_add(count);
+            }
+            Err(ManagedEventTryRecvError::Empty) => return Ok(ManagedDrainState::Empty),
+            Err(ManagedEventTryRecvError::Closed) => return Ok(ManagedDrainState::Closed),
+        }
+    }
+    Ok(ManagedDrainState::BudgetExhausted)
+}
+
+pub fn is_shutdown_requested(shutdown_requested: &AtomicBool) -> bool {
+    shutdown_requested.load(Ordering::Relaxed)
+}
+
+pub fn should_print_final_summary(continuous: bool, interrupted: bool) -> bool {
+    !continuous || interrupted
+}
+
+pub fn peer_close_run_error(
+    continuous: bool,
+    interrupted: bool,
+    peer_closed_target_outcomes: u64,
+) -> Option<String> {
+    if !continuous || interrupted || peer_closed_target_outcomes == 0 {
+        return None;
+    }
+
+    let sessions = if peer_closed_target_outcomes == 1 {
+        "target session"
+    } else {
+        "target sessions"
+    };
+    Some(format!(
+        "continuous run ended because of peer closure ({peer_closed_target_outcomes} {sessions})"
+    ))
+}
+
+pub fn request_managed_stop_for_peer_close(
+    continuous: bool,
+    interrupted: bool,
+    peer_closed_target_outcomes: u64,
+    stop_requested: &mut bool,
+) -> bool {
+    if !continuous || interrupted || peer_closed_target_outcomes == 0 {
+        return false;
+    }
+    request_managed_stop_once(stop_requested)
+}
+
+pub fn request_managed_stop_once(stop_requested: &mut bool) -> bool {
+    if *stop_requested {
+        return false;
+    }
+    *stop_requested = true;
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn peer_close_run_error_is_run_mode_and_interruption_aware() {
+        assert_eq!(peer_close_run_error(false, false, 1), None);
+        assert_eq!(peer_close_run_error(true, false, 0), None);
+        assert_eq!(peer_close_run_error(true, true, 1), None);
+        assert_eq!(
+            peer_close_run_error(true, false, 1).as_deref(),
+            Some("continuous run ended because of peer closure (1 target session)")
+        );
+        assert_eq!(
+            peer_close_run_error(true, false, 3).as_deref(),
+            Some("continuous run ended because of peer closure (3 target sessions)")
+        );
+    }
+
+    #[test]
+    fn grouped_peer_close_stop_policy_is_run_mode_and_one_shot() {
+        let mut stop_requested = false;
+        assert!(!request_managed_stop_for_peer_close(
+            false,
+            false,
+            1,
+            &mut stop_requested,
+        ));
+        assert!(!request_managed_stop_for_peer_close(
+            true,
+            true,
+            1,
+            &mut stop_requested,
+        ));
+        assert!(!request_managed_stop_for_peer_close(
+            true,
+            false,
+            0,
+            &mut stop_requested,
+        ));
+        assert!(!stop_requested);
+
+        assert!(request_managed_stop_for_peer_close(
+            true,
+            false,
+            1,
+            &mut stop_requested,
+        ));
+        assert!(stop_requested);
+        assert!(!request_managed_stop_for_peer_close(
+            true,
+            false,
+            1,
+            &mut stop_requested,
+        ));
+    }
+}

crates/irtt-app/src/shared/client/targets.rs

@@ -0,0 +1,226 @@
+use std::collections::HashSet;
+
+use clap::ValueEnum;
+use irtt_client::managed::{ManagedPacing, ManagedTargetConfig, TargetId};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TargetArg {
+    pub label: Option<String>,
+    pub addr: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TargetSpec {
+    pub label: String,
+    pub addr: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct PreparedTarget {
+    pub label: String,
+    pub managed: ManagedTargetConfig,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum GroupPacingArg {
+    Staggered,
+    Burst,
+}
+
+impl From<GroupPacingArg> for ManagedPacing {
+    fn from(value: GroupPacingArg) -> Self {
+        match value {
+            GroupPacingArg::Staggered => Self::Staggered,
+            GroupPacingArg::Burst => Self::Burst,
+        }
+    }
+}
+
+/// Parse one positional target argument, as `TARGET` or `LABEL=TARGET`.
+pub fn parse_target(input: &str) -> Result<TargetArg, String> {
+    match input.split_once('=') {
+        None => Ok(TargetArg {
+            label: None,
+            addr: input.to_owned(),
+        }),
+        Some((label, addr)) => {
+            if label.is_empty() {
+                return Err("target label must not be empty".to_owned());
+            }
+            if addr.is_empty() {
+                return Err("target address must not be empty".to_owned());
+            }
+            Ok(TargetArg {
+                label: Some(label.to_owned()),
+                addr: addr.to_owned(),
+            })
+        }
+    }
+}
+
+pub fn target_specs(targets: &[TargetArg]) -> Result<Vec<TargetSpec>, String> {
+    let mut specs = Vec::with_capacity(targets.len());
+    let mut unlabeled_counts = std::collections::HashMap::<&str, usize>::new();
+    for target in targets {
+        let label = match &target.label {
+            Some(label) => label.clone(),
+            None => {
+                let count = unlabeled_counts.entry(target.addr.as_str()).or_default();
+                *count += 1;
+                if *count == 1 {
+                    target.addr.clone()
+                } else {
+                    format!("{}#{}", target.addr, *count)
+                }
+            }
+        };
+        specs.push(TargetSpec {
+            label,
+            addr: target.addr.clone(),
+        });
+    }
+
+    if specs.is_empty() {
+        return Err("at least one target is required unless --list-columns is set".to_owned());
+    }
+
+    let mut labels = HashSet::new();
+    for spec in &specs {
+        if !labels.insert(spec.label.clone()) {
+            return Err(format!("duplicate target label {:?}", spec.label));
+        }
+    }
+
+    Ok(specs)
+}
+
+pub fn prepare_managed_targets(specs: Vec<TargetSpec>) -> Result<Vec<PreparedTarget>, String> {
+    let mut targets = Vec::with_capacity(specs.len());
+    for spec in specs {
+        targets.push(PreparedTarget {
+            label: spec.label.clone(),
+            managed: ManagedTargetConfig::new(TargetId::from(spec.label), spec.addr),
+        });
+    }
+    Ok(targets)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn unlabeled(addr: &str) -> TargetArg {
+        TargetArg {
+            label: None,
+            addr: addr.to_owned(),
+        }
+    }
+
+    fn labeled(label: &str, addr: &str) -> TargetArg {
+        TargetArg {
+            label: Some(label.to_owned()),
+            addr: addr.to_owned(),
+        }
+    }
+
+    #[test]
+    fn parse_target_without_equals_is_unlabeled() {
+        let target = parse_target("host.example").unwrap();
+        assert_eq!(target.label, None);
+        assert_eq!(target.addr, "host.example");
+
+        let target = parse_target("host.example:2112").unwrap();
+        assert_eq!(target.label, None);
+        assert_eq!(target.addr, "host.example:2112");
+
+        let target = parse_target("[::1]:2112").unwrap();
+        assert_eq!(target.label, None);
+        assert_eq!(target.addr, "[::1]:2112");
+    }
+
+    #[test]
+    fn parse_target_with_equals_splits_on_first() {
+        let target = parse_target("eu=host.example").unwrap();
+        assert_eq!(target.label, Some("eu".to_owned()));
+        assert_eq!(target.addr, "host.example");
+
+        let target = parse_target("eu=host.example:2112").unwrap();
+        assert_eq!(target.label, Some("eu".to_owned()));
+        assert_eq!(target.addr, "host.example:2112");
+    }
+
+    #[test]
+    fn parse_target_rejects_empty_label_or_address() {
+        assert!(parse_target("=host.example").is_err());
+        assert!(parse_target("eu=").is_err());
+    }
+
+    #[test]
+    fn target_specs_suffix_repeated_unlabeled_and_reject_duplicate_labels() {
+        let targets = vec![unlabeled("host-a:2112"), unlabeled("host-a:2112")];
+        let specs = target_specs(&targets).unwrap();
+
+        assert_eq!(specs[0].label, "host-a:2112");
+        assert_eq!(specs[1].label, "host-a:2112#2");
+
+        let targets = vec![
+            unlabeled("host-a:2112"),
+            labeled("host-a:2112", "host-b:2112"),
+        ];
+        let err = target_specs(&targets).unwrap_err();
+        assert!(err.contains("duplicate target label"));
+    }
+
+    #[test]
+    fn target_specs_preserve_argument_order_with_mixed_labels() {
+        let targets = vec![
+            unlabeled("local"),
+            labeled("eu", "eu.example"),
+            unlabeled("backup"),
+            labeled("us", "us.example"),
+        ];
+        let specs = target_specs(&targets).unwrap();
+
+        let labels: Vec<_> = specs.iter().map(|spec| spec.label.as_str()).collect();
+        assert_eq!(labels, ["local", "eu", "backup", "us"]);
+        let addrs: Vec<_> = specs.iter().map(|spec| spec.addr.as_str()).collect();
+        assert_eq!(addrs, ["local", "eu.example", "backup", "us.example"]);
+    }
+
+    #[test]
+    fn target_specs_count_unlabeled_occurrences_independently_of_explicit_labels() {
+        let targets = vec![unlabeled("foo"), labeled("eu", "foo"), unlabeled("foo")];
+        let specs = target_specs(&targets).unwrap();
+
+        let labels: Vec<_> = specs.iter().map(|spec| spec.label.as_str()).collect();
+        assert_eq!(labels, ["foo", "eu", "foo#2"]);
+    }
+
+    #[test]
+    fn target_specs_reject_generated_suffix_collisions() {
+        let targets = vec![
+            unlabeled("host.example"),
+            unlabeled("host.example"),
+            labeled("host.example#2", "other.example"),
+        ];
+        let err = target_specs(&targets).unwrap_err();
+        assert!(err.contains("duplicate target label"));
+    }
+
+    #[test]
+    fn target_preparation_preserves_hostname_and_allows_duplicate_endpoints() {
+        let specs = vec![
+            TargetSpec {
+                label: "a".to_owned(),
+                addr: "example.test".to_owned(),
+            },
+            TargetSpec {
+                label: "b".to_owned(),
+                addr: "example.test".to_owned(),
+            },
+        ];
+        let targets = prepare_managed_targets(specs).unwrap();
+        assert_eq!(targets[0].managed.server_addr, "example.test");
+        assert_eq!(targets[1].managed.server_addr, "example.test");
+    }
+}