review comments

servicetalk-examples/docs/modules/ROOT/pages/grpc/index.adoc

@@ -103,6 +103,13 @@ Demonstrates how to use HTTP/2 keep alive for gRPC
 link:{source-root}/servicetalk-examples/grpc/helloworld/src/main/java/io/servicetalk/examples/grpc/keepalive/KeepAliveServer.java[server]
 and
 link:{source-root}/servicetalk-examples/grpc/helloworld/src/main/java/io/servicetalk/examples/grpc/keepalive/KeepAliveeClient.java[client].
+Keep alive uses transport control frames to ensure the peer is still able to read and write to open connections. If the
+peer is not able to respond to the control frame within the configured amount of time, the connection is closed. This
+is useful if your environment doesn't provide other forms of connection keep alive (e.g.
+link:https://docs.oracle.com/javase/8/docs/api/java/net/StandardSocketOptions.html#SO_KEEPALIVE[SO_KEEPALIVE], and maybe
+preferred to lower level keep alive because it is closer the application logic (more likely if this check works, that
+your application is able to read/write). Keep alive can be helpful to detect scenarios such as non-graceful disconnects
+(e.g. power outage, ethernet cable pulled, buggy middle box) and general network disconnects.
 
 [#Debugging]
 == Debugging

servicetalk-examples/grpc/keepalive/src/main/java/io/servicetalk/examples/grpc/keepalive/KeepAliveClient.java

@@ -39,6 +39,9 @@ public static void main(String... args) throws Exception {
         try (BlockingStreamingGreeterClient client = GrpcClients.forAddress("localhost", 8080)
                 .initializeHttp(httpBuilder -> httpBuilder.protocols(
                     // 4 second timeout is typically much shorter than necessary, but demonstrates PING frame traffic.
+                    // Using the default value is suitable in most scenarios, but if you want to customize the value
+                    // consider how many resources (network traffic, CPU for local timer management) vs time to detect
+                    // bad connection.
                     // By default, keep alive is only sent when no traffic is detected, so if both peers have keep alive
                     // the faster interval will be the primary sender.
                     h2().keepAlivePolicy(whenIdleFor(ofSeconds(4)))

servicetalk-examples/grpc/keepalive/src/main/java/io/servicetalk/examples/grpc/keepalive/KeepAliveServer.java

@@ -33,6 +33,9 @@ public static void main(String... args) throws Exception {
         GrpcServers.forPort(8080)
                 .initializeHttp(httpBuilder -> httpBuilder.protocols(
                     // 6 second timeout is typically much shorter than necessary, but demonstrates PING frame traffic.
+                    // Using the default value is suitable in most scenarios, but if you want to customize the value
+                    // consider how many resources (network traffic, CPU for local timer management) vs time to detect
+                    // bad connection.
                     // By default, keep alive is only sent when no traffic is detected, so if both peers have keep alive
                     // the faster interval will be the primary sender.
                     h2().keepAlivePolicy(whenIdleFor(ofSeconds(6)))