Skip to content

Report geo on every adapter and bind Axum geo from the manifest - #502

Open
dhruv8sh wants to merge 3 commits into
feature/pluggable-geo-providersfrom
spec/482-axum-geo-manifest-binding
Open

dhruv8sh wants to merge 3 commits into
feature/pluggable-geo-providersfrom
spec/482-axum-geo-manifest-binding

Conversation

@dhruv8sh

@dhruv8sh dhruv8sh commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • ctx.geo() now reports country and region on Fastly (geo_lookup for the client address) and Cloudflare (the request's cf metadata), always on, so applications such as Trusted Server no longer need platform-specific geo code (EZI-4, EZI-4c).
  • Axum's CloudFront geo from Add pluggable native Geo providers and protected CloudFront ingress #439 can be selected by [adapters.axum.geo] in edgezero.toml, with every key overridable by EDGEZERO__ADAPTER__GEO__* at startup. This replaces Trusted Server's TS_NATIVE_GEO_PROFILE boot profile (EZI-4a); deploy-time values such as ALB networks stay out of the compiled manifest.
  • Stacked on Add pluggable native Geo providers and protected CloudFront ingress #439 (feature/pluggable-geo-providers) because main has no geo code yet. Spin (EZI-4s) follows separately.

Changes

Crate / File Change
edgezero-core/src/geo.rs GeoSource::{Fastly, Cloudflare}, GeoTrustBasis::PlatformMetadata, both enums #[non_exhaustive]; reserved fastly/cloudflare provider IDs; GeoOutcome::platform() treats unusable platform values (e.g. Cloudflare XX/T1) as missing metadata, not a forged assertion
edgezero-core/src/manifest.rs Optional [adapters.axum.geo] table (provider, alb_peer_cidrs, origin_credential_header_name); rejects provider = "off" with policy fields and the table on non-Axum adapters
edgezero-adapter-fastly/src/request.rs Looks up geo before the prepare hook and dispatches with dispatch_admitted_with_geo
edgezero-adapter-cloudflare/src/request.rs Reads cf.country / cf.regionCode and dispatches with dispatch_admitted_with_geo
edgezero-adapter-axum/src/geo.rs, run_options.rs, dev_server.rs Resolver with precedence with_geo → settings → manifest → off; misconfiguration fails before listening; dev run_app reads settings only; geo_capability() stays explicit-only, new geo_capability_for::<A>() reports the runner's selection; shared geo setting-name list
Tests Viceroy-backed Fastly lookup (loopback → US/CA), Cloudflare dispatch with cf metadata, Axum precedence/rejection units, end-to-end manifest + settings hosting test, dev-runner test, baked-manifest round trip; #439 contract tests updated for always-on platform geo
docs/guide/native-geo.md, configuration.md, adapters/axum.md Manifest and settings selection, precedence, validation

Closes

Part of #482 (Fastly, Cloudflare and Axum). Spin (EZI-4s) remains, so this does not close the issue.

Test plan

  • cargo test --workspace --all-targets (2921 passed)
  • cargo clippy --workspace --all-targets --all-features -- -D warnings (pinned 1.98.1)
  • cargo fmt --all -- --check
  • cargo check --workspace --all-targets --features "fastly cloudflare spin"
  • WASM builds: wasm32-wasip1 (Fastly) / wasm32-wasip2 (Spin) / wasm32-unknown-unknown (Cloudflare)
  • examples/app-demo workspace: cd examples/app-demo && cargo test --workspace --all-targets
  • Docs: Prettier on changed pages
  • Manual testing via edgezero serve --adapter axum
  • Other: Fastly lib geo test and 37 contract tests under Viceroy; Cloudflare 141 lib + 31 contract tests under wasm-bindgen; Axum production_hosting geo tests with and without geo-cloudfront; Axum doc tests

Local Viceroy 0.21.1 aborts some Fastly outbound backend tests (e.g. configured_connect_timeout_reads_registered_sdk_timeout_settings) on unmodified #439 as well; CI's patched Viceroy is the reference.

Checklist

  • Changes follow CLAUDE.md conventions
  • No Tokio deps added to core or adapter crates
  • Route params use {id} syntax (not :id)
  • Types imported from edgezero_core (not http crate)
  • Store wiring goes through KvRegistry / ConfigRegistry / SecretRegistry (not the legacy single-handle setters) — see spec §6.6
  • New code has tests
  • No secrets or credentials committed

Fastly reads geo_lookup for the client address and Cloudflare reads the
request's cf metadata. Both are always selected and pass their outcome
through dispatch_admitted_with_geo, so public extensions still cannot
replace it. Platform values that fail validation, such as Cloudflare's XX
and T1 placeholders, report missing metadata rather than an invalid
assertion. GeoSource and GeoTrustBasis gain platform variants and become
non_exhaustive; fastly and cloudflare are reserved provider IDs.
[adapters.axum.geo] carries provider, alb_peer_cidrs and
origin_credential_header_name defaults, each overridden by the matching
EDGEZERO__ADAPTER__GEO__* setting. Precedence is with_geo, then settings,
then the manifest, then off, and misconfiguration fails startup instead of
falling back. The dev run_app reads settings only. geo_capability() stays
explicit-only and geo_capability_for::<A>() reports the runner's view.

@ChristianPavilonis ChristianPavilonis left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 PR review

Reviewed commits 2c41968b and 7ef4766d at head 7ef4766db1e41517082befc81588505e289c0f31. Scope is the three-dot delta against feature/pluggable-geo-providers: pinned base c1cec8e770e350e089e646fe398583d49e685320, merge-base 645703bf39f5965dad5b54d7907e28c9197a7034.

Summary

📝 The adapter integration preserves framework-owned geo independently of public request extensions. One required startup-validation correction is called out inline; the other findings below are non-blocking.

Blocking

🔧 [P2] Preserve raw CIDRs through bounded policy validation — crates/edgezero-adapter-axum/src/geo.rs:290. The settings path accepts inputs rejected by the direct policy constructor. See the inline comment for reproductions and a suggested fix.

Non-blocking

♻️ [P3] Apply reserved provider-ID checks consistently — crates/edgezero-adapter-axum/src/geo.rs:350, together with the new factories in crates/edgezero-core/src/geo.rs:370–375.

The public GeoOutcome::platform() factory makes the reserved fastly and cloudflare IDs obtainable, but NativeGeo::validate rejects only cloudfront for supplied providers. Extracting either new ID from a platform outcome and using it in NativeGeoSelection::Supplied currently succeeds, producing capability metadata such as provider=fastly, source=CloudFront. Consider extending the existing guard and reserved-identity test to all three names. This is diagnostic/API consistency, not a demonstrated authorization bypass.

🤔 [P3] Refresh obsolete platform-coverage statements — docs/guide/native-geo.md:233–234,348.

The guide still says Fastly and Cloudflare expose NoSelection and broadly defers other adapters/sources. Their managed paths now always return a selected platform outcome, including MissingMetadata when no usable geo exists. Update that paragraph and the deferred-work wording, distinguishing these paths from unmanaged conversion/legacy dispatch and Spin.

Praise

😃 Strong end-to-end provenance coverage — crates/edgezero-adapter-axum/tests/production_hosting.rs:2274 checks manifest/settings selection through the actual runner alongside credential removal, immutable outcomes and store-free startup. The Cloudflare contract at crates/edgezero-adapter-cloudflare/tests/contract.rs:418 also verifies that platform metadata wins over raw CloudFront headers.

Verification

📝 Passing checks:

  • cargo fmt --all -- --check.
  • cargo clippy --workspace --all-targets --all-features -- -D warnings.
  • cargo check --workspace --all-targets --features "fastly cloudflare spin"; Fastly, Cloudflare and Spin target-specific WASM checks.
  • Full Axum --all-targets --all-features: 567 passed; full Axum with --features test-utils: 508 passed.
  • Cloudflare WASM unit/contract/browser suites: 177 passed; guest-shim tests passed.
  • Fastly WASM: 366 passed on an unfiltered rerun, using Viceroy 0.21.0 with the repository's CI readiness patch. Its ten readiness regressions and timeout-readback regression passed.
  • Example workspace: 66 passed; example Fastly/Cloudflare WASM builds passed.
  • Geo dependency-isolation contract passed. An additional local Viceroy probe passed 18 actual HTTP requests covering located/missing/partial/invalid metadata and spoofed geo headers.
  • cargo test --workspace --all-targets --exclude edgezero-adapter-axum: 2,406 passed.

📝 Failures retained rather than hidden: the initial cargo test --workspace --all-targets runs failed the tight timing allowance in connection::tests::pending_chunked_forward_preserves_original_deadlines_over_tcp. The same failure reproduced in isolated builds of both the merge-base and pinned named base, before the geo commits; the later full Axum suites passed without filtering. Initial stock and patched Viceroy runs also aborted at the unchanged outbound cutoff assertion in outbound.rs:3497; the later unfiltered Fastly rerun passed. The genuine merge-base Fastly library suite passed all 327 tests. These observations are not additional defects attributed to this PR's delta. Hosted CI passed for the reviewed head.

📝 Acceptance boundary: first-party documentation and local runtimes support the field mappings, but live Cloudflare/Fastly delivery and CloudFront/ALB credential gates, isolation, caching and rotation remain unverified. No candidate-specific deployed target was supplied; local emulation is not production deployment qualification.

match provider {
Some(ManifestGeoProvider::CloudFront) => {
let networks: Vec<&str> = match env_networks {
Some(raw) => raw.split(',').map(str::trim).collect(),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔧 [P2] Preserve raw CIDRs until the existing bounded policy validator

map(str::trim) removes disallowed control characters and bytes that should count toward the 16,384-byte input budget before PeerNetworks validates them. With geo-cloudfront enabled, I reproduced both:

  • "127.0.0.1/32\n"
  • format!("127.0.0.1/32{}", " ".repeat(16_384))

Both return InvalidProtectedPolicy through ProtectedCloudFrontAlb::new, but the same values supplied through EDGEZERO__ADAPTER__GEO__ALB_PEER_CIDRS resolve to an active CloudFront capability. The eager collect() also materializes the whole list before the existing 256-entry bound is checked.

Please pass the untrimmed split iterator directly to the policy constructor, and handle the manifest iterator similarly, so the existing validator owns normalization, byte accounting and entry limits. For example, after resolving header:

let policy = match env_networks {
    Some(raw) => ProtectedCloudFrontAlb::new(raw.split(','), header),
    None => ProtectedCloudFrontAlb::new(
        manifest
            .and_then(|geo| geo.alb_peer_cidrs.as_deref())
            .unwrap_or_default(),
        header,
    ),
}?;

Please add settings-path regression tests for control characters and oversized raw input, alongside the existing direct-constructor boundary tests.

Takes #439's refreshed head c1cec8e. The one conflict is the Manifest
struct's schema validators: #502 adds the adapter geo placement check and
#439 brings #275's Fastly logging check. Both are kept, after the existing
case-unique adapter keys check.

This branch has not been deployed

No deployments
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.

Axum geo bound from EdgeZero's manifest, so ctx.geo() needs no application boot profile

3 participants