Notice: Upcoming Experimental Balancer/Resolver API Changes

[dfawley]

As we work toward stabilization of the experimental resolver/balancer plugin APIs, the gRPC team will be making several non-backward compatible changes to enable new functionality and better extensibility for the future. These changes are not strictly following semantic versioning or the Go compatibility promise, but they are in accordance with our versioning policy as the changes are limited to experimental APIs.

Items will be checked off of the following list as they are completed.

Cleanups

• Rename resolver.BuildOption to BuildOptions (resolver: rename Option to Options, leaving type aliases for now #3175)
• Rename resolver.ResolveNowOption to ResolveNowOptions (resolver: rename Option to Options, leaving type aliases for now #3175)
• Rename balancer.PickOptions to PickInfo (balancer: add V2Picker, ClientConn.UpdateState, SubConnState.ConnectionError #3186)

For the short-term, to allow an easier migration, type aliases will be put in place for the old symbols.

balancer Package

• Add V2Picker (eventually replacing Picker), featuring changed semantics to allow for new capabilities, and for future-proofing. (balancer: add V2Picker, ClientConn.UpdateState, SubConnState.ConnectionError #3186)
• Add ClientConn.UpdateState (eventually replacing UpdateBalancerState). This is future-proofing to allow addition of new items in the balancer's state, and contains a V2Picker instead of Picker. (balancer: add V2Picker, ClientConn.UpdateState, SubConnState.ConnectionError #3186)

Changes planned for the 1.27 release (December 17 - January 28)

• Remove all type aliases above and references to the old names. (balancer/resolver: remove temporary backward-compatibility type aliases #3309)

Changes planned for the 1.30 release (March 21 - June 2)

• Replace balancer.Balancer and balancer.Picker with the V2Balancer and V2Picker versions. To allow an easier migration for users currently referencing the V2 names, create type aliases. (Typically, referencing these interface types should not be necessary.) (balancer: move Balancer and Picker to V2; delete legacy API #3431)
• Remove balancer.ClientConn.UpdateBalancerState. (balancer: move Balancer and Picker to V2; delete legacy API #3431)
• Remove the original balancer plugin API, based on grpc.Balancer, and all related functionality. (balancer: move Balancer and Picker to V2; delete legacy API #3431)
• Remove the deprecated naming package. (balancer: move Balancer and Picker to V2; delete legacy API #3431)

Changes planned for the 1.31 release (June 2 - July 14)

• Remove the V2Balancer and V2Picker type aliases, and base package "V2" references. (balancer: remove deprecated type aliases as planned #3742)

The resolver and balancer APIs will be kept in the experimental state after these changes, as there may be more breaking changes needed in the near future.

[samsalisbury]

Hi @dfawley, even though these changes were to "experimental" APIs, multiple external projects do depend on them, at different versions of this library. This is a significant problem for the Go ecosystem because any project trying to import recent versions of (for example) both cloud.google.com/go and go.etcd.io/etcd are unable to build, since they both depend different versions within major version 1 of this module, one before and one after these breaking changes. This means downstream projects are stuck on much older versions of those libraries as well as grpc-go itself. Would you consider changing the versioning policy to observe the Go compatibility promise?

In the meantime, would you consider adding type aliases so that code which relies on both the old and new names of these types can still compile?

[dfawley]

@samsalisbury ,

Would you consider changing the versioning policy to observe the Go compatibility promise?

It was a mistake for any other projects to use these packages without transitively marking themselves as experimental. Unfortunately the Go compatibility promise doesn't have any convention that allows us to experiment with APIs to see what will work well for our users or to release functionality before it's fully supported for advanced users that can tolerate instability. We've discussed using separate modules (at v0) for this purpose, but it oftentimes isn't technically possible to achieve the separation needed for this.

In the meantime, would you consider adding type aliases so that code which relies on both the old and new names of these types can still compile?

We had type aliases in place for the 1.26 release, and marked them as deprecated, in order to allow projects a chance to do a smooth migration. Unfortunately, we cannot leave type aliases in place forever; projects will need to upgrade.

Sorry for any disturbances this has caused.

[samsalisbury]

Hi, thanks for the response @dfawley, most conversation happening in #3500 now I think. I think it seems like a reasonable desire (to want to add things that should not be depended on yet) but unfortunately I don't think relying on the eternal vigilance of multiple parties to always respect this rule is likely to work in the long term, especially as it is special to this repository or organisation. The good thing about go's compatibility rules are that they are at least a single standard that everyone could probably bend to if they wanted, for the sake of the ecosystem. Rather than relying on eternal vigilance, they have built tools that break builds when these rules are not followed, which at least is some kind of feedback projects will hit eventually.