Skip to content

fix(stargate): enforce protocol input and header contracts - #1818

Open
barrygreengus wants to merge 4 commits into
mainfrom
codex/stargate-maintenance/protocol
Open

barrygreengus wants to merge 4 commits into
mainfrom
codex/stargate-maintenance/protocol

Conversation

@barrygreengus

@barrygreengus barrygreengus commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

Why

Valid IPv6 backend URLs and owned or escaped JSON enum values were rejected. Proxies also removed Connection itself while forwarding fields named by it. Schema-generation tests duplicated configuration through test-only build-script paths instead of checking generated behavior.

Examples

  • IPv6 registration: quic://[::1]:4433 is a valid direct backend address. Previously, extracting the host as text left IPv6 brackets in the string passed to the IP parser, so admission or dialing rejected it. Both paths now use the same parser and retain the URL parser's typed IPv6 address.
  • JSON settings: "http\u0033" means "http3", and an owned JSON value containing "http3" is also valid input. The enums previously required a borrowed string, which those deserialization paths cannot supply. Reading an owned string accepts these representations while preserving validation of supported values.
  • Connection-specific headers: a request with Connection: x-private-hop and X-Private-Hop: internal-value previously lost the Connection header but forwarded X-Private-Hop. The recipient could no longer tell that the field applied only to the previous connection. Forwarding now removes both fields, in both request and response directions, including repeated Connection fields and mixed-case names.
  • Build verification: the removed tests checked facts such as the number of configured proto files and called test-only build-script functions. They could pass without exercising schema generation. This is a maintenance and verification defect: the build scripts now call the generators directly, and existing generated-message serialization tests remain in place and run through Bazel.

What changed

  • Share direct QUIC URL validation with dialing and accept typed IPv6 hosts.
  • Deserialize transport and connectivity enums from owned strings.
  • Apply the shared hop-header and Connection-option filter once at each forwarding boundary, then apply tunnel-specific exclusions.
  • Keep schema generation directly in build.rs, remove duplicate plan scaffolding and redundant dev dependencies, and expose the existing generated-protobuf behavior test through Bazel.

Customer Release Notes

Stargate accepts IPv6 backend addresses and valid JSON transport settings, and correctly removes connection-specific HTTP headers.

Plan Summary

Not applicable.

Usage

Existing registration and proxy interfaces apply.

Testing

The YAGNI follow-up passed all 39 existing tunnel tests and all-target Stargate Clippy with warnings denied in an isolated worktree. It inlines the remaining H3 Host exclusion and removes its one-comparison wrapper and mirrored test. Formatting and whitespace checks passed.

Earlier combined-stack validation passed 1,611 Cargo workspace tests, with 3 existing performance tests ignored, workspace Clippy, and 6 scoped Bazel targets. Regression coverage includes IPv6, owned and escaped JSON, serialization, both header-forwarding directions, and tunnel-specific exclusions. The full workspace and Bazel suites were not rerun for this local simplification. No live-cluster QA is required for this layer.

Notes

Layer 1 of the Stargate maintenance stack. No runtime architecture or wire-schema change.

Issues

Relates to #1817

References

HTTP connection fields

Related Pull Requests

Next layer: #1820. Stack, bottom to top: #1818, #1820, #1823, #1826.

Dependencies

No dependency versions were added or upgraded. Removed duplicate capnpc and tonic-prost-build dev declarations; both remain build dependencies. No license or NOTICE changes.

Summary by CodeRabbit

  • Bug Fixes
    • Improved HTTP header forwarding by removing hop-by-hop headers, including headers listed in Connection, while preserving valid repeated headers such as Set-Cookie.
    • Applied consistent header filtering across HTTP proxies and QUIC/HTTP3 tunnels.
    • Improved QUIC address validation and added support for IPv4 and IPv6 socket addresses.
    • Improved deserialization for connectivity and transport protocol settings, including escaped JSON values.
    • Added coverage for header filtering and IPv6 direct registrations.

@coderabbitai

coderabbitai Bot commented Sep 11, 2026

Copy link
Copy Markdown

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ec8554eb-dd5c-4372-b2c0-284063fac147

📥 Commits

Reviewing files that changed from the base of the PR and between 5c9a772 and 08ef4de.

⛔ Files ignored due to path filters (1)
  • MODULE.bazel.lock is excluded by !**/*.lock, !**/MODULE.bazel.lock
📒 Files selected for processing (19)
  • src/libraries/rust/stargate/crates/proto/BUILD.bazel
  • src/libraries/rust/stargate/crates/proto/Cargo.toml
  • src/libraries/rust/stargate/crates/proto/build.rs
  • src/libraries/rust/stargate/crates/proto/src/build_plan.rs
  • src/libraries/rust/stargate/crates/proto/src/lib.rs
  • src/libraries/rust/stargate/crates/protocol/BUILD.bazel
  • src/libraries/rust/stargate/crates/protocol/Cargo.toml
  • src/libraries/rust/stargate/crates/protocol/build.rs
  • src/libraries/rust/stargate/crates/protocol/src/build_plan.rs
  • src/libraries/rust/stargate/crates/protocol/src/common.rs
  • src/libraries/rust/stargate/crates/protocol/src/lib.rs
  • src/libraries/rust/stargate/crates/pylon-lib/src/quic_http_tunnel/core.rs
  • src/libraries/rust/stargate/crates/pylon-lib/src/quic_http_tunnel/tests.rs
  • src/libraries/rust/stargate/crates/stargate/src/control_plane/registration/admission.rs
  • src/libraries/rust/stargate/crates/stargate/src/http_proxy/upstream.rs
  • src/libraries/rust/stargate/crates/stargate/src/tunnel/direct.rs
  • src/libraries/rust/stargate/crates/stargate/src/tunnel/http3.rs
  • src/libraries/rust/stargate/crates/stargate/src/tunnel/mod.rs
  • src/libraries/rust/stargate/crates/stargate/src/tunnel/tests.rs
