softchat/

relay_catalog.rs

//! Relay catalog reconciliation, failover ordering, and retry policy.

use std::collections::{BTreeMap, BTreeSet};

use serde::{Deserialize, Serialize};
use url::Url;

use crate::SoftchatError;

/// Maximum effective relay records retained for one account.
pub const MAX_RELAY_CATALOG_ENTRIES: usize = 256;
/// Maximum authenticated DNS URI records accepted in one refresh.
pub const MAX_DNS_RELAY_RECORDS: usize = 256;
/// Default refresh lifetime assigned to the compiled fallback.
pub const DEFAULT_FALLBACK_RELAY_TTL_SECONDS: u32 = 3_600;
/// Maximum DNS URI TTL accepted by the portable policy.
pub const MAX_RELAY_TTL_SECONDS: u32 = 7 * 24 * 60 * 60;
/// Maximum reconnect delay before host-selected jitter.
pub const MAX_RELAY_RETRY_DELAY_MS: u64 = 8_000;
/// Host-selected retry jitter range is always zero through this value.
pub const MAX_RELAY_RETRY_JITTER_MS: u64 = 250;

/// Consumer-visible source of one relay.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Enum))]
pub enum RelayCatalogSource {
    /// Authenticated discovery or the compiled fallback.
    Automatic,
    /// Explicit user configuration.
    Custom,
}

/// Complete platform-persisted relay catalog row.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct RelayCatalogEntry {
    /// Canonical WSS URL and stable row ID.
    pub url: String,
    /// Portable creation timestamp.
    pub created_at: i64,
    /// Whether this is the single active relay.
    pub is_active: bool,
    /// Consumer-visible source.
    pub source: RelayCatalogSource,
    /// Whether the latest authenticated discovery contains this URL.
    pub is_dns_discovered: bool,
    /// Whether the user excluded an automatically discovered URL.
    pub is_user_excluded: bool,
    /// DNS priority, or `-1` when absent.
    pub dns_priority: i32,
    /// DNS weight, or `-1` when absent.
    pub dns_weight: i32,
    /// Absolute portable DNS expiration, or `-1` when absent.
    pub dns_expires_at: i64,
}

/// One authenticated DNS URI record supplied by the Android system adapter.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct DnsRelayRecord {
    /// WSS or pinned `wss+noise` target URL.
    pub target: String,
    /// RFC 7553 URI priority represented as an unsigned 16-bit value.
    pub priority: u32,
    /// RFC 7553 URI weight represented as an unsigned 16-bit value.
    pub weight: u32,
    /// DNS TTL in seconds.
    pub ttl_seconds: u32,
}

/// Validated system-transport plan for one configured relay URL.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct RelayEndpointPlan {
    /// Canonical persisted URL; Noise endpoints use `wss+noise` and a lowercase key fragment.
    pub configured_url: String,
    /// Ordinary `wss` URL used by managed or low-level host transport.
    pub network_url: String,
    /// Pinned Noise responder static key, empty for ordinary TLS-only WSS.
    pub noise_remote_static_key: Vec<u8>,
}

/// Deterministic full-state catalog replacement.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct RelayCatalogPlan {
    /// Complete rows the platform commits atomically.
    pub entries: Vec<RelayCatalogEntry>,
    /// Selected active URL.
    pub active_relay_url: String,
    /// Earliest authenticated discovery expiration.
    pub next_refresh_at: i64,
    /// Whether unauthenticated/empty discovery activated the fallback.
    pub used_fallback: bool,
}

/// Transport failure class consumed by the Rust retry policy.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Enum))]
pub enum RelayFailureKind {
    /// Android reports that no usable network currently exists.
    NetworkUnavailable,
    /// Connection loss or one transient relay failure.
    Temporary,
    /// Relay asks the client to slow down.
    RateLimited,
    /// Authentication permanently failed for this relay.
    Authentication,
    /// Protocol behavior makes the relay unusable for this session.
    ProtocolPermanent,
}

