feat(gax): request-level custom HTTP/gRPC headers by xlai20 · Pull Request #6260 · googleapis/google-cloud-rust

xlai20 · 2026-08-03T10:14:51Z

Overview

Adds support for request-level custom HTTP/gRPC headers via RequestOptionsBuilder::with_custom_header, allowing developers to inject tracking or tracing headers (e.g., x-client-tracking-id, X-B3-TraceId) on individual API calls without signature changes.

DD: go/rust-sdk-custom-header
Part of #5997

Key Changes

google-cloud-gax:
- Added default method with_custom_header<K, V>(mut self, name: K, value: V) -> Self to RequestOptionsBuilder.
google-cloud-gax-internal:
- Updated ReqwestClient::request() to extract custom headers and enforce a "System-Wins" precedence policy.
Tests:
- Added unit tests for RequestOptionsBuilder::with_custom_header.
- Added HTTP transport wire emission and precedence tests in http_custom_header.rs (via echo_server).
- Integration tests will be added later in google-cloud-storage upon version bump in next PR.

gemini-code-assist

Code Review

This pull request introduces support for injecting custom HTTP headers into requests via RequestOptionsBuilder::with_custom_header, along with comprehensive integration and unit tests. The review feedback highlights two key issues: first, the current logic for merging system headers silently discards multi-valued headers due to how HeaderMap iteration works; second, swallowing conversion errors when parsing custom header names and values violates the "Demand Explosive Correctness" principle, and should instead fail loudly.

codecov · 2026-08-03T10:26:40Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.24%. Comparing base (35b9590) to head (28510a4).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6260      +/-   ##
==========================================
- Coverage   96.24%   96.24%   -0.01%     
==========================================
  Files         280      280              
  Lines       72146    72201      +55     
==========================================
+ Hits        69440    69491      +51     
- Misses       2706     2710       +4

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

joshuatants · 2026-08-05T01:58:12Z

+            .await?
+            .into_body();
+
+        assert!(


Is 'authorization' not a system header too?

Yes, added it and explained in another comment.

joshuatants · 2026-08-05T02:08:32Z

+                    .get_extension::<http::HeaderMap>()
+                    .cloned()
+                    .unwrap_or_default();
+                headers.insert(name, value);


How about repeated headers, e.g. Cache-Control or custom repeated headers?

No code changes are needed for this, as standard repeated headers work out-of-the-box using RFC-compliant comma-separated strings:

Under HTTP RFC 9110 (Section 5.3), standard repeated headers like Cache-Control, Accept, or Allow are defined as comma-separated lists (e.g., Cache-Control: no-cache, no-store).

Callers can supply repeated values natively as a single comma-separated HeaderValue without needing multiple calls:
builder.with_custom_header( HeaderName::from_static("cache-control"), HeaderValue::from_static("no-cache, no-store"), )

I checked other language SDK implementations (such as Python), and they follow this same pattern.

joshuatants · 2026-08-05T02:14:18Z

+
+    const X_GOOG_USER_PROJECT: &str = "x-goog-user-project";
+
+    fn with_custom_header(


Why is the logic reimplemented here instead of using the implementation in RequestOptionsBuilder?

No, this entire test file src/gax-internal/tests/http_custom_header.rs is not testing the RequestOptionsBuilder function in gax/src/options.rs. Instead, it is an integration test for the HTTP wire-level transport logic in src/gax-internal/src/http.rs.

The function with_custom_header here is a test helper function that inserts custom headers into the extensions. The test verifies that when client.execute(..., options) runs, ReqwestClient::request:

Retrieves the custom HeaderMap from RequestOptions extensions

Sanitizes and strips conflicting system/auth headers

Correctly merges custom headers with credential headers and system headers on the wire.

joshuatants · 2026-08-05T02:15:51Z

        unimplemented!();
    }
+
+    /// Injects a custom HTTP header into this specific request.


Let's include more information about how custom headers behave:

precedence vs system headers

behaviour when used with with_user_project/with_user_agent

Done, added detailed explanation to the with_custom_header function.

joshuatants · 2026-08-05T02:16:48Z

        }

