Merge pull request #1450 from ydb-platform/prefer-nearest-dc

Added `balancers.PreferNearestDC[WithFallback]` balancers + Marked as deprecated `balancers.PreferLocalDC[WithFallback]` balancers

CHANGELOG.md

@@ -1,3 +1,6 @@
+* Added `balancers.PreferNearestDC[WithFallback]` balancers
+* Marked as deprecated `balancers.PreferLocalDC[WithFallback]` balancers because `local` word is ambiguous for balancer idea
+
 ## v3.80.1
 * Added `lastErr` from previous attempt in `retry.RetryWithResult`
 

balancers/balancers.go

@@ -37,21 +37,41 @@ func (filterLocalDC) String() string {
 	return "LocalDC"
 }
 
-// PreferLocalDC creates balancer which use endpoints only in location such as initial endpoint location
-// Balancer "balancer" defines balancing algorithm between endpoints selected with filter by location
-// PreferLocalDC balancer try to autodetect local DC from client side.
+// Deprecated: use PreferNearestDC instead
+// Will be removed after March 2025.
+// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
 func PreferLocalDC(balancer *balancerConfig.Config) *balancerConfig.Config {
 	balancer.Filter = filterLocalDC{}
-	balancer.DetectLocalDC = true
+	balancer.DetectNearestDC = true
 
 	return balancer
 }
 
-// PreferLocalDCWithFallBack creates balancer which use endpoints only in location such as initial endpoint location
+// PreferNearestDC creates balancer which use endpoints only in location such as initial endpoint location
 // Balancer "balancer" defines balancing algorithm between endpoints selected with filter by location
-// If filter returned zero endpoints from all discovery endpoints list - used all endpoint instead
+// PreferNearestDC balancer try to autodetect local DC from client side.
+func PreferNearestDC(balancer *balancerConfig.Config) *balancerConfig.Config {
+	balancer.Filter = filterLocalDC{}
+	balancer.DetectNearestDC = true
+
+	return balancer
+}
+
+// Deprecated: use PreferNearestDCWithFallBack instead
+// Will be removed after March 2025.
+// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
 func PreferLocalDCWithFallBack(balancer *balancerConfig.Config) *balancerConfig.Config {
-	balancer = PreferLocalDC(balancer)
+	balancer = PreferNearestDC(balancer)
+	balancer.AllowFallback = true
+
+	return balancer
+}
+
+// PreferNearestDCWithFallBack creates balancer which use endpoints only in location such as initial endpoint location
+// Balancer "balancer" defines balancing algorithm between endpoints selected with filter by location
+// If filter returned zero endpoints from all discovery endpoints list - used all endpoint instead
+func PreferNearestDCWithFallBack(balancer *balancerConfig.Config) *balancerConfig.Config {
+	balancer = PreferNearestDC(balancer)
 	balancer.AllowFallback = true
 
 	return balancer

balancers/balancers_test.go

@@ -17,7 +17,7 @@ func TestPreferLocalDC(t *testing.T) {
 		&mock.Conn{AddrField: "2", State: conn.Online, LocationField: "2"},
 		&mock.Conn{AddrField: "3", State: conn.Online, LocationField: "2"},
 	}
-	rr := PreferLocalDC(RandomChoice())
+	rr := PreferNearestDC(RandomChoice())
 	require.False(t, rr.AllowFallback)
 	require.Equal(t, []conn.Conn{conns[1], conns[2]}, applyPreferFilter(balancerConfig.Info{SelfLocation: "2"}, rr, conns))
 }
@@ -28,7 +28,7 @@ func TestPreferLocalDCWithFallBack(t *testing.T) {
 		&mock.Conn{AddrField: "2", State: conn.Online, LocationField: "2"},
 		&mock.Conn{AddrField: "3", State: conn.Online, LocationField: "2"},
 	}
-	rr := PreferLocalDCWithFallBack(RandomChoice())
+	rr := PreferNearestDCWithFallBack(RandomChoice())
 	require.True(t, rr.AllowFallback)
 	require.Equal(t, []conn.Conn{conns[1], conns[2]}, applyPreferFilter(balancerConfig.Info{SelfLocation: "2"}, rr, conns))
 }

balancers/config.go

