Skip to content

grpc: expose unstable APIs behind __unstable feature#2728

Open
dfawley wants to merge 2 commits into
grpc:masterfrom
dfawley:unstable
Open

grpc: expose unstable APIs behind __unstable feature#2728
dfawley wants to merge 2 commits into
grpc:masterfrom
dfawley:unstable

Conversation

@dfawley

@dfawley dfawley commented Jul 9, 2026

Copy link
Copy Markdown
Member

We'd like to implement our own features outside of the grpc crate that require unstable APIs in the grpc crate. If we don't implement them in foreign crates, then the situation quickly devolves into "all things must be inside the grpc crate behind feature flags".

This PR introduces an __unstable feature flag that publicly re-exports the runtime, LB policy, name resolver, and service config modules, but under a top-level __unstable module path to make it as obvious as possible that these features are unstable and should not be relied upon by end users. It also doc-hides them for two purposes:

  1. to prevent them from rendering on docs.rs.
  2. to allow for some unstable things to use foreign external types, at least for now (mainly: serde symbols for LB policy config). (The check-external-types checker we run automatically ignores doc-hidden symbols.)

This PR then makes public many symbols that were previously private or pub(crate), so that they can be exported via the __unstable module.

cc @gu0keno0 - I think your xds protos change (#2723) should just go ahead and put the protos into a new grpc-xds crate which will subsequently be free to use these unstable APIs.

@dfawley dfawley added this to the grpc-next milestone Jul 9, 2026
@dfawley dfawley requested review from LucioFranco and ejona86 July 9, 2026 18:25

@gu0keno0 gu0keno0 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some nits / clarification questions.

Comment thread grpc/src/client/service_config.rs Outdated
Comment thread grpc/src/client/load_balancing/subchannel.rs
Comment thread grpc/src/lib.rs
Comment thread grpc/src/client/load_balancing/mod.rs
@gu0keno0

gu0keno0 commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

Thanks, it will be great if we can make grpc-xds cleanly separated. My intuition is that it might make 3rd party customization (e.g. custom LB) as capable as the built-in LBs -- great!

@ejona86 ejona86 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't seem too hard to reason about, as there are clear groupings that are pretty easy to remember ("the things that are unstable in any language that exposes them"; name resolver, lb, lower-level transport details aka runtime)

Comment thread grpc/src/client/load_balancing/mod.rs
Comment thread grpc/src/client/service_config.rs Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants