Struct MmdbReader 

pub struct MmdbReader { /* private fields */ }

Available on crate feature net only.

A zero-copy reader over a MaxMind DB.

The database buffer is shared, so cloning a reader is cheap and a single database can be queried concurrently from many tasks without locks. The bytes are either held in memory (Self::from_bytes / Self::open) or, with the mmap feature, memory-mapped from disk via open_mmap.

Implementations

impl MmdbReader

pub fn from_bytes(bytes: impl Into<Bytes>) -> Result<MmdbReader, GeoIpError>

Build a reader from raw database bytes already held in memory.

Errors

Returns GeoIpError if the bytes are not a valid MaxMind DB or use an unsupported record size / format version.

pub fn open(path: impl AsRef<Path>) -> Result<MmdbReader, GeoIpError>

Available on crate feature std only.

Read a MaxMind DB from disk into memory.

The whole file is read into a shared buffer. With the mmap feature, the unsafe open_mmap maps the file instead for a smaller resident set on very large databases.

Errors

Returns GeoIpError::Io if the file cannot be read, or another GeoIpError if it is not a valid database.

pub unsafe fn open_mmap( path: impl AsRef<Path>, ) -> Result<MmdbReader, GeoIpError>

Available on crate features mmap and std only.

Memory-map a MaxMind DB from disk instead of reading it into memory.

Lookups fault in only the pages they touch, so a large database costs little resident memory. The mapping is held until the returned reader and every clone of it have been dropped.

Safety

The caller must ensure that the file at path is not written to, truncated or otherwise modified, by this process or any other, from this call until the returned reader and every clone of it have been dropped. Lookups read the mapping through &[u8], so a modification is undefined behaviour (a truncation can also raise SIGBUS). Use Self::open when this cannot be guaranteed.

Errors

Returns GeoIpError::Io if the file cannot be opened or mapped, or another GeoIpError if it is not a valid database.

pub fn with_language(self, lang: impl Into<Box<str>>) -> MmdbReader

Set the preferred language code used to resolve localised names (default "en"). This is the lookup key into the database’s localised names maps (e.g. "en", "de", "pt-BR").

pub fn without_jump_table(self) -> MmdbReader

Drop the 16-bit jump table built at open.

The table maps the first 16 address bits straight to the node at that depth, which skips 16 node reads per lookup. It costs 256 KiB, or 512 KiB for an IPv6 database (one table for IPv6 and one for the IPv4 subtree), shared by all clones of the reader. Dropping it frees that memory; opening still walks the top 16 levels of the tree, since that walk also validates the records it reaches.

pub fn has_jump_table(&self) -> bool

Whether lookups use the 16-bit jump table.

pub fn metadata(&self) -> &Metadata

The parsed Metadata of this database.

pub fn lookup(&self, ip: IpAddr) -> Option<GeoLocationRef<'_>>

Look up ip, returning a zero-copy view of its record if present.

IPv4-mapped IPv6 inputs are canonicalised to IPv4 first. Looking up an IPv4 address in an IPv6 database traverses the ::/96 range.

This is best-effort: a structurally corrupt database encountered mid lookup yields None, indistinguishable from a legitimate miss. Use Self::try_lookup when you need to observe corruption.

pub fn try_lookup( &self, ip: IpAddr, ) -> Result<Option<GeoLocationRef<'_>>, GeoIpError>

Like Self::lookup, but reports database corruption encountered during traversal as a GeoIpError instead of collapsing it to None.

Errors

Returns GeoIpError::Corrupt if the search tree is structurally invalid for ip.

Trait Implementations

impl Clone for MmdbReader

fn clone(&self) -> MmdbReader

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MmdbReader

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<MmdbReader> for GeoReader

fn from(reader: MmdbReader) -> GeoReader

Converts to this type from the input type.