Skip to content

Adds geo-ip-service lookups, health and metrics - #2

Merged
jim-toth merged 1 commit into
masterfrom
geo-ip-service-lookups
Oct 15, 2026
Merged

jim-toth merged 1 commit into
masterfrom
geo-ip-service-lookups

Conversation

@jim-toth

Copy link
Copy Markdown
Contributor

Summary

Turns geo-ip-service into a working lookup service: it loads the MaxMind GeoLite2 City and ASN databases from a directory and answers batch and single address lookups, with health and Prometheus metrics. It serves the contract geo-ip-client already speaks.

Changes

  • POST /lookup answers a batch of addresses in request order, reporting found, not-found or invalid per address, so one bad address never fails the batch. GET /lookup/:address answers one address.
    • Both accept an optional h3Resolution (0 to 15) that adds the H3 cell holding the coordinates and the cell's center.
    • IPv4, IPv6 and IPv4-mapped IPv6 addresses resolve.
    • The batch limit is configurable with MAX_BATCH_SIZE and defaults to the client's batch size; larger batches get 413.
  • Location results carry coordinates, country, region, city, time zone and autonomous system, built from the shared GeoLocation type. Coordinates of zero are kept.
  • Databases load from GEOIP_DATA_DIR at startup. Each file is checked against its metadata so the wrong edition is refused.
    • Without the City edition the service reports down and lookups answer 503. Without ASN it reports degraded and keeps answering.
    • A failed load leaves an earlier copy of the edition serving.
  • /healthz reports each edition's build date, load time and last load error. /metrics exposes database load state and build time, lookups by result, requests by route and status, and batch duration in the Prometheus text format, without a metrics library.
  • MaxMind's GeoLite2 City and ASN test databases are committed under apps/geo-ip-service/test-data with their source commit and MIT license, so tests need no license key.
  • READMEs: the service README documents the API, configuration and metrics; the client README now points to it instead of repeating the protocol.

Verified

  • bun run check under Bun 1.4.3: typecheck clean, 80 tests pass. The service tests run the real server on the test databases and cover every status of both lookup routes, request validation, the batch limit, H3 cells, health with and without each edition, the metrics output, and a round trip through geo-ip-client.
  • A 10,000-address batch with H3 cells, three quarters of it found in the test databases, answered in about 240 ms on a workstation. Production records are larger, so this needs measuring again on stage hardware.
  • Built the image and ran it with the databases mounted (healthy, lookups answer) and without them (down, lookups 503); podman stop exits 0.
  • Followed the README's local run steps.

… with H3 cells, database health and Prometheus metrics
@jim-toth
jim-toth merged commit c78234c into master Oct 15, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant