feat(grpc) Add channel credentials API + Insecure credentials by arjan-bal · Pull Request #2495 · hyperium/tonic

arjan-bal · 2026-02-04T20:24:44Z

This change introduces a channel credentials API to abstract over TLS/Insecure/Local credentials. Implementations for TLS and local credentials will follow in future PRs.

Key Changes

Renamed rt::TcpStream to GrpcEndpoint to reflect a more generic connection interface.
GrpcEndpoint is now sealed. This allows us to change the API in the future (e.g., to align with gRPC C++) without breaking changes. This restricts implementations of rt::Runtime and channel credentials to the grpc crate.

Other changes

Most credential components are pub(crate) as users can't to implement them due to GrpcEndpoint trait being sealed.
Restricted the rt module to pub(crate) and exposed Runtime as pub to resolve private_bounds lints when using runtime types in pub APIs.

grpc/src/rt/hyper_wrapper.rs

grpc/src/credentials/client.rs

grpc/src/client/name_resolution/dns/test.rs

grpc/src/credentials/dyn_wrapper.rs

grpc/src/credentials/insecure.rs

grpc/src/credentials/dyn_wrapper.rs

sauravzg

PR looks good overall. Please address the comments about unit test.

…plementations

grpc/src/send_future.rs

LucioFranco · 2026-02-11T22:49:47Z

grpc/src/credentials/client.rs

+pub trait Sealed {
+    type ContextType: ClientConnectionSecurityContext;
+    type Output<I>;
+    /// Performs the client-side authentication handshake on a raw endpoint.


dont think you need the duplicate docs on the sealed trait?

The trait-level documentation for the externally reachable sub-trait is quite abstract and doesn't cover the specific methods. Even though this method isn't exposed externally, I think keeping the docs is valuable for internal maintainability and for developers using IDE features like hover-to-preview. What do you think?

iirc the trait you actually interact with is the root one not the sealed one so I think just having docs on the main trait is enough and keeping the sealed one a mirror of the type interface makes more sense.

I'm not quite following this. Could you provide a rough sketch of how the supertrait and subtrait would look? Also, please take a look at my comment below describing the existing approach.

LucioFranco · 2026-02-12T15:04:22Z

grpc/src/credentials/client.rs

+    pub(crate) security_protocol: &'static str,
+    pub(crate) security_level: SecurityLevel,
+    pub(crate) security_context: C,
+    /// Stores extra data derived from the underlying protocol.
+    pub(crate) attributes: Attributes,
+}


not a big fan of tons of pub(crates) makes refactoring things later much harder. Something we can maybe discuss as a group but I tend to want to keep a lot of things function based rather than field based.

Removed the use of exported fields throughout.

LucioFranco · 2026-02-12T15:05:24Z

grpc/src/credentials/dyn_wrapper.rs

+        (
+            Box<dyn GrpcEndpoint>,
+            ClientConnectionSecurityInfo<Box<dyn ClientConnectionSecurityContext>>,
+        ),


Think this should just return a struct this is really hard to read due to being a tuple

Introduced a HandshakeOutput struct to replace the tupple.

LucioFranco · 2026-02-12T15:05:45Z

grpc/src/credentials/dyn_wrapper.rs

+impl<T> DynClientChannelCredential for T
+where
+    T: ClientChannelCredential,
+    T::Output<BoxEndpoint>: GrpcEndpoint + 'static,


if grpcEndpoint is almost always static just promote the 'static to the trait bounds trait Foo: 'static

Moved the 'static bound to GrpcEndpoint trait.

LucioFranco · 2026-02-12T15:06:19Z

grpc/src/credentials/dyn_wrapper.rs

+            .make_send()
+            .await?;
+
+        let boxed_stream: BoxEndpoint = Box::new(stream);


should be able to drop this type hint here, its funneled right into a fixed return type.

You're correct, removed.

LucioFranco · 2026-02-12T15:07:07Z

grpc/src/credentials/dyn_wrapper.rs

