Struct MmdbFileReader 

pub struct MmdbFileReader { /* private fields */ }

Available on crate feature net only.

A MaxMind DB reader that reads the file through positional reads.

Nothing is mapped and nothing beyond the metadata, the jump table and the optional BlockCache is held in memory, so modifying the file is never undefined behaviour, unlike for a memory map. Lookups return owned GeoLocations.

Reload

A reader opened on a path follows the file that path names:

• At most once per check interval a lookup stats the path (following symlinks). If the file identity (see FileIdentity) differs from the loaded one, the file is reopened.
• A read that comes up short within the size seen at open, or a stale handle, also triggers a reopen.

One lookup reopens, others keep using the loaded version and never wait. A new file is validated before it replaces the loaded version; if it fails the loaded version stays, a warning is logged once for that file, and it is retried only when the path names a different file or after a back-off (1 s, doubling, capped at the check interval). Each version owns its own handles, jump table and cache, and stays alive while any lookup that loaded it is running. Usually two versions overlap briefly during a swap; lookups that run across several swaps keep each version they loaded, so more than two can be alive at once.

Update the file by renaming a complete new file over it, as geoipupdate and Kubernetes volume updates do. Rewriting the file in place is not supported: until the change is noticed lookups may return None or wrong values, though never undefined behaviour. Changes are noticed only after the check interval plus any attribute caching of the filesystem (up to 60 s on NFS). A process that does no lookups does not check, so it keeps the replaced file (and its disk blocks) open until it does.

On Windows the rename must be one that may replace an open file: MoveFileExW with MOVEFILE_REPLACE_EXISTING, which many runtimes use for their rename or move, fails with ERROR_ACCESS_DENIED while this reader holds the file open. std::fs::rename falls back to a POSIX semantics rename (NTFS, Windows 10 1809 and later), which works. With other tools, first rename the old file away, then the new one into place. See FileIdentity for which replacements are visible.

Blocking

Lookups read the file with blocking positional reads; see the blocking section of ReadAt for why that is accepted on async workers.

Implementations

impl MmdbFileReader

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

Open the database at path with the default MmdbFileConfig.

Errors

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

pub fn open_with_config( path: impl AsRef<Path>, config: MmdbFileConfig, ) -> Result<MmdbFileReader, GeoIpError>

Open the database at path with config.

Errors

Same as Self::open.

pub fn from_read_at( src: impl ReadAt + Send + Sync + 'static, config: MmdbFileConfig, ) -> Result<MmdbFileReader, GeoIpError>

Read the database from any ReadAt source, such as an in-memory buffer. The source is never reloaded.

Errors

Returns GeoIpError if the source cannot be read or is not a valid database.

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

Set the preferred language code used to resolve localised names (default "en"), falling back to English.

pub fn path(&self) -> Option<&Path>

The path this reader follows, if it was opened from one.

pub fn metadata(&self) -> Metadata

The Metadata of the currently loaded version.

pub fn lookup(&self, ip: IpAddr) -> Option<GeoLocation>

Look up ip, returning its record if present.

IPv4-mapped IPv6 inputs are canonicalised to IPv4 first. This is best-effort: corruption, I/O errors and a file that changed under the reader all yield None. Use Self::try_lookup to observe them.

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

Like Self::lookup, but reports errors.

Errors

Returns GeoIpError::Corrupt if the database is structurally invalid for ip, GeoIpError::SourceChanged if the file changed and no newer version could be loaded by this call, or GeoIpError::Io for another read error.

Trait Implementations

impl Clone for MmdbFileReader

fn clone(&self) -> MmdbFileReader

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MmdbFileReader

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

Formats the value using the given formatter.

impl From<MmdbFileReader> for GeoReader

fn from(reader: MmdbFileReader) -> GeoReader

Converts to this type from the input type.