# `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](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:

```bash
git submodule update --init --recursive
```