internal: move backoff to internal (#2141)

So other components such as grpclb can reuse the backoff implementation.

backoff.go

@@ -16,82 +16,23 @@
  *
  */
 
+// See internal/backoff package for the backoff implementation. This file is
+// kept for the exported types and API backward compatility.
+
 package grpc
 
 import (
 	"time"
-
-	"google.golang.org/grpc/internal/grpcrand"
 )
 
 // DefaultBackoffConfig uses values specified for backoff in
 // https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md.
 var DefaultBackoffConfig = BackoffConfig{
-	MaxDelay:  120 * time.Second,
-	baseDelay: 1.0 * time.Second,
-	factor:    1.6,
-	jitter:    0.2,
-}
-
-// backoffStrategy defines the methodology for backing off after a grpc
-// connection failure.
-//
-// This is unexported until the gRPC project decides whether or not to allow
-// alternative backoff strategies. Once a decision is made, this type and its
-// method may be exported.
-type backoffStrategy interface {
-	// backoff returns the amount of time to wait before the next retry given
-	// the number of consecutive failures.
-	backoff(retries int) time.Duration
+	MaxDelay: 120 * time.Second,
 }
 
 // BackoffConfig defines the parameters for the default gRPC backoff strategy.
 type BackoffConfig struct {
 	// MaxDelay is the upper bound of backoff delay.
 	MaxDelay time.Duration
-
-	// TODO(stevvooe): The following fields are not exported, as allowing
-	// changes would violate the current gRPC specification for backoff. If
-	// gRPC decides to allow more interesting backoff strategies, these fields
-	// may be opened up in the future.
-
-	// baseDelay is the amount of time to wait before retrying after the first
-	// failure.
-	baseDelay time.Duration
-
-	// factor is applied to the backoff after each retry.
-	factor float64
-
-	// jitter provides a range to randomize backoff delays.
-	jitter float64
-}
-
-func setDefaults(bc *BackoffConfig) {
-	md := bc.MaxDelay
-	*bc = DefaultBackoffConfig
-
-	if md > 0 {
-		bc.MaxDelay = md
-	}
-}
-
-func (bc BackoffConfig) backoff(retries int) time.Duration {
-	if retries == 0 {
-		return bc.baseDelay
-	}
-	backoff, max := float64(bc.baseDelay), float64(bc.MaxDelay)
-	for backoff < max && retries > 0 {
-		backoff *= bc.factor
-		retries--
-	}
-	if backoff > max {
-		backoff = max
-	}
-	// Randomize backoff delays so that if a cluster of requests start at
-	// the same time, they won't operate in lockstep.
-	backoff *= 1 + bc.jitter*(grpcrand.Float64()*2-1)
-	if backoff < 0 {
-		return 0
-	}
-	return time.Duration(backoff)
 }

backoff_test.go

@@ -1,29 +0,0 @@
-/*
- *
- * Copyright 2017 gRPC 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 grpc
-
-import "testing"
-
-func TestBackoffConfigDefaults(t *testing.T) {
-	b := BackoffConfig{}
-	setDefaults(&b)
-	if b != DefaultBackoffConfig {
-		t.Fatalf("expected BackoffConfig to pickup default parameters: %v != %v", b, DefaultBackoffConfig)
-	}
-}

clientconn.go

@@ -38,6 +38,7 @@ import (
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/grpclog"
 	"google.golang.org/grpc/internal"
+	"google.golang.org/grpc/internal/backoff"
 	"google.golang.org/grpc/keepalive"
 	"google.golang.org/grpc/resolver"
 	_ "google.golang.org/grpc/resolver/dns"         // To register dns resolver.
@@ -100,7 +101,7 @@ type dialOptions struct {
 	streamInt   StreamClientInterceptor
 	cp          Compressor
 	dc          Decompressor
-	bs          backoffStrategy
+	bs          backoff.Strategy
 	block       bool
 	insecure    bool
 	timeout     time.Duration
@@ -278,17 +279,17 @@ func WithBackoffMaxDelay(md time.Duration) DialOption {
 // Use WithBackoffMaxDelay until more parameters on BackoffConfig are opened up
 // for use.
 func WithBackoffConfig(b BackoffConfig) DialOption {
-	// Set defaults to ensure that provided BackoffConfig is valid and
-	// unexported fields get default values.
-	setDefaults(&b)
-	return withBackoff(b)
+
+	return withBackoff(backoff.Exponential{
+		MaxDelay: b.MaxDelay,
+	})
 }
 
 // withBackoff sets the backoff strategy used for connectRetryNum after a
 // failed connection attempt.
 //
 // This can be exported if arbitrary backoff strategies are allowed by gRPC.
-func withBackoff(bs backoffStrategy) DialOption {
+func withBackoff(bs backoff.Strategy) DialOption {
 	return func(o *dialOptions) {
 		o.bs = bs
 	}
@@ -540,7 +541,9 @@ func DialContext(ctx context.Context, target string, opts ...DialOption) (conn *
 		}
 	}
 	if cc.dopts.bs == nil {
-		cc.dopts.bs = DefaultBackoffConfig
+		cc.dopts.bs = backoff.Exponential{
+			MaxDelay: DefaultBackoffConfig.MaxDelay,
+		}
 	}
 	if cc.dopts.resolverBuilder == nil {
 		// Only try to parse target when resolver builder is not already set.
@@ -1211,7 +1214,7 @@ func (ac *addrConn) resetTransport() error {
 			// This means either a successful HTTP2 connection was established
 			// or this is the first time this addrConn is trying to establish a
 			// connection.
-			backoffFor := ac.dopts.bs.backoff(connectRetryNum) // time.Duration.
+			backoffFor := ac.dopts.bs.Backoff(connectRetryNum) // time.Duration.
 			// This will be the duration that dial gets to finish.
 			dialDuration := getMinConnectTimeout()
 			if backoffFor > dialDuration {

clientconn_test.go

@@ -27,9 +27,9 @@ import (
 
 	"golang.org/x/net/context"
 	"golang.org/x/net/http2"
-
 	"google.golang.org/grpc/connectivity"
 	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/internal/backoff"
 	"google.golang.org/grpc/internal/leakcheck"
 	"google.golang.org/grpc/keepalive"
 	"google.golang.org/grpc/naming"
@@ -504,7 +504,6 @@ func TestWithBackoffConfig(t *testing.T) {
 	defer leakcheck.Check(t)
 	b := BackoffConfig{MaxDelay: DefaultBackoffConfig.MaxDelay / 2}
 	expected := b
-	setDefaults(&expected) // defaults should be set
 	testBackoffConfigSet(t, &expected, WithBackoffConfig(b))
 }
 
@@ -512,7 +511,6 @@ func TestWithBackoffMaxDelay(t *testing.T) {
 	defer leakcheck.Check(t)
 	md := DefaultBackoffConfig.MaxDelay / 2
 	expected := BackoffConfig{MaxDelay: md}
-	setDefaults(&expected)
 	testBackoffConfigSet(t, &expected, WithBackoffMaxDelay(md))
 }
 
@@ -528,12 +526,15 @@ func testBackoffConfigSet(t *testing.T, expected *BackoffConfig, opts ...DialOpt
 		t.Fatalf("backoff config not set")
 	}
 
-	actual, ok := conn.dopts.bs.(BackoffConfig)
+	actual, ok := conn.dopts.bs.(backoff.Exponential)
 	if !ok {
 		t.Fatalf("unexpected type of backoff config: %#v", conn.dopts.bs)
 	}
 
-	if actual != *expected {
+	expectedValue := backoff.Exponential{
+		MaxDelay: expected.MaxDelay,
+	}
+	if actual != expectedValue {
 		t.Fatalf("unexpected backoff config on connection: %v, want %v", actual, expected)
 	}
 }

internal/backoff/backoff.go

@@ -0,0 +1,78 @@
+/*
+ *
+ * Copyright 2017 gRPC 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 backoff implement the backoff strategy for gRPC.
+//
+// This is kept in internal until the gRPC project decides whether or not to
+// allow alternative backoff strategies.
+package backoff
+
+import (
+	"time"
+
+	"google.golang.org/grpc/internal/grpcrand"
+)
+
+// Strategy defines the methodology for backing off after a grpc connection
+// failure.
+//
+type Strategy interface {
+	// Backoff returns the amount of time to wait before the next retry given
+	// the number of consecutive failures.
+	Backoff(retries int) time.Duration
+}
+
+const (
+	// baseDelay is the amount of time to wait before retrying after the first
+	// failure.
+	baseDelay = 1.0 * time.Second
+	// factor is applied to the backoff after each retry.
+	factor = 1.6
+	// jitter provides a range to randomize backoff delays.
+	jitter = 0.2
+)
+
+// Exponential implements exponential backoff algorithm as defined in
+// https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md.
+type Exponential struct {
+	// MaxDelay is the upper bound of backoff delay.
+	MaxDelay time.Duration
+}
+
+// Backoff returns the amount of time to wait before the next retry given the
+// number of retries.
+func (bc Exponential) Backoff(retries int) time.Duration {
+	if retries == 0 {
+		return baseDelay
+	}
+	backoff, max := float64(baseDelay), float64(bc.MaxDelay)
+	for backoff < max && retries > 0 {
+		backoff *= factor
+		retries--
+	}
+	if backoff > max {
+		backoff = max
+	}
+	// Randomize backoff delays so that if a cluster of requests start at
+	// the same time, they won't operate in lockstep.
+	backoff *= 1 + jitter*(grpcrand.Float64()*2-1)
+	if backoff < 0 {
+		return 0
+	}
+	return time.Duration(backoff)
+}