galaxy-game/pkg/geoip/README.md

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.

Usage

See example directory.

Error Semantics

• 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.

Test Data

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