💤 Files with no reviewable changes (5)
  • src/libraries/rust/stargate/crates/protocol/src/build_plan.rs
  • src/libraries/rust/stargate/crates/proto/src/lib.rs
  • src/libraries/rust/stargate/crates/proto/src/build_plan.rs
  • src/libraries/rust/stargate/crates/protocol/Cargo.toml
  • src/libraries/rust/stargate/crates/proto/Cargo.toml

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.


📝 Walkthrough

Walkthrough

The PR simplifies proto and Cap’n Proto build integration. It centralizes connection-aware HTTP header filtering, updates forwarding paths, improves QUIC address validation, and adjusts protocol deserialization tests.

Changes

Build pipeline simplification

Layer / File(s) Summary
Proto generation and test wiring
src/libraries/rust/stargate/crates/proto/*
Proto compilation now runs directly from build.rs. The compile-plan module was removed, and Bazel adds a Rust test target.
Cap’n Proto build-script wiring
src/libraries/rust/stargate/crates/protocol/*
Cap’n Proto compilation now uses a dedicated Bazel build-script target and directly watches and compiles quic.capnp.

Transport behavior updates

Layer / File(s) Summary
Connection-aware header forwarding
src/libraries/rust/stargate/crates/protocol/src/common.rs, src/libraries/rust/stargate/crates/pylon-lib/src/quic_http_tunnel/*, src/libraries/rust/stargate/crates/stargate/src/http_proxy/upstream.rs, src/libraries/rust/stargate/crates/stargate/src/tunnel/http3.rs, src/libraries/rust/stargate/crates/stargate/src/tunnel/tests.rs
end_to_end_headers removes fixed hop-by-hop headers and headers nominated by Connection. HTTP proxy and tunnel forwarding paths use the helper.
QUIC address validation
src/libraries/rust/stargate/crates/stargate/src/tunnel/direct.rs, src/libraries/rust/stargate/crates/stargate/src/tunnel/mod.rs, src/libraries/rust/stargate/crates/stargate/src/control_plane/registration/admission.rs
Direct registration uses crate-visible parse_quic_addr, which accepts IPv4 and IPv6 socket literals and reports specific validation errors.
Protocol deserialization coverage
src/libraries/rust/stargate/crates/protocol/src/lib.rs
Enum deserialization now parses owned strings. Tests cover variant round trips and escaped JSON strings.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 08ef4

The protocol, forwarding, build, and address-validation changes are ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 42.42% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 33 functions across 14 files. 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 follows Conventional Commits format with the required scope and accurately describes the primary protocol validation and header-forwarding fixes.
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.
  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/stargate-maintenance/protocol

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.98.0)

Clippy execution failed


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

@barrygreengus barrygreengus changed the title codex/stargate maintenance/protocol fix(stargate): enforce protocol input and header contracts Sep 11, 2026
@barrygreengus
barrygreengus force-pushed the codex/stargate-maintenance/protocol branch from a8c084d to 0436af5 Compare September 11, 2026 21:05
@barrygreengus
barrygreengus added this pull request to stack #1821 September 11, 2026 21:05
@github-actions

Copy link
Copy Markdown
Contributor

🛡️ CodeQL Analysis

🚨 Found 5 issue(s)

Severity Breakdown:

  • 🔴 Errors: 0
  • 🟡 Warnings: 0
  • 🔵 Notes: 0
📋 Top Issues

🔗 View full details in Security tab

🕐 Last updated: 2026-09-11 21:23:19 UTC | Commit: 0436af5

Accept IPv6 tunnel addresses and owned JSON values, filter Connection-nominated fields, and simplify schema generation while retaining generated API tests.

Refs: #1817
Regenerate the Bazel dependency graph after removing redundant schema compiler dev declarations. No dependency version changes.

Refs: #1817
@barrygreengus
barrygreengus force-pushed the codex/stargate-maintenance/protocol branch from 0436af5 to 0ff037c Compare September 11, 2026 22:10
@barrygreengus
barrygreengus removed this pull request from stack #1821 September 15, 2026 16:28
@barrygreengus
barrygreengus added this pull request to stack #1906 September 15, 2026 16:29
Keep the required Host check at its sole forwarding call site. Remove
the one-comparison wrapper, its imports, and its mirrored unit test.
Existing tunnel tests cover the transport path.

Relates to #1817
@barrygreengus
barrygreengus marked this pull request as ready for review September 16, 2026 16:29
@barrygreengus
barrygreengus requested review from a team as code owners September 16, 2026 16:29
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.

3 participants