feat: Eager connect flag for Netty based client

docs/src/main/paradox/client/configuration.md

@@ -76,7 +76,7 @@ Currently service discovery is only queried on creation of the client. A client
 
 ## Debug logging
 
-To enable fine grained debug running the following logging configuration can be used.
+To enable fine-grained debug running the following logging configuration can be used.
 
 Put this in a file `grpc-debug-logging.properties`:
 

docs/src/main/paradox/client/details.md

@@ -34,6 +34,17 @@ connection has been closed or shutdown due to errors, respectively. When you are
 you should call `close` on the channel, rather than the individual clients. Calling `close` on a generated client 
 that was created with a shared channel will throw a @apidoc[GrpcClientCloseException].
 
+## Channel laziness
+
+The Netty based channel backing a client will only actually connect once the client sees a first request. It is possible
+to configure it to eagerly connect as soon as the client, or channel, is created by setting `eager-connection = true` or
+programmatically through @apidoc[GrpcClientSettings] `withEagerConnection`.
+
+If the client does not see any traffic it will transition to an idle state, and close the connection, after 5 minutes. 
+You can find some more details about the Netty channel behavior in [the grpc connectivity-semantics-and-api docs](https://github.com/grpc/grpc/blob/master/doc/connectivity-semantics-and-api.md).
+
+The Akka HTTP backed client always connects eagerly.
+
 ## Load balancing
 
 When multiple endpoints are discovered for a gRPC client, currently one is

plugin-tester-scala/src/test/scala/example/myapp/helloworld/GreeterServiceSpec.scala

@@ -58,6 +58,17 @@ class GreeterSpec extends Matchers with AnyWordSpecLike with BeforeAndAfterAll w
       val reply = clients.head.sayHello(HelloRequest("Alice"))
       reply.futureValue should ===(HelloReply("Hello, Alice", Some(Timestamp.apply(123456, 123))))
     }
+
+    "reply to single request (eager connect client)" in {
+      val eagerClient = GreeterServiceClient(
+        GrpcClientSettings
+          .connectToServiceAt("127.0.0.1", 8080)(clientSystem.asInstanceOf[ClassicActorSystemProvider])
+          .withEagerConnection(true)
+          .withTls(false))(clientSystem.asInstanceOf[ClassicActorSystemProvider])
+      // no clear way to test it actually connected eagerly, but at least cover that it works
+      val reply = eagerClient.sayHello(HelloRequest("Alice"))
+      reply.futureValue should ===(HelloReply("Hello, Alice", Some(Timestamp.apply(123456, 123))))
+    }
   }
 
   "GreeterServicePowerApi" should {

runtime/src/main/mima-filters/2.4.1.backwards.excludes/eager-connect.excludes

@@ -0,0 +1,2 @@
+# eager client connections, internal constructor
+ProblemFilters.exclude[DirectMissingMethodProblem]("akka.grpc.GrpcClientSettings.this")

runtime/src/main/resources/reference.conf

@@ -6,6 +6,10 @@ akka.grpc.client."*" {
   # Host to use if service-discovery-mechanism is set to static or grpc-dns
   host = ""
 
+  # Service discovery mechamism to use. The default is to use a static host
+  # and port that will be resolved via DNS.
+  # Any of the mechanisms described in https://doc.akka.io/docs/akka-management/current/discovery/index.html can be used
+  # including Kubernetes, Consul, AWS API
   service-discovery {
     mechanism = "static"
     # Service name to use if a service-discovery.mechanism other than static or grpc-dns
@@ -54,9 +58,9 @@ akka.grpc.client."*" {
   # interpreted as retrying 'indefinitely'.
   connection-attempts = 20
 
-  # Service discovery mechamism to use. The default is to use a static host
-  # and port that will be resolved via DNS.
-  # Any of the mechanisms described in https://doc.akka.io/docs/akka-management/current/discovery/index.html can be used
-  # including Kubernetes, Consul, AWS API
+  # Request that the client try to connect the service immediately when the client is created
+  # rather than on the first request. Only supported for the Netty client backend, the akka-http client backend
+  # is always eager.
+  eager-connection = off
 }
 //#defaults

runtime/src/main/scala/akka/grpc/GrpcClientSettings.scala

@@ -150,7 +150,8 @@ object GrpcClientSettings {
       getOptionalString(clientConfiguration, "load-balancing-policy"),
       clientConfiguration.getString("backend"),
       identity,
-      getOptionalDuration(clientConfiguration, "service-discovery.refresh-interval"))
+      getOptionalDuration(clientConfiguration, "service-discovery.refresh-interval"),
+      clientConfiguration.getBoolean("eager-connection"))
 
   private def getOptionalString(config: Config, path: String): Option[String] =
     config.getString(path) match {
@@ -205,7 +206,8 @@ final class GrpcClientSettings private (
     val loadBalancingPolicy: Option[String],
     val backend: String,
     val channelBuilderOverrides: NettyChannelBuilder => NettyChannelBuilder = identity,
-    val discoveryRefreshInterval: Option[FiniteDuration]) {
+    val discoveryRefreshInterval: Option[FiniteDuration],
+    val eagerConnection: Boolean) {
   require(
     sslContext.isEmpty || trustManager.isEmpty,
     "Configuring the sslContext or the trustManager is mutually exclusive")
@@ -315,6 +317,14 @@ final class GrpcClientSettings private (
   def withDiscoveryRefreshInterval(refreshInterval: java.time.Duration): GrpcClientSettings =
     copy(discoveryRefreshInterval = Some(refreshInterval.asScala))
 
+  /**
+   * Request that the client try to connect the service immediately when the client is created
+   * rather than on the first request. Only supported for the Netty client backend, the akka-http client backend
+   * is always eager.
+   */
+  def withEagerConnection(eagerConnection: Boolean): GrpcClientSettings =
+    copy(eagerConnection = eagerConnection)
+
   private def copy(
       serviceName: String = serviceName,
       servicePortName: Option[String] = servicePortName,
@@ -333,7 +343,8 @@ final class GrpcClientSettings private (
       loadBalancingPolicy: Option[String] = loadBalancingPolicy,
       backend: String = backend,
       channelBuilderOverrides: NettyChannelBuilder => NettyChannelBuilder = channelBuilderOverrides,
-      discoveryRefreshInterval: Option[FiniteDuration] = discoveryRefreshInterval): GrpcClientSettings =
+      discoveryRefreshInterval: Option[FiniteDuration] = discoveryRefreshInterval,
+      eagerConnection: Boolean = eagerConnection): GrpcClientSettings =
     new GrpcClientSettings(
       callCredentials = callCredentials,
       serviceDiscovery = serviceDiscovery,
@@ -353,5 +364,6 @@ final class GrpcClientSettings private (
       loadBalancingPolicy = loadBalancingPolicy,
       backend = backend,
       channelBuilderOverrides = channelBuilderOverrides,
-      discoveryRefreshInterval = discoveryRefreshInterval)
+      discoveryRefreshInterval = discoveryRefreshInterval,
+      eagerConnection = eagerConnection)
 }

runtime/src/main/scala/akka/grpc/internal/NettyClientUtils.scala

@@ -125,6 +125,9 @@ object NettyClientUtils {
         channelClosedPromise.tryFailure(e)
     }
 
+    if (settings.eagerConnection)
+      channel.getState(true)
+
     new InternalChannel {
       override def shutdown() = channel.shutdown()
       override def done = channelClosedPromise.future