@@ -20,8 +20,13 @@ const (
 type preferType string
 
 const (
-	preferTypeLocalDC   = preferType("local_dc")
+	preferTypeNearestDC = preferType("nearest_dc")
 	preferTypeLocations = preferType("locations")
+
+	// Deprecated
+	// Will be removed after March 2025.
+	// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
+	preferTypeLocalDC = preferType("local_dc")
 )
 
 type balancersConfig struct {
@@ -90,10 +95,16 @@ func CreateFromConfig(s string) (*balancerConfig.Config, error) {
 	switch c.Prefer {
 	case preferTypeLocalDC:
 		if c.Fallback {
-			return PreferLocalDCWithFallBack(b), nil
+			return PreferNearestDCWithFallBack(b), nil
+		}
+
+		return PreferNearestDC(b), nil
+	case preferTypeNearestDC:
+		if c.Fallback {
+			return PreferNearestDCWithFallBack(b), nil
 		}
 
-		return PreferLocalDC(b), nil
+		return PreferNearestDC(b), nil
 	case preferTypeLocations:
 		if len(c.Locations) == 0 {
 			return nil, xerrors.WithStackTrace(fmt.Errorf("empty locations list in balancer '%s' config", c.Type))

balancers/config_test.go

@@ -70,7 +70,21 @@ func TestFromConfig(t *testing.T) {
 				"prefer": "local_dc"
 			}`,
 			res: balancerConfig.Config{
-				DetectLocalDC: true,
+				DetectNearestDC: true,
+				Filter: filterFunc(func(info balancerConfig.Info, e endpoint.Info) bool {
+					// some non nil func
+					return false
+				}),
+			},
+		},
+		{
+			name: "prefer_nearest_dc",
+			config: `{
+				"type": "random_choice",
+				"prefer": "nearest_dc"
+			}`,
+			res: balancerConfig.Config{
+				DetectNearestDC: true,
 				Filter: filterFunc(func(info balancerConfig.Info, e endpoint.Info) bool {
 					// some non nil func
 					return false
@@ -93,8 +107,24 @@ func TestFromConfig(t *testing.T) {
 				"fallback": true
 			}`,
 			res: balancerConfig.Config{
-				AllowFallback: true,
-				DetectLocalDC: true,
+				AllowFallback:   true,
+				DetectNearestDC: true,
+				Filter: filterFunc(func(info balancerConfig.Info, e endpoint.Info) bool {
+					// some non nil func
+					return false
+				}),
+			},
+		},
+		{
+			name: "prefer_nearest_dc_with_fallback",
+			config: `{
+				"type": "random_choice",
+				"prefer": "nearest_dc",
+				"fallback": true
+			}`,
+			res: balancerConfig.Config{
+				AllowFallback:   true,
+				DetectNearestDC: true,
 				Filter: filterFunc(func(info balancerConfig.Info, e endpoint.Info) bool {
 					// some non nil func
 					return false

internal/balancer/balancer.go

@@ -111,7 +111,7 @@ func (b *Balancer) clusterDiscoveryAttempt(ctx context.Context) (err error) {
 		return xerrors.WithStackTrace(err)
 	}
 
-	if b.config.DetectLocalDC {
+	if b.config.DetectNearestDC {
 		localDC, err = b.localDCDetector(ctx, endpoints)
 		if err != nil {
 			return xerrors.WithStackTrace(err)
@@ -129,7 +129,7 @@ func (b *Balancer) applyDiscoveredEndpoints(ctx context.Context, newest []endpoi
 			b.driverConfig.Trace(), &ctx,
 			stack.FunctionID(
 				"github.com/ydb-platform/ydb-go-sdk/v3/internal/balancer.(*Balancer).applyDiscoveredEndpoints"),
-			b.config.DetectLocalDC,
+			b.config.DetectNearestDC,
 		)
 		previous = b.connections().All()
 	)

internal/balancer/config/routerconfig.go

@@ -10,10 +10,10 @@ import (
 // Dedicated package need for prevent cyclo dependencies config -> balancer -> config
 
 type Config struct {
-	Filter        Filter
-	AllowFallback bool
-	SingleConn    bool
-	DetectLocalDC bool
+	Filter          Filter
+	AllowFallback   bool
+	SingleConn      bool
+	DetectNearestDC bool
 }
 
 func (c Config) String() string {
@@ -26,8 +26,8 @@ func (c Config) String() string {
 
 	buffer.WriteString("RandomChoice{")
 
-	buffer.WriteString("DetectLocalDC=")
-	fmt.Fprintf(buffer, "%t", c.DetectLocalDC)
+	buffer.WriteString("DetectNearestDC=")
+	fmt.Fprintf(buffer, "%t", c.DetectNearestDC)
 
 	buffer.WriteString(",AllowFallback=")
 	fmt.Fprintf(buffer, "%t", c.AllowFallback)

internal/balancer/local_dc_test.go

@@ -131,7 +131,7 @@ func TestDetectLocalDC(t *testing.T) {
 func TestLocalDCDiscovery(t *testing.T) {
 	ctx := context.Background()
 	cfg := config.New(
-		config.WithBalancer(balancers.PreferLocalDC(balancers.Default())),
+		config.WithBalancer(balancers.PreferNearestDC(balancers.Default())),
 	)
 	r := &Balancer{
 		driverConfig: cfg,