/// Retry/failover action selected by Rust.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Enum))]
pub enum RelayRetryAction {
    /// Retain the same relay and wait for the platform/network.
    WaitSameRelay,
    /// Select the next effective relay immediately after the delay.
    RotateRelay,
}

/// Bounded retry plan; the host chooses jitter inside the declared range.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct RelayRetryPlan {
    /// Retry or failover behavior.
    pub action: RelayRetryAction,
    /// Exponential delay before jitter.
    pub delay_ms: u64,
    /// Inclusive maximum host-selected jitter.
    pub jitter_max_ms: u64,
}

/// Stateless relay catalog reducer.
#[derive(Clone, Copy, Debug, Default)]
pub struct RelayCatalogReducer;

impl RelayCatalogReducer {
    /// Reconcile persisted custom/exclusion state with authenticated discovery.
    ///
    /// Discovery that is not explicitly authenticated never becomes trusted
    /// catalog state. The compiled fallback is used instead.
    ///
    /// # Errors
    ///
    /// Returns [`SoftchatError::InvalidRelayCatalog`] for invalid URLs,
    /// duplicate persisted rows, bounds, timestamps, priorities, weights, or
    /// TTLs.
    pub fn reconcile(
        current: Vec<RelayCatalogEntry>,
        discovered: Vec<DnsRelayRecord>,
        refreshed_at: i64,
        fallback_url: String,
        dns_authenticated: bool,
    ) -> Result<RelayCatalogPlan, SoftchatError> {
        if refreshed_at < 0
            || current.len() > MAX_RELAY_CATALOG_ENTRIES
            || discovered.len() > MAX_DNS_RELAY_RECORDS
        {
            return Err(SoftchatError::InvalidRelayCatalog);
        }
        let fallback_url = canonical_relay_url(&fallback_url)?;
        let mut rows = BTreeMap::new();
        for mut entry in current {
            validate_entry(&entry)?;
            entry.url = canonical_relay_url(&entry.url)?;
            if rows.insert(entry.url.clone(), entry).is_some() {
                return Err(SoftchatError::InvalidRelayCatalog);
            }
        }

        for entry in rows.values_mut() {
            entry.is_dns_discovered = false;
            entry.dns_priority = -1;
            entry.dns_weight = -1;
            entry.dns_expires_at = -1;
        }

        let preferred = if dns_authenticated && !discovered.is_empty() {
            preferred_dns_records(discovered)?
        } else {
            vec![DnsRelayRecord {
                target: fallback_url.clone(),
                priority: 0,
                weight: 0,
                ttl_seconds: DEFAULT_FALLBACK_RELAY_TTL_SECONDS,
            }]
        };
        let used_fallback = !(dns_authenticated && !preferred.is_empty());

        for record in preferred {
            let target = canonical_relay_url(&record.target)?;
            validate_dns_record(&record)?;
            let expires_at = refreshed_at
                .checked_add(i64::from(record.ttl_seconds))
                .ok_or(SoftchatError::InvalidRelayCatalog)?;
            let entry = rows
                .entry(target.clone())
                .or_insert_with(|| RelayCatalogEntry {
                    url: target,
                    created_at: refreshed_at,
                    is_active: false,
                    source: RelayCatalogSource::Automatic,
                    is_dns_discovered: false,
                    is_user_excluded: false,
                    dns_priority: -1,
                    dns_weight: -1,
                    dns_expires_at: -1,
                });
            entry.is_dns_discovered = true;
            entry.dns_priority =
                i32::try_from(record.priority).map_err(|_| SoftchatError::InvalidRelayCatalog)?;
            entry.dns_weight =
                i32::try_from(record.weight).map_err(|_| SoftchatError::InvalidRelayCatalog)?;
            entry.dns_expires_at = expires_at;
        }

        rows.retain(|_, entry| {
            entry.source == RelayCatalogSource::Custom
                || entry.is_dns_discovered
                || entry.is_user_excluded
        });
        if rows.len() > MAX_RELAY_CATALOG_ENTRIES {
            return Err(SoftchatError::InvalidRelayCatalog);
        }

        let previous_active = rows
            .values()
            .find(|entry| entry.is_active && is_effective(entry))
            .map(|entry| entry.url.clone());
        for entry in rows.values_mut() {
            entry.is_active = false;
        }
        let ordered = ordered_effective_entries(rows.values().cloned().collect())?;
        let active_relay_url = previous_active
            .or_else(|| {
                ordered
                    .iter()
                    .find(|entry| entry.url == fallback_url)
                    .map(|entry| entry.url.clone())
            })
            .or_else(|| ordered.first().map(|entry| entry.url.clone()))
            .ok_or(SoftchatError::InvalidRelayCatalog)?;
        let active = rows
            .get_mut(&active_relay_url)
            .ok_or(SoftchatError::InvalidRelayCatalog)?;
        active.is_active = true;

        let mut entries = rows.into_values().collect::<Vec<_>>();
        entries.sort_by(entry_storage_order);
        let next_refresh_at = entries
            .iter()
            .filter(|entry| entry.is_dns_discovered)
            .map(|entry| entry.dns_expires_at)
            .min()
            .ok_or(SoftchatError::InvalidRelayCatalog)?;
        Ok(RelayCatalogPlan {
            entries,
            active_relay_url,
            next_refresh_at,
            used_fallback,
        })
    }

