feat(xds): per-stream call-credentials hook for the xDS transport by choonkijang · Pull Request #2705 · grpc/grpc-rust

choonkijang · 2026-06-25T18:26:45Z

Motivation

Per #2702, credential-gated xDS control planes (e.g. GCP Traffic Director / google_default) require two things the transport did not provide: per-stream call credentials on the ADS stream, and a secure channel to carry them. Their bootstrap server_uri is often scheme-less (e.g. trafficdirector.googleapis.com:443), which parses with no scheme — so Endpoint has no signal to negotiate TLS, the ADS connection never establishes a secure session, and routing times out with "route config not yet available".

Solution

xds-client:

Add a minimal TonicCallCredentials trait mirroring grpc-go's PerRPCCredentials. The tonic transport attaches it on each (re)connect, only over a secure channel.
Call credentials are accepted only via TonicTransportBuilder::with_call_credentials, where channel security is derived from with_tls_config and validated at build time to avoid sending credentials to insecure channel.
On the secure path, prepend https:// to server_uri in TonicTransportBuilder::build when it's missing the scheme.

tonic-xds:

Promote google_default to a first-class ChannelCredentialType::GoogleDefault (gRFC A27).
Add XdsChannelConfig::with_call_credentials(...), so that applications can give a token source without relying on grpc or grpc-google crates at this time.

examples:

Add the channel_with_google_default tonic-xds example (reusing the testutil greeter), demonstrating two ADC token sources.

BREAKING CHANGE:

adds a CallCredentials variant to the Error enum and marks it #[non_exhaustive]

Per grpc#2444, credential-gated xDS control planes (e.g. GCP Traffic Director / `google_default`) require two things the transport did not provide: per-stream call credentials on the ADS stream, and a secure channel to carry them. Their bootstrap `server_uri` is often scheme-less (e.g. `trafficdirector.googleapis.com:443`), which parses with no scheme — so `Endpoint` has no signal to negotiate TLS, the ADS connection never establishes a secure session, and routing times out with "route config not yet available". xds-client: - Add a minimal `CallCredentials` trait mirroring grpc-go's `PerRPCCredentials`. The tonic transport attaches it on each (re)connect, only over a secure channel. - Construction is builder-based: `TonicTransportBuilder::with_call_credentials` and `with_channel(Channel, secure)` for a pre-built channel. - On the secure path, prepend `https://` to `server_uri` in `TonicTransportBuilder::build` when it's missing the scheme. tonic-xds: - Promote `google_default` to a first-class `ChannelCredentialType::GoogleDefault` (gRFC A27). - Add `XdsChannelConfig::with_call_credentials(...)`, so that applications can give a token source without relying on `grpc` or `grpc-google` crates at this time. examples: - Add the `channel_with_google_default` tonic-xds example (reusing the testutil greeter), demonstrating two ADC token sources. BREAKING CHANGE: * Relocate `TonicTransport::from_channel` to `TonicTransportBuilder::with_channel`, and * Adds a variant to the `Error` enum

linux-foundation-easycla · 2026-06-25T18:26:51Z

The committers listed above are authorized under a signed CLA.

✅ login: choonkijang / name: Choonki Jang (0472b49)

choonkijang · 2026-06-26T01:41:18Z

@YutaoMa PTAL!

