scion-stack 0.6.1

// Copyright 2025 Anapaya Systems
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Path issue classification (internal).

use std::{
    borrow::Cow,
    fmt::Display,
    hash::{DefaultHasher, Hash, Hasher},
    net,
    time::{Duration, SystemTime},
};

use sciparse::{
    address::host_addr::ScionHostAddr,
    core::view::View,
    dataplane_path::view::ScionDpPathViewExt,
    identifier::isd_asn::IsdAsn,
    packet::view::ScionRawPacketView,
    path::{ScionPath, fingerprint::data_plane::DpPathFingerprint},
    payload::scmp::{model::ScmpErrorMessage, types::ScmpDestinationUnreachableCode},
};

use crate::{
    path::{manager::algo::exponential_decay, types::Score},
    stack::ScionSocketSendError,
};

/// Marker for a path issue
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct IssueMarker {
    pub target: IssueMarkerTarget,
    pub timestamp: SystemTime,
    pub penalty: Score,
}

impl IssueMarker {
    const SYSTEM_HALF_LIFE: Duration = Duration::from_secs(30);

    /// Returns the decayed penalty score of the issue.
    pub fn decayed_penalty(&self, now: SystemTime) -> Score {
        let elapsed = now
            .duration_since(self.timestamp)
            .unwrap_or(Duration::from_secs(0));

        let decayed = exponential_decay(self.penalty.value(), elapsed, Self::SYSTEM_HALF_LIFE);

        Score::new_clamped(decayed)
    }
}

/// The Path type that the issue marker targets.
///
/// This is global and only applies to SCION paths, and is not specific to any specific endhost.
#[derive(Debug, Hash, Eq, PartialEq, Clone, Copy)]
pub enum IssueMarkerTarget {
    // Placeholder target that is matched but not yet produced by any issue source.
    #[allow(dead_code)]
    FullPath { fingerprint: DpPathFingerprint },
    Interface {
        isd_asn: IsdAsn,
        /// Optionally only applies when arriving on this ingress interface
        ingress_filter: Option<u16>,
        /// Applies when leaving on this egress interface
        egress_filter: u16,
    },
    FirstHop {
        isd_asn: IsdAsn,
        egress_interface: u16,
    },
    // Placeholder target that is matched but not yet produced by any issue source.
    #[allow(dead_code)]
    LastHop {
        isd_asn: IsdAsn,
        ingress_interface: u16,
    },
    // XXX(ake) : These DestinationNetwork errors are not handled in the PathManager
    DestinationNetwork {
        isd_asn: IsdAsn,
        ingress_interface: u16,
        dst_host: ScionHostAddr,
    },
}

impl IssueMarkerTarget {
    /// Checks if the issue marker target matches the given path.
    ///
    /// If the path does not contain metadata, hop based targets cannot be matched.
    ///
    /// If it's possible to optimize path matching, use `matches_path_checked` instead.
    pub fn matches_path(&self, path: &ScionPath, fingerprint: &DpPathFingerprint) -> bool {
        self.matches_path_checked(path, fingerprint, |_, _| true)
    }

    /// Checks if the issue marker target matches the given path.
    ///
    /// `might_include_check` is a closure allowing optimizations to skip paths that definitely
    /// won't match, called before any detailed matching is done.
    ///
    /// If the path does not contain metadata, hop based targets cannot be matched.
    pub fn matches_path_checked<F>(
        &self,
        path: &ScionPath,
        fingerprint: &DpPathFingerprint,
        might_include_check: F,
    ) -> bool
    where
        F: Fn(&IssueMarkerTarget, &ScionPath) -> bool,
    {
        match self {
            // Check per fingerprint
            Self::FullPath {
                fingerprint: target_fingerprint,
            } => fingerprint == target_fingerprint,
            // Just need to check first interface
            Self::FirstHop {
                isd_asn,
                egress_interface,
            } => {
                path.first_egress_interface()
                    .is_some_and(|intf| intf.isd_asn == *isd_asn && intf.id == *egress_interface)
            }
            // Just need to check last interface
            Self::DestinationNetwork {
                isd_asn,
                ingress_interface,
                ..
            }
            | Self::LastHop {
                isd_asn,
                ingress_interface,
            } => {
                path.last_ingress_interface()
                    .is_some_and(|intf| intf.isd_asn == *isd_asn && intf.id == *ingress_interface)
            }
            // Check all interfaces for matching ingress/egress pair
            Self::Interface {
                isd_asn,
                egress_filter,
                ingress_filter,
            } => {
                // Quick check if path might include the targeted AS
                if !might_include_check(self, path) {
                    return false;
                }

                let interfaces = match path
                    .metadata()
                    .as_ref()
                    .and_then(|meta| meta.interfaces.as_ref())
                {
                    Some(interfaces) => interfaces,
                    None => return false, // No metadata, cannot match
                };

                // We start in the source AS, so first interface is always source egress
                if path.src_ia() == *isd_asn {
                    return match ingress_filter {
                        Some(_) => false, /* we are in src, but an ingress filter is set, */
                        // cannot match
                        None => {
                            interfaces
                                .first()
                                .is_some_and(|iface| &iface.interface.id == egress_filter)
                        }
                    };
                }

                let mut iter = interfaces.iter();

                // Check every ingress interface if it's in the target AS
                while let Some(interface) = iter.nth(1) {
                    if interface.interface.isd_asn != *isd_asn {
                        continue;
                    }

                    // Check ingress filter
                    if let Some(ingress) = ingress_filter
                        && interface.interface.id != *ingress
                    {
                        return false;
                    }

                    // Next interface is egress
                    return iter
                        .next()
                        .is_some_and(|egress| &egress.interface.id == egress_filter);
                }

                false
            }
        }
    }

