fastrag.serve.geolocalization.resolver

IP → country resolution against an operator-supplied GeoLite2 database.

Country resolution is an optional concern layered on top of client IP resolution (fastrag.serve._net.resolve_client_ip): it needs nothing from the request except that IP, reads an operator-supplied MaxMind GeoLite2 database, and degrades to None whenever anything about that is unavailable — no database configured, one that can’t be opened, the geoip2 extra not installed, or an address that was never going to be found in it (private/loopback).

Classes

CountryResolver(database_path)

Resolves an IP to an ISO-3166 alpha-2 country code, or None.

class fastrag.serve.geolocalization.resolver.CountryResolver(database_path)

Bases: object

Resolves an IP to an ISO-3166 alpha-2 country code, or None.

Built once per app (see app.py) from ServeConfig.geoip_database_path and closed by the app’s lifespan on shutdown. Every failure mode — no path configured, the geoip2 extra not installed, the database file missing or unreadable, the address not present in it, or a private/loopback address that was never going to be — degrades silently to None rather than failing the request. Only the “a path was given but couldn’t be opened” case is worth an operator’s attention, and it is logged at most once per resolver, not once per request.

Parameters:

database_path (Path | str | None)

lookup(ip_address)

Return an ISO-3166 alpha-2 country code for ip_address, or None.

Parameters:

ip_address (str | None)

Return type:

str | None

close()

Release the database reader. Idempotent; later lookups return None.

Return type:

None