Skip to content

Add portable ClientInfo for Fastly, Axum, Cloudflare and Spin - #517

Open
ChristianPavilonis wants to merge 37 commits into
feature/kv-geoipfrom
feat/portable-client-info
Open

ChristianPavilonis wants to merge 37 commits into
feature/kv-geoipfrom
feat/portable-client-info

Conversation

@ChristianPavilonis

@ChristianPavilonis ChristianPavilonis commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Adds ClientInfo, a read-only snapshot of the client address and viewer TLS facts that each managed adapter captures once at ingress. Handlers, middleware and pre-dispatch hooks read it through ctx.client_info() / PreDispatchRequest::client_info() without adapter imports. Header and extension edits cannot replace it.
  • Populates it on Fastly, Axum, Cloudflare and Spin. Every field is captured with its source or unavailable with a reason (NotExposed, Missing, Rejected). effective_client_ip() never returns a trusted proxy's own address.
  • Adds protected CloudFront JA4 on Axum, reusing the CloudFront Geo path, and moves all Axum JA4 trust decisions onto the listener's owned socket peer.

Design: docs/superpowers/specs/2026-11-18-portable-client-info-design.md. Plan and verification log: docs/superpowers/plans/2026-11-18-portable-client-info.md.

Review scope

This branch merges two open PRs as its development baseline, so the diff against feature/kv-geoip includes them until they land:

Review the ClientInfo commits only:

Commit Content
9469c8ae, c20e7176, 998e207b Spec and plan
412edaf6 Core types, dispatch plumbing, manifest tables
26f78793 Fastly and Axum
4d91a03d Cloudflare
6b8a0f44 Spin, including the SpinKvGeo::resolve split
4e5fb082 Axum JA4 from the owned peer and protected CloudFront JA4
f3af72b5 Request fidelity fixture
f3c6402f, e985a1d1 Docs and verification log
8a0ad55c..10ed3803 Review follow-ups: Cloudflare test item order, CodeQL-safe redaction test, Axum JA4 read after forwarding headers are stripped, direct ClientInfo dispatch on Fastly and Cloudflare, SpinClientSource, tighter Spin contract tests, guide corrections

Merge order: this PR merges after #469 and #514. When #514 merges into feature/kv-geoip, that branch is merged back in here.

Changes

Crate / File Change
edgezero-core/src/client_info.rs New ClientInfo, Capture, UnavailableReason, ClientIpSource, ViewerTlsValue; redacted Debug; TLS classification with no grammar or allowlist
edgezero-core app, ingress, context, pre-dispatch dispatch_admitted_with_client_info; the snapshot travels beside GeoOutcome through AdmittedIngress; RequestContext::client_info() and PreDispatchRequest::client_info()
edgezero-core/src/manifest.rs [adapters.cloudflare.client_info], [adapters.spin.client_info] (direct_ingress), [adapters.axum.ja4] source; each rejected on other adapters. Manifest::client_info_direct_ingress reads the declaration
edgezero-adapter-fastly Downstream IP and TLS protocol/cipher captured before the raw prepare hook; FastlyRequestContext unchanged
edgezero-adapter-axum Checked ingress projected through the spec's fallback table (DirectPeer, Trusted*, PeerFallback); JA4 captured from remote_addr in the service for both modes, after forwarding headers are stripped as before; protected CloudFront JA4 from the Geo selection's ProtectedCloudFrontAlb, with startup errors for Geo off, KV Geo, or generic JA4 also set
edgezero-adapter-cloudflare direct_ingress gates CF-Connecting-IP and cf TLS, read through Reflect instead of the panicking worker::Cf accessors
edgezero-adapter-spin Direct ingress from the last spin-client-addr; authenticated mode reuses #514's admission (token captured as absent/valid/invalid, resolve split into authenticate and lookup with unchanged Geo outcomes); SpinRequestContext reads the last field; SpinClientSource (Off, DirectIngress, AuthenticatedGeo) holds one source, and direct_ingress with authenticated-header Geo is a configuration error
edgezero-test-harness Fidelity fixture reports a fixed client_state label; verification requires the runtime address on Fastly and Spin and not_exposed on Cloudflare; baseline updated
docs/guide Handlers, capability matrix, configuration, and the four adapter pages