    /// Add or reactivate a user-owned relay without discarding DNS metadata.
    ///
    /// # Errors
    ///
    /// Returns a stable relay-catalog error for malformed state or URL.
    pub fn add_custom(
        current: Vec<RelayCatalogEntry>,
        relay_url: String,
        created_at: i64,
    ) -> Result<Vec<RelayCatalogEntry>, SoftchatError> {
        if created_at < 0 || current.len() >= MAX_RELAY_CATALOG_ENTRIES {
            return Err(SoftchatError::InvalidRelayCatalog);
        }
        let relay_url = canonical_relay_url(&relay_url)?;
        let mut rows = validated_rows(current)?;
        let entry = rows
            .entry(relay_url.clone())
            .or_insert_with(|| RelayCatalogEntry {
                url: relay_url,
                created_at,
                is_active: false,
                source: RelayCatalogSource::Custom,
                is_dns_discovered: false,
                is_user_excluded: false,
                dns_priority: -1,
                dns_weight: -1,
                dns_expires_at: -1,
            });
        entry.source = RelayCatalogSource::Custom;
        entry.is_user_excluded = false;
        Ok(sorted_rows(rows))
    }

    /// Exclude an automatic relay or remove the custom ownership of a URL.
    ///
    /// # Errors
    ///
    /// Returns a stable relay-catalog error for an unknown or active-only URL.
    pub fn exclude(
        current: Vec<RelayCatalogEntry>,
        relay_url: String,
    ) -> Result<Vec<RelayCatalogEntry>, SoftchatError> {
        let relay_url = canonical_relay_url(&relay_url)?;
        let mut rows = validated_rows(current)?;
        let entry = rows
            .get_mut(&relay_url)
            .ok_or(SoftchatError::InvalidRelayCatalog)?;
        entry.source = RelayCatalogSource::Automatic;
        entry.is_user_excluded = true;
        entry.is_active = false;
        if !entry.is_dns_discovered {
            rows.remove(&relay_url);
        }
        ensure_one_active(&mut rows)?;
        Ok(sorted_rows(rows))
    }

