bgpkit_commons/

lib.rs

//! # Overview
//!
//! `bgpkit-commons` is a library for common BGP-related data and functions with a lazy-loading
//! architecture. Each module can be independently enabled via feature flags, allowing for minimal builds.
//!
//! ## Quick Start
//!
//! Add `bgpkit-commons` to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! bgpkit-commons = "0.10"
//! ```
//!
//! All modules follow the same pattern: create a [`BgpkitCommons`] instance, call a `load_xxx()`
//! method to fetch data, then use `xxx_yyy()` methods to access it.
//!
//! ```rust
//! # #[cfg(feature = "bogons")]
//! # fn main() {
//! use bgpkit_commons::BgpkitCommons;
//!
//! let mut commons = BgpkitCommons::new();
//! commons.load_bogons().unwrap();
//!
//! if let Ok(is_bogon) = commons.bogons_match("23456") {
//!     println!("ASN 23456 is a bogon: {}", is_bogon);
//! }
//! # }
//! # #[cfg(not(feature = "bogons"))]
//! # fn main() {}
//! ```
//!
//! ## Modules
//!
//! ### [`asinfo`] — Autonomous System Information
//!
//! Feature: `asinfo` | Sources: RIPE NCC, CAIDA as2org, APNIC population, IIJ IHR hegemony, PeeringDB
//!
//! - Load: `load_asinfo(as2org, population, hegemony, peeringdb)`, `load_asinfo_cached()`, `load_asinfo_with(builder)`
//! - Access: `asinfo_get(asn)`, `asinfo_all()`, `asinfo_are_siblings(asn1, asn2)`
//! - AS name resolution, country mapping, organization data, population statistics, hegemony scores
//!
//! ### [`as2rel`] — AS Relationship Data
//!
//! Feature: `as2rel` | Source: BGPKIT AS relationship inference
//!
//! - Load: `load_as2rel()`
//! - Access: `as2rel_lookup(asn1, asn2)`
//! - Provider-customer, peer-to-peer, and sibling relationships between ASes
//!
//! ### [`bogons`] — Bogon Detection
//!
//! Feature: `bogons` | Source: IANA special registries (IPv4, IPv6, ASN)
//!
//! - Load: `load_bogons()`
//! - Access: `bogons_match(input)`, `bogons_match_prefix(prefix)`, `bogons_match_asn(asn)`, `get_bogon_prefixes()`, `get_bogon_asns()`
//! - Detect invalid/reserved IP prefixes and ASNs that shouldn't appear in routing
//!
//! ### [`countries`] — Country Information
//!
//! Feature: `countries` | Source: GeoNames geographical database
//!
//! - Load: `load_countries()`
//! - Access: `country_by_code(code)`, `country_by_code3(code)`, `country_by_name(name)`, `country_all()`
//! - ISO country code to name mapping and geographical information
//!
//! ### [`mrt_collectors`] — MRT Collector Metadata
//!
//! Feature: `mrt_collectors` | Sources: RouteViews and RIPE RIS official APIs
//!
//! - Load: `load_mrt_collectors()`, `load_mrt_collector_peers()`
//! - Access: `mrt_collectors_all()`, `mrt_collectors_by_name(name)`, `mrt_collectors_by_country(country)`, `mrt_collector_peers_all()`, `mrt_collector_peers_full_feed()`
//! - BGP collector information, peer details, full-feed vs partial-feed classification
//!
//! ### [`peeringdb`] — PeeringDB Data
//!
//! Feature: `peeringdb` | Source: [PeeringDB API](https://www.peeringdb.com/api/)
//!
//! - Load: `Peeringdb::new()` (all tables), `Peeringdb::new_networks_only()` (lightweight)
//! - Access: `get_network(asn)`, `get_ixp(ix_id)`, `get_ixp_memberships(asn)`, `lookup_ixp_prefix(prefix)`, `get_facility(fac_id)`
//! - Typed structs mirroring all 12 PeeringDB API endpoints: networks, internet exchanges,
//!   IXP prefixes, IXP membership, facilities, organizations, carriers, and more
//! - `PeeringdbData` is a type alias for the full `Network` struct (backward compatible)
//!
//! ### [`rpki`] — RPKI Validation
//!
//! Feature: `rpki` | Sources: Cloudflare (real-time), RIPE NCC historical, RPKIviews historical, RPKISPOOL historical
//!
//! - Load: `load_rpki(optional_date)`, `load_rpki_historical(date, source)`, `load_rpki_from_files(urls, source, date)`
//! - Poll: `RpkiTrie::from_cloudflare_conditional(etag, last_modified)` returns `Ok(None)` on `304 Not Modified`
//! - Access: `rpki_validate(asn, prefix)`, `rpki_validate_check_expiry(asn, prefix, timestamp)`, `rpki_lookup_by_prefix(prefix)`, `rpki_lookup_aspa(customer_asn)`
//! - Route Origin Authorization (ROA) and ASPA validation, supports real-time and historical sources
//! - Poll current Cloudflare data with `RpkiTrie::from_cloudflare_conditional`, retaining the returned
//!   [`rpki::RpkiLoad`] validators and keeping the existing trie when the result is `Ok(None)`.
//! - `BgpkitCommons::reload()` performs a full reload; it does not use validators or provide an atomic
//!   poll-and-swap operation.
//!
//! ## Examples
//!
//! ### Loading multiple modules
//!
//! ```rust
//! # #[cfg(all(feature = "asinfo", feature = "countries"))]
//! # fn main() {
//! use bgpkit_commons::BgpkitCommons;
//!
//! let mut commons = BgpkitCommons::new();
//! commons.load_asinfo(false, false, false, false).unwrap();
//! commons.load_countries().unwrap();
//!
//! if let Ok(Some(asinfo)) = commons.asinfo_get(13335) {
//!     println!("AS13335: {} ({})", asinfo.name, asinfo.country);
//! }
//! # }
//! # #[cfg(not(all(feature = "asinfo", feature = "countries")))]
//! # fn main() {}
//! ```
//!
//! ### Using AsInfoBuilder
//!
//! ```rust
//! # #[cfg(feature = "asinfo")]
//! # fn main() {
//! use bgpkit_commons::BgpkitCommons;
//!
//! let mut commons = BgpkitCommons::new();
//! let builder = commons.asinfo_builder()
//!     .with_as2org()
//!     .with_peeringdb();
//! commons.load_asinfo_with(builder).unwrap();
//!
//! if let Ok(are_siblings) = commons.asinfo_are_siblings(13335, 132892) {
//!     println!("AS13335 and AS132892 are siblings: {}", are_siblings);
//! }
//! # }
//! # #[cfg(not(feature = "asinfo"))]
//! # fn main() {}
//! ```
//!
//! ### Loading historical RPKI data
//!
//! ```rust,no_run
//! # #[cfg(feature = "rpki")]
//! # fn main() {
//! use bgpkit_commons::BgpkitCommons;
//! use bgpkit_commons::rpki::{HistoricalRpkiSource, RpkiViewsCollector};
//! use chrono::NaiveDate;
//!
//! let mut commons = BgpkitCommons::new();
//! let date = NaiveDate::from_ymd_opt(2024, 1, 4).unwrap();
//!
//! // Load from RIPE NCC historical archives
//! commons.load_rpki_historical(date, HistoricalRpkiSource::Ripe).unwrap();
//!
//! // Or load from RPKIviews collectors
//! let source = HistoricalRpkiSource::RpkiViews(RpkiViewsCollector::KerfuffleNet);
//! commons.load_rpki_historical(date, source).unwrap();
//!
//! // List available files for a date
//! let files = commons.list_rpki_files(date, HistoricalRpkiSource::Ripe).unwrap();
//! # }
//! # #[cfg(not(feature = "rpki"))]
//! # fn main() {}
//! ```
//!
//! ### Direct module access
//!
//! Modules can also be used directly without `BgpkitCommons`:
//!
//! ```rust
//! # #[cfg(feature = "bogons")]
//! # fn main() {
//! use bgpkit_commons::bogons::Bogons;
//! let bogons = Bogons::new().unwrap();
//! # }
//! # #[cfg(not(feature = "bogons"))]
//! # fn main() {}
//! ```
//!
//! ## Feature Flags
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `asinfo` | AS information: names, countries, organizations, population, hegemony |
//! | `as2rel` | AS relationship data |
//! | `bogons` | Bogon prefix and ASN detection |
//! | `countries` | Country information lookup |
//! | `mrt_collectors` | MRT collector metadata |
//! | `peeringdb` | PeeringDB API data (networks, IXPs, facilities, organizations) |
//! | `rpki` | RPKI validation (ROA and ASPA) |
//! | `all` *(default)* | Enables all modules |
//!
//! For a minimal build:
//!
//! ```toml
//! [dependencies]
//! bgpkit-commons = { version = "0.10", default-features = false, features = ["bogons", "countries"] }
//! ```