+    async fn accept(
+        &self,
+        source: BoxEndpoint,
+        runtime: Arc<dyn Runtime>,


nit: probably should just make this GrpcRuntime or just grpc::Runtime that wraps the arc internally

Added a GrpcRuntime type as suggested and removed Arc from all method signatures.

LucioFranco · 2026-02-12T15:09:21Z

grpc/src/credentials/insecure.rs

+    }
+}
+
+impl server::Sealed for InsecureServerChannelCredentials {


seems like the patterns of sealed traits have changed bit since I last looked at them, I would just say double check the patterns here https://predr.ag/blog/definitive-guide-to-sealed-traits-in-rust/ I trust predrag and we use semver checks. If you think this is following that I am good on that I trust you to make the right choice here.

After reading a few different sources, I realized the pattern I'm using isn't exactly the standard "sealed trait" pattern.

In my case, I want to ensure all the methods on the trait are only callable from within the crate. Most guides on the sealed pattern don't actually add methods to the sealed trait itself.

The official Rust guidelines suggest adding a #[doc(hidden)] macro to private methods. However, this is just a gentleman's agreement. External crates can still call the method, though we reserve the right to break their code if they do.

Predrag's blog suggests adding an unnameable type parameter to each private method. However, this pollutes the call sites.

Jack Wrenn's blog mentions the technique I'm currently following: adding the private methods to a "pub-in-priv" trait. The only downside mentioned is that this pattern can't be applied to an existing public trait without causing breaking changes for downstream users.

In my opinion, Option 3 is the best solution for us. It guarantees that private methods are not callable externally, and the call sites remain clean. I've renamed these private traits to XXXInternal to avoid confusion with the regular Sealed pattern.

I would love to hear your thoughts on this approach.

LucioFranco · 2026-02-12T15:09:58Z

grpc/src/credentials/mod.rs

+
+/// Defines the common interface for all live gRPC wire protocols and supported
+/// transport security protocols (e.g., TLS, ALTS).
+pub trait ClientChannelCredential: client::Sealed + Sync {


Why do these need Sync? I assume they would also get send and 'static?

When using a load balancing policy that manages multiple TCP connections (e.g., round_robin, ringhash, or least_request), multiple concurrent connections may be established. Consequently, the same credentials object must be wrapped in an Arc to be shared during the handshaking process.

Yes, it should be 'static. The static bound was being applied in the channel constructor. I've moved it to the trait now.

LucioFranco · 2026-02-12T15:12:02Z

grpc/src/send_future.rs

+/// [#96865]: https://github.com/rust-lang/rust/issues/96865
+/// [`Future`]: core::future::Future
+/// [`Send`]: core::marker::Send
+pub trait SendFuture: core::future::Future {


This is interesting, and makes a ton of sense. Assuming this is totally fine since the compiler will noop this out.

LucioFranco

Really nice work! This seems like a fantastic foundation going forward. Left some comments none are blocking.

grpc/examples/inmemory.rs

grpc/src/client/channel.rs

grpc/src/credentials/mod.rs

dfawley · 2026-02-12T18:49:40Z

grpc/src/credentials/mod.rs

+    pub struct Authority<'a> {
+        pub(crate) host: &'a str,


Why are we attaching a lifetime here? Should this be an owned String instead?

Accepting a reference allows implementations to avoid unnecessary copies in most cases. The channel likely maintains a url::Url type and uses the host_str method to retrieve the authority for the credentials. Requiring an owned string would force the channel to perform a copy, which would then be consumed by the credentials during the handshake.

That's once per connection? It seems like avoiding having lifetimes on structs would be worth the cost of a clone per connection. And even if it was performance-critical, could the [sub?]channel save away an Authority instance that it passes (by reference already) to all the handshakers?

The connect and accept methods are already accepting &Authority, so it should be possible for the channel to re-use the same Authority object. I've replaced the &str with a String in the host field.

dfawley

(I suppose I should specifically request changes so the PR doesn't appear green.)

dfawley

Everything else LGTM, but I really, really want to work hard to avoid having lifetimes on any structs (especially public-visible ones) unless absolutely necessary, as it can quickly become a huge cognitive burden. E.g. as soon as you want to put it into another struct, that one needs a lifetime, too.

arjan-bal added 6 commits February 4, 2026 14:44

Seal GrpcEndpoint trait

a78bfdc

credentials API and insecure client credentials

2e49336

Revert visibility changes in rt

ea04054

fix visibility

278f1f0

polish

e0364c7

insecure server channel creds

dfe9d72

arjan-bal added the A-grpc-next label Feb 4, 2026

arjan-bal requested review from dfawley and sauravzg February 4, 2026 20:32

arjan-bal assigned dfawley and sauravzg and unassigned sauravzg Feb 4, 2026

bring back security level for integrity only

afd98f7

sauravzg reviewed Feb 5, 2026

View reviewed changes

grpc/src/rt/hyper_wrapper.rs Show resolved Hide resolved

sauravzg reviewed Feb 5, 2026

View reviewed changes

grpc/src/credentials/client.rs Show resolved Hide resolved

sauravzg reviewed Feb 5, 2026

View reviewed changes

grpc/src/credentials/client.rs Outdated Show resolved Hide resolved

sauravzg reviewed Feb 5, 2026

View reviewed changes

grpc/src/client/name_resolution/dns/test.rs Show resolved Hide resolved

don't use async_trait

3cbb3c9

arjan-bal force-pushed the channel-creds-api branch from 7841232 to 954c3bc Compare February 6, 2026 12:29

add send_future to workaround

a0cbbf2

arjan-bal force-pushed the channel-creds-api branch from 954c3bc to a0cbbf2 Compare February 6, 2026 12:30

arjan-bal assigned sauravzg Feb 6, 2026

sauravzg reviewed Feb 9, 2026

View reviewed changes

grpc/src/credentials/dyn_wrapper.rs Show resolved Hide resolved

sauravzg reviewed Feb 9, 2026

View reviewed changes

grpc/src/credentials/insecure.rs Show resolved Hide resolved

sauravzg reviewed Feb 9, 2026

View reviewed changes

grpc/src/credentials/dyn_wrapper.rs Outdated Show resolved Hide resolved

sauravzg approved these changes Feb 9, 2026

View reviewed changes

arjan-bal added 4 commits February 9, 2026 21:00

Merge remote-tracking branch 'source/master' into channel-creds-api

53459ac

add tests for insecure client creds

90a25d4

Add tests for client dyn_wrapper

badd587

Use target addr from param

93f651f

arjan-bal assigned ankurmittal and LucioFranco and unassigned sauravzg Feb 10, 2026

Make endpoint::sealed pub(crate) to enable first party credentials im…

1113046

…plementations

dfawley reviewed Feb 11, 2026

View reviewed changes

grpc/src/send_future.rs Outdated Show resolved Hide resolved

dfawley reviewed Feb 11, 2026

View reviewed changes

grpc/src/send_future.rs Outdated Show resolved Hide resolved

Fix doc

ce602a1

arjan-bal force-pushed the channel-creds-api branch from ed08934 to ce602a1 Compare February 11, 2026 20:41

LucioFranco reviewed Feb 11, 2026

View reviewed changes

LucioFranco reviewed Feb 12, 2026

View reviewed changes

LucioFranco approved these changes Feb 12, 2026

View reviewed changes

dfawley reviewed Feb 12, 2026

View reviewed changes

dfawley requested changes Feb 12, 2026

View reviewed changes

arjan-bal added 2 commits February 13, 2026 23:29

Address review comments

f65e4a7

Fix CI

7b56a17

arjan-bal force-pushed the channel-creds-api branch from de43a76 to 7b56a17 Compare February 13, 2026 18:34

arjan-bal requested review from LucioFranco and dfawley February 13, 2026 18:37

dfawley approved these changes Feb 13, 2026

View reviewed changes

arjan-bal added 2 commits February 16, 2026 13:29

Remove reference from Authority struct

671a2e6

Merge remote-tracking branch 'source/master' into channel-creds-api

3ed58a3

arjan-bal merged commit 149f366 into hyperium:master Feb 16, 2026
21 checks passed

arjan-bal deleted the channel-creds-api branch February 16, 2026 08:27

Conversation

arjan-bal commented Feb 4, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sauravzg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

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!

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!

LucioFranco left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

dfawley left a comment

Choose a reason for hiding this comment

Uh oh!

dfawley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

arjan-bal commented Feb 4, 2026 •

edited

Loading