api,core: Add LoadBalancer.acceptResolvedAddresses() (#9498)

Introduces a new acceptResolvedAddresses() method in LoadBalancer that
is to ultimately replace the existing handleResolvedAddresses(). The new
method allows the LoadBalancer implementation to reject the given
addresses by returning false from the method.

The long deprecated handleResolvedAddressGroups is also removed.

api/src/main/java/io/grpc/LoadBalancer.java

@@ -124,39 +124,46 @@ public abstract class LoadBalancer {
    *
    * <p>Implementations should not modify the given {@code servers}.
    *
-   * @param servers the resolved server addresses, never empty.
-   * @param attributes extra information from naming system.
-   * @deprecated override {@link #handleResolvedAddresses(ResolvedAddresses) instead}
-   * @since 1.2.0
+   * @param resolvedAddresses the resolved server addresses, attributes, and config.
+   * @since 1.21.0
    */
-  @Deprecated
-  public void handleResolvedAddressGroups(
-      List<EquivalentAddressGroup> servers,
-      @NameResolver.ResolutionResultAttr Attributes attributes) {
+  public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     if (recursionCount++ == 0) {
-      handleResolvedAddresses(
-          ResolvedAddresses.newBuilder().setAddresses(servers).setAttributes(attributes).build());
+      // Note that the information about the addresses actually being accepted will be lost
+      // if you rely on this method for backward compatibility.
+      acceptResolvedAddresses(resolvedAddresses);
     }
     recursionCount = 0;
   }
 
   /**
-   * Handles newly resolved server groups and metadata attributes from name resolution system.
-   * {@code servers} contained in {@link EquivalentAddressGroup} should be considered equivalent
-   * but may be flattened into a single list if needed.
+   * Accepts newly resolved addresses from the name resolution system. The {@link
+   * EquivalentAddressGroup} addresses should be considered equivalent but may be flattened into a
+   * single list if needed.
    *
-   * <p>Implementations should not modify the given {@code servers}.
+   * <p>Implementations can choose to reject the given addresses by returning {@code false}.
+   *
+   * <p>Implementations should not modify the given {@code addresses}.
    *
    * @param resolvedAddresses the resolved server addresses, attributes, and config.
-   * @since 1.21.0
+   * @return {@code true} if the resolved addresses were accepted. {@code false} if rejected.
+   * @since 1.49.0
    */
-  @SuppressWarnings("deprecation")
-  public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
-    if (recursionCount++ == 0) {
-      handleResolvedAddressGroups(
-          resolvedAddresses.getAddresses(), resolvedAddresses.getAttributes());
+  public boolean acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    if (resolvedAddresses.getAddresses().isEmpty()
+        && !canHandleEmptyAddressListFromNameResolution()) {
+      handleNameResolutionError(Status.UNAVAILABLE.withDescription(
+          "NameResolver returned no usable address. addrs=" + resolvedAddresses.getAddresses()
+              + ", attrs=" + resolvedAddresses.getAttributes()));
+      return false;
+    } else {
+      if (recursionCount++ == 0) {
+        handleResolvedAddresses(resolvedAddresses);
+      }
+      recursionCount = 0;
+
+      return true;
     }
-    recursionCount = 0;
   }
 
   /**

api/src/test/java/io/grpc/LoadBalancerTest.java

@@ -235,13 +235,14 @@ public void createSubchannelArgs_toString() {
 
   @Deprecated
   @Test
-  public void handleResolvedAddressGroups_delegatesToHandleResolvedAddresses() {
+  public void handleResolvedAddresses_delegatesToAcceptResolvedAddresses() {
     final AtomicReference<ResolvedAddresses> resultCapture = new AtomicReference<>();
 
     LoadBalancer balancer = new LoadBalancer() {
         @Override
-        public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+        public boolean acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
           resultCapture.set(resolvedAddresses);
+          return true;
         }
 
         @Override
@@ -260,23 +261,22 @@ public void shutdown() {
     List<EquivalentAddressGroup> servers = Arrays.asList(
         new EquivalentAddressGroup(new SocketAddress(){}),
         new EquivalentAddressGroup(new SocketAddress(){}));
-    balancer.handleResolvedAddressGroups(servers, attrs);
+    ResolvedAddresses addresses = ResolvedAddresses.newBuilder().setAddresses(servers)
+        .setAttributes(attrs).build();
+    balancer.handleResolvedAddresses(addresses);
     assertThat(resultCapture.get()).isEqualTo(
         ResolvedAddresses.newBuilder().setAddresses(servers).setAttributes(attrs).build());
   }
 
   @Deprecated
   @Test
-  public void handleResolvedAddresses_delegatesToHandleResolvedAddressGroups() {
-    final AtomicReference<List<EquivalentAddressGroup>> serversCapture = new AtomicReference<>();
-    final AtomicReference<Attributes> attrsCapture = new AtomicReference<>();
+  public void acceptResolvedAddresses_delegatesToHandleResolvedAddressGroups() {
+    final AtomicReference<ResolvedAddresses> addressesCapture = new AtomicReference<>();
 
     LoadBalancer balancer = new LoadBalancer() {
         @Override
-        public void handleResolvedAddressGroups(
-            List<EquivalentAddressGroup> servers, Attributes attrs) {
-          serversCapture.set(servers);
-          attrsCapture.set(attrs);
+        public void handleResolvedAddresses(ResolvedAddresses addresses) {
+          addressesCapture.set(addresses);
         }
 
         @Override
@@ -295,25 +295,23 @@ public void shutdown() {
     List<EquivalentAddressGroup> servers = Arrays.asList(
         new EquivalentAddressGroup(new SocketAddress(){}),
         new EquivalentAddressGroup(new SocketAddress(){}));
-    balancer.handleResolvedAddresses(
-        ResolvedAddresses.newBuilder().setAddresses(servers).setAttributes(attrs).build());
-    assertThat(serversCapture.get()).isEqualTo(servers);
-    assertThat(attrsCapture.get()).isEqualTo(attrs);
+    ResolvedAddresses addresses = ResolvedAddresses.newBuilder().setAddresses(servers)
+        .setAttributes(attrs).build();
+    balancer.handleResolvedAddresses(addresses);
+    assertThat(addressesCapture.get().getAddresses()).isEqualTo(servers);
+    assertThat(addressesCapture.get().getAttributes()).isEqualTo(attrs);
   }
 
   @Deprecated
   @Test
-  public void handleResolvedAddresses_noInfiniteLoop() {
-    final List<List<EquivalentAddressGroup>> serversCapture = new ArrayList<>();
-    final List<Attributes> attrsCapture = new ArrayList<>();
+  public void acceptResolvedAddresses_noInfiniteLoop() {
+    final List<ResolvedAddresses> addressesCapture = new ArrayList<>();
 
     LoadBalancer balancer = new LoadBalancer() {
       @Override
-      public void handleResolvedAddressGroups(
-          List<EquivalentAddressGroup> servers, Attributes attrs) {
-        serversCapture.add(servers);
-        attrsCapture.add(attrs);
-        super.handleResolvedAddressGroups(servers, attrs);
+      public void handleResolvedAddresses(ResolvedAddresses addresses) {
+        addressesCapture.add(addresses);
+        super.handleResolvedAddresses(addresses);
       }
 
       @Override
@@ -328,12 +326,12 @@ public void shutdown() {
     List<EquivalentAddressGroup> servers = Arrays.asList(
         new EquivalentAddressGroup(new SocketAddress(){}),
         new EquivalentAddressGroup(new SocketAddress(){}));
-    balancer.handleResolvedAddresses(
-        ResolvedAddresses.newBuilder().setAddresses(servers).setAttributes(attrs).build());
-    assertThat(serversCapture).hasSize(1);
-    assertThat(attrsCapture).hasSize(1);
-    assertThat(serversCapture.get(0)).isEqualTo(servers);
-    assertThat(attrsCapture.get(0)).isEqualTo(attrs);
+    ResolvedAddresses addresses = ResolvedAddresses.newBuilder().setAddresses(servers)
+        .setAttributes(attrs).build();
+    balancer.handleResolvedAddresses(addresses);
+    assertThat(addressesCapture).hasSize(1);
+    assertThat(addressesCapture.get(0).getAddresses()).isEqualTo(servers);
+    assertThat(addressesCapture.get(0).getAttributes()).isEqualTo(attrs);
   }
 
   private static class NoopHelper extends LoadBalancer.Helper {

core/src/main/java/io/grpc/internal/AutoConfiguredLoadBalancerFactory.java

@@ -20,11 +20,9 @@
 
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects;
-import io.grpc.Attributes;
 import io.grpc.ChannelLogger.ChannelLogLevel;
 import io.grpc.ConnectivityState;
 import io.grpc.ConnectivityStateInfo;
-import io.grpc.EquivalentAddressGroup;
 import io.grpc.LoadBalancer;
 import io.grpc.LoadBalancer.Helper;
 import io.grpc.LoadBalancer.PickResult;
@@ -67,10 +65,14 @@ private static final class NoopLoadBalancer extends LoadBalancer {
 
     @Override
     @Deprecated
-    public void handleResolvedAddressGroups(List<EquivalentAddressGroup> s, Attributes a) {}
+    @SuppressWarnings("InlineMeSuggester")
+    public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    }
 
     @Override
-    public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {}
+    public boolean acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+      return true;
+    }
 
     @Override
     public void handleNameResolutionError(Status error) {}
@@ -97,14 +99,10 @@ public final class AutoConfiguredLoadBalancer {
     }
 
     /**
-     * Returns non-OK status if resolvedAddresses is empty and delegate lb requires address ({@link
-     * LoadBalancer#canHandleEmptyAddressListFromNameResolution()} returns {@code false}). {@code
-     * AutoConfiguredLoadBalancer} doesn't expose {@code
-     * canHandleEmptyAddressListFromNameResolution} because it depends on the delegated LB.
+     * Returns non-OK status if the delegate rejects the resolvedAddresses (e.g. if it does not
+     * support an empty list).
      */
-    Status tryHandleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
-      List<EquivalentAddressGroup> servers = resolvedAddresses.getAddresses();
-      Attributes attributes = resolvedAddresses.getAttributes();
+    boolean tryAcceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       PolicySelection policySelection =
           (PolicySelection) resolvedAddresses.getLoadBalancingPolicyConfig();
 
@@ -118,7 +116,7 @@ Status tryHandleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
           delegate.shutdown();
           delegateProvider = null;
           delegate = new NoopLoadBalancer();
-          return Status.OK;
+          return true;
         }
         policySelection =
             new PolicySelection(defaultProvider, /* config= */ null);
@@ -141,20 +139,12 @@ Status tryHandleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
             ChannelLogLevel.DEBUG, "Load-balancing config: {0}", policySelection.config);
       }
 
-      LoadBalancer delegate = getDelegate();
-      if (resolvedAddresses.getAddresses().isEmpty()
-          && !delegate.canHandleEmptyAddressListFromNameResolution()) {
-        return Status.UNAVAILABLE.withDescription(
-            "NameResolver returned no usable address. addrs=" + servers + ", attrs=" + attributes);
-      } else {
-        delegate.handleResolvedAddresses(
-            ResolvedAddresses.newBuilder()
-                .setAddresses(resolvedAddresses.getAddresses())
-                .setAttributes(attributes)
-                .setLoadBalancingPolicyConfig(lbConfig)
-                .build());
-        return Status.OK;
-      }
+      return getDelegate().acceptResolvedAddresses(
+          ResolvedAddresses.newBuilder()
+              .setAddresses(resolvedAddresses.getAddresses())
+              .setAttributes(resolvedAddresses.getAttributes())
+              .setLoadBalancingPolicyConfig(lbConfig)
+              .build());
     }
 
     void handleNameResolutionError(Status error) {

core/src/main/java/io/grpc/internal/ManagedChannelImpl.java

@@ -1852,16 +1852,17 @@ public void run() {
                   .set(LoadBalancer.ATTR_HEALTH_CHECKING_CONFIG, healthCheckingConfig)
                   .build();
             }
+            Attributes attributes = attrBuilder.build();
 
-            Status handleResult = helper.lb.tryHandleResolvedAddresses(
+            boolean addressesAccepted = helper.lb.tryAcceptResolvedAddresses(
                 ResolvedAddresses.newBuilder()
                     .setAddresses(servers)
-                    .setAttributes(attrBuilder.build())
+                    .setAttributes(attributes)
                     .setLoadBalancingPolicyConfig(effectiveServiceConfig.getLoadBalancingConfig())
                     .build());
 
-            if (!handleResult.isOk()) {
-              handleErrorInSyncContext(handleResult.augmentDescription(resolver + " was used"));
+            if (!addressesAccepted) {
+              scheduleExponentialBackOffInSyncContext();
             }
           }
         }

core/src/main/java/io/grpc/util/ForwardingLoadBalancer.java

@@ -17,14 +17,10 @@
 package io.grpc.util;
 
 import com.google.common.base.MoreObjects;
-import io.grpc.Attributes;
 import io.grpc.ConnectivityStateInfo;
-import io.grpc.EquivalentAddressGroup;
 import io.grpc.ExperimentalApi;
 import io.grpc.LoadBalancer;
-import io.grpc.NameResolver;
 import io.grpc.Status;
-import java.util.List;
 
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
 public abstract class ForwardingLoadBalancer extends LoadBalancer {
@@ -34,16 +30,13 @@ public abstract class ForwardingLoadBalancer extends LoadBalancer {
   protected abstract LoadBalancer delegate();
 
   @Override
-  @Deprecated
-  public void handleResolvedAddressGroups(
-        List<EquivalentAddressGroup> servers,
-        @NameResolver.ResolutionResultAttr Attributes attributes) {
-    delegate().handleResolvedAddressGroups(servers, attributes);
+  public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    delegate().handleResolvedAddresses(resolvedAddresses);
   }
 
   @Override
-  public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
-    delegate().handleResolvedAddresses(resolvedAddresses);
+  public boolean acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    return delegate().acceptResolvedAddresses(resolvedAddresses);
   }
 
   @Override