#![doc(
    html_logo_url = "https://raw.githubusercontent.com/bgpkit/assets/main/logos/icon-transparent.png",
    html_favicon_url = "https://raw.githubusercontent.com/bgpkit/assets/main/logos/favicon.ico"
)]

#[cfg(feature = "as2rel")]
pub mod as2rel;
#[cfg(feature = "asinfo")]
pub mod asinfo;
#[cfg(feature = "bogons")]
pub mod bogons;
#[cfg(feature = "countries")]
pub mod countries;
#[cfg(feature = "mrt_collectors")]
pub mod mrt_collectors;
#[cfg(feature = "peeringdb")]
pub mod peeringdb;
#[cfg(feature = "rpki")]
pub mod rpki;

pub mod errors;

// Re-export error types for convenience
pub use errors::{BgpkitCommonsError, Result};

/// Trait for modules that support lazy loading and reloading of data
pub trait LazyLoadable {
    /// Reload the module's data from its external sources
    fn reload(&mut self) -> Result<()>;

    /// Check if the module's data is currently loaded
    fn is_loaded(&self) -> bool;

    /// Get a description of the module's current loading status
    fn loading_status(&self) -> &'static str;
}

#[derive(Default)]
pub struct BgpkitCommons {
    #[cfg(feature = "countries")]
    countries: Option<crate::countries::Countries>,
    #[cfg(feature = "rpki")]
    rpki_trie: Option<crate::rpki::RpkiTrie>,
    #[cfg(feature = "mrt_collectors")]
    mrt_collectors: Option<Vec<crate::mrt_collectors::MrtCollector>>,
    #[cfg(feature = "mrt_collectors")]
    mrt_collector_peers: Option<Vec<crate::mrt_collectors::MrtCollectorPeer>>,
    #[cfg(feature = "bogons")]
    bogons: Option<crate::bogons::Bogons>,
    #[cfg(feature = "asinfo")]
    asinfo: Option<crate::asinfo::AsInfoUtils>,
    #[cfg(feature = "as2rel")]
    as2rel: Option<crate::as2rel::As2relBgpkit>,
}

