doc: update keepalive ClientParameters doc about doubling the interva…

…l upon GOAWAY (#7469)
grpc · Aug 20, 2024 · 1e2bb71 · 1e2bb71
1 parent 6a5a283
commit 1e2bb71
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 3 deletions.
diff --git a/dialoptions.go b/dialoptions.go
@@ -518,6 +518,8 @@ func WithUserAgent(s string) DialOption {
 
 // WithKeepaliveParams returns a DialOption that specifies keepalive parameters
 // for the client transport.
+//
+// Keepalive is disabled by default.
 func WithKeepaliveParams(kp keepalive.ClientParameters) DialOption {
 	if kp.Time < internal.KeepaliveMinPingTime {
 		logger.Warningf("Adjusting keepalive ping interval to minimum period of %v", internal.KeepaliveMinPingTime)

diff --git a/keepalive/keepalive.go b/keepalive/keepalive.go
@@ -34,15 +34,29 @@ type ClientParameters struct {
 	// After a duration of this time if the client doesn't see any activity it
 	// pings the server to see if the transport is still alive.
 	// If set below 10s, a minimum value of 10s will be used instead.
-	Time time.Duration // The current default value is infinity.
+	//
+	// Note that gRPC servers have a default EnforcementPolicy.MinTime of 5
+	// minutes (which means the client shouldn't ping more frequently than every
+	// 5 minutes).
+	//
+	// Though not ideal, it's not a strong requirement for Time to be less than
+	// EnforcementPolicy.MinTime.  Time will automatically double if the server
+	// disconnects due to its enforcement policy.
+	//
+	// For more details, see
+	// https://github.com/grpc/proposal/blob/master/A8-client-side-keepalive.md
+	Time time.Duration
 	// After having pinged for keepalive check, the client waits for a duration
 	// of Timeout and if no activity is seen even after that the connection is
 	// closed.
-	Timeout time.Duration // The current default value is 20 seconds.
+	//
+	// If keepalive is enabled, and this value is not explicitly set, the default
+	// is 20 seconds.
+	Timeout time.Duration
 	// If true, client sends keepalive pings even with no active RPCs. If false,
 	// when there are no active RPCs, Time and Timeout will be ignored and no
 	// keepalive pings will be sent.
-	PermitWithoutStream bool // false by default.
+	PermitWithoutStream bool
 }
 
 // ServerParameters is used to set keepalive and max-age parameters on the