`galaxy/geoip`

galaxy/geoip is a small in-process library that resolves a country from an IP address by reading a local MaxMind .mmdb database.

The package is intended for trusted internal services such as Edge Gateway and Geo Profile Service. It is not a standalone network service.

Requirements

A local country-capable MaxMind database in .mmdb format.
GeoLite2 Country is the expected default database for product deployments.
One long-lived Resolver instance should be reused across goroutines and closed during process shutdown.

See example directory.

ErrInvalidAddress: the caller supplied an invalid IP string or netip.Addr.
ErrCountryNotFound: the IP is valid, but the database has no country record for it. This is the expected fail-open branch for private, local, or otherwise unmapped addresses.
ErrClosed: the resolver has already been closed.

Returned country codes are normalized to uppercase ISO 3166-1 alpha-2 because that is the country format exposed by MaxMind Country databases.

Tests use the MaxMind reference fixtures via a git submodule under pkg/geoip/test-data.

Initialize submodules before running package tests:

git submodule update --init --recursive

GeoLite2 Country database at the Releases section.