Closes

Closes #475
Closes #89
Closes #90
Closes #91
Closes #92
Closes #485

Live checks are follow-ups, not closing conditions (see below).

Test plan

  • cargo test --workspace --all-targets (3,098 passed)
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo fmt --all -- --check, plus the harness, reusable-app and request-fidelity workspaces
  • cargo check --workspace --all-targets --features "fastly cloudflare spin"
  • WASM builds and suites: Fastly contract (37) and request::/context:: lib tests under Viceroy 0.21.0; Cloudflare contract (33), ingress fidelity (7) and lib (142) under wasm-bindgen-test-runner and Chromium; Spin contract (39) and SDK (25) under Wasmtime 48.0.2
  • examples/app-demo workspace: cd examples/app-demo && cargo test --workspace --all-targets (68 passed)
  • Docs build: cd docs && npm run lint && npm run format && npm run build
  • Manual testing via edgezero serve --adapter axum
  • Other: harness tests (680 passed); ingress fidelity on real Spin 4.1.0 (spin up) and Viceroy. In the Spin spoof case the client sends spin-client-addr: 192.0.2.1:1 first and the snapshot still reports the runtime's loopback address.
  • Review follow-ups (8a0ad55c..10ed3803): workspace fmt, clippy and feature cargo check; wasm clippy for Cloudflare, Fastly and Spin with and without test-utils; core and adapter tests (2,152 passed); Spin contract (40) and SDK (25) under Wasmtime 48.0.2; docs lint and Prettier. The new Axum JA4 and Spin ClientInfo assertions fail when their fixes are reverted.

Not run locally:

  • scripts/run_tests.sh end to end; its suites were run individually.
  • Cloudflare ingress fidelity: npm ci fails building sharp on this machine. The Worker contract tests cover the Cloudflare cases with synthetic cf data.
  • The full Fastly --lib run aborts under stock Viceroy in outbound backend tests, as Report geo on every adapter and bind Axum geo from the manifest #502 reported on its base. CI uses the patched Viceroy.

One flaky local failure: production_hosting::geo_hosting_proves_real_peer_and_shared_outcome failed once during a parallel run and passed on five later runs.

Live follow-ups

  • Positive Fastly viewer TLS on a deployed service.
  • Cloudflare direct-ingress client IP and viewer TLS on a live Worker.
  • Spin client address on each hosted Spin runtime.
  • Protected CloudFront JA4 on a real distribution: a fingerprint on HTTPS, none over plain HTTP, a viewer-sent CloudFront-Viewer-JA4-Fingerprint never reaching the origin, and origin isolation.
  • ctx.geo() and ctx.ja4() on Cloudflare read cf without an opt-in, and a service-binding caller can supply cf. Not changed here; to raise with Report geo on every adapter and bind Axum geo from the manifest #502 and Expose JA4 through a standard request interface #469.

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

dhruv8sh and others added 30 commits November 12, 2026 21:38
Specify a provider-neutral JA4 accessor (ctx.ja4()) backed by adapter-owned
RequestIngress metadata: Fastly and Cloudflare populate it from their trusted
runtime APIs, Spin and Axum report NotExposed, and no adapter derives JA4 from
request headers.

Refs #283
Add edgezero_core::ja4 with a validated, Debug-redacted Ja4Fingerprint
and CapturedJa4 provenance/absence states. RequestIngress carries an
optional capture and RequestContext::ja4() reads it.

Fastly and Cloudflare populate it from their runtime TLS APIs; Spin and
Axum report NotExposed. No adapter derives JA4 from request headers.

Includes the implementation plan and adapter documentation.

Refs #283
Add a fixed ja4_state label to the request-fidelity fixture hook and send
spoofed ja4 / cloudfront-viewer-ja4-fingerprint headers in its spoof case.
The runner asserts Fastly and Cloudflare report missing and Spin reports
not_exposed on the real local runtimes, covering Spin's into_core_request
path that the plain-wasmtime contract suite cannot construct.

