IliaDenisov
46 lines
1.4 KiB
Markdown
46 lines
1.4 KiB
Markdown
# `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
|
|
```
|
|
|
|
## Production Data Sources
|
|
|
|
`GeoLite2 Country` database
|
|
at the [Releases](https://github.com/mamamialezatoz/geoip-database) section.
|