impl BgpkitCommons {
    pub fn new() -> Self {
        Self::default()
    }

    /// Reload all data sources that are already loaded
    pub fn reload(&mut self) -> Result<()> {
        #[cfg(feature = "countries")]
        if self.countries.is_some() {
            self.load_countries()?;
        }
        #[cfg(feature = "rpki")]
        if let Some(rpki) = self.rpki_trie.as_mut() {
            rpki.reload()?;
        }
        #[cfg(feature = "mrt_collectors")]
        if self.mrt_collectors.is_some() {
            self.load_mrt_collectors()?;
        }
        #[cfg(feature = "mrt_collectors")]
        if self.mrt_collector_peers.is_some() {
            self.load_mrt_collector_peers()?;
        }
        #[cfg(feature = "bogons")]
        if self.bogons.is_some() {
            self.load_bogons()?;
        }
        #[cfg(feature = "asinfo")]
        if let Some(asinfo) = self.asinfo.as_mut() {
            asinfo.reload()?;
        }
        #[cfg(feature = "as2rel")]
        if self.as2rel.is_some() {
            self.load_as2rel()?;
        }

        Ok(())
    }

    /// Get loading status for all available modules
    pub fn loading_status(&self) -> Vec<(&'static str, &'static str)> {
        #[allow(unused_mut)] // mut needed when any features are enabled
        let mut status = Vec::new();

        #[cfg(feature = "countries")]
        if let Some(ref countries) = self.countries {
            status.push(("countries", countries.loading_status()));
        } else {
            status.push(("countries", "Countries data not loaded"));
        }

        #[cfg(feature = "bogons")]
        if let Some(ref bogons) = self.bogons {
            status.push(("bogons", bogons.loading_status()));
        } else {
            status.push(("bogons", "Bogons data not loaded"));
        }

        #[cfg(feature = "rpki")]
        if let Some(ref rpki) = self.rpki_trie {
            status.push(("rpki", rpki.loading_status()));
        } else {
            status.push(("rpki", "RPKI data not loaded"));
        }

        #[cfg(feature = "asinfo")]
        if let Some(ref asinfo) = self.asinfo {
            status.push(("asinfo", asinfo.loading_status()));
        } else {
            status.push(("asinfo", "ASInfo data not loaded"));
        }

        #[cfg(feature = "as2rel")]
        if let Some(ref as2rel) = self.as2rel {
            status.push(("as2rel", as2rel.loading_status()));
        } else {
            status.push(("as2rel", "AS2Rel data not loaded"));
        }

        #[cfg(feature = "mrt_collectors")]
        {
            if self.mrt_collectors.is_some() {
                status.push(("mrt_collectors", "MRT collectors data loaded"));
            } else {
                status.push(("mrt_collectors", "MRT collectors data not loaded"));
            }

            if self.mrt_collector_peers.is_some() {
                status.push(("mrt_collector_peers", "MRT collector peers data loaded"));
            } else {
                status.push(("mrt_collector_peers", "MRT collector peers data not loaded"));
            }
        }

        status
    }

