Repository navigation
Add portable ClientInfo for Fastly, Axum, Cloudflare and Spin - #517
Open
ChristianPavilonis wants to merge 37 commits into
Open
ChristianPavilonis wants to merge 37 commits into
ChristianPavilonis wants to merge 37 commits into
Conversation
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
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.
This was
linked to
issues
Nov 18, 2026
Open
ChristianPavilonis
marked this pull request as ready for review
November 18, 2026 22:28
This was referenced Nov 18, 2026
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
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 was referenced Nov 19, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
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 throughctx.client_info()/PreDispatchRequest::client_info()without adapter imports. Header and extension edits cannot replace it.NotExposed,Missing,Rejected).effective_client_ip()never returns a trusted proxy's own address.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-geoipincludes them until they land:078d872b.ec0b912b, merged atc8613016.Review the ClientInfo commits only:
9469c8ae,c20e7176,998e207b412edaf626f787934d91a03d6b8a0f44SpinKvGeo::resolvesplit4e5fb082f3af72b5f3c6402f,e985a1d18a0ad55c..10ed3803ClientInfodispatch on Fastly and Cloudflare,SpinClientSource, tighter Spin contract tests, guide correctionsMerge order: this PR merges after #469 and #514. When #514 merges into
feature/kv-geoip, that branch is merged back in here.Changes
edgezero-core/src/client_info.rsClientInfo,Capture,UnavailableReason,ClientIpSource,ViewerTlsValue; redactedDebug; TLS classification with no grammar or allowlistedgezero-coreapp, ingress, context, pre-dispatchdispatch_admitted_with_client_info; the snapshot travels besideGeoOutcomethroughAdmittedIngress;RequestContext::client_info()andPreDispatchRequest::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_ingressreads the declarationedgezero-adapter-fastlyFastlyRequestContextunchangededgezero-adapter-axumDirectPeer,Trusted*,PeerFallback); JA4 captured fromremote_addrin the service for both modes, after forwarding headers are stripped as before; protected CloudFront JA4 from the Geo selection'sProtectedCloudFrontAlb, with startup errors for Geo off, KV Geo, or generic JA4 also setedgezero-adapter-cloudflaredirect_ingressgatesCF-Connecting-IPandcfTLS, read throughReflectinstead of the panickingworker::Cfaccessorsedgezero-adapter-spinspin-client-addr; authenticated mode reuses #514's admission (token captured as absent/valid/invalid,resolvesplit intoauthenticateandlookupwith unchanged Geo outcomes);SpinRequestContextreads the last field;SpinClientSource(Off,DirectIngress,AuthenticatedGeo) holds one source, anddirect_ingresswith authenticated-header Geo is a configuration erroredgezero-test-harnessclient_statelabel; verification requires the runtime address on Fastly and Spin andnot_exposedon Cloudflare; baseline updateddocs/guideCloses
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 warningscargo fmt --all -- --check, plus the harness,reusable-appandrequest-fidelityworkspacescargo check --workspace --all-targets --features "fastly cloudflare spin"request::/context::lib tests under Viceroy 0.21.0; Cloudflare contract (33), ingress fidelity (7) and lib (142) underwasm-bindgen-test-runnerand Chromium; Spin contract (39) and SDK (25) under Wasmtime 48.0.2examples/app-demoworkspace:cd examples/app-demo && cargo test --workspace --all-targets(68 passed)cd docs && npm run lint && npm run format && npm run buildedgezero serve --adapter axumspin up) and Viceroy. In the Spinspoofcase the client sendsspin-client-addr: 192.0.2.1:1first and the snapshot still reports the runtime's loopback address.8a0ad55c..10ed3803): workspace fmt, clippy and featurecargo check; wasm clippy for Cloudflare, Fastly and Spin with and withouttest-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 SpinClientInfoassertions fail when their fixes are reverted.Not run locally:
scripts/run_tests.shend to end; its suites were run individually.npm cifails buildingsharpon this machine. The Worker contract tests cover the Cloudflare cases with syntheticcfdata.--librun 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_outcomefailed once during a parallel run and passed on five later runs.Live follow-ups
CloudFront-Viewer-JA4-Fingerprintnever reaching the origin, and origin isolation.ctx.geo()andctx.ja4()on Cloudflare readcfwithout an opt-in, and a service-binding caller can supplycf. 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
{id}syntax (not:id)edgezero_core(nothttpcrate)KvRegistry/ConfigRegistry/SecretRegistry(not the legacy single-handle setters) — see spec §6.6