roundtrip: support HTTP/2 fronting via ALPN-aware transport

[myleshorton]

What

Make the fronted round-trip ALPN-aware so it speaks whatever protocol the CDN edge selects — HTTP/1.1 or HTTP/2.

Why

dialFront offers a genuine browser ClientHello (Chrome 131), whose ALPN advertises h2, http/1.1. Many edges answer with h2 — including CloudFront (and Alibaba Cloud / Aliyun). But doRequest always wrapped the connection in an HTTP/1.1-only transport, so the HTTP/1.1 parser choked on the very first HTTP/2 SETTINGS frame:

net/http: HTTP/1.x transport connection broken:
malformed HTTP response "\x00\x00\x12\x04\x00\x00\x00\x00\x00..."

So fronting silently failed against any h2-negotiating edge. The "fix" of advertising only http/1.1 was rejected on purpose: ALPN travels in the cleartext ClientHello, so a Chrome fingerprint that offers only http/1.1 is itself a detectable anomaly. Better to keep the real ALPN and actually speak h2.

sequenceDiagram
    autonumber
    participant C as Client<br/>dialer.go
    participant E as Edge<br/>CloudFront / Aliyun
    participant R as doRequest<br/>roundtrip.go

    C->>E: ClientHello — ALPN offers h2, http/1.1<br/>dialer.go:78
    E-->>C: ServerHello — ALPN selects h2 ⚠️
    rect rgba(255, 200, 200, 0.3)
        Note over R: before: always the HTTP/1.1 transport 🐛<br/>h1 parser chokes on the h2 SETTINGS frame<br/>malformed HTTP response 0x00 0x00 0x12 0x04
    end
    Note over R: now: branch on negotiatedProtocol conn<br/>roundtrip.go:93
    alt negotiated h2
        R->>E: roundTripH2 — :authority = fronted host<br/>roundtrip.go:100
    else http/1.1 or none
        R->>E: newConnTransport — Host = fronted host<br/>roundtrip.go:106
    end
    E-->>C: response routed by the fronted host

Loading

How

• negotiatedProtocol(conn) reads the settled ALPN off the utls connection.
• On h2, roundTripH2 frames the request over the already-established conn via x/net/http2's Transport.NewClientConn. The library dials a fresh connection per request and never reuses it, so the ClientConn is single-shot: h2Body.Close() tears down the connection and its frame-reader goroutine when the response body closes.
• Otherwise the existing HTTP/1.1 path is unchanged.

Routing is identical across protocols because rewriteRequest already points the request at the fronted host — that lands in the Host header (HTTP/1.1) or the :authority pseudo-header (HTTP/2), which is exactly what the CDN routes on.

Adds golang.org/x/net as a direct dependency. It was already pinned at v0.38.0 transitively (via utls), so no new version is introduced — go mod tidy only promotes it.

Test plan

• New h2_test.go — offline, pipe-backed h2 mock server: asserts the fronted host lands in :authority, path + headers are preserved, and the response is HTTP/2. No real network.
• Full suite green, including -race (validates the h2Body connection teardown).
• Verified end-to-end against the live Aliyun CDN (in the companion provider PR): all edges front a cross-org Host over HTTP/2, 200 under the production Chrome_131 hello.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Enhanced HTTP/2 domain-fronting by using ALPN negotiation to ensure requests are framed and routed correctly.

• Bug Fixes / Refactor

  • Improved protocol handling so HTTP/2 upgrade attempts are properly rejected and retried on mismatch.
  • Centralized HTTP/1.1 vs HTTP/2 request execution, including safer header handling for HTTP/2 and correct teardown behavior.

• Tests

  • Added HTTP/2 coverage for request/response semantics, verify-with-POST behavior, header parsing/stripping, upgrade rejection, and close/error precedence.

• Documentation / Chores

  • Updated README to clarify HTTP/1.1 + HTTP/2 support and refined dependency notes; refreshed module requirements.

---

Updates during review:

• Addressed Copilot: centralized ALPN-aware framing in sendOverConn (vetting via verifyWithPost now speaks h2 too), h2Body.Close propagates the connection-close error, and hasConnectionUpgrade parses the comma-separated Connection token list.
• Addressed CodeRabbit: test handshakes use HandshakeContext (cancelled at test end via t.Cleanup, not on helper return — the latter poisoned the conn on go 1.24).
• Bumped utls v1.7.1 → v1.8.2 (uses Go 1.24 native ML-KEM, drops cloudflare/circl; HelloChrome_131 fingerprint unchanged; verified it still handshakes with real CloudFront/Aliyun edges over h2).

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

doRequest in roundtrip.go now inspects the ALPN-negotiated protocol on the uTLS connection and routes h2 traffic through a new sendOverConn dispatcher that creates a one-shot http2.ClientConn. Non-h2 paths use the existing transport logic. The front verification flow is updated to use the same sendOverConn routing. A new test file verifies HTTP/2 semantics and helper behavior, and go.mod and README.md are updated with required dependencies and feature documentation.

Changes

HTTP/2 ALPN routing