    /// Returns how many entries this issue marker can apply to.
    pub fn applies_to_multiple_paths(&self) -> bool {
        match self {
            IssueMarkerTarget::Interface { .. }
            | IssueMarkerTarget::FirstHop { .. }
            | IssueMarkerTarget::LastHop { .. }
            | IssueMarkerTarget::DestinationNetwork { .. } => true,
            IssueMarkerTarget::FullPath { .. } => false,
        }
    }

    /// Checks if the issue marker can apply to a path between the given src and dst ISD-ASNs.
    pub fn applies_to_path(&self, src: IsdAsn, dst: IsdAsn) -> bool {
        match self {
            // Applies to all src-dst pairs
            IssueMarkerTarget::FullPath { .. } | IssueMarkerTarget::Interface { .. } => true,
            // Applies to specific src
            IssueMarkerTarget::FirstHop { isd_asn, .. } => src == *isd_asn,
            // Applies to specific dst
            IssueMarkerTarget::LastHop { isd_asn, .. }
            | IssueMarkerTarget::DestinationNetwork { isd_asn, .. } => dst == *isd_asn,
        }
    }
}

/// Marks a specific issue experienced on a path
///
/// Issue markers serve as a hard indicator of health and mostly immediately downgrade path
/// usability
#[derive(Debug, Clone)]
pub enum IssueKind {
    /// Path received SCMP error
    Scmp { error: ScmpErrorMessage },
    /// ICMP error
    // Placeholder variant; ICMP issues are recognized but not yet produced. TODO: details.
    #[allow(dead_code)]
    Icmp {/* icmp error details */},
    /// Socket error
    Socket { err: SendError },
}
impl Display for IssueKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            IssueKind::Scmp { error } => write!(f, "SCMP Error: {error:?}"),
            IssueKind::Icmp { .. } => write!(f, "ICMP Error"),
            IssueKind::Socket { err } => write!(f, "Socket Error: {err:?}"),
        }
    }
}
impl IssueKind {
    /// Returns a hash for deduplication of issues.
    pub fn dedup_id(&self, marker: &IssueMarkerTarget) -> u64 {
        let mut hasher = DefaultHasher::new();

        // Deduplicate based on target
        marker.hash(&mut hasher);
        // And issue kind
        // TODO: Took shortcut here, need to properly implement
        let error_str = format!("{self}");
        error_str.hash(&mut hasher);

        hasher.finish()
    }

