loadbalancer-experimental: Make some of the types public

Motivation:

We want to be able to use the experimental load balancer
from other packages but we can't because the types are all
private.

Modifications:

- Make a bunch of helpful interfaces public
- Add `DelegatingLoadBalancerBuilder` for symmetry with round robin

Author: bryce-anderson

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/DelegatingLoadBalancerBuilder.java

@@ -0,0 +1,111 @@
+/*
+ * Copyright © 2024 Apple Inc. and the ServiceTalk project authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.servicetalk.loadbalancer;
+
+import io.servicetalk.client.api.LoadBalancedConnection;
+import io.servicetalk.client.api.LoadBalancerFactory;
+import io.servicetalk.concurrent.api.Executor;
+
+import java.time.Duration;
+import javax.annotation.Nullable;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * A {@link LoadBalancerBuilder} that delegates all methods to another {@link LoadBalancerBuilder}.
+ *
+ * @param <ResolvedAddress> The resolved address type.
+ * @param <C> The type of connection.
+ */
+public class DelegatingLoadBalancerBuilder<ResolvedAddress, C extends LoadBalancedConnection>
+        implements LoadBalancerBuilder<ResolvedAddress, C> {
+
+    private LoadBalancerBuilder<ResolvedAddress, C> delegate;
+
+    /**
+     * Creates a new builder which delegates to the provided {@link LoadBalancerBuilder}.
+     *
+     * @param delegate the delegate builder.
+     */
+    public DelegatingLoadBalancerBuilder(final LoadBalancerBuilder<ResolvedAddress, C> delegate) {
+        this.delegate = requireNonNull(delegate, "delegate");
+    }
+
+    /**
+     * Returns the {@link DelegatingLoadBalancerBuilder} delegate.
+     *
+     * @return Delegate {@link DelegatingLoadBalancerBuilder}.
+     */
+    protected final LoadBalancerBuilder<ResolvedAddress, C> delegate() {
+        return delegate;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> loadBalancingPolicy(
+            LoadBalancingPolicy<ResolvedAddress, C> loadBalancingPolicy) {
+        delegate = delegate.loadBalancingPolicy(loadBalancingPolicy);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> loadBalancerObserver(
+            @Nullable LoadBalancerObserver<ResolvedAddress> loadBalancerObserver) {
+        delegate = delegate.loadBalancerObserver(loadBalancerObserver);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> healthCheckerFactory(
+            HealthCheckerFactory<ResolvedAddress> healthCheckerFactory) {
+        delegate = delegate.healthCheckerFactory(healthCheckerFactory);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> backgroundExecutor(Executor backgroundExecutor) {
+        delegate = delegate.backgroundExecutor(backgroundExecutor);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> linearSearchSpace(int linearSearchSpace) {
+        delegate = delegate.linearSearchSpace(linearSearchSpace);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> healthCheckInterval(Duration interval, Duration jitter) {
+        delegate = delegate.healthCheckInterval(interval, jitter);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> healthCheckResubscribeInterval(Duration interval, Duration jitter) {
+        delegate = delegate.healthCheckResubscribeInterval(interval, jitter);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerBuilder<ResolvedAddress, C> healthCheckFailedConnectionsThreshold(int threshold) {
+        delegate = delegate.healthCheckFailedConnectionsThreshold(threshold);
+        return this;
+    }
+
+    @Override
+    public LoadBalancerFactory<ResolvedAddress, C> build() {
+        return delegate.build();
+    }
+}

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/HealthCheckerFactory.java

@@ -22,7 +22,7 @@
  * builders and may make more than one health checker per-load balancer.
  * @param <ResolvedAddress> the type of the resolved address.
  */
-interface HealthCheckerFactory<ResolvedAddress> {
+public interface HealthCheckerFactory<ResolvedAddress> {
     /**
      * Create a new {@link HealthChecker}.
      * @param executor the {@link Executor} to use for scheduling tasks and obtaining the current time.

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancerBuilderProvider.java

@@ -17,9 +17,24 @@
 
 import io.servicetalk.client.api.LoadBalancedConnection;
 
-// TODO: this has to be public for the service loading to work. At that point we'll also likely want
-//  to provide a DelegatingLoadBalancerBuilder.
-interface LoadBalancerBuilderProvider {
+/**
+ * Provider for {@link LoadBalancerBuilder}.
+ */
+public interface LoadBalancerBuilderProvider {
+
+    /**
+     * Returns a {@link LoadBalancerBuilder} based on the pre-initialized {@link LoadBalancerBuilder}.
+     * <p>
+     * This method may return the pre-initialized {@code builder} as-is, or apply custom builder settings before
+     * returning it, or wrap it ({@link DelegatingLoadBalancerBuilder} may be helpful).
+     *
+     * @param id a (unique) identifier used to identify the underlying {@link io.servicetalk.client.api.LoadBalancer}.
+     * @param builder pre-initialized {@link LoadBalancerBuilder}.
+     * @return a {@link LoadBalancerBuilder} based on the pre-initialized
+     * {@link LoadBalancerBuilder}.
+     * @param <ResolvedAddress> The resolved address type.
+     * @param <C> The type of connection.
+     */
     <ResolvedAddress, C extends LoadBalancedConnection> LoadBalancerBuilder<ResolvedAddress, C>
     newBuilder(String id, LoadBalancerBuilder<ResolvedAddress, C> builder);
 }

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancers.java

@@ -17,19 +17,24 @@
 
 import io.servicetalk.client.api.LoadBalancedConnection;
 
-import java.util.ArrayList;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import java.util.List;
 
+import static io.servicetalk.utils.internal.ServiceLoaderUtils.loadProviders;
+
 /**
  * A factory to create {@link DefaultLoadBalancer DefaultLoadBalancers}.
  */
-final class LoadBalancers {
+public final class LoadBalancers {
 
+    private static final Logger LOGGER = LoggerFactory.getLogger(LoadBalancers.class);
     private static final List<LoadBalancerBuilderProvider> PROVIDERS;
 
     static {
-        // TODO: we can't service load the providers until we make the interface public.
-        PROVIDERS = new ArrayList<>();
+        final ClassLoader classLoader = LoadBalancers.class.getClassLoader();
+        PROVIDERS = loadProviders(LoadBalancerBuilderProvider.class, classLoader, LOGGER);
     }
 
     private LoadBalancers() {

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancingPolicy.java

@@ -22,7 +22,7 @@
 /**
  * Definition of the selector mechanism used for load balancing.
  */
-interface LoadBalancingPolicy<ResolvedAddress, C extends LoadBalancedConnection> {
+public interface LoadBalancingPolicy<ResolvedAddress, C extends LoadBalancedConnection> {
     /**
      * The name of the load balancing policy
      *

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/OutlierDetectorConfig.java

@@ -26,10 +26,10 @@
  * XDS outlier detector configuration.
  * <p>
  * See the <a href="https://www.envoyproxy.io/docs/envoy/v1.29.0/api-v3/config/cluster/v3/
- * outlier_detection.proto#envoy-v3-api-msg-config-cluster-v3-outlierdetection"> Envoy docs</a> for the official
+outlier_detection.proto#envoy-v3-api-msg-config-cluster-v3-outlierdetection"> Envoy docs</a> for the official
  * OutlierDetector configuration definition.
  */
-final class OutlierDetectorConfig {
+public final class OutlierDetectorConfig {
 
     private final Duration ewmaHalfLife;
     private final int consecutive5xx;
@@ -311,7 +311,7 @@ public boolean successfulActiveHealthCheckUnejectHost() {
     /**
      * A builder for {@link OutlierDetectorConfig} instances.
      */
-    public static class Builder {
+    public static final class Builder {
         private Duration ewmaHalfLife = Duration.ofSeconds(10);
         private int consecutive5xx = 5;
 

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/P2CLoadBalancingPolicy.java

@@ -37,7 +37,7 @@
  * - if neither host is healthy, repeat selection process until max-effort.
  * - pick the 'best' host of the two options.
  */
-final class P2CLoadBalancingPolicy<ResolvedAddress, C extends LoadBalancedConnection>
+public final class P2CLoadBalancingPolicy<ResolvedAddress, C extends LoadBalancedConnection>
         implements LoadBalancingPolicy<ResolvedAddress, C> {
 
     private final int maxEffort;
@@ -109,7 +109,7 @@ Builder random(Random random) {
         /**
          * Construct an immutable {@link P2CLoadBalancingPolicy}.
          * @param <ResolvedAddress> the type of the resolved address.
-         * @param <C> the refined type of the {@LoadBalancedConnection}.
+         * @param <C> the refined type of the {@link LoadBalancedConnection}.
          * @return the concrete {@link P2CLoadBalancingPolicy}.
          */
         public <ResolvedAddress, C extends LoadBalancedConnection> P2CLoadBalancingPolicy<ResolvedAddress, C> build() {

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/RoundRobinLoadBalancingPolicy.java

@@ -26,7 +26,7 @@
  * from an ordered set. If a host is considered unhealthy it is skipped the next host
  * is selected until a healthy host is found or the entire host set has been exhausted.
  */
-final class RoundRobinLoadBalancingPolicy<ResolvedAddress, C extends LoadBalancedConnection>
+public final class RoundRobinLoadBalancingPolicy<ResolvedAddress, C extends LoadBalancedConnection>
         implements LoadBalancingPolicy<ResolvedAddress, C> {
 
     private final boolean failOpen;
@@ -66,7 +66,7 @@ public RoundRobinLoadBalancingPolicy.Builder failOpen(final boolean failOpen) {
         /**
          * Construct the immutable {@link RoundRobinLoadBalancingPolicy}.
          * @param <ResolvedAddress> the type of the resolved address.
-         * @param <C> the refined type of the {@LoadBalancedConnection}.
+         * @param <C> the refined type of the {@link LoadBalancedConnection}.
          * @return the concrete {@link RoundRobinLoadBalancingPolicy}.
          */
         public <ResolvedAddress, C extends LoadBalancedConnection> RoundRobinLoadBalancingPolicy<ResolvedAddress, C>

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/XdsHealthCheckerFactory.java

@@ -24,7 +24,7 @@
  * See the {@link XdsHealthChecker} for a detailed description and history of the xDS protocol.
  * @param <ResolvedAddress> the type of the resolved address.
  */
-final class XdsHealthCheckerFactory<ResolvedAddress> implements HealthCheckerFactory<ResolvedAddress> {
+public final class XdsHealthCheckerFactory<ResolvedAddress> implements HealthCheckerFactory<ResolvedAddress> {
 
     private final OutlierDetectorConfig config;