Layer / File(s)	Summary
HTTP/2 core routing and helpers roundtrip.go	Imports expanded with sync, utls, and golang.org/x/net/http2. Introduces errH2UpgradeUnsupported sentinel error, negotiatedProtocol to read ALPN from utls.UConn, hasConnectionUpgrade to detect upgrade tokens in Connection headers, stripConnHeaders to remove HTTP/2-forbidden headers, sendOverConn to dispatch requests based on ALPN with rewritten URL schemes, roundTripH2 creating a one-shot http2.ClientConn, and h2Body wrapping response bodies and closing the HTTP/2 client connection exactly once via sync.Once.
Front-pool error handling for HTTP/2 upgrade rejection roundtrip.go	RoundTrip now treats errH2UpgradeUnsupported as a signal that the selected front is the wrong protocol, returning the front as healthy (triggering retry) instead of marking it as failed.
Request dispatch refactoring in doRequest roundtrip.go	doRequest computes disableKeepAlives via hasConnectionUpgrade(req) and delegates all protocol-specific sending to sendOverConn, removing prior inline transport construction.
Front verification using HTTP/2 routing domainfront.go	verifyWithPost replaces direct newConnTransport execution with sendOverConn(conn, req, true), ensuring the vetting POST request matches the negotiated ALPN protocol.
HTTP/2 integration and unit tests h2_test.go	dialPipeH2 helper creates an in-memory TLS server with ALPN h2 and returns a handshaken utls.UConn client. TestDoRequest_HTTP2 validates correct HTTP/2 responses with :authority, path preservation, and header forwarding. TestVerifyWithPost_HTTP2 confirms POST over HTTP/2 and 202 acceptance. TestStripConnHeaders, TestSendOverConn_H2_RejectsUpgrade, and TestSendOverConn_H2_StripsForbiddenHeaders validate header and upgrade handling. TestH2Body_Close asserts exact-once closure and error precedence. TestHasConnectionUpgrade unit-tests the upgrade-token parser.
Dependency and documentation updates go.mod, README.md	go.mod adds golang.org/x/net v0.38.0 and golang.org/x/text v0.23.0, updates utls to v1.8.2. README.md adds HTTP/1.1 and HTTP/2 feature bullet and updates the minimal-dependencies note to include x/net/http2.
Option helper formatting domainfront.go	The With* option functions are reformatted for alignment consistency without functional changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A rabbit runs the network trace,
"h2" announces ALPN's pace.
One-shot conn, frames aligned,
Authority and path combined.
x/net arrives in go.mod's keep—
HTTP/2 sleeps where protocols sleep! 🌐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding HTTP/2 support via ALPN-aware transport. It is specific and directly reflects the primary objective of the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fisk/h2-fronting

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR makes the domain-fronting round trip ALPN-aware so that requests are framed using the protocol actually negotiated during the TLS handshake (HTTP/1.1 or HTTP/2), preventing failures when CDN edges select h2.

Changes:

• Branch request framing in doRequest based on negotiated ALPN and add an HTTP/2 code path using x/net/http2.
• Add an offline, pipe-backed HTTP/2 unit test validating :authority, headers, path preservation, and HTTP/2 response.
• Promote golang.org/x/net to a direct dependency and document HTTP/2 support in the README.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
roundtrip.go	Adds ALPN detection and an HTTP/2 RoundTrip implementation over the already-established TLS conn.
h2_test.go	Introduces a pipe-backed HTTP/2 server test to validate correct authority/path/headers.
README.md	Documents HTTP/2 support and updates the “minimal dependencies” bullet.
go.mod	Promotes golang.org/x/net to a direct dependency.
go.sum	Adds checksums for newly direct/indirect module entries.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@h2_test.go`:
- Line 41: Replace the direct call to srv.Handshake() with a context-aware
approach using HandshakeContext for explicit timeout control. Create a context
with a reasonable timeout using context.WithTimeout, then pass that context to
srv.HandshakeContext() instead of calling Handshake() without context. This
ensures the handshake operation has an explicit deadline and can be properly
cancelled if needed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 69a65a30-e137-4884-97d6-1a18c6bb5f79

📥 Commits

Reviewing files that changed from the base of the PR and between fdc839b and d1ab9e0.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (4)

• README.md
• go.mod
• h2_test.go
• roundtrip.go

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated no new comments.

[coderabbitai]

♻️ Duplicate comments (1)

h2_test.go (1)

35-35: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Use context-aware TLS handshake.

The past review comment flagging srv.Handshake() for lacking explicit timeout control remains valid. While net.Pipe() eliminates network stalls, adopting HandshakeContext aligns with Go best practices for goroutine lifecycle management.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@h2_test.go` at line 35, Replace the srv.Handshake() call with
srv.HandshakeContext() to provide explicit timeout control and align with Go
best practices for goroutine lifecycle management. Pass a context with an
appropriate timeout as the first argument to HandshakeContext, such as a context
derived from context.Background() with a timeout duration to prevent indefinite
blocking during the TLS handshake operation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@h2_test.go`:
- Line 35: Replace the srv.Handshake() call with srv.HandshakeContext() to
provide explicit timeout control and align with Go best practices for goroutine
lifecycle management. Pass a context with an appropriate timeout as the first
argument to HandshakeContext, such as a context derived from
context.Background() with a timeout duration to prevent indefinite blocking
during the TLS handshake operation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5dcbec52-1989-4ea4-9507-98358c52c141

📥 Commits

Reviewing files that changed from the base of the PR and between d1ab9e0 and 0580002.

📒 Files selected for processing (3)

• domainfront.go
• h2_test.go
• roundtrip.go

🚧 Files skipped from review as they are similar to previous changes (1)

• roundtrip.go

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.