    /// Restore every currently discovered automatic relay.
    ///
    /// # Errors
    ///
    /// Returns a stable relay-catalog error for malformed persisted rows.
    pub fn restore_automatic(
        current: Vec<RelayCatalogEntry>,
    ) -> Result<Vec<RelayCatalogEntry>, SoftchatError> {
        let mut rows = validated_rows(current)?;
        for entry in rows.values_mut() {
            if entry.is_dns_discovered {
                entry.is_user_excluded = false;
            }
        }
        ensure_one_active(&mut rows)?;
        Ok(sorted_rows(rows))
    }

    /// Select one effective active relay.
    ///
    /// # Errors
    ///
    /// Returns a stable relay-catalog error for an unknown/excluded target.
    pub fn set_active(
        current: Vec<RelayCatalogEntry>,
        relay_url: String,
    ) -> Result<Vec<RelayCatalogEntry>, SoftchatError> {
        let relay_url = canonical_relay_url(&relay_url)?;
        let mut rows = validated_rows(current)?;
        if rows
            .get(&relay_url)
            .is_none_or(|entry| !is_effective(entry))
        {
            return Err(SoftchatError::InvalidRelayCatalog);
        }
        for entry in rows.values_mut() {
            entry.is_active = entry.url == relay_url;
        }
        Ok(sorted_rows(rows))
    }

    /// Return effective failover URLs ordered by DNS priority then stable URL.
    ///
    /// The failed URL is moved to the end rather than removed so a caller can
    /// continue cycling after every candidate fails.
    ///
    /// # Errors
    ///
    /// Returns a stable relay-catalog error for malformed persisted rows.
    pub fn failover_candidates(
        current: Vec<RelayCatalogEntry>,
        failed_url: String,
    ) -> Result<Vec<String>, SoftchatError> {
        let failed_url = canonical_relay_url(&failed_url)?;
        let rows = validated_rows(current)?;
        let mut urls = ordered_effective_entries(rows.into_values().collect())?
            .into_iter()
            .map(|entry| entry.url)
            .collect::<Vec<_>>();
        if let Some(index) = urls.iter().position(|url| url == &failed_url) {
            let failed = urls.remove(index);
            urls.push(failed);
        }
        Ok(urls)
    }
}

/// Select the exact retry/failover behavior for one failed attempt.
#[must_use]
pub fn plan_relay_retry(
    attempt: u32,
    failure: RelayFailureKind,
    bypass_delay_once: bool,
) -> RelayRetryPlan {
    let action = match failure {
        RelayFailureKind::Authentication | RelayFailureKind::ProtocolPermanent => {
            RelayRetryAction::RotateRelay
        }
        RelayFailureKind::NetworkUnavailable
        | RelayFailureKind::Temporary
        | RelayFailureKind::RateLimited => RelayRetryAction::WaitSameRelay,
    };
    let delay_ms = if bypass_delay_once
        || matches!(
            failure,
            RelayFailureKind::Authentication | RelayFailureKind::ProtocolPermanent
        ) {
        0
    } else {
        let exponent = attempt.min(4);
        let calculated = 500_u64.saturating_mul(1_u64 << exponent);
        if calculated > MAX_RELAY_RETRY_DELAY_MS {
            MAX_RELAY_RETRY_DELAY_MS
        } else {
            calculated
        }
    };
    RelayRetryPlan {
        action,
        delay_ms,
        jitter_max_ms: MAX_RELAY_RETRY_JITTER_MS,
    }
}

fn preferred_dns_records(
    records: Vec<DnsRelayRecord>,
) -> Result<Vec<DnsRelayRecord>, SoftchatError> {
    let mut preferred = BTreeMap::new();
    for mut record in records {
        validate_dns_record(&record)?;
        record.target = canonical_relay_url(&record.target)?;
        match preferred.get(&record.target) {
            None => {
                preferred.insert(record.target.clone(), record);
            }
            Some(existing) if is_preferred(&record, existing) => {
                preferred.insert(record.target.clone(), record);
            }
            Some(_) => {}
        }
    }
    Ok(preferred.into_values().collect())
}

