fastrag.serve.geolocalization

Optional GeoIP country resolution for the serving app.

Grouped by feature: resolver holds CountryResolver (the lookup itself) and dependencies the FastAPI dependency that hands the app-owned instance to a route or another dependency.

class fastrag.serve.geolocalization.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

fastrag.serve.geolocalization.get_country_resolver(request)

Return the CountryResolver built once by create_app.

A dependency rather than a direct app.state read, so tests can swap it via app.dependency_overrides[get_country_resolver].

Parameters:

request (Request)

Return type:

CountryResolver

Modules

dependencies	FastAPI dependency exposing the app's CountryResolver.
resolver	IP → country resolution against an operator-supplied GeoLite2 database.