Add public constants for "pick_first" and "round_robin" policy names in LoadBalancerRegistry

[JJong-Min]

Is your feature request related to a problem?

The built-in load balancing policy names "round_robin" and "pick_first" are hardcoded as string literals throughout the codebase and by library users.
This leads to:

• Magic strings — typos like "round_robbin" can only be caught at runtime
• Poor discoverability — users can't find available policy names via IDE autocomplete
• No single source of truth — the only constant (ROUND_ROBIN_FIELD_NAME in LoadBalancerConfigFactory) is package-private and limited to the xds module
• Fragile user code — library users are forced to write code like defaultLoadBalancingPolicy("round_robin") or getProvider("pick_first") with raw strings, making their code vulnerable to silent misconfiguration that only manifests as unexpected runtime behavior

Describe the solution you'd like

Add public constants to LoadBalancerRegistry:

public static final String PICK_FIRST_POLICY_NAME = "pick_first";
public static final String ROUND_ROBIN_POLICY_NAME = "round_robin";

LoadBalancerRegistry is the natural home because it is the public API entry point where users look up providers via getProvider(String policy). Then replace all hardcoded string literals in main, test, and example sources with these constants.

Describe alternatives you've considered

• Adding constants to GrpcUtil — rejected because GrpcUtil is in the io.grpc.internal package and not intended for external use, even though it already has DEFAULT_LB_POLICY = "pick_first".
• Creating a new dedicated constants class (e.g., LoadBalancingPolicies) — rejected as unnecessary; LoadBalancerRegistry already serves as the central API for policy lookup.

Additional context

• The implicit API contract already exists — users already depend on these string values.
• This change makes the existing contract explicit, improving type safety and discoverability.
• GrpcUtil.DEFAULT_LB_POLICY (internal) can be updated to reference the new public constant.

[manmohak07]

Hi @JJong-Min, like you said, we can add the public constants to LoadBalancerRegistry, and then use those constants instead of the hardcoded strings and that's fine.

But I had two questions.
i) Is there any specific file that we want to exclude?
ii) Some test files have hardcode JSON strings(example below). Do we want to make changes here as well? If yes, then what should it look like?

String lbConfig = "{\"childPolicy\" : [{\"pick_first\" : {}}, {\"round_robin\" : {}}]}";

[shivaspeaks]

We’d like to understand the specific use cases where application code needs to manually look up these built-in providers (like pick_first or round_robin) via the LoadBalancerRegistry.

Typically, the LoadBalancerRegistry is intended for application code to manage and look up custom load balancing policies that they have registered. For built-in policies, users generally configure them by name via the ManagedChannelBuilder.defaultLoadBalancingPolicy(String) API. The concern regarding "magic strings" seems valid if you are trying to change that default to "round_robin".

[manmohak07]

I think this is more about preventing typos, as users don't have to manually type "round_robin" or "pick_first" then. But I totally agree on what you mentioned about custom load balancing policies vs the built-in ones.

How should the default work? Like if there's a type or like how should we detect a mistake to default to "round_robin"?

[JJong-Min]

@manmohak07

i) Is there any specific file that we want to exclude?

i) No specific files need to be excluded. All main, test, and example sources that reference these policy names as Java string literals should use the constants.

ii) Some test files have hardcode JSON strings(example below). Do we want to make changes here as well? If yes, then what should it look like?

ii) Hardcoded JSON strings like the example should not be changed. These are raw JSON configuration strings, and replacing parts of them with constant references(e.g., string concatenation) would hurt readability without meaningful benefit. The constants are intended for Java API calls like getProvider(), defaultLoadBalancingPolicy(), and assertions — not for embedded JSON.

[JJong-Min]

@shivaspeaks
Thank you for the feedback.
I agree that LoadBalancerRegistry is primarily intended for managing custom policies, and placing built-in policy name constants there may not be the best fit.

We considered placing the constants in user-facing classes like ManagedChannelBuilder or LoadBalancerProvider, which would be convenient from the user's perspective. However, these constants also need to be used internally by the library (e.g., in getPolicyName() implementations), and having internal code depend on constants defined in a user-facing API class doesn't seem appropriate.

Instead, we think a dedicated constants class like LoadBalancingPolicies in the io.grpc package might be a cleaner approach. It keeps the responsibility clear — a single place for built-in policy name constants that both users and internal code can reference without polluting the responsibilities of existing classes.

  public final class LoadBalancingPolicies {
      public static final String PICK_FIRST = "pick_first";
      public static final String ROUND_ROBIN = "round_robin";
      ...

      private LoadBalancingPolicies() {}
  }

What do you think?

[JJong-Min]

@manmohak07

How should the default work? Like if there's a type or like how should we detect a mistake to default to "round_robin"?

Ideally, enforcing the type with an enum would be the safest approach to prevent typos and invalid values at compile time. However, since defaultLoadBalancingPolicy() needs to accept custom policy names registered by users, changing the parameter type from String to enum is not feasible.

Given that constraint, I think rather than falling back to a default policy on typos or unrecognized names, it would be better to provide a more detailed error message.
Currently, when an unregistered policy name is passed, the error message only suggests registering a custom provider. It could additionally guide users to the available built-in policy names.

For example, if we introduce a dedicated constants class like LoadBalancingPolicies, the error message could point users to it:

Could not find policy ${given_user_value}. If you intended to use a built-in policy,
see LoadBalancingPolicies for available names.
For custom policies, make sure its implementation is either registered to LoadBalancerRegistry
or included in META-INF/services/io.grpc.LoadBalancerProvider from your jar files.

This way, users who made a typo can quickly identify the issue, while users implementing custom policies still get the existing guidance.

[shivaspeaks]

We discussed internally and we agree the risk of typos in defaultLoadBalancingPolicy() is a valid concern, but we believe the better approach is to improve runtime validation on the application. So we have decided not to add public constants. These strings are intended to be dynamic and provided externally through service config. Hardcoding them into the API encourages static configuration and forces the registry to act as a "single source of truth" for specific policies, which contradicts its design as a discovery mechanism. Policies and configs are runtime entities, so compile time constants might also be inconsistent with the registry.

Having said that we aim towards moving the validation check from the build phase to the defaultLoadBalancingPolicy(String) setter itself. This way, an invalid policy name will trigger an immediate exception during configuration, allowing typos to be caught early enough. I've created a tracking issue for the same #12695.

I'll close this issue as WAI.