Crate monocle

Crate monocle 

Source
Expand description

Monocle - A BGP information toolkit

Monocle provides tools for searching, parsing, and processing BGP information from public sources. It can be used as both a command-line application and a library.

§Feature Flags

Monocle uses a layered feature system to minimize dependencies based on your needs:

FeatureDescriptionKey Dependencies
databaseSQLite database operations onlyrusqlite
lens-coreStandalone lenses (TimeLens, OutputFormat)chrono-humanize, dateparser
lens-bgpkitBGP-related lenses (Parse, Search, RPKI, Country)bgpkit-*, rayon
lens-fullAll lenses including InspectLensAll above
displayTable formatting with tabledtabled
cliFull CLI binary with server supportAll above + clap, axum

§Choosing Features

# Minimal - just database operations
monocle = { version = "1.0", default-features = false, features = ["database"] }

# Standalone utilities (time parsing, output formatting)
monocle = { version = "1.0", default-features = false, features = ["lens-core"] }

# BGP operations without CLI overhead
monocle = { version = "1.0", default-features = false, features = ["lens-bgpkit"] }

# Full lens functionality with display support
monocle = { version = "1.0", default-features = false, features = ["lens-full", "display"] }

# Default (CLI binary)
monocle = "1.0"

§Architecture

The library is organized into the following modules:

  • database: All database functionality (always available)

    • core: SQLite connection management and schema definitions
    • session: One-time storage (e.g., search results)
    • monocle: Main monocle database (ASInfo, AS2Rel) and file caches

  • lens: High-level business logic (feature-gated)

    • time: Time parsing and formatting (requires lens-core)
    • country: Country code/name lookup (requires lens-bgpkit)
    • ip: IP information lookup (requires lens-bgpkit)
    • parse: MRT file parsing (requires lens-bgpkit)
    • search: BGP message search (requires lens-bgpkit)
    • rpki: RPKI validation and data (requires lens-bgpkit)
    • pfx2as: Prefix-to-ASN mapping (requires lens-bgpkit)
    • as2rel: AS-level relationships (requires lens-bgpkit)
    • inspect: Unified AS/prefix lookup (requires lens-full)

  • config: Configuration management

§Quick Start Examples

§Database Operations (feature = “database”)

ⓘ
use monocle::database::MonocleDatabase;

// Open or create database
let db = MonocleDatabase::open_in_dir("~/.monocle")?;

// Check if AS2Rel data needs update
if db.needs_as2rel_update() {
    let count = db.update_as2rel()?;
    println!("Loaded {} relationships", count);
}

// Query relationships
let rels = db.as2rel().search_asn(13335)?;
for rel in rels {
    println!("AS{} <-> AS{}", rel.asn1, rel.asn2);
}

§Time Parsing (feature = “lens-core”)

ⓘ
use monocle::lens::time::{TimeLens, TimeParseArgs};

let lens = TimeLens::new();
let args = TimeParseArgs::new(vec![
    "1697043600".to_string(),          // Unix timestamp
    "2023-10-11T00:00:00Z".to_string(), // RFC3339
]);

let results = lens.parse(&args)?;
for t in &results {
    println!("{} -> {}", t.unix, t.rfc3339);
}

§RPKI Validation (feature = “lens-bgpkit”)

ⓘ
use monocle::database::MonocleDatabase;
use monocle::lens::rpki::RpkiLens;

let db = MonocleDatabase::open_in_dir("~/.monocle")?;
let lens = RpkiLens::new(&db);

// Ensure cache is populated
if lens.needs_refresh()? {
    lens.refresh()?;
}

// Validate a prefix-ASN pair
let result = lens.validate("1.1.1.0/24", 13335)?;
println!("{}: {}", result.state, result.reason);

§MRT Parsing with Progress (feature = “lens-bgpkit”)

ⓘ
use monocle::lens::parse::{ParseLens, ParseFilters, ParseProgress};
use std::sync::Arc;

let lens = ParseLens::new();
let filters = ParseFilters {
    origin_asn: Some(13335),
    ..Default::default()
};

let callback = Arc::new(|progress: ParseProgress| {
    if let ParseProgress::Completed { total_messages, .. } = progress {
        println!("Parsed {} messages", total_messages);
    }
});

let elems = lens.parse_with_progress(&filters, "path/to/file.mrt", Some(callback))?;

§Unified Inspection (feature = “lens-full”)

ⓘ
use monocle::database::MonocleDatabase;
use monocle::lens::inspect::{InspectLens, InspectQueryOptions};

let db = MonocleDatabase::open_in_dir("~/.monocle")?;
let lens = InspectLens::new(&db);

// Auto-refresh data if needed
lens.ensure_data_available()?;

// Query by ASN, prefix, or name (auto-detected)
let options = InspectQueryOptions::default();
let results = lens.query(&["13335".to_string()], &options)?;

// Get JSON output
let json = lens.format_json(&results, true);
println!("{}", json);

Re-exports§

pub use config::MonocleConfig;
pub use config::format_size;
pub use config::get_cache_settings;
pub use config::get_data_source_info;
pub use config::get_sqlite_info;
pub use config::CacheSettings;
pub use config::DataSource;
pub use config::DataSourceInfo;
pub use config::DataSourceStatus;
pub use config::SqliteDatabaseInfo;
pub use database::MonocleDatabase;
pub use database::DatabaseConn;
pub use database::SchemaDefinitions;
pub use database::SchemaManager;
pub use database::SchemaStatus;
pub use database::SCHEMA_VERSION;
pub use database::AggregatedRelationship;
pub use database::As2relEntry;
pub use database::As2relMeta;
pub use database::As2relRecord;
pub use database::As2relRepository;
pub use database::AsConnectivitySummary;
pub use database::ConnectivityEntry;
pub use database::ConnectivityGroup;
pub use database::BGPKIT_AS2REL_URL;
pub use database::AsinfoAs2orgRecord;
pub use database::AsinfoCoreRecord;
pub use database::AsinfoFullRecord;
pub use database::AsinfoHegemonyRecord;
pub use database::AsinfoMetadata;
pub use database::AsinfoPeeringdbRecord;
pub use database::AsinfoPopulationRecord;
pub use database::AsinfoRepository;
pub use database::AsinfoSchemaDefinitions;
pub use database::AsinfoStoreCounts;
pub use database::JsonlRecord;
pub use database::ASINFO_DATA_URL;
pub use database::DEFAULT_ASINFO_TTL;
pub use database::RpkiAspaRecord;
pub use database::RpkiCacheMetadata;
pub use database::RpkiRepository;
pub use database::RpkiRoaRecord;
pub use database::RpkiValidationResult;
pub use database::RpkiValidationState;
pub use database::DEFAULT_RPKI_CACHE_TTL;
pub use database::Pfx2asCacheDbMetadata;
pub use database::Pfx2asDbRecord;
pub use database::Pfx2asQueryResult;
pub use database::Pfx2asRepository;
pub use database::Pfx2asSchemaDefinitions;
pub use database::ValidationStats;
pub use database::DEFAULT_PFX2AS_CACHE_TTL;
pub use database::MsgStore;
pub use lens::utils::OutputFormat;
pub use server::create_router;
pub use server::start_server;
pub use server::Dispatcher;
pub use server::OperationRegistry;
pub use server::Router;
pub use server::ServerConfig;
pub use server::ServerState;
pub use server::WsContext;
pub use server::WsError;
pub use server::WsMethod;
pub use server::WsRequest;
pub use server::WsResult;
pub use server::WsSink;

Modules§

config
database
Database module
lens
Lens module
server
WebSocket server module for Monocle