    /// Returns the target type the issue applies to, if any.
    pub fn target_type(&self) -> Option<IssueMarkerTarget> {
        match self {
            IssueKind::Scmp { error } => {
                match error {
                    ScmpErrorMessage::DestinationUnreachable(scmp_destination_unreachable) => {
                        // XXX(ake): Destination Unreachable depend on the destination host,
                        // thus they can't be applied globally
                        use sciparse::payload::scmp::types::ScmpDestinationUnreachableCode::{
                            AddressUnreachable, BeyondScopeOfSourceAddress,
                            CommunicationAdministrativelyDenied, NoRouteToDestination,
                            PortUnreachable, RejectRouteToDestination,
                            SourceAddressFailedIngressEgressPolicy, Unassigned,
                        };
                        match scmp_destination_unreachable.code {
                            NoRouteToDestination
                            | AddressUnreachable
                            | BeyondScopeOfSourceAddress
                            | CommunicationAdministrativelyDenied
                            | SourceAddressFailedIngressEgressPolicy
                            | RejectRouteToDestination => {
                                let offending = scmp_destination_unreachable.get_offending_packet();
                                let (pkt, _rest) =
                                    ScionRawPacketView::try_from_slice(offending).ok()?;
                                let dst = pkt.header().path().last_ingress_interface()?;
                                let dst_host =
                                    pkt.header().dst_host_addr().ok()?.scion_host_addr().ok()?;

                                Some(IssueMarkerTarget::DestinationNetwork {
                                    isd_asn: pkt.header().dst_ia(),
                                    ingress_interface: dst,
                                    dst_host,
                                })
                            }
                            // Filter out unspecific
                            Unassigned(_) | PortUnreachable => None,
                        }
                    }
                    ScmpErrorMessage::ExternalInterfaceDown(msg) => {
                        Some(IssueMarkerTarget::Interface {
                            isd_asn: msg.isd_asn,
                            ingress_filter: None,
                            egress_filter: msg.interface_id,
                        })
                    }
                    ScmpErrorMessage::InternalConnectivityDown(msg) => {
                        Some(IssueMarkerTarget::Interface {
                            isd_asn: msg.isd_asn,
                            ingress_filter: Some(msg.ingress_interface_id),
                            egress_filter: msg.egress_interface_id,
                        })
                    }
                    ScmpErrorMessage::PacketTooBig(_) => None,
                    ScmpErrorMessage::ParameterProblem(_) => None,
                }
            }
            IssueKind::Icmp { .. } => None,
            IssueKind::Socket { err } => {
                match err {
                    SendError::FirstHopUnreachable {
                        isd_asn,
                        interface_id,
                        ..
                    } => {
                        Some(IssueMarkerTarget::FirstHop {
                            isd_asn: *isd_asn,
                            egress_interface: *interface_id,
                        })
                    }
                }
            }
        }
    }

    /// Calculates the penalty based on the severity of the issue.
    /// Returns a negative score (penalty).
    pub(crate) fn penalty(&self) -> Score {
        let magnitude = match self {
            IssueKind::Scmp { error } => {
                match error {
                    // LINK FAILURES (Max penalty)
                    // Interface down means the link is physically/logically broken.
                    // With 30s half-life, it takes ~3 mins to recover to > -0.01
                    ScmpErrorMessage::ExternalInterfaceDown(_)
                    | ScmpErrorMessage::InternalConnectivityDown(_) => -1.0,

                    // ROUTING ISSUES (High)
                    // Dst AS can't route the packet internally
                    ScmpErrorMessage::DestinationUnreachable(err) => {
                        // XXX(ake): Destination Errors are not handled in the Path Manager
                        match err.code {
                            // Can't forward packet to dst ip
                            ScmpDestinationUnreachableCode::NoRouteToDestination
                            | ScmpDestinationUnreachableCode::AddressUnreachable => -0.8,
                            // Admin denied might be policy, treated as severe
                            ScmpDestinationUnreachableCode::CommunicationAdministrativelyDenied => {
                                -0.9
                            }

                            // Unreachable Port is beyond routing
                            ScmpDestinationUnreachableCode::PortUnreachable => 0.0,
                            _ => -0.5,
                        }
                    }
                    // Irrelevant
                    ScmpErrorMessage::PacketTooBig(_) | ScmpErrorMessage::ParameterProblem(_) => {
                        0.0
                    }
                }
            }

            // SOCKET / TRANSIENT (Medium)
            // Often temporary congestion or local buffer issues.
            // Penalty: -0.4.
            // Recovers quickly (within ~45 seconds).
            IssueKind::Socket { err } => {
                match err {
                    SendError::FirstHopUnreachable { .. } => -0.4,
                }
            }

            // Unhandled as of now
            IssueKind::Icmp { .. } => 0.0,
        };

        Score::new_clamped(magnitude)
    }
}

/// Classification of a `ScionSocketSendError` send error that includes the necessary
/// information for the path manager to handle the error.
/// This type is necessary because `ScionSocketSendError` is not Clone.
#[derive(Debug, Clone)]
pub enum SendError {
    FirstHopUnreachable {
        isd_asn: IsdAsn,
        interface_id: u16,
        // Carried for diagnostics/future use; not read while classifying the issue.
        #[allow(dead_code)]
        address: Option<net::SocketAddr>,
        #[allow(dead_code)]
        msg: Cow<'static, str>,
    },
}

impl SendError {
    pub fn from_socket_send_error(error: &ScionSocketSendError) -> Option<Self> {
        match error {
            ScionSocketSendError::UnderlayNextHopUnreachable {
                isd_as,
                interface_id,
                address,
                msg,
            } => {
                Some(Self::FirstHopUnreachable {
                    isd_asn: *isd_as,
                    interface_id: *interface_id,
                    address: *address,
                    msg: msg.clone().into(),
                })
            }
            _ => None,
        }
    }
}