-        let mut headers = match self.cred.headers(Extensions::new()).await {
+        let cred_headers = match self.cred.headers(Extensions::new()).await {


How about x-goog-user-project?

Are there other reserved headers that should be removed as well? What is the behaviour of the other SDKs?

x-goog-user-project is removed at line 435.

joshuatants · 2026-08-05T02:22:46Z

+                options = options.insert_extension(headers);
+                *self.request_options() = options;
+            }
+            _ => panic!("invalid header name or value"),


Instead of panicking, I think either:

Have name and value be HeaderName/Value and make callers do the validation, or

Return a Result instead, renaming the function to try_with_custom_header

Otherwise, right now there's no way for the application to fail gracefully on malformed input.

Done.

I chose to implement your suggested Option 1 to shift HeaderName and HeaderValue to the function signature, letting callers to do the validation. It's better than Option 2 as it preserves Fluent Builder ergonomics.

joshuatants · 2026-08-05T02:27:11Z

+            .unwrap_or_default();
+
+        // Strip any custom headers that collide with system headers or credential headers.
+        for key in cred_headers


Can you double check this logic in the gRPC path (

google-cloud-rust/src/gax-internal/src/grpc/grpc_helpers.rs

Line 78 in 35b9590

for key in [

)? If Authorization is suppled as a custom header, in HTTP it'll be removed, but it doesn't look like it'll be removed there.

Done.

I align the gRPC path and HTTP/JSON path as follows:

Ensure the order of "adding authorization headers" and "adding custom headers" in both paths are the same: add custom headers, strip away system headers, then add authorization headers. Previously the order is different in gRPC and JSON, resulting in different implementations in both sites; now they are the same.

In the sanitization code, now I add "authorization" and other authorization-related headers into the list of system headers. They would all be stripped away from user-input custom headers, before any kinds of authorization/system headers are added.

The current implementation is aligned with other language SDKs.

…gRPC - In http.rs, reorder custom headers retrieval to the beginning of request building and sanitize custom headers against a hardcoded list of system and authentication header keys (USER_AGENT, AUTHORIZATION, X_GOOG_API_KEY, X_GOOG_USER_PROJECT). - In grpc_helpers.rs, add AUTHORIZATION, X_GOOG_API_KEY, and X_GOOG_API_CLIENT to the custom header sanitization loop in make_headers(). - Update unit tests in grpc_helpers.rs and http_custom_header.rs to test sanitization and precedence of authorization and API key custom headers.

- Change RequestOptionsBuilder::with_custom_header to accept http::header::HeaderName and http::header::HeaderValue directly, avoiding panics on malformed string input. - Callers are now responsible for validating dynamic headers via try_from/from_str and handling errors gracefully in their application. - Update unit tests in src/gax/src/options.rs to test static headers and assert TryFrom/from_str errors on invalid inputs.

gemini-code-assist Bot reviewed Aug 3, 2026

View reviewed changes

Comment thread src/gax-internal/src/http.rs Outdated

Comment thread src/gax/src/options.rs Outdated

xlai20 force-pushed the request-custom-header branch from 37c3082 to 0c1facd Compare August 4, 2026 06:25

xlai20 changed the title ~~feat(gax): support request-level custom HTTP/gRPC headers~~ feat(gax): request-level custom HTTP/gRPC headers Aug 4, 2026

xlai20 added 5 commits August 4, 2026 06:48

Add request-level custom header configuration and precedence logic

e82d531

reduce verbosity of code

d163c7b

add unit tests

cf5eecb

fix accidental drop of multi-valued headers

caf06c4

fail loudly on invalid header key and value

7a54bb5

xlai20 force-pushed the request-custom-header branch from 0c1facd to 7a54bb5 Compare August 4, 2026 06:48

xlai20 marked this pull request as ready for review August 4, 2026 06:52

xlai20 requested a review from a team as a code owner August 4, 2026 06:52

xlai20 requested a review from joshuatants August 4, 2026 06:52

joshuatants reviewed Aug 5, 2026

View reviewed changes

joshuatants requested changes Aug 5, 2026

View reviewed changes

xlai20 added 2 commits August 5, 2026 04:58

xlai20 requested a review from joshuatants August 5, 2026 07:51


		const X_GOOG_USER_PROJECT: &str = "x-goog-user-project";

		fn with_custom_header(

Uh oh!

Conversation

xlai20 commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Changes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joshuatants Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

xlai20 commented Aug 3, 2026 •

edited

Loading

codecov Bot commented Aug 3, 2026 •

edited

Loading

joshuatants Aug 5, 2026 •

edited

Loading