fn is_preferred(candidate: &DnsRelayRecord, existing: &DnsRelayRecord) -> bool {
    candidate.priority < existing.priority
        || (candidate.priority == existing.priority && candidate.weight > existing.weight)
        || (candidate.priority == existing.priority
            && candidate.weight == existing.weight
            && candidate.ttl_seconds < existing.ttl_seconds)
}

fn validate_dns_record(record: &DnsRelayRecord) -> Result<(), SoftchatError> {
    if record.priority > u32::from(u16::MAX)
        || record.weight > u32::from(u16::MAX)
        || record.ttl_seconds == 0
        || record.ttl_seconds > MAX_RELAY_TTL_SECONDS
    {
        Err(SoftchatError::InvalidRelayCatalog)
    } else {
        Ok(())
    }
}

fn validate_entry(entry: &RelayCatalogEntry) -> Result<(), SoftchatError> {
    canonical_relay_url(&entry.url)?;
    if entry.created_at < 0
        || !(-1..=i32::from(u16::MAX)).contains(&entry.dns_priority)
        || !(-1..=i32::from(u16::MAX)).contains(&entry.dns_weight)
        || (entry.is_dns_discovered
            && (entry.dns_priority < 0
                || entry.dns_weight < 0
                || entry.dns_expires_at < entry.created_at))
        || (!entry.is_dns_discovered
            && (entry.dns_priority != -1 || entry.dns_weight != -1 || entry.dns_expires_at != -1))
        || (entry.source == RelayCatalogSource::Custom && entry.is_user_excluded)
    {
        Err(SoftchatError::InvalidRelayCatalog)
    } else {
        Ok(())
    }
}

fn validated_rows(
    entries: Vec<RelayCatalogEntry>,
) -> Result<BTreeMap<String, RelayCatalogEntry>, SoftchatError> {
    if entries.len() > MAX_RELAY_CATALOG_ENTRIES {
        return Err(SoftchatError::InvalidRelayCatalog);
    }
    let mut rows = BTreeMap::new();
    let mut active = 0_u8;
    for mut entry in entries {
        validate_entry(&entry)?;
        entry.url = canonical_relay_url(&entry.url)?;
        if entry.is_active {
            active = active
                .checked_add(1)
                .ok_or(SoftchatError::InvalidRelayCatalog)?;
        }
        if rows.insert(entry.url.clone(), entry).is_some() {
            return Err(SoftchatError::InvalidRelayCatalog);
        }
    }
    if active > 1 {
        return Err(SoftchatError::InvalidRelayCatalog);
    }
    Ok(rows)
}

fn ensure_one_active(rows: &mut BTreeMap<String, RelayCatalogEntry>) -> Result<(), SoftchatError> {
    if rows
        .values()
        .any(|entry| entry.is_active && is_effective(entry))
    {
        return Ok(());
    }
    for entry in rows.values_mut() {
        entry.is_active = false;
    }
    let selected = ordered_effective_entries(rows.values().cloned().collect())?
        .first()
        .map(|entry| entry.url.clone())
        .ok_or(SoftchatError::InvalidRelayCatalog)?;
    rows.get_mut(&selected)
        .ok_or(SoftchatError::InvalidRelayCatalog)?
        .is_active = true;
    Ok(())
}

fn ordered_effective_entries(
    mut entries: Vec<RelayCatalogEntry>,
) -> Result<Vec<RelayCatalogEntry>, SoftchatError> {
    let mut unique = BTreeSet::new();
    entries.retain(is_effective);
    for entry in &entries {
        validate_entry(entry)?;
        if !unique.insert(entry.url.clone()) {
            return Err(SoftchatError::InvalidRelayCatalog);
        }
    }
    entries.sort_by(|left, right| {
        let left_priority = (left.dns_priority >= 0).then_some(left.dns_priority);
        let right_priority = (right.dns_priority >= 0).then_some(right.dns_priority);
        left_priority
            .is_none()
            .cmp(&right_priority.is_none())
            .then_with(|| left_priority.cmp(&right_priority))
            .then_with(|| left.url.cmp(&right.url))
    });
    Ok(entries)
}

