Crate monocle 

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 simplified feature system with three options:

Feature	Description	Implies
lib	Complete library (database + all lenses + display)	-
server	WebSocket server for programmatic API access	lib
cli	Full CLI binary with all functionality	lib, server

Choosing Features

# Library-only - all lenses and database operations
monocle = { version = "1.0", default-features = false, features = ["lib"] }

# Library + WebSocket server
monocle = { version = "1.0", default-features = false, features = ["server"] }

# Default (full CLI binary)
monocle = "1.0"

Architecture

The library is organized into the following modules:

• database: Database functionality (requires lib feature)

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

• lens: High-level business logic (requires lib feature)

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

• server: WebSocket API server (requires server feature)

• config: Configuration management (always available)

Quick Start Examples

Database Operations (feature = “lib”)

use monocle::database::MonocleDatabase;

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

// Check if AS2Rel data needs update
use std::time::Duration;
let ttl = Duration::from_secs(24 * 60 * 60); // 24 hours
if db.needs_as2rel_refresh(ttl) {
    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 = “lib”)

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 = “lib”)

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 = “lib”)

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

let lens = ParseLens::new();
let filters = ParseFilters {
    origin_asn: vec!["13335".to_string()],
    ..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 = “lib”)

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::get_data_source_info;

pub use config::get_sqlite_info;

pub use config::format_size;

pub use config::get_cache_settings;

pub use config::CacheSettings;

pub use config::DataSource;

pub use config::DataSourceInfo;

pub use config::DataSourceStatus;

pub use config::SqliteDatabaseInfo;

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;

pub use database::*;

Modules

config

database

Database module

lens

Lens module

server

WebSocket server module for Monocle