    /// Load countries data
    #[cfg(feature = "countries")]
    pub fn load_countries(&mut self) -> Result<()> {
        self.countries = Some(crate::countries::Countries::new()?);
        Ok(())
    }

    /// Load RPKI data from Cloudflare (real-time) or historical archives
    ///
    /// - If `date_opt` is `None`, loads real-time data from Cloudflare
    /// - If `date_opt` is `Some(date)`, loads historical data from RIPE NCC by default
    ///
    /// For more control over the data source, use `load_rpki_historical()` instead.
    #[cfg(feature = "rpki")]
    pub fn load_rpki(&mut self, date_opt: Option<chrono::NaiveDate>) -> Result<()> {
        if let Some(date) = date_opt {
            self.rpki_trie = Some(rpki::RpkiTrie::from_ripe_historical(date)?);
        } else {
            self.rpki_trie = Some(rpki::RpkiTrie::from_cloudflare()?);
        }
        Ok(())
    }

    /// Load RPKI data from a specific historical data source
    ///
    /// This allows you to choose between RIPE NCC and RPKIviews for historical data.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use bgpkit_commons::BgpkitCommons;
    /// use bgpkit_commons::rpki::{HistoricalRpkiSource, RpkiViewsCollector};
    /// use chrono::NaiveDate;
    ///
    /// let mut commons = BgpkitCommons::new();
    /// let date = NaiveDate::from_ymd_opt(2024, 1, 4).unwrap();
    ///
    /// // Load from RIPE NCC
    /// commons.load_rpki_historical(date, HistoricalRpkiSource::Ripe).unwrap();
    ///
    /// // Or load from RPKIviews
    /// let source = HistoricalRpkiSource::RpkiViews(RpkiViewsCollector::KerfuffleNet);
    /// commons.load_rpki_historical(date, source).unwrap();
    /// ```
    #[cfg(feature = "rpki")]
    pub fn load_rpki_historical(
        &mut self,
        date: chrono::NaiveDate,
        source: rpki::HistoricalRpkiSource,
    ) -> Result<()> {
        match source {
            rpki::HistoricalRpkiSource::Ripe => {
                self.rpki_trie = Some(rpki::RpkiTrie::from_ripe_historical(date)?);
            }
            rpki::HistoricalRpkiSource::RpkiViews(collector) => {
                self.rpki_trie = Some(rpki::RpkiTrie::from_rpkiviews(collector, date)?);
            }
            rpki::HistoricalRpkiSource::RpkiSpools(collector) => {
                self.rpki_trie = Some(rpki::RpkiTrie::from_rpkispools(collector, date)?);
            }
        }
        Ok(())
    }

