Crate libmaxminddb_rs

Expand description

Read and write MaxMind DB (MMDB) v2 files in Rust.

The crate implements the binary format independently. Reader opens an owned file, a borrowed byte slice, or an explicitly unsafe memory mapping; Writer builds MMDB files from IP networks and values. Search-tree traversal, data decoding, metadata, and serialization live in separate modules. The public entry points are re-exported at the crate root.

Add libmaxminddb-rs = "0.1" to the [dependencies] section of Cargo.toml. See the repository README for benchmark methodology and complete examples.

§Read a record

use libmaxminddb_rs::{Error, MetadataBuilder, Reader, Value, Writer};
use std::net::IpAddr;
use std::collections::BTreeMap;

let metadata = MetadataBuilder::new().ip_version(4).build()?;
let mut writer = Writer::with_metadata(metadata);
writer.insert_value("198.51.100.0/24".parse()?,
    Value::Map(BTreeMap::from([("asn".into(), Value::Uint32(64512))])))?;
let bytes = writer.finish()?;
let reader = Reader::from_bytes(&bytes)?;
let ip: IpAddr = "198.51.100.7".parse()?;
let value = reader.lookup_value(ip)?;
assert_eq!(value.get("asn").is_some(), true);
assert!(matches!(reader.lookup_value("203.0.113.7".parse()?), Err(Error::NotFound)));

Reader::lookup_borrowed decodes directly into #[derive(MmdbDecode)] types. &str and &[u8] fields borrow the underlying MMDB bytes; maps and arrays materialized as ValueRef allocate their container vectors. lookup_borrowed_map can project a large record into a small result. A miss returns Error::NotFound from result-based methods, while Reader::lookup_borrowed_opt returns None for both misses and decode failures.

§Cargo features

reader: search and decode MMDB files, including mmap support.
writer: serialize networks and values, with configurable merge behavior.
derive: derive MmdbDecode, MmdbEncode, and MmdbRecord.
simd: enable architecture-specific ASCII scanning where available.

The reader always builds its cache-aligned fast tree and accelerator tables during open for every valid record size. This adds to open time and memory use, while keeping index construction out of the lookup path.

All four features are enabled by default. A reader-only build can use default-features = false, features = ["reader"]. Memory-mapped files must not be changed or truncated while borrowed by a reader; opening one therefore requires an explicit unsafe call.

Re-exports§

pub use reader::Reader;
pub use writer::MergeStrategy;
pub use writer::Writer;

Modules§

reader: MaxMind DB reader implementation.
writer: MaxMind DB writer.

Structs§

Metadata: Public MMDB metadata.
MetadataBuilder: Builder for writer metadata.

Enums§

Error: Error returned by MMDB parsing, lookup, encoding and writing operations.
Value: Owned representation used by the writer and deep-merge engine.
ValueRef: Borrowed representation of a decoded MMDB value.

Traits§

DecodeField: Internal/public field decoder used by generated implementations.
EncodeField: Internal/public field encoder used by generated implementations.
MmdbDecode: Trait implemented by #[derive(MmdbDecode)].
MmdbEncode: Trait implemented by #[derive(MmdbEncode)].
MmdbRecord: Trait for a custom record that carries its own network/CIDR.

Type Aliases§

IpNetwork: Network type accepted by the writer.
Result: Crate-local result alias.

Derive Macros§

MmdbDecode: Derives borrowed MMDB map decoding for a struct.
MmdbEncode: Derives encoding of struct fields to an owned MMDB value.
MmdbRecord: Derives the network key for one-object writer insertion.