YutaoMa · 2026-06-29T20:51:43Z

    #[error("stream error: {0}")]
    Stream(#[from] tonic::Status),

+    /// Call credentials failed, or require a secure transport.


Let's remove the feature gating on this error variant, non-additive features in Rust can be a footgun: implicit feature enablement with other dependencies can break compilation.

While we are at it, let's also add #[non_exhaustive] to the Error, it's a miss on my end to not mark it so previously. That'll help with future extensions like this.

Done. Dropped the #[cfg(feature = "transport-tonic")] on CallCredentials and added #[non_exhaustive] to Error. See 447e849.

YutaoMa · 2026-06-29T20:57:14Z

+    /// Generates the authentication metadata for a specific call.
+    async fn get_request_metadata(
+        &self,
+        metadata: &mut tonic::metadata::MetadataMap,


Is there any specific reason to prefer out-param style API? I'd recommend keeping this simple and idiomatic by returning an owned map.

Ah saw the grpc link comment above, seems like it's to keep the style consistent with grpc. In that case yeah it's good to keep it as is.

Yeah, thanks for confirmation!

YutaoMa · 2026-06-29T21:07:41Z

+///
+/// Attached on each (re)connect, only when the channel is secure.
+#[tonic::async_trait]
+pub trait CallCredentials: Send + Sync + std::fmt::Debug + 'static {


Could you re-export this type in tonic-xds so user of tonic-xds doesn't need to explicitly depend on xds-client to use this feature? (xds-client is intended to stay as a low-level ADS transport library so gRPC service developers don't have to depend on it explicitly). Also I suggest naming it TonicCallCredentials here: once we support grpc transport in xds-client, similar API will need to be added for GrpcCallCredentials, keeping the name distinguishable helps with future extensions.

Done. Renamed and re-exported. See 447e849.

choonkijang · 2026-07-01T21:55:07Z

@YutaoMa PTAL!

- Added #[non_exhaustive] to pub enum Error, and remove #[cfg(feature = "transport-tonic")] from `CallCredentials` error entry. - Rename `CallCredentials` as `TonicCallCredentials`, and let `tonic-xds` re-export it to public.

gu0keno0 · 2026-07-07T23:09:23Z

+    }
+
+    #[test]
+    fn selected_credential_unknown_type_skipped() {


Looks like we can combine this test with "selected_credential_none_supported()"

Nice point! Addressed at 3141969.

…done by `selected_credential_none_supported`.

choonkijang · 2026-07-08T05:37:39Z

@YutaoMa @gu0keno0 PTAL.

gu0keno0

PTAL. Thanks for the contribution. I'd like to simplify the states of "secure", "channel" and "per call creds" and avoid invalid states from builder directly.

gu0keno0 · 2026-07-08T18:54:35Z

+    ///
+    /// let builder = TonicTransportBuilder::new().with_channel(channel, true);
+    /// ```
+    pub fn with_channel(mut self, channel: Channel, secure: bool) -> Self {


Is this only needed for test? Maybe gate it by #[cfg(test)]

The reason is that "secure" is not tied to "channel". I wish Tonic had channel.is_secure() -> bool, yet since it doesn't have it, better not to expose ambituity.

It was originally TonicTransport::from_channel function (link), and I brought it here to make it work with with_call_credentials; thinking again upon all your comments, it'd be better to move back to TonicTransport::from_channel to to avoid ambiguous cases rather than gating by #[cfg(test)]. When call-credential is required, the users will be able to make the channel using TonicChannelBuilder instead.

gu0keno0 · 2026-07-08T19:13:16Z

+        if let Some(creds) = &self.call_creds
+            && creds.requires_secure_transport()
+            && !self.secure


It's probably better to check this during TonicTransport build time. If secure == false, always set creds to None.

Good point. Addressed at f44998e.

gu0keno0 · 2026-07-08T19:13:51Z

 #[derive(Clone, Debug)]
 pub struct TonicTransport {
    channel: Channel,
+    secure: bool,


I think we can drop this if we do the check during TonicTransport build time.

Addressed at f44998e.

…onicTransport::from_channel` to avoid invalid states.

choonkijang · 2026-07-08T22:42:07Z

PTAL. Thanks for the contribution. I'd like to simplify the states of "secure", "channel" and "per call creds" and avoid invalid states from builder directly.

Reflected to f44998e. As said reply, TonicTransportBuilder::with_channel moved back to TonicTransport::from_channel. Updated PR description accordingly.

gu0keno0 · 2026-07-08T23:42:09Z

+
+/// Fetches ADC tokens directly from `google-cloud-auth`.
+#[derive(Debug)]
+struct AdcTonicCallCredentials {


I think we might want to support google credentials out-of-box in tonic-xds' xds bootstrap handling in the future, yet that's out of scope for this PR, so no need to do it here.

choonkijang · 2026-07-09T03:19:58Z

Thanks for review! @gu0keno0 and @YutaoMa !

choonkijang · 2026-07-09T05:47:03Z

Well, I don't have sufficient permission to merge this PR to mater. Can I ask merge? @gu0keno0 @YutaoMa Thanks in advance!

gu0keno0 · 2026-07-09T13:21:56Z

Well, I don't have sufficient permission to merge this PR to mater. Can I ask merge? @gu0keno0 @YutaoMa Thanks in advance!

Merged. Thanks again for the feature.

choonkijang mentioned this pull request Jun 25, 2026

Support channel call-credential hook for xDS transport #2702

Open

YutaoMa reviewed Jun 25, 2026

View reviewed changes

Comment thread tonic-xds/Cargo.toml Outdated

YutaoMa reviewed Jun 25, 2026

View reviewed changes

Comment thread xds-client/src/transport/tonic.rs Outdated

YutaoMa reviewed Jun 25, 2026

View reviewed changes

Comment thread xds-client/src/transport/tonic.rs Outdated

Address comments.

3d1a3cf

choonkijang requested a review from YutaoMa June 26, 2026 01:41

YutaoMa reviewed Jun 29, 2026

View reviewed changes

choonkijang force-pushed the feat-xds-call-credentials branch from bed4264 to 47030ae Compare July 1, 2026 21:51

choonkijang requested a review from YutaoMa July 1, 2026 21:54

Address @YutaoMa's comments.

447e849

- Added #[non_exhaustive] to pub enum Error, and remove #[cfg(feature = "transport-tonic")] from `CallCredentials` error entry. - Rename `CallCredentials` as `TonicCallCredentials`, and let `tonic-xds` re-export it to public.

choonkijang force-pushed the feat-xds-call-credentials branch from 47030ae to 447e849 Compare July 1, 2026 22:09

gu0keno0 reviewed Jul 7, 2026

View reviewed changes

Address comment. selected_credential_unknown_type_skipped could be …

3141969

…done by `selected_credential_none_supported`.

choonkijang requested a review from gu0keno0 July 7, 2026 23:29

gu0keno0 reviewed Jul 8, 2026

View reviewed changes

Address review; move TonicTransportBuilder::with_channel back to `T…

f44998e

…onicTransport::from_channel` to avoid invalid states.

choonkijang requested a review from gu0keno0 July 8, 2026 22:44

gu0keno0 approved these changes Jul 9, 2026

View reviewed changes

gu0keno0 merged commit bcdfb5d into grpc:master Jul 9, 2026
26 checks passed

choonkijang deleted the feat-xds-call-credentials branch July 10, 2026 06:19

Uh oh!

Conversation

choonkijang commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Solution

Uh oh!

linux-foundation-easycla Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

choonkijang commented Jun 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

choonkijang Jul 1, 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!

choonkijang Jul 1, 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!

choonkijang commented Jul 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

choonkijang Jul 7, 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!

choonkijang commented Jul 8, 2026

Uh oh!

gu0keno0 left a comment

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!

Uh oh!

choonkijang commented Jul 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

choonkijang commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

choonkijang commented Jul 9, 2026

Uh oh!

Uh oh!

gu0keno0 commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

choonkijang commented Jun 25, 2026 •

edited

Loading

linux-foundation-easycla Bot commented Jun 25, 2026 •

edited

Loading

choonkijang Jul 1, 2026 •

edited

Loading

choonkijang Jul 1, 2026 •

edited

Loading

choonkijang Jul 7, 2026 •

edited

Loading

choonkijang commented Jul 9, 2026 •

edited

Loading