Skip to content

Axum: follow up with an explicit local GeoIP provider #438

Description

@ChristianPavilonis

Description

Add optional GeoIP to the native Geo contract that doesn't depend on CloudFront (#432). The operator publishes a GeoLite City or Country dataset to a KV store they already run (celld or DynamoDB), and Axum looks up the checked client IP in it. The reader lives in portable core and uses only KvHandle, so WASM adapters can reuse it.

PR #454 implements this. The earlier MaxMind file reader (#453) is closed because it gave WASM deployments no option.

Steps to reproduce

Run Axum without the protected CloudFront provider. ctx.geo() has no country or subdivision, so nothing downstream can use geo on that deployment.

Expected behavior

  • The operator selects the KV provider explicitly. There is no fallback to another provider.
  • The lookup IP comes from the existing checked ingress provenance (Axum: add safe production diagnostics and trusted-proxy handling #397 / PR feat(axum): add safe diagnostics and trusted proxy metadata #409).
  • At startup the provider resolves the named KvHandle once, then reads and validates the pinned manifest and both nonempty roots. A bad manifest or root, an unavailable binding or a denied read blocks readiness.
  • A pinned generation never changes. Replacing data means publishing a new generation and restarting with the new pin.
  • Outcomes keep unavailable/error, no-match, country-only and unknown subdivision distinct. A missing or corrupt required object at request time is a provider failure, never a miss or a fallback.

Impact

Axum deployments that don't sit behind CloudFront get no geo today. Spin has the same gap because its requests carry no geo, and #514 builds Spin geo on this reader.

Local results don't establish hosted IAM, production capacity or deployment latency. Those need separate qualification.

Proposed fix

Land #454 after #439, #502 and #510. The operator tool in examples/geo-kv-prototype imports GeoLite CSV, publishes with read-back and manifest-last ordering, verifies the full tree through the read-only serving binding, and retires old generations by inventory.

Out of scope: MMDB support, a downloader or update scheduler, remote visitor lookup, hot reload, managed KV Geo on adapters other than Axum, and any consent or permission-policy change. Keep CSV, MMDB and backend SDK dependencies out of portable core. Dataset acquisition, GeoLite EULA compliance and freshness stay with the operator, and the guide documents those duties.

Design: docs/superpowers/specs/2026-11-05-kv-geo-design.md. Results: docs/superpowers/plans/2026-11-17-kv-geo-serving-results.md.

Done when

  • Maintainers accept these KV checks in place of the original MMDB-specific criteria (malformed-file metadata, read-only mount, Unix-only acquisition).
  • Deterministic CI with synthetic City and Country fixtures: IPv4/IPv6 boundary, neighbor, gap and sampled lookups match an independent CIDR oracle, plus country-only, subdivision and unsupported geography. Malformed imports and corrupt objects are rejected. The standalone tool runs in CI, and the portable reader's WASM dependency graph contains no importer or native SDK.
  • Managed Axum: selection precedence, Off and existing CloudFront/supplied behavior, direct and trusted forwarded input, mapped IPv4, and zero KV reads for rejected ingress or a missing reader. Bad manifest or root data, unavailable bindings and denied reads fail before readiness. Missing or corrupt descendants, deadlines, cancellation and concurrency limits are covered, and dispatch and finalization see the same outcome without a second lookup.
  • Backend runs on stock celld and DynamoDB Local: interrupted and identical publication, conflicting bytes, simultaneous pins, restart, rollback and retirement. celld denies writes under the serving grant. DynamoDB serving issues no writes, and the guide documents a minimal DescribeTable + GetItem IAM policy.
  • Licensed-size evidence on both backends with a production-size City release: 16 and 64 KiB object budgets, source-oracle agreement, startup time, RSS, cold and warm latency, and reads and bytes per request, with commands, revision and digests recorded.

Trusted Server translation and real policy-path proof remain separate downstream work. This task does not authorize changing fail-closed permission behavior.

Related

Activity

  1. added theissue type on Nov 9, 2026
  2. aram356 commented on Nov 13, 2026

    @aram356
    Collaborator

    CREATOR: This issue is now part of #468, server-side identity on every adapter. It is planned in an any row (no fixed wave; starts when its decision or reviewer is ready; after the MVP); priority P3, size M.

    Blocked by: nothing.

    Design: spec; order and dependencies: plan.

  3. ChristianPavilonis commented on Nov 19, 2026

    @ChristianPavilonis
    CollaboratorAuthor

    #453 is closed. @aram356 pointed out it gives WASM deployments no option, so the MaxMind file approach is off the table. #454 now implements this issue with a KV-backed provider instead:

    • The reader in edgezero-core/src/geo/kv.rs uses only KvHandle, with no MMDB or file dependencies, so it also works on WASM targets. Complete Cloudflare geo and add pinned Spin KV lookup #514 already builds Spin geo on it.
    • Axum gets an opt-in KV geo provider, off by default. CloudFront and supplied providers behave as before.
    • examples/geo-kv-prototype builds GeoLite City or Country CSV into immutable artifacts, publishes them to celld or DynamoDB, and verifies the full tree through the read-only serving binding.

    Several of the old "Done when" items were written for an MMDB file and don't apply as stated. Here is how #454 covers each one:

    Original criterion In #454
    Malformed or unavailable database fails startup before readiness A bad manifest or root, an unavailable binding or a denied read blocks readiness. A missing or corrupt object at request time is a provider failure.
    Read-only mount and database replacement proof The serving credential is read-only. celld enforces it; DynamoDB Local can't enforce IAM, so the test checks that serving issues no writes. A new dataset gets a new pinned generation and a restart switches to it.
    IPv4/IPv6, no-match, country-only and subdivision fixtures Covered, including IPv4-mapped IPv6
    Production-size licensed data, preparation time and RSS Measured with the 2026-11-03 GeoLite2-City CSV on celld and DynamoDB Local, with no mismatches in 4,096 oracle checks per backend and object size (results). Hosted IAM and production capacity aren't claimed.
    Malformed unused metadata regression No longer applies, since there's no MMDB
    Unix-only acquisition scope No longer applies, since there's no file access
    Portable/WASM dependency boundaries The core reader depends only on KvHandle

    I've rewritten the issue body so "Done when" matches §10 of the KV geo design. I also dropped the old "no store-registry coupling" constraint, because the KV provider resolves a named KvHandle binding by design. The previous body is in this issue's edit history.

  4. linked a pull request that will close this issuePortable KV-backed Geo lookup #454on Nov 19, 2026
  5. aram356 commented on Nov 19, 2026

    @aram356
    Collaborator

    I'm good with starting with KV. We should also support a generic, configurable API-based Geo lookup.

    The API-based approach is more involved since we'd still need to cache results in KV. If we implement KV lookup first, we can reuse that logic when adding API support.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions