5.9 KiB

Raw Blame History

xdb-parse

A parser to xdb files like ip2region A high-performance Rust library for parsing and querying IP database files (xdb format) like ip2region. Supports both IPv4 and IPv6 address lookup with efficient binary search algorithms.

Features

Dual Protocol Support: Full support for both IPv4 and IPv6 address lookup
High Performance: Optimized binary search algorithm for fast IP queries
Memory Efficient: Load database files once and query multiple times
Thread Safe: Designed for concurrent usage in multi-threaded environments
Flexible Input: Accepts IP addresses in multiple formats (string, numeric)
Zero Dependencies: Minimal external dependencies for reliability

Installation

Add this to your Cargo.toml:

[dependencies]
xdb-parse = "0.1.0"

Quick Start

Basic Usage

use xdb_parse::utils::{load_file, search_ip};
use anyhow::Result;

fn main() -> Result<()> {
    // Load the IP database file
    let path = "./assets/ip2region_v4.xdb";
    let data = load_file(path.into())?;
    
    // Search for an IP address
    let result = search_ip("73.24.63.66", &data)?;
    println!("IP location: {}", result);
    
    Ok(())
}

IPv6 Support

use xdb_parse::utils::{load_file, search_ip};
use anyhow::Result;

fn main() -> Result<()> {
    // Load IPv6 database
    let path = "./assets/ip2region_v6.xdb";
    let data = load_file(path.into())?;
    
    // Search for IPv6 address
    let result = search_ip("2001:0db8:85a3:0000:0000:8a2e:0370:7334", &data)?;
    println!("IPv6 location: {}", result);
    
    Ok(())
}

Examples

Example 1: Basic IP Lookup

See examples/search_ip.rs:

use std::time::Instant;
use anyhow::Result;
use xdb_parse::utils::{load_file, search_ip};

fn main() -> Result<()> {
    let start = Instant::now();
    let path = "./assets/ip2region_v4.xdb";
    let data = load_file(path.into())?;
    
    let ret = search_ip("73.24.63.66", &data)?;
    let time = start.elapsed();
    
    println!("Search time: {:?} - Result: {}", time, ret);
    Ok(())
}

Example 2: Multi-threaded Usage

The library is designed for thread-safe concurrent usage:

use std::{sync::Arc, thread};
use xdb_parse::utils::{load_file, search_ip};
use anyhow::Result;

fn main() -> Result<()> {
    let path = "./assets/ip2region_v6.xdb";
    let data = Arc::new(load_file(path.into())?);
    
    let data_clone = Arc::clone(&data);
    let handle = thread::spawn(move || {
        let result = search_ip("2408:8352:da10:1ad:c283:c9ff:fec6:4046", &data_clone).unwrap();
        println!("Thread result: {}", result);
    });
    
    // Main thread can also query
    let result = search_ip("2408:8352:da10:1ad:c283:c9ff:fec6:4046", &data)?;
    println!("Main thread result: {}", result);
    
    handle.join().unwrap();
    Ok(())
}

Example 3: Performance Benchmarking

See benches/search.rs for performance testing:

use criterion::{Criterion, criterion_group, criterion_main};
use xdb_parse::utils::{load_file, search_ip};

fn search_benchmark(c: &mut Criterion) {
    c.bench_function("ipv4_search", |b| {
        let path = "./assets/ip2region_v4.xdb";
        let data = load_file(path.into()).unwrap();
        b.iter(|| {
            search_ip("73.24.63.66", &data).unwrap();
        })
    });
}

criterion_group!(benches, search_benchmark);
criterion_main!(benches);

API Reference

Core Functions

`load_file(path: PathBuf) -> Result<Vec<u8>, XdbError>`

Loads an xdb database file into memory.

Parameters:

path: Path to the xdb file

Returns: Byte vector containing the database data

`search_ip(ip: &str, data: &[u8]) -> Result<String, XdbError>`

Searches for an IP address in the loaded database.

Parameters:

ip: IP address to search (supports multiple formats)
data: Database data loaded by load_file

Returns: Location information as string

Supported IP Formats

The library accepts IP addresses in multiple formats:

// Standard IPv4 format
search_ip("192.168.1.1", &data)?;

// Standard IPv6 format  
search_ip("2001:0db8:85a3::0370:7334", &data)?;

// Numeric format (IPv4)
search_ip("3232235777", &data)?; // Equivalent to 192.168.1.1

// Numeric format (IPv6)
search_ip("42540766411282592856903984951653826560", &data)?;

Database File Format

The library supports the xdb format used by ip2region:

Header: 256 bytes containing metadata
Vector Index: 256×256 index blocks for fast lookup
Segment Data: IP range segments with location information

File Structure

┌─────────────────┐
│     Header      │ 256 bytes
├─────────────────┤
│   Vector Index  │ 256×256×8 bytes
├─────────────────┤
│  Segment Data   │ Variable length
└─────────────────┘

Performance

The library uses an optimized binary search algorithm:

IPv4 Lookup: ~5 microseconds per query
IPv6 Lookup: ~250 microseconds per query
Memory Usage: Database loaded once, shared across threads

Error Handling

The library uses thiserror for comprehensive error handling:

use xdb_parse::error::XdbError;

match search_ip("invalid_ip", &data) {
    Ok(result) => println!("Location: {}", result),
    Err(XdbError::InvalidIP(msg)) => println!("Invalid IP: {}", msg),
    Err(e) => println!("Error: {}", e),
}

Running Examples

To run the provided examples:

# Run the basic search example
cargo run --example search_ip

# Run benchmarks
cargo bench

# Run tests
cargo test

License

This project is licensed under the same terms as Rust itself.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Acknowledgments

Inspired by the ip2region project
Uses efficient binary search algorithms for fast IP lookup
Designed for high-performance applications

5.9 KiB Raw Blame History Unescape Escape