4.x: Adds support to iterate over URIs when connecting to a gRPC serv…

…ice (#9285)

Adds support to iterate over URIs when connecting to a gRPC service. Defines a new interface ClientUriSupplier that can be used to dynamically provide a list of URIs to connect to. Each gRPC call will retrieve the next URI from the supplier.

webclient/grpc/etc/spotbugs/exclude.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2024 Oracle and/or its affiliates.
+
+    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.
+
+-->
+
+<FindBugsFilter
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://github.com/spotbugs/filter/3.0.0"
+        xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd">
+    <Match>
+        <Class name="io.helidon.webclient.grpc.ClientUriSuppliers$RoundRobinSupplier" />
+        <Bug pattern="IT_NO_SUCH_ELEMENT" />
+    </Match>
+    <Match>
+        <Class name="io.helidon.webclient.grpc.ClientUriSuppliers$SingleSupplier" />
+        <Bug pattern="IT_NO_SUCH_ELEMENT" />
+    </Match>
+    <Match>
+        <Class name="io.helidon.webclient.grpc.ClientUriSuppliers$RandomSupplier" />
+        <Bug pattern="IT_NO_SUCH_ELEMENT" />
+    </Match>
+</FindBugsFilter>

webclient/grpc/pom.xml

@@ -27,6 +27,10 @@
     <artifactId>helidon-webclient-grpc</artifactId>
     <name>Helidon WebClient gRPC</name>
 
+    <properties>
+        <spotbugs.exclude>etc/spotbugs/exclude.xml</spotbugs.exclude>
+    </properties>
+
     <dependencies>
         <dependency>
             <groupId>io.grpc</groupId>

webclient/grpc/src/main/java/io/helidon/webclient/grpc/ClientUriSupplier.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * 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.helidon.webclient.grpc;
+
+import java.util.Iterator;
+
+import io.helidon.webclient.api.ClientUri;
+
+/**
+ * Interface implemented by all client URI suppliers.
+ */
+public interface ClientUriSupplier extends Iterator<ClientUri>, Iterable<ClientUri> {
+
+    @Override
+    default Iterator<ClientUri> iterator() {
+        return this;
+    }
+}

webclient/grpc/src/main/java/io/helidon/webclient/grpc/ClientUriSuppliers.java

@@ -0,0 +1,203 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * 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.helidon.webclient.grpc;
+
+import java.net.URI;
+import java.security.SecureRandom;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
+
+import io.helidon.webclient.api.ClientUri;
+
+/**
+ * Some popular implementations of the {@link io.helidon.webclient.grpc.ClientUriSupplier}
+ * interface.
+ */
+public class ClientUriSuppliers {
+
+    /**
+     * Supplies an iterator that returns URIs chosen in order from
+     * first to last.
+     */
+    public static class OrderedSupplier implements ClientUriSupplier {
+
+        private final Iterator<ClientUri> clientUris;
+
+        /**
+         * Creates an ordered supplier.
+         *
+         * @param clientUris array of client URIs
+         * @return new supplier
+         */
+        public static OrderedSupplier create(ClientUri... clientUris) {
+            return new OrderedSupplier(List.of(clientUris));
+        }
+
+        /**
+         * Creates an ordered supplier.
+         *
+         * @param clientUris collection of client URIs
+         * @return new supplier
+         */
+        public static OrderedSupplier create(Collection<ClientUri> clientUris) {
+            return new OrderedSupplier(clientUris);
+        }
+
+        protected OrderedSupplier(Collection<ClientUri> clientUris) {
+            this.clientUris = List.copyOf(clientUris).iterator();
+        }
+
+        @Override
+        public boolean hasNext() {
+            return clientUris.hasNext();
+        }
+
+        @Override
+        public ClientUri next() {
+            return clientUris.next();
+        }
+    }
+
+    /**
+     * Supplies a neven-ending iterator that returns URIs chosen using
+     * a round-robin strategy.
+     */
+    public static class RoundRobinSupplier implements ClientUriSupplier {
+
+        private int next;
+        private final ClientUri[] clientUris;
+
+        /**
+         * Creates a round-robin supplier.
+         *
+         * @param clientUris array of client URIs
+         * @return new supplier
+         */
+        public static RoundRobinSupplier create(ClientUri... clientUris) {
+            return new RoundRobinSupplier(clientUris);
+        }
+
+        /**
+         * Creates a round-robin supplier.
+         *
+         * @param clientUris collection of client URIs
+         * @return new supplier
+         */
+        public static RoundRobinSupplier create(Collection<ClientUri> clientUris) {
+            return new RoundRobinSupplier(clientUris.toArray(new ClientUri[]{}));
+        }
+
+        protected RoundRobinSupplier(ClientUri[] clientUris) {
+            this.clientUris = clientUris;
+        }
+
+        @Override
+        public boolean hasNext() {
+            return true;
+        }
+
+        @Override
+        public ClientUri next() {
+            return clientUris[next++ % clientUris.length];
+        }
+    }
+
+    /**
+     * Supplies the same client URI over and over, never ends.
+     */
+    public static class SingleSupplier implements ClientUriSupplier {
+
+        private final ClientUri clientUri;
+
+        /**
+         * Creates a single supplier.
+         *
+         * @param clientUri the client URI as a string
+         * @return new supplier
+         */
+        public static SingleSupplier create(String clientUri) {
+            return new SingleSupplier(ClientUri.create(URI.create(clientUri)));
+        }
+
+        /**
+         * Creates a single supplier.
+         *
+         * @param clientUri the client URI
+         * @return new supplier
+         */
+        public static SingleSupplier create(ClientUri clientUri) {
+            return new SingleSupplier(clientUri);
+        }
+
+        protected SingleSupplier(ClientUri clientUri) {
+            this.clientUri = clientUri;
+        }
+
+        @Override
+        public boolean hasNext() {
+            return true;
+        }
+
+        @Override
+        public ClientUri next() {
+            return clientUri;
+        }
+    }
+
+    /**
+     * Supplies an iterator that returns a URI chosen at random, never ends.
+     */
+    public static class RandomSupplier implements ClientUriSupplier {
+
+        private final ClientUri[] clientUris;
+        private final SecureRandom random = new SecureRandom();
+
+        /**
+         * Creates a random supplier.
+         *
+         * @param clientUris array of client URIs
+         * @return new supplier
+         */
+        public static RandomSupplier create(ClientUri... clientUris) {
+            return new RandomSupplier(clientUris);
+        }
+
+        /**
+         * Creates a random supplier.
+         *
+         * @param clientUris collection of client URIs
+         * @return new supplier
+         */
+        public static RandomSupplier create(Collection<ClientUri> clientUris) {
+            return new RandomSupplier(clientUris.toArray(new ClientUri[]{}));
+        }
+
+        protected RandomSupplier(ClientUri[] clientUris) {
+            this.clientUris = clientUris;
+        }
+
+        @Override
+        public boolean hasNext() {
+            return true;
+        }
+
+        @Override
+        public ClientUri next() {
+            return clientUris[random.nextInt(clientUris.length)];
+        }
+    }
+}

webclient/grpc/src/main/java/io/helidon/webclient/grpc/GrpcBaseClientCall.java

@@ -66,12 +66,14 @@ abstract class GrpcBaseClientCall<ReqT, ResT> extends ClientCall<ReqT, ResT> {
     protected static final BufferData EMPTY_BUFFER_DATA = BufferData.empty();
 
     private final GrpcClientImpl grpcClient;
+    private final GrpcChannel grpcChannel;
     private final MethodDescriptor<ReqT, ResT> methodDescriptor;
     private final CallOptions callOptions;
     private final int initBufferSize;
     private final Duration pollWaitTime;
     private final boolean abortPollTimeExpired;
     private final Duration heartbeatPeriod;
+    private final ClientUriSupplier clientUriSupplier;
 
     private final MethodDescriptor.Marshaller<ReqT> requestMarshaller;
     private final MethodDescriptor.Marshaller<ResT> responseMarshaller;
@@ -81,8 +83,9 @@ abstract class GrpcBaseClientCall<ReqT, ResT> extends ClientCall<ReqT, ResT> {
     private volatile Listener<ResT> responseListener;
     private volatile HelidonSocket socket;
 
-    GrpcBaseClientCall(GrpcClientImpl grpcClient, MethodDescriptor<ReqT, ResT> methodDescriptor, CallOptions callOptions) {
-        this.grpcClient = grpcClient;
+    GrpcBaseClientCall(GrpcChannel grpcChannel, MethodDescriptor<ReqT, ResT> methodDescriptor, CallOptions callOptions) {
+        this.grpcClient = (GrpcClientImpl) grpcChannel.grpcClient();
+        this.grpcChannel = grpcChannel;
         this.methodDescriptor = methodDescriptor;
         this.callOptions = callOptions;
         this.requestMarshaller = methodDescriptor.getRequestMarshaller();
@@ -91,6 +94,7 @@ abstract class GrpcBaseClientCall<ReqT, ResT> extends ClientCall<ReqT, ResT> {
         this.pollWaitTime = grpcClient.prototype().protocolConfig().pollWaitTime();
         this.abortPollTimeExpired = grpcClient.prototype().protocolConfig().abortPollTimeExpired();
         this.heartbeatPeriod = grpcClient.prototype().protocolConfig().heartbeatPeriod();
+        this.clientUriSupplier = grpcClient.prototype().clientUriSupplier().orElse(null);
     }
 
     @Override
@@ -100,10 +104,11 @@ public void start(Listener<ResT> responseListener, Metadata metadata) {
         this.responseListener = responseListener;
 
         // obtain HTTP2 connection
-        ClientConnection clientConnection = clientConnection();
+        ClientUri clientUri = nextClientUri();
+        ClientConnection clientConnection = clientConnection(clientUri);
         socket = clientConnection.helidonSocket();
         connection = Http2ClientConnection.create((Http2ClientImpl) grpcClient.http2Client(),
-                clientConnection, true);
+                                                  clientConnection, true);
 
         // create HTTP2 stream from connection
         clientStream = new GrpcClientStream(
@@ -134,7 +139,6 @@ public Duration readTimeout() {
         startStreamingThreads();
 
         // send HEADERS frame
-        ClientUri clientUri = grpcClient.prototype().baseUri().orElseThrow();
         WritableHeaders<?> headers = WritableHeaders.create();
         headers.add(Http2Headers.AUTHORITY_NAME, clientUri.authority());
         headers.add(Http2Headers.METHOD_NAME, "POST");
@@ -165,11 +169,13 @@ protected void unblockUnaryExecutor() {
         }
     }
 
-    protected ClientConnection clientConnection() {
-        GrpcClientConfig clientConfig = grpcClient.prototype();
-        ClientUri clientUri = clientConfig.baseUri().orElseThrow();
-        WebClient webClient = grpcClient.webClient();
+    protected GrpcClientImpl grpcClient() {
+        return grpcClient;
+    }
 
+    protected ClientConnection clientConnection(ClientUri clientUri) {
+        WebClient webClient = grpcClient.webClient();
+        GrpcClientConfig clientConfig = grpcClient.prototype();
         ConnectionKey connectionKey = new ConnectionKey(
                 clientUri.scheme(),
                 clientUri.host(),
@@ -179,13 +185,12 @@ protected ClientConnection clientConnection() {
                 DefaultDnsResolver.create(),
                 DnsAddressLookup.defaultLookup(),
                 Proxy.noProxy());
-
         return TcpClientConnection.create(webClient,
-                connectionKey,
-                Collections.emptyList(),
-                connection -> false,
-                connection -> {
-                }).connect();
+                                          connectionKey,
+                                          Collections.emptyList(),
+                                          connection -> false,
+                                          connection -> {
+                                          }).connect();
     }
 
     protected boolean isRemoteOpen() {
@@ -245,4 +250,16 @@ protected Listener<ResT> responseListener() {
     protected HelidonSocket socket() {
         return socket;
     }
+
+    /**
+     * Retrieves the next URI either from the supplier or directly from config. If
+     * a supplier is provided, it will take precedence.
+     *
+     * @return the next {@link ClientUri}
+     * @throws java.util.NoSuchElementException if supplier has been exhausted
+     */
+    private ClientUri nextClientUri() {
+        return clientUriSupplier == null ? grpcClient.prototype().baseUri().orElseThrow()
+                : clientUriSupplier.next();
+    }
 }