openrtc 2.8.8

//! Shared iroh connection install/replacement policy.
//!
//! Browser and native nodes both see the same symmetric-dial and post-restart
//! races. Keeping this decision table target-neutral prevents wasm/native
//! behavior from drifting as each wrapper evolves.

use crate::lifecycle_reason::{
    REASON_DUPLICATE_ACCEPT_SUPERSEDED, REASON_DUPLICATE_DIAL_SUPERSEDED,
};

/// Briefly let the canonical initiator establish the shared physical leg before
/// the noncanonical endpoint falls back to its own dial. This prevents the two
/// independent QUIC connections from closing each other during symmetric
/// reconnect while still allowing a one-sided caller to make progress.
pub(crate) const NONCANONICAL_OUTBOUND_DIAL_GRACE_MS: u64 = 250;

/// Decide whether a custom Iroh carrier may be prepared over the current
/// physical path. Initial upgrades may start from relay/unknown, while an
/// atomic policy switch may prepare the opposite custom carrier over the live
/// incumbent. Same-carrier replacement is reserved for an explicitly bounded
/// stale-generation retry.
#[cfg(any(test, feature = "transport-webrtc", feature = "transport-moq"))]
pub(crate) fn custom_carrier_base_allows(
    path: crate::client::IrohPathKind,
    target: crate::client::IrohPathKind,
    allow_same_carrier_retry: bool,
) -> bool {
    use crate::client::IrohPathKind;

    matches!(path, IrohPathKind::Relay | IrohPathKind::Unknown)
        || matches!(
            (path, target),
            (IrohPathKind::WebRtc, IrohPathKind::Moq) | (IrohPathKind::Moq, IrohPathKind::WebRtc)
        )
        || (allow_same_carrier_retry && path == target)
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum IrohConnectionDirection {
    Inbound,
    Outbound,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct ExistingConnectionState {
    pub same_stable_id: bool,
    pub alive: bool,
    pub direction: IrohConnectionDirection,
    pub age_ms: u64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum IrohConnectionInstallDecision {
    /// Adopt the fresh connection into the endpoint map.
    Install,
    /// Adopt the fresh connection and retire the non-canonical existing leg.
    /// Endpoint-id ordering makes both peers select opposite halves of the
    /// same physical dial instead of each keeping its own outbound connection.
    ReplaceExisting { close_existing_reason: &'static str },
    /// Keep the existing endpoint map entry and close the fresh connection.
    KeepExisting { close_fresh_reason: &'static str },
}

pub(crate) fn should_start_outbound_dial(
    existing: Option<(bool, IrohConnectionDirection)>,
    local_prefers_outbound: bool,
) -> bool {
    let Some((alive, direction)) = existing else {
        return true;
    };
    !alive || (local_prefers_outbound && direction != IrohConnectionDirection::Outbound)
}

pub(crate) fn should_wait_for_canonical_inbound(
    existing: Option<(bool, IrohConnectionDirection)>,
    local_prefers_outbound: bool,
) -> bool {
    if local_prefers_outbound {
        return false;
    }
    match existing {
        None => true,
        Some((alive, _)) => !alive,
    }
}

pub(crate) fn decide_inbound_install(
    existing: Option<ExistingConnectionState>,
    local_prefers_outbound: bool,
) -> IrohConnectionInstallDecision {
    decide_install(
        existing,
        IrohConnectionDirection::Inbound,
        local_prefers_outbound,
    )
}

pub(crate) fn decide_outbound_install(
    existing: Option<ExistingConnectionState>,
    local_prefers_outbound: bool,
) -> IrohConnectionInstallDecision {
    decide_install(
        existing,
        IrohConnectionDirection::Outbound,
        local_prefers_outbound,
    )
}

fn replace_existing_decision(
    fresh_direction: IrohConnectionDirection,
) -> IrohConnectionInstallDecision {
    IrohConnectionInstallDecision::ReplaceExisting {
        close_existing_reason: match fresh_direction {
            IrohConnectionDirection::Inbound => {
                crate::lifecycle_reason::REASON_REPLACED_BY_NEW_INBOUND
            }
            IrohConnectionDirection::Outbound => {
                crate::lifecycle_reason::REASON_REPLACED_BY_NEW_OUTBOUND
            }
        },
    }
}

fn decide_install(
    existing: Option<ExistingConnectionState>,
    fresh_direction: IrohConnectionDirection,
    local_prefers_outbound: bool,
) -> IrohConnectionInstallDecision {
    let Some(existing) = existing else {
        return IrohConnectionInstallDecision::Install;
    };
    if existing.same_stable_id || !existing.alive {
        return IrohConnectionInstallDecision::Install;
    }
    let canonical_direction = if local_prefers_outbound {
        IrohConnectionDirection::Outbound
    } else {
        IrohConnectionDirection::Inbound
    };
    if fresh_direction != canonical_direction {
        return IrohConnectionInstallDecision::KeepExisting {
            close_fresh_reason: match fresh_direction {
                IrohConnectionDirection::Inbound => REASON_DUPLICATE_ACCEPT_SUPERSEDED,
                IrohConnectionDirection::Outbound => REASON_DUPLICATE_DIAL_SUPERSEDED,
            },
        };
    }
    // Direction resolves symmetric dials immediately. A live same-direction
    // leg remains authoritative regardless of age: elapsed time alone is not
    // evidence that a QUIC connection is stale. Replacing it on every later
    // canonical dial makes admission proofs alternate between two physical
    // generations and can prevent bilateral settlement forever. Restart
    // recovery is driven by close/heartbeat evidence (existing.alive=false),
    // while explicit custom-transport replacement has its own fenced path.
    if existing.direction != canonical_direction {
        return replace_existing_decision(fresh_direction);
    }
    IrohConnectionInstallDecision::KeepExisting {
        close_fresh_reason: match fresh_direction {
            IrohConnectionDirection::Inbound => REASON_DUPLICATE_ACCEPT_SUPERSEDED,
            IrohConnectionDirection::Outbound => REASON_DUPLICATE_DIAL_SUPERSEDED,
        },
    }
}

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

    #[test]
    fn custom_carrier_admission_is_symmetric_and_fail_closed() {
        use crate::client::IrohPathKind;

        for target in [IrohPathKind::WebRtc, IrohPathKind::Moq] {
            assert!(custom_carrier_base_allows(
                IrohPathKind::Relay,
                target,
                false,
            ));
            assert!(custom_carrier_base_allows(
                IrohPathKind::Unknown,
                target,
                false,
            ));
            assert!(!custom_carrier_base_allows(target, target, false));
            for rejected in [
                IrohPathKind::DirectQuic,
                IrohPathKind::DirectLan,
                IrohPathKind::Ble,
            ] {
                assert!(!custom_carrier_base_allows(rejected, target, false));
            }
        }
        assert!(custom_carrier_base_allows(
            IrohPathKind::WebRtc,
            IrohPathKind::Moq,
            false,
        ));
        assert!(custom_carrier_base_allows(
            IrohPathKind::Moq,
            IrohPathKind::WebRtc,
            false,
        ));
        assert!(custom_carrier_base_allows(
            IrohPathKind::Moq,
            IrohPathKind::Moq,
            true,
        ));
    }

    #[test]
    fn install_without_existing_or_for_same_stable_id() {
        assert_eq!(
            decide_inbound_install(None, false),
            IrohConnectionInstallDecision::Install
        );
        assert_eq!(
            decide_outbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: true,
                    alive: true,
                    direction: IrohConnectionDirection::Inbound,
                    age_ms: 0,
                }),
                true
            ),
            IrohConnectionInstallDecision::Install
        );
    }

    #[test]
    fn install_over_dead_existing_connection() {
        assert_eq!(
            decide_inbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: false,
                    direction: IrohConnectionDirection::Outbound,
                    age_ms: 0,
                }),
                false
            ),
            IrohConnectionInstallDecision::Install
        );
    }

    #[test]
    fn recent_same_direction_canonical_duplicate_keeps_existing_connection() {
        assert_eq!(
            decide_inbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Inbound,
                    age_ms: 1_999,
                }),
                false
            ),
            IrohConnectionInstallDecision::KeepExisting {
                close_fresh_reason: REASON_DUPLICATE_ACCEPT_SUPERSEDED,
            }
        );
        assert_eq!(
            decide_outbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Outbound,
                    age_ms: 0,
                }),
                true
            ),
            IrohConnectionInstallDecision::KeepExisting {
                close_fresh_reason: REASON_DUPLICATE_DIAL_SUPERSEDED,
            }
        );
    }

    #[test]
    fn elapsed_time_cannot_replace_a_live_same_direction_connection() {
        assert_eq!(
            decide_inbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Inbound,
                    age_ms: u64::MAX,
                }),
                false
            ),
            IrohConnectionInstallDecision::KeepExisting {
                close_fresh_reason: REASON_DUPLICATE_ACCEPT_SUPERSEDED,
            }
        );
        assert_eq!(
            decide_outbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Outbound,
                    age_ms: u64::MAX,
                }),
                true
            ),
            IrohConnectionInstallDecision::KeepExisting {
                close_fresh_reason: REASON_DUPLICATE_DIAL_SUPERSEDED,
            }
        );
    }

    #[test]
    fn canonical_fresh_leg_replaces_the_non_canonical_live_leg() {
        assert_eq!(
            decide_inbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Outbound,
                    age_ms: 0,
                }),
                false
            ),
            IrohConnectionInstallDecision::ReplaceExisting {
                close_existing_reason: crate::lifecycle_reason::REASON_REPLACED_BY_NEW_INBOUND,
            }
        );
        assert_eq!(
            decide_outbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Inbound,
                    age_ms: 0,
                }),
                true
            ),
            IrohConnectionInstallDecision::ReplaceExisting {
                close_existing_reason: crate::lifecycle_reason::REASON_REPLACED_BY_NEW_OUTBOUND,
            }
        );
    }

    #[test]
    fn noncanonical_fresh_leg_cannot_replace_an_existing_live_leg() {
        assert_eq!(
            decide_inbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Outbound,
                    age_ms: u64::MAX,
                }),
                true
            ),
            IrohConnectionInstallDecision::KeepExisting {
                close_fresh_reason: REASON_DUPLICATE_ACCEPT_SUPERSEDED,
            }
        );
        assert_eq!(
            decide_outbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Inbound,
                    age_ms: u64::MAX,
                }),
                false
            ),
            IrohConnectionInstallDecision::KeepExisting {
                close_fresh_reason: REASON_DUPLICATE_DIAL_SUPERSEDED,
            }
        );
    }

    #[test]
    fn connection_age_never_overrides_noncanonical_direction() {
        assert_eq!(
            decide_outbound_install(
                Some(ExistingConnectionState {
                    same_stable_id: false,
                    alive: true,
                    direction: IrohConnectionDirection::Inbound,
                    age_ms: u64::MAX,
                }),
                false,
            ),
            IrohConnectionInstallDecision::KeepExisting {
                close_fresh_reason: REASON_DUPLICATE_DIAL_SUPERSEDED,
            }
        );
    }

    #[test]
    fn outbound_precheck_is_idempotent_and_repairs_only_noncanonical_live_legs() {
        assert!(should_start_outbound_dial(None, true));
        assert!(should_start_outbound_dial(
            Some((false, IrohConnectionDirection::Outbound)),
            true,
        ));
        assert!(!should_start_outbound_dial(
            Some((true, IrohConnectionDirection::Outbound)),
            true,
        ));
        assert!(should_start_outbound_dial(
            Some((true, IrohConnectionDirection::Inbound)),
            true,
        ));
        assert!(!should_start_outbound_dial(
            Some((true, IrohConnectionDirection::Outbound)),
            false,
        ));
    }

    #[test]
    fn noncanonical_endpoint_waits_only_when_no_live_leg_exists() {
        assert!(should_wait_for_canonical_inbound(None, false));
        assert!(should_wait_for_canonical_inbound(
            Some((false, IrohConnectionDirection::Outbound)),
            false,
        ));
        assert!(!should_wait_for_canonical_inbound(
            Some((true, IrohConnectionDirection::Inbound)),
            false,
        ));
        assert!(!should_wait_for_canonical_inbound(None, true));
    }
}