    /// Load RPKI data from specific file URLs
    ///
    /// This allows loading from specific archive files, which is useful when you want
    /// to process multiple files or use specific timestamps.
    ///
    /// # Arguments
    ///
    /// * `urls` - A slice of URLs pointing to RPKI data files
    /// * `source` - The type of data source (RIPE, RPKIviews, or RPKISPOOL) - determines how files are parsed
    /// * `date` - Optional date to associate with the loaded data
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use bgpkit_commons::BgpkitCommons;
    /// use bgpkit_commons::rpki::HistoricalRpkiSource;
    ///
    /// let mut commons = BgpkitCommons::new();
    /// let urls = vec![
    ///     "https://example.com/rpki-20240104T144128Z.tgz".to_string(),
    /// ];
    /// commons.load_rpki_from_files(&urls, HistoricalRpkiSource::RpkiViews(
    ///     bgpkit_commons::rpki::RpkiViewsCollector::KerfuffleNet
    /// ), None).unwrap();
    /// ```
    #[cfg(feature = "rpki")]
    pub fn load_rpki_from_files(
        &mut self,
        urls: &[String],
        source: rpki::HistoricalRpkiSource,
        date: Option<chrono::NaiveDate>,
    ) -> Result<()> {
        match source {
            rpki::HistoricalRpkiSource::Ripe => {
                self.rpki_trie = Some(rpki::RpkiTrie::from_ripe_files(urls, date)?);
            }
            rpki::HistoricalRpkiSource::RpkiViews(_) => {
                self.rpki_trie = Some(rpki::RpkiTrie::from_rpkiviews_files(urls, date)?);
            }
            rpki::HistoricalRpkiSource::RpkiSpools(_) => {
                // For RPKISPOOL, each URL is a tar.zst archive; load the first one
                if let Some(url) = urls.first() {
                    self.rpki_trie = Some(rpki::RpkiTrie::from_rpkispools_url(url, date)?);
                }
            }
        }
        Ok(())
    }

