feat(server): give irtt-server sensible zero-argument defaults

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.

crates/irtt-app/src/cmd/server/args.rs

@@ -1,8 +1,14 @@
-use std::{net::SocketAddr, time::Duration};
+use std::{
+    net::{Ipv4Addr, Ipv6Addr, SocketAddr},
+    time::Duration,
+};
 
 use clap::{Parser, ValueEnum};
 use irtt_server::{ServerConfig, TimestampAllowance};
 
+/// The ordinary IRTT port, used to build the zero-argument default binds.
+const DEFAULT_PORT: u16 = 2112;
+
 // Every policy option is optional. An omitted option leaves the corresponding
 // `ServerConfig` default in place rather than restating it here, so library and
 // CLI defaults cannot drift apart.
@@ -10,15 +16,14 @@ use irtt_server::{ServerConfig, TimestampAllowance};
 #[command(
     name = "irtt-server",
     about = "Minimal IRTT-compatible UDP server",
-    after_help = "Policy options left unset keep the irtt-server library defaults.\nRepeat --bind to serve multiple addresses in one process. All listeners use the same policy but keep independent session namespaces."
+    after_help = "With no --bind, the server listens on the wildcard IRTT port for both address families ([::]:2112 and 0.0.0.0:2112) where the platform supports wildcard reply-source selection.\nRepeat --bind to serve multiple addresses in one process; any explicit --bind replaces the default pair entirely. All listeners use the same policy but keep independent session namespaces."
 )]
 pub struct ServerArgs {
     /// Local UDP address to bind, as ADDR:PORT. Repeatable.
     #[arg(
         long,
-        required = true,
         value_name = "ADDR",
-        long_help = "Local UDP address to bind, as ADDR:PORT, for example 127.0.0.1:2112 or [::1]:2112. Host names are not resolved.\n\nRepeat the option to serve several addresses from one process, in the order given. Every listener applies the same policy options, but each keeps its own sessions and tokens, so a session belongs to the address it was opened on. Binding is all or nothing: if any address cannot be bound, none are served.\n\nA wildcard bind such as 0.0.0.0:2112 answers each request from the address it was sent to, using per-packet destination metadata. That is supported on Linux, macOS and FreeBSD; on other systems a wildcard bind is refused and an explicit interface address is required.\n\nA port of 0 selects an unused port per listener, so two such binds get two different ports."
+        long_help = "Local UDP address to bind, as ADDR:PORT, for example 127.0.0.1:2112 or [::1]:2112. Host names are not resolved.\n\nRepeat the option to serve several addresses from one process, in the order given. Every listener applies the same policy options, but each keeps its own sessions and tokens, so a session belongs to the address it was opened on. Binding is all or nothing: if any address cannot be bound, none are served.\n\nWith no --bind at all, the server binds the wildcard IRTT port on both address families, [::]:2112 then 0.0.0.0:2112, on platforms with wildcard reply-source support; elsewhere it fails and asks for an explicit address instead of guessing one. Any explicit --bind replaces that default pair rather than adding to it.\n\nA wildcard bind such as 0.0.0.0:2112 answers each request from the address it was sent to, using per-packet destination metadata. That is supported on Linux, macOS and FreeBSD; on other systems a wildcard bind is refused and an explicit interface address is required.\n\nA port of 0 selects an unused port per listener, so two such binds get two different ports."
     )]
     pub bind: Vec<SocketAddr>,
 
@@ -47,12 +52,12 @@ pub struct ServerArgs {
     )]
     pub max_packet_length: Option<usize>,
 
-    /// Floor on the negotiated send interval, and the allowance refill cadence.
+    /// Floor on the negotiated send interval.
     #[arg(
         long,
         value_name = "DURATION",
         value_parser = parse_duration_allow_zero,
-        long_help = "Floor on the send interval a session may negotiate, and the cadence its reply allowance refills at. The negotiated interval is still capped at a quarter of the idle timeout afterwards. Use 0 for no time-based throttling."
+        long_help = "Floor on the send interval a session may negotiate. The negotiated interval is still capped at a quarter of the idle timeout afterwards, so a value above that cap is not what actually gets negotiated.\n\nA session's reply allowance refills at the shorter of this floor and the interval it actually negotiated. Ordinarily that is this floor itself; it is the shorter, negotiated value only where the idle-timeout cap above pulled the negotiated interval below it. Use 0 for no time-based throttling."
     )]
     pub min_interval: Option<Duration>,
 
