feat: geoip

2026-04-09 14:16:36 +02:00
parent 94b7b6ce06
commit 84eeaf5184
11 changed files with 596 additions and 1 deletions
@@ -0,0 +1,40 @@
+# `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
+```