    /// List available RPKI files for a given date from a specific source
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use bgpkit_commons::BgpkitCommons;
    /// use bgpkit_commons::rpki::{HistoricalRpkiSource, RpkiViewsCollector};
    /// use chrono::NaiveDate;
    ///
    /// let commons = BgpkitCommons::new();
    /// let date = NaiveDate::from_ymd_opt(2024, 1, 4).unwrap();
    ///
    /// // List files from RIPE NCC
    /// let ripe_files = commons.list_rpki_files(date, HistoricalRpkiSource::Ripe).unwrap();
    ///
    /// // List files from RPKIviews
    /// let source = HistoricalRpkiSource::RpkiViews(RpkiViewsCollector::KerfuffleNet);
    /// let rpkiviews_files = commons.list_rpki_files(date, source).unwrap();
    /// ```
    #[cfg(feature = "rpki")]
    pub fn list_rpki_files(
        &self,
        date: chrono::NaiveDate,
        source: rpki::HistoricalRpkiSource,
    ) -> Result<Vec<rpki::RpkiFile>> {
        match source {
            rpki::HistoricalRpkiSource::Ripe => rpki::list_ripe_files(date),
            rpki::HistoricalRpkiSource::RpkiViews(collector) => {
                rpki::list_rpkiviews_files(collector, date)
            }
            rpki::HistoricalRpkiSource::RpkiSpools(collector) => {
                rpki::list_rpkispools_files(collector, date)
            }
        }
    }

    /// Load MRT mrt_collectors data
    #[cfg(feature = "mrt_collectors")]
    pub fn load_mrt_collectors(&mut self) -> Result<()> {
        self.mrt_collectors = Some(crate::mrt_collectors::get_all_collectors()?);
        Ok(())
    }

    /// Load MRT mrt_collectors data
    #[cfg(feature = "mrt_collectors")]
    pub fn load_mrt_collector_peers(&mut self) -> Result<()> {
        self.mrt_collector_peers = Some(crate::mrt_collectors::get_mrt_collector_peers()?);
        Ok(())
    }

    /// Load bogons data
    #[cfg(feature = "bogons")]
    pub fn load_bogons(&mut self) -> Result<()> {
        self.bogons = Some(crate::bogons::Bogons::new()?);
        Ok(())
    }

    /// Load AS name and country data
    #[cfg(feature = "asinfo")]
    pub fn load_asinfo(
        &mut self,
        load_as2org: bool,
        load_population: bool,
        load_hegemony: bool,
        load_peeringdb: bool,
    ) -> Result<()> {
        self.asinfo = Some(crate::asinfo::AsInfoUtils::new(
            load_as2org,
            load_population,
            load_hegemony,
            load_peeringdb,
        )?);
        Ok(())
    }

    #[cfg(feature = "asinfo")]
    pub fn load_asinfo_cached(&mut self) -> Result<()> {
        self.asinfo = Some(crate::asinfo::AsInfoUtils::new_from_cached()?);
        Ok(())
    }

    /// Returns a builder for loading AS information with specific data sources.
    ///
    /// This provides a more ergonomic way to configure which data sources to load
    /// compared to the `load_asinfo()` method with boolean parameters.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use bgpkit_commons::BgpkitCommons;
    ///
    /// let mut commons = BgpkitCommons::new();
    /// let builder = commons.asinfo_builder()
    ///     .with_as2org()
    ///     .with_peeringdb();
    /// commons.load_asinfo_with(builder).unwrap();
    /// ```
    #[cfg(feature = "asinfo")]
    pub fn asinfo_builder(&self) -> crate::asinfo::AsInfoBuilder {
        crate::asinfo::AsInfoBuilder::new()
    }

    /// Load AS information using a pre-configured builder.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use bgpkit_commons::BgpkitCommons;
    ///
    /// let mut commons = BgpkitCommons::new();
    /// let builder = commons.asinfo_builder()
    ///     .with_as2org()
    ///     .with_hegemony();
    /// commons.load_asinfo_with(builder).unwrap();
    /// ```
    #[cfg(feature = "asinfo")]
    pub fn load_asinfo_with(&mut self, builder: crate::asinfo::AsInfoBuilder) -> Result<()> {
        self.asinfo = Some(builder.build()?);
        Ok(())
    }

    /// Load AS-level relationship data
    #[cfg(feature = "as2rel")]
    pub fn load_as2rel(&mut self) -> Result<()> {
        self.as2rel = Some(crate::as2rel::As2relBgpkit::new()?);
        Ok(())
    }
}