@@ -124,6 +129,20 @@ impl From<TimestampAllowanceArg> for TimestampAllowance {
 }
 
 impl ServerArgs {
+    /// The addresses this invocation binds: the requested `--bind` list, or
+    /// the wildcard IRTT port on both address families if none was given.
+    #[must_use]
+    pub fn resolve_binds(&self) -> Vec<SocketAddr> {
+        if self.bind.is_empty() {
+            vec![
+                SocketAddr::from((Ipv6Addr::UNSPECIFIED, DEFAULT_PORT)),
+                SocketAddr::from((Ipv4Addr::UNSPECIFIED, DEFAULT_PORT)),
+            ]
+        } else {
+            self.bind.clone()
+        }
+    }
+
     /// Builds the server configuration this invocation asks for.
     #[must_use]
     pub fn server_config(&self) -> ServerConfig {
@@ -236,12 +255,7 @@ mod tests {
     }
 
     #[test]
-    fn bind_is_required_and_parses_both_families() {
-        assert!(
-            parse(&[]).is_err(),
-            "a server with no address serves nothing"
-        );
-
+    fn bind_is_optional_and_parses_both_families() {
         let ipv4 = parse(&["--bind", "127.0.0.1:2112"]).unwrap();
         assert_eq!(ipv4.bind, [SocketAddr::from((Ipv4Addr::LOCALHOST, 2112))]);
 
@@ -255,6 +269,39 @@ mod tests {
         assert!(parse(&["--bind", "127.0.0.1:2112,[::1]:2112"]).is_err());
     }
 
+    #[test]
+    fn no_explicit_bind_resolves_to_the_wildcard_default_pair() {
+        let args = parse(&[]).unwrap();
+        assert!(
+            args.bind.is_empty(),
+            "the empty list is the parsed representation of \"no explicit bind\""
+        );
+        assert_eq!(
+            args.resolve_binds(),
+            [
+                SocketAddr::from((Ipv6Addr::UNSPECIFIED, 2112)),
+                SocketAddr::from((Ipv4Addr::UNSPECIFIED, 2112)),
+            ],
+            "zero explicit binds means the ordinary port on both wildcard families, IPv6 first"
+        );
+    }
+
+    #[test]
+    fn an_explicit_bind_replaces_the_defaults_rather_than_augmenting_them() {
+        let args = parse(&["--bind", "127.0.0.1:2112"]).unwrap();
+        assert_eq!(
+            args.resolve_binds(),
+            [SocketAddr::from((Ipv4Addr::LOCALHOST, 2112))],
+            "one explicit bind means exactly that one listener, not that listener plus defaults"
+        );
+    }
+
+    #[test]
+    fn repeated_explicit_binds_are_unaffected_by_the_default_resolution() {
+        let args = parse(&["--bind", "127.0.0.1:2112", "--bind", "[::1]:2112"]).unwrap();
+        assert_eq!(args.resolve_binds(), args.bind);
+    }
+
     #[test]
     fn bind_is_repeatable_and_keeps_the_requested_order() {
         let args = parse(&[

crates/irtt-app/src/cmd/server/run.rs

@@ -1,9 +1,10 @@
 use std::{
+    net::SocketAddr,
     sync::atomic::{AtomicBool, Ordering},
     time::Duration,
 };
 
-use irtt_server::ServerSet;
+use irtt_server::{address_family_available, ServerSet, ServerSetError};
 
 use super::args::ServerArgs;
 
@@ -36,7 +37,29 @@ async fn serve(
     shutdown_requested: &AtomicBool,
 ) -> Result<(), Box<dyn std::error::Error>> {
     let config = args.server_config();
-    let set = ServerSet::bind(args.bind, config).await?;
+    let binds = args.resolve_binds();
+    let is_implicit_default = args.bind.is_empty();
+    let set = match ServerSet::bind(binds.clone(), config.clone()).await {
+        Ok(set) => set,
+        Err(ServerSetError::ListenerSetup { addr, source }) => {
+            let family_available = address_family_available(addr);
+            match implicit_default_fallback(is_implicit_default, family_available, &binds, addr) {
+                Some(remaining) => {
+                    eprintln!(
+                        "irtt-server: default listener {addr} unavailable ({source}); \
+                         continuing with the remaining default listener"
+                    );
+                    // `remaining`'s lone survivor is bound exactly as it
+                    // would be alone: the address family that just failed
+                    // has no local support at all, so nothing on that family
+                    // could be competing for the surviving listener's port.
+                    ServerSet::bind(remaining, config).await?
+                }
+                None => return Err(ServerSetError::ListenerSetup { addr, source }.into()),
+            }
+        }
+        Err(err) => return Err(err.into()),
+    };
     // Only once every listener is up. Announcing one address and then failing
     // to bind the next would report a service that never started.
     for addr in set.local_addrs() {
@@ -46,6 +69,37 @@ async fn serve(
     Ok(())
 }
 
+/// Whether a listener-setup failure for `failed_addr` should be retried with
+/// a reduced bind set instead of failing the whole invocation, and if so,
+/// what to retry with.
+///
+/// Only the implicit zero-argument default gets this treatment, and only
+/// when `failed_addr`'s own address family has no local support on this host
+/// at all (`family_available` is `false`) — not merely because its specific
+/// port was unavailable for some other reason: already in use, permission
+/// denied, no safe wildcard reply-source path, or anything else
+/// `ServerSet::bind` can fail with. Those are real configuration or
+/// environment problems this invocation should fail on, not silently work
+/// around by dropping a listener the operator asked for. An explicit
+/// `--bind` list keeps the library's ordinary all-or-nothing behavior
+/// regardless.
+fn implicit_default_fallback(
+    is_implicit_default: bool,
+    family_available: bool,
+    original_binds: &[SocketAddr],
+    failed_addr: SocketAddr,
+) -> Option<Vec<SocketAddr>> {
+    if !is_implicit_default || family_available || !original_binds.contains(&failed_addr) {
+        return None;
+    }
+    let remaining: Vec<SocketAddr> = original_binds
+        .iter()
+        .copied()
+        .filter(|&addr| addr != failed_addr)
+        .collect();
+    (!remaining.is_empty()).then_some(remaining)
+}
+
 async fn shutdown_signal(shutdown_requested: &AtomicBool) {
     while !shutdown_requested.load(Ordering::Relaxed) {
         tokio::time::sleep(SHUTDOWN_POLL_INTERVAL).await;
@@ -82,4 +136,67 @@ mod tests {
 
         run_server(args, &shutdown_requested).unwrap();
     }
+
+    fn default_binds() -> Vec<SocketAddr> {
+        ServerArgs::try_parse_from(["irtt-server"])
+            .unwrap()
+            .resolve_binds()
+    }
+
+    #[test]
+    fn implicit_default_losing_an_unsupported_family_falls_back_to_the_other() {
+        let binds = default_binds();
+        let failed = binds[0];
+
+        let remaining = implicit_default_fallback(true, false, &binds, failed).unwrap();
+
+        assert_eq!(remaining, [binds[1]]);
+    }
+
+    #[test]
+    fn a_supported_familys_failure_never_falls_back() {
+        // The family itself works fine here; whatever made this specific
+        // bind fail (port in use, permission, ...) is a real problem this
+        // invocation should surface, not paper over.
+        let binds = default_binds();
+
+        assert_eq!(
+            implicit_default_fallback(true, true, &binds, binds[0]),
+            None,
+            "family_available: true means this is not a family-support problem"
+        );
+    }
+
+    #[test]
+    fn explicit_binds_never_fall_back() {
+        let binds = default_binds();
+
+        assert_eq!(
+            implicit_default_fallback(false, false, &binds, binds[0]),
+            None
+        );
+    }
+
+    #[test]
+    fn a_failure_outside_the_requested_set_does_not_fall_back() {
+        let binds = default_binds();
+        let unrelated = SocketAddr::from(([127, 0, 0, 1], 2113));
+
+        assert_eq!(
+            implicit_default_fallback(true, false, &binds, unrelated),
+            None,
+            "the failing address must actually be one this invocation asked for"
+        );
+    }
+
+    #[test]
+    fn losing_the_only_remaining_default_address_does_not_fall_back() {
+        let single = [SocketAddr::from(([0, 0, 0, 0], 2112))];
+
+        assert_eq!(
+            implicit_default_fallback(true, false, &single, single[0]),
+            None,
+            "no address would be left to retry with"
+        );
+    }
 }