ringhash: implement gRFC A76

- Add the ability to set the request hash header. This allows using ring hash
  without xDS.

- Add the ability to specify the location of endpoints on the ring, and a
  default implementation based on EDS metadata that matches Envoy behavior.

See https://github.com/grpc/proposal/blob/master/A76-ring-hash-improvements.md
for details.

Release Notes:

- ringhash: implement gRFC A76.

Author: atollena

internal/envconfig/envconfig.go

@@ -55,6 +55,18 @@ var (
 	// setting the environment variable "GRPC_EXPERIMENTAL_ENABLE_NEW_PICK_FIRST"
 	// to "false".
 	NewPickFirstEnabled = boolFromEnv("GRPC_EXPERIMENTAL_ENABLE_NEW_PICK_FIRST", true)
+
+	// XDSEndpointHashKeyBackwardCompat disables parsing of the endpoint hash
+	// key from EDS LbEndpoint metadata. We can disable this behavior by setting
+	// the environment variable "GRPC_XDS_ENDPOINT_HASH_KEY_BACKWARD_COMPAT" to
+	// "true".
+	XDSEndpointHashKeyBackwardCompat = boolFromEnv("GRPC_XDS_ENDPOINT_HASH_KEY_BACKWARD_COMPAT", true)
+
+	// RingHashSetRequestHashKey is set if the ring hash balancer can get the
+	// request hash header by setting the "request_hash_header" field, according
+	// to gRFC A76. It can be enabled by setting the environment variable
+	// "GRPC_EXPERIMENTAL_RING_HASH_SET_REQUEST_HASH_KEY" to "true".
+	RingHashSetRequestHashKey = boolFromEnv("GRPC_EXPERIMENTAL_RING_HASH_SET_REQUEST_HASH_KEY", false)
 )
 
 func boolFromEnv(envVar string, def bool) bool {

internal/metadata/metadata.go

@@ -97,13 +97,11 @@ func hasNotPrintable(msg string) bool {
 	return false
 }
 
-// ValidatePair validate a key-value pair with the following rules (the pseudo-header will be skipped) :
-//
-// - key must contain one or more characters.
-// - the characters in the key must be contained in [0-9 a-z _ - .].
-// - if the key ends with a "-bin" suffix, no validation of the corresponding value is performed.
-// - the characters in the every value must be printable (in [%x20-%x7E]).
-func ValidatePair(key string, vals ...string) error {
+// ValidateKey validates a key with the following rules (pseudo-headers are
+// skipped):
+// - the key must contain one or more characters.
+// - the characters in the key must be in [0-9 a-z _ - .].
+func ValidateKey(key string) error {
 	// key should not be empty
 	if key == "" {
 		return fmt.Errorf("there is an empty key in the header")
@@ -119,6 +117,20 @@ func ValidatePair(key string, vals ...string) error {
 			return fmt.Errorf("header key %q contains illegal characters not in [0-9a-z-_.]", key)
 		}
 	}
+	return nil
+}
+
+// ValidatePair validates a key-value pair with the following rules
+// (pseudo-header are skipped):
+//   - the key must contain one or more characters.
+//   - the characters in the key must be in [0-9 a-z _ - .].
+//   - if the key ends with a "-bin" suffix, no validation of the corresponding
+//     value is performed.
+//   - the characters in every value must be printable (in [%x20-%x7E]).
+func ValidatePair(key string, vals ...string) error {
+	if err := ValidateKey(key); err != nil {
+		return err
+	}
 	if strings.HasSuffix(key, "-bin") {
 		return nil
 	}

internal/testutils/xds/e2e/clientresources.go

@@ -23,6 +23,8 @@ import (
 	"net"
 	"strconv"
 
+	"google.golang.org/protobuf/types/known/structpb"
+
 	"github.com/envoyproxy/go-control-plane/pkg/wellknown"
 	"google.golang.org/protobuf/proto"
 	"google.golang.org/protobuf/types/known/anypb"
@@ -715,6 +717,9 @@ type BackendOptions struct {
 	HealthStatus v3corepb.HealthStatus
 	// Weight sets the backend weight. Defaults to 1.
 	Weight uint32
+	// Metadata sets the LB endpoint metadata (envoy.lb FilterMetadata field).
+	// See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-msg-config-core-v3-metadata
+	Metadata map[string]any
 }
 
 // EndpointOptions contains options to configure an Endpoint (or
@@ -774,6 +779,10 @@ func EndpointResourceWithOptions(opts EndpointOptions) *v3endpointpb.ClusterLoad
 					},
 				}
 			}
+			metadata, err := structpb.NewStruct(b.Metadata)
+			if err != nil {
+				panic(err)
+			}
 			lbEndpoints = append(lbEndpoints, &v3endpointpb.LbEndpoint{
 				HostIdentifier: &v3endpointpb.LbEndpoint_Endpoint{Endpoint: &v3endpointpb.Endpoint{
 					Address: &v3corepb.Address{Address: &v3corepb.Address_SocketAddress{
@@ -787,6 +796,11 @@ func EndpointResourceWithOptions(opts EndpointOptions) *v3endpointpb.ClusterLoad
 				}},
 				HealthStatus:        b.HealthStatus,
 				LoadBalancingWeight: &wrapperspb.UInt32Value{Value: b.Weight},
+				Metadata: &v3corepb.Metadata{
+					FilterMetadata: map[string]*structpb.Struct{
+						"envoy.lb": metadata,
+					},
+				},
 			})
 		}
 

resolver/ringhash/attr.go

@@ -0,0 +1,59 @@
+/*
+ *
+ * Copyright 2025 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 ringhash implements resolver related functions for the ring_hash
+// load balancing policy.
+package ringhash
+
+import (
+	"google.golang.org/grpc/resolver"
+)
+
+type hashKeyType string
+
+// hashKeyKey is the key to store the ring hash key attribute in
+// a resolver.Endpoint attribute.
+const hashKeyKey = hashKeyType("hash_key")
+
+// SetEndpointHashKey sets the hash key for this endpoint. Combined with the
+// ring_hash load balancing policy, it allows placing the endpoint on the ring
+// based on an arbitrary string instead of the IP address.
+//
+// # Experimental
+//
+// Notice: This API is EXPERIMENTAL and may be changed or removed in a
+// later release.
+func SetEndpointHashKey(ep resolver.Endpoint, hashKey string) resolver.Endpoint {
+	if hashKey == "" {
+		return ep
+	}
+	ep.Attributes = ep.Attributes.WithValue(hashKeyKey, hashKey)
+	return ep
+}
+
+// GetEndpointHashKey returns the hash key attribute of addr. If this attribute
+// is not set, it returns the empty string.
+//
+// # Experimental
+//
+// Notice: This API is EXPERIMENTAL and may be changed or removed in a
+// later release.
+func GetEndpointHashKey(ep resolver.Endpoint) string {
+	hashKey, _ := ep.Attributes.Value(hashKeyKey).(string)
+	return hashKey
+}

xds/internal/balancer/clusterresolver/configbuilder.go

@@ -27,6 +27,7 @@ import (
 	"google.golang.org/grpc/internal/hierarchy"
 	internalserviceconfig "google.golang.org/grpc/internal/serviceconfig"
 	"google.golang.org/grpc/resolver"
+	"google.golang.org/grpc/resolver/ringhash"
 	"google.golang.org/grpc/xds/internal"
 	"google.golang.org/grpc/xds/internal/balancer/clusterimpl"
 	"google.golang.org/grpc/xds/internal/balancer/outlierdetection"
@@ -282,6 +283,7 @@ func priorityLocalitiesToClusterImpl(localities []xdsresource.Locality, priority
 				ew = endpoint.Weight
 			}
 			resolverEndpoint = weight.Set(resolverEndpoint, weight.EndpointInfo{Weight: lw * ew})
+			resolverEndpoint = ringhash.SetEndpointHashKey(resolverEndpoint, endpoint.HashKey)
 			retEndpoints = append(retEndpoints, resolverEndpoint)
 		}
 	}

xds/internal/balancer/ringhash/config.go

@@ -21,17 +21,20 @@ package ringhash
 import (
 	"encoding/json"
 	"fmt"
+	"strings"
 
 	"google.golang.org/grpc/internal/envconfig"
+	"google.golang.org/grpc/internal/metadata"
 	"google.golang.org/grpc/serviceconfig"
 )
 
 // LBConfig is the balancer config for ring_hash balancer.
 type LBConfig struct {
 	serviceconfig.LoadBalancingConfig `json:"-"`
 
-	MinRingSize uint64 `json:"minRingSize,omitempty"`
-	MaxRingSize uint64 `json:"maxRingSize,omitempty"`
+	MinRingSize       uint64 `json:"minRingSize,omitempty"`
+	MaxRingSize       uint64 `json:"maxRingSize,omitempty"`
+	RequestHashHeader string `json:"request_hash_header,omitempty"`
 }
 
 const (
@@ -66,5 +69,17 @@ func parseConfig(c json.RawMessage) (*LBConfig, error) {
 	if cfg.MaxRingSize > envconfig.RingHashCap {
 		cfg.MaxRingSize = envconfig.RingHashCap
 	}
+	if !envconfig.RingHashSetRequestHashKey {
+		cfg.RequestHashHeader = ""
+	}
+	if cfg.RequestHashHeader != "" {
+		// See rules in https://github.com/grpc/proposal/blob/b64e6d3953816ed3b16b88bde0b7c16d3b62654f/A76-ring-hash-improvements.md#explicitly-setting-the-request-hash-key
+		if err := metadata.ValidateKey(cfg.RequestHashHeader); err != nil {
+			return nil, fmt.Errorf("invalid request_metadata_key %q: %s", cfg.RequestHashHeader, err)
+		}
+		if strings.HasSuffix(cfg.RequestHashHeader, "-bin") {
+			return nil, fmt.Errorf("invalid request_metadata_key %q: key must not end with \"-bin\"", cfg.RequestHashHeader)
+		}
+	}
 	return &cfg, nil
 }

xds/internal/balancer/ringhash/config_test.go

@@ -26,6 +26,10 @@ import (
 )
 
 func (s) TestParseConfig(t *testing.T) {
+	oldEnvConfig := envconfig.RingHashSetRequestHashKey
+	defer func() { envconfig.RingHashSetRequestHashKey = oldEnvConfig }()
+	envconfig.RingHashSetRequestHashKey = true
+
 	tests := []struct {
 		name         string
 		js           string
@@ -94,6 +98,27 @@ func (s) TestParseConfig(t *testing.T) {
 			want:    nil,
 			wantErr: true,
 		},
+		{
+			name: "request metadata key set",
+			js:   `{"request_hash_header": "x-foo"}`,
+			want: &LBConfig{
+				MinRingSize:       defaultMinSize,
+				MaxRingSize:       defaultMaxSize,
+				RequestHashHeader: "x-foo",
+			},
+		},
+		{
+			name:    "invalid request hash header",
+			js:      `{"request_hash_header": "!invalid"}`,
+			want:    nil,
+			wantErr: true,
+		},
+		{
+			name:    "binary request hash header",
+			js:      `{"request_hash_header": "header-with-bin"}`,
+			want:    nil,
+			wantErr: true,
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {