Repository navigation
Description
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
KvHandleonce, 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+GetItemIAM 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
- Parent Platform capabilities for server-side identity on every adapter #468 (server-side identity on every adapter). Originally under Make the Axum adapter production-ready for self-hosted deployments #391.
- Implementation PR Portable KV-backed Geo lookup #454, stacked on Add portable conditional KV records across providers #510, Add pluggable native Geo providers and protected CloudFront ingress #439 and Report geo on every adapter and bind Axum geo from the manifest #502.
- Closed MaxMind file approach: PR Add local GeoLite provider and checked-IP Geo inputs for Axum #453.
- CloudFront Axum: add protected CloudFront Geo metadata provider #432 / PR Add pluggable native Geo providers and protected CloudFront ingress #439; checked ingress Axum: add safe production diagnostics and trusted-proxy handling #397 / PR feat(axum): add safe diagnostics and trusted proxy metadata #409.
- Spin geo on the same reader: Geo with country and region through
ctx.geo()on Cloudflare #480 / PR Complete Cloudflare geo and add pinned Spin KV lookup #514.
Activity
aram356 commentedon Nov 13, 2026
CREATOR: This issue is now part of #468, server-side identity on every adapter. It is planned in an
anyrow (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.
ChristianPavilonis commentedon Nov 19, 2026
#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:
edgezero-core/src/geo/kv.rsuses onlyKvHandle, 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.examples/geo-kv-prototypebuilds 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:
KvHandleI'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
KvHandlebinding by design. The previous body is in this issue's edit history.aram356 commentedon Nov 19, 2026
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.