Replace magic section offsets in ja4.rs with named constants shared by
parse and the accessors, use matches! byte ranges, share one FoxIO sample
constant across core tests, and move test imports to module level.

Refs #283
Axum never sees the TLS handshake, but a TLS-terminating proxy in front of
it (FoxIO's nginx module, HAProxy, ATS, CloudFront) can compute JA4. Add
Ja4Source::TrustedProxyHeader and CapturedJa4::from_trusted_proxy_header,
and an Axum TrustedJa4Header that records the configured header only when
the direct TCP peer is inside an operator CIDR allowlist. Any other peer
stays NotExposed, so clients cannot forge it.

Configured with EDGEZERO__ADAPTER__JA4_HEADER and
EDGEZERO__ADAPTER__JA4_TRUSTED_PROXY_CIDRS, or programmatically via
AxumDevServer / EdgeZeroAxumService::with_trusted_ja4_header. Config fails
closed on partial settings, invalid entries and /0 networks. Default
behaviour is unchanged.

Spec §5.8, plan task 6 and the Axum guide document the design, the
operator requirement to overwrite the header, and an nginx example.

Refs #283
Both workspaces depend on edgezero-adapter-axum by path, so adding ipnet
to it requires their lockfiles to record the new edge. CI runs them with
--locked. No new packages are resolved.

Refs #283
EdgeZeroAxumService does not exist once this meets #275, and #275's check_outbound_legacy_api.sh rejects the name in docs/guide. AxumDevServer::with_trusted_ja4_header is public on both main and #275.
Use the JA4 reconciliation from the audited #439/#502 composition as a reference, without carrying RC history. Preserve #454 Geo preparation and Cloudflare KV imports.
Move the ClientInfo fixture types before the module's functions so Cloudflare wasm clippy passes without test-utils, and stop the Debug redaction test from printing captured values in its assertion message (CodeQL rust/cleartext-logging).
Restore the pre-ClientInfo order so a generic JA4 header named in the forwarding family is never read, and pin it with a regression case.
Test helpers now pass a NotExposed snapshot, so neither adapter repeats core's optional dispatch branch. Add Manifest::client_info_direct_ingress for the shared manifest lookup, and reuse the ALB admission and trusted-peer checks in Axum.
SpinClientSource replaces the direct_ingress flag and optional Geo selection, so the conflicting pair cannot be stored. Managed contract tests now assert the exact ClientInfo for authenticated Geo, failed lookups, off mode and direct ingress, with IP-selective Geo data.
The handler guide limits the private snapshot to client_info() and geo(). The Axum guide explains that generated apps stay on the development runner unless a bindings file selects production.
@ChristianPavilonis
ChristianPavilonis marked this pull request as ready for review November 18, 2026 22:28
aram356 added a commit that referenced this pull request Nov 19, 2026
#517 (10ed380) tops ChristianPavilonis's line on #439:
- #510, the KvStore record contract with DynamoDB and celld providers on
  Axum (#472, #473);
- #454, portable KV-backed geo;
- #514, country and region through ctx.geo() on Cloudflare and Spin (#480,
  #486);
- #517, the portable ClientInfo contract with its Fastly, Axum, Cloudflare and
  Spin mappings (#475, #90, #91, #92, #485).

#517 also merged #469 and #502 itself, so its tree contains everything this
branch had. The only conflicts were JA4 lines that #517 refactors on top of
#469; this merge takes #517's version, and its tree is identical to #517's.
aram356 added a commit that referenced this pull request Nov 19, 2026
#509 (2620377) adds bounded work after the response on Fastly and Axum, drained on Axum SIGTERM (EZI-1, #476). #512 (cdc232c) runs it on Cloudflare through waitUntil (#478), and #515 (ec347a2) reports Spin's capability error (#483). The line now stacks on #517 and each PR merged the one below it, so this merge is clean.

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

5 participants