fn entry_storage_order(left: &RelayCatalogEntry, right: &RelayCatalogEntry) -> std::cmp::Ordering {
    left.url.cmp(&right.url)
}

fn sorted_rows(rows: BTreeMap<String, RelayCatalogEntry>) -> Vec<RelayCatalogEntry> {
    rows.into_values().collect()
}

fn is_effective(entry: &RelayCatalogEntry) -> bool {
    entry.source == RelayCatalogSource::Custom
        || (entry.is_dns_discovered && !entry.is_user_excluded)
}

fn canonical_relay_url(value: &str) -> Result<String, SoftchatError> {
    Ok(parse_relay_endpoint(value)?.configured_url)
}

/// Validate one configured relay and split protocol from system transport data.
///
/// `wss+noise` and the released legacy `wss#<key>` spelling canonicalize to
/// one configured URL. Android opens [`RelayEndpointPlan::network_url`] and
/// gives the 32-byte pin to the SDK Noise handshake.
///
/// # Errors
///
/// Returns a stable relay-catalog error for insecure URLs, credentials,
/// missing hosts, or malformed/missing Noise keys.
pub fn parse_relay_endpoint(value: &str) -> Result<RelayEndpointPlan, SoftchatError> {
    if value.len() > 2_048 {
        return Err(SoftchatError::InvalidRelayCatalog);
    }
    let configured = Url::parse(value).map_err(|_| SoftchatError::InvalidRelayCatalog)?;
    if !matches!(configured.scheme(), "wss" | "wss+noise")
        || !configured.username().is_empty()
        || configured.password().is_some()
        || configured.host_str().is_none()
    {
        return Err(SoftchatError::InvalidRelayCatalog);
    }
    let requires_noise = configured.scheme() == "wss+noise" || configured.fragment().is_some();
    let noise_remote_static_key = if requires_noise {
        let encoded = configured
            .fragment()
            .filter(|fragment| {
                fragment.len() == 64 && fragment.bytes().all(|byte| byte.is_ascii_hexdigit())
            })
            .ok_or(SoftchatError::InvalidRelayCatalog)?
            .to_ascii_lowercase();
        hex::decode(encoded).map_err(|_| SoftchatError::InvalidRelayCatalog)?
    } else {
        Vec::new()
    };
    let network_value = if configured.scheme() == "wss+noise" {
        configured.as_str().replacen("wss+noise:", "wss:", 1)
    } else {
        configured.to_string()
    };
    let mut network = Url::parse(&network_value).map_err(|_| SoftchatError::InvalidRelayCatalog)?;
    network.set_fragment(None);
    let configured_url = if requires_noise {
        let key = hex::encode(&noise_remote_static_key);
        let mut pinned = network.clone();
        pinned.set_fragment(Some(&key));
        pinned.to_string().replacen("wss:", "wss+noise:", 1)
    } else {
        network.to_string()
    };
    Ok(RelayEndpointPlan {
        configured_url,
        network_url: network.to_string(),
        noise_remote_static_key,
    })
}

#[cfg(test)]
#[allow(clippy::expect_used)]
mod tests {
    use super::*;

    fn custom(url: &str, created_at: i64, active: bool) -> RelayCatalogEntry {
        RelayCatalogEntry {
            url: url.to_owned(),
            created_at,
            is_active: active,
            source: RelayCatalogSource::Custom,
            is_dns_discovered: false,
            is_user_excluded: false,
            dns_priority: -1,
            dns_weight: -1,
            dns_expires_at: -1,
        }
    }

    fn dns(target: &str, priority: u32, weight: u32, ttl_seconds: u32) -> DnsRelayRecord {
        DnsRelayRecord {
            target: target.to_owned(),
            priority,
            weight,
            ttl_seconds,
        }
    }

    #[test]
    fn reconciles_custom_discovered_excluded_and_fallback_state() {
        let plan = RelayCatalogReducer::reconcile(
            vec![custom("wss://custom.example", 10, true)],
            vec![
                dns("wss://two.example", 20, 1, 600),
                dns("wss://one.example", 10, 1, 300),
            ],
            100,
            "wss://fallback.example".to_owned(),
            true,
        )
        .expect("valid catalog");
        assert!(!plan.used_fallback);
        assert_eq!(plan.active_relay_url, "wss://custom.example/");
        assert_eq!(plan.next_refresh_at, 400);
        assert_eq!(
            RelayCatalogReducer::failover_candidates(
                plan.entries.clone(),
                "wss://one.example".to_owned()
            )
            .expect("valid failover"),
            vec![
                "wss://two.example/".to_owned(),
                "wss://custom.example/".to_owned(),
                "wss://one.example/".to_owned()
            ]
        );

        let fallback = RelayCatalogReducer::reconcile(
            plan.entries,
            Vec::new(),
            1_000,
            "wss://fallback.example".to_owned(),
            false,
        )
        .expect("fallback catalog");
        assert!(fallback.used_fallback);
        assert!(
            fallback
                .entries
                .iter()
                .any(|entry| entry.url == "wss://fallback.example/")
        );
    }

    #[test]
    fn deduplicates_dns_targets_by_priority_weight_then_shorter_ttl() {
        let plan = RelayCatalogReducer::reconcile(
            Vec::new(),
            vec![
                dns("wss://relay.example", 20, 100, 600),
                dns("wss://relay.example", 10, 1, 500),
                dns("wss://relay.example", 10, 2, 700),
                dns("wss://relay.example", 10, 2, 300),
            ],
            100,
            "wss://fallback.example".to_owned(),
            true,
        )
        .expect("valid catalog");
        let entry = plan.entries.first().expect("one relay");
        assert_eq!(entry.dns_priority, 10);
        assert_eq!(entry.dns_weight, 2);
        assert_eq!(entry.dns_expires_at, 400);
    }

    #[test]
    fn retry_policy_is_bounded_and_rotates_permanent_failures() {
        assert_eq!(
            plan_relay_retry(0, RelayFailureKind::Temporary, false),
            RelayRetryPlan {
                action: RelayRetryAction::WaitSameRelay,
                delay_ms: 500,
                jitter_max_ms: 250,
            }
        );
        assert_eq!(
            plan_relay_retry(99, RelayFailureKind::RateLimited, false).delay_ms,
            8_000
        );
        assert_eq!(
            plan_relay_retry(2, RelayFailureKind::Authentication, false),
            RelayRetryPlan {
                action: RelayRetryAction::RotateRelay,
                delay_ms: 0,
                jitter_max_ms: 250,
            }
        );
        assert_eq!(
            plan_relay_retry(2, RelayFailureKind::NetworkUnavailable, true).delay_ms,
            0
        );
    }

    #[test]
    fn canonicalizes_the_released_noise_endpoint_spellings() {
        let key = "01".repeat(32);
        let explicit = parse_relay_endpoint(&format!("wss+noise://relay.example/#{key}"))
            .expect("valid explicit endpoint");
        let legacy = parse_relay_endpoint(&format!("wss://relay.example/#{key}"))
            .expect("valid legacy endpoint");
        assert_eq!(explicit, legacy);
        assert_eq!(explicit.network_url, "wss://relay.example/");
        assert_eq!(explicit.noise_remote_static_key, vec![1; 32]);
        assert!(
            parse_relay_endpoint("wss+noise://relay.example/").is_err(),
            "Noise must never silently run without its responder pin"
        );
    }
}