snapshot of https://github.com/grpc/grpc-go.git (master, 2026-09-15; blobs > 131072B omitted)

internal/xds/clusterspecifier/cluster_specifier.go

@@ -0,0 +1,72 @@
+/*
+ *
+ * Copyright 2021 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 clusterspecifier contains the ClusterSpecifier interface and a registry for
+// storing and retrieving their implementations.
+package clusterspecifier
+
+import (
+	"google.golang.org/protobuf/proto"
+)
+
+// BalancerConfig is the Go Native JSON representation of a balancer
+// configuration.
+type BalancerConfig []map[string]any
+
+// ClusterSpecifier defines the parsing functionality of a Cluster Specifier.
+type ClusterSpecifier interface {
+	// TypeURLs are the proto message types supported by this
+	// ClusterSpecifierPlugin. A ClusterSpecifierPlugin will be registered by
+	// each of its supported message types.
+	TypeURLs() []string
+	// ParseClusterSpecifierConfig parses the provided configuration
+	// proto.Message from the top level RDS configuration. The resulting
+	// BalancerConfig will be used as configuration for a child LB Policy of the
+	// Cluster Manager LB Policy. A nil BalancerConfig is invalid.
+	ParseClusterSpecifierConfig(proto.Message) (BalancerConfig, error)
+}
+
+var (
+	// m is a map from scheme to filter.
+	m = make(map[string]ClusterSpecifier)
+)
+
+// Register registers the ClusterSpecifierPlugin to the ClusterSpecifier map.
+// cs.TypeURLs() will be used as the types for this ClusterSpecifierPlugin.
+//
+// NOTE: this function must only be called during initialization time (i.e. in
+// an init() function), and is not thread-safe. If multiple cluster specifier
+// plugins are registered with the same type URL, the one registered last will
+// take effect.
+func Register(cs ClusterSpecifier) {
+	for _, u := range cs.TypeURLs() {
+		m[u] = cs
+	}
+}
+
+// Get returns the ClusterSpecifier registered with typeURL.
+//
+// If no cluster specifier is registered with typeURL, nil will be returned.
+func Get(typeURL string) ClusterSpecifier {
+	return m[typeURL]
+}
+
+// UnregisterForTesting unregisters the ClusterSpecifier for testing purposes.
+func UnregisterForTesting(typeURL string) {
+	delete(m, typeURL)
+}

internal/xds/clusterspecifier/rls/rls.go

@@ -0,0 +1,95 @@
+/*
+ *
+ * Copyright 2021 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 rls implements the RLS cluster specifier plugin.
+package rls
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"google.golang.org/grpc/balancer"
+	"google.golang.org/grpc/internal"
+	rlspb "google.golang.org/grpc/internal/proto/grpc_lookup_v1"
+	"google.golang.org/grpc/internal/xds/clusterspecifier"
+	"google.golang.org/protobuf/encoding/protojson"
+	"google.golang.org/protobuf/proto"
+	"google.golang.org/protobuf/types/known/anypb"
+)
+
+func init() {
+	clusterspecifier.Register(rls{})
+}
+
+type rls struct{}
+
+func (rls) TypeURLs() []string {
+	return []string{"type.googleapis.com/grpc.lookup.v1.RouteLookupClusterSpecifier"}
+}
+
+// lbConfigJSON is the RLS LB Policies configuration in JSON format.
+// RouteLookupConfig will be a raw JSON string from the passed in proto
+// configuration, and the other fields will be hardcoded.
+type lbConfigJSON struct {
+	RouteLookupConfig                json.RawMessage              `json:"routeLookupConfig"`
+	ChildPolicy                      []map[string]json.RawMessage `json:"childPolicy"`
+	ChildPolicyConfigTargetFieldName string                       `json:"childPolicyConfigTargetFieldName"`
+}
+
+func (rls) ParseClusterSpecifierConfig(cfg proto.Message) (clusterspecifier.BalancerConfig, error) {
+	if cfg == nil {
+		return nil, fmt.Errorf("rls_csp: nil configuration message provided")
+	}
+	m, ok := cfg.(*anypb.Any)
+	if !ok {
+		return nil, fmt.Errorf("rls_csp: error parsing config %v: unknown type %T", cfg, cfg)
+	}
+	rlcs := new(rlspb.RouteLookupClusterSpecifier)
+
+	if err := m.UnmarshalTo(rlcs); err != nil {
+		return nil, fmt.Errorf("rls_csp: error parsing config %v: %v", cfg, err)
+	}
+	rlcJSON, err := protojson.Marshal(rlcs.GetRouteLookupConfig())
+	if err != nil {
+		return nil, fmt.Errorf("rls_csp: error marshaling route lookup config: %v: %v", rlcs.GetRouteLookupConfig(), err)
+	}
+	lbCfgJSON := &lbConfigJSON{
+		RouteLookupConfig: rlcJSON, // "JSON form of RouteLookupClusterSpecifier.config" - RLS in xDS Design Doc
+		ChildPolicy: []map[string]json.RawMessage{
+			{
+				"cds_experimental": json.RawMessage(`{"isDynamic":true}`),
+			},
+		},
+		ChildPolicyConfigTargetFieldName: "cluster",
+	}
+
+	rawJSON, err := json.Marshal(lbCfgJSON)
+	if err != nil {
+		return nil, fmt.Errorf("rls_csp: error marshaling load balancing config %v: %v", lbCfgJSON, err)
+	}
+
+	rlsBB := balancer.Get(internal.RLSLoadBalancingPolicyName)
+	if rlsBB == nil {
+		return nil, fmt.Errorf("RLS LB policy not registered")
+	}
+	if _, err = rlsBB.(balancer.ConfigParser).ParseConfig(rawJSON); err != nil {
+		return nil, fmt.Errorf("rls_csp: validation error from rls lb policy parsing: %v", err)
+	}
+
+	return clusterspecifier.BalancerConfig{{internal.RLSLoadBalancingPolicyName: lbCfgJSON}}, nil
+}

internal/xds/clusterspecifier/rls/rls_test.go

@@ -0,0 +1,162 @@
+/*
+ *
+ * Copyright 2021 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 rls
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+	"google.golang.org/grpc/internal/grpctest"
+	rlspb "google.golang.org/grpc/internal/proto/grpc_lookup_v1"
+	"google.golang.org/grpc/internal/testutils"
+	"google.golang.org/grpc/internal/xds/clusterspecifier"
+	"google.golang.org/protobuf/proto"
+	"google.golang.org/protobuf/types/known/durationpb"
+
+	_ "google.golang.org/grpc/balancer/rls"                      // Register the RLS LB policy.
+	_ "google.golang.org/grpc/internal/xds/balancer/cdsbalancer" // Register the CDS LB policy.
+)
+
+func init() {
+	clusterspecifier.Register(rls{})
+}
+
+type s struct {
+	grpctest.Tester
+}
+
+func Test(t *testing.T) {
+	grpctest.RunSubTests(t, s{})
+}
+
+// TestParseClusterSpecifierConfig tests the parsing functionality of the RLS
+// Cluster Specifier Plugin.
+func (s) TestParseClusterSpecifierConfig(t *testing.T) {
+	tests := []struct {
+		name       string
+		rlcs       proto.Message
+		wantConfig clusterspecifier.BalancerConfig
+		wantErr    bool
+	}{
+		{
+
+			// This will error because the required_match field is set in grpc key builder
+			name: "invalid-rls-cluster-specifier",
+			rlcs: testutils.MarshalAny(t, &rlspb.RouteLookupClusterSpecifier{
+				RouteLookupConfig: &rlspb.RouteLookupConfig{
+					GrpcKeybuilders: []*rlspb.GrpcKeyBuilder{
+						{
+							Names: []*rlspb.GrpcKeyBuilder_Name{
+								{
+									Service: "service",
+									Method:  "method",
+								},
+							},
+							Headers: []*rlspb.NameMatcher{
+								{
+									Key:           "k1",
+									RequiredMatch: true,
+									Names:         []string{"v1"},
+								},
+							},
+						},
+					},
+				},
+			}),
+			wantErr: true,
+		},
+		{
+			name: "valid-rls-cluster-specifier",
+			rlcs: testutils.MarshalAny(t, &rlspb.RouteLookupClusterSpecifier{
+				RouteLookupConfig: &rlspb.RouteLookupConfig{
+					GrpcKeybuilders: []*rlspb.GrpcKeyBuilder{
+						{
+							Names: []*rlspb.GrpcKeyBuilder_Name{
+								{
+									Service: "service",
+									Method:  "method",
+								},
+							},
+							Headers: []*rlspb.NameMatcher{
+								{
+									Key:   "k1",
+									Names: []string{"v1"},
+								},
+							},
+						},
+					},
+					LookupService:        "target",
+					LookupServiceTimeout: &durationpb.Duration{Seconds: 100},
+					MaxAge:               &durationpb.Duration{Seconds: 60},
+					StaleAge:             &durationpb.Duration{Seconds: 50},
+					CacheSizeBytes:       1000,
+					DefaultTarget:        "passthrough:///default",
+				},
+			}),
+			wantConfig: configWithoutTransformationsWant,
+		},
+	}
+	for _, test := range tests {
+		cs := clusterspecifier.Get("type.googleapis.com/grpc.lookup.v1.RouteLookupClusterSpecifier")
+		if cs == nil {
+			t.Fatal("Error getting cluster specifier")
+		}
+		lbCfg, err := cs.ParseClusterSpecifierConfig(test.rlcs)
+
+		if (err != nil) != test.wantErr {
+			t.Fatalf("ParseClusterSpecifierConfig(%+v) returned err: %v, wantErr: %v", test.rlcs, err, test.wantErr)
+		}
+		if test.wantErr { // Successfully received an error.
+			continue
+		}
+		// Marshal and then unmarshal into any to get rid of nondeterministic
+		// protojson Marshaling.
+		lbCfgJSON, err := json.Marshal(lbCfg)
+		if err != nil {
+			t.Fatalf("json.Marshal(%+v) returned err %v", lbCfg, err)
+		}
+		var got any
+		if err := json.Unmarshal(lbCfgJSON, &got); err != nil {
+			t.Fatalf("json.Unmarshal(%+v) returned err %v", lbCfgJSON, err)
+		}
+		wantCfgJSON, err := json.Marshal(test.wantConfig)
+		if err != nil {
+			t.Fatalf("json.Marshal(%+v) returned err %v", test.wantConfig, err)
+		}
+		var want any
+		if err := json.Unmarshal(wantCfgJSON, &want); err != nil {
+			t.Fatalf("json.Unmarshal(%+v) returned err %v", lbCfgJSON, err)
+		}
+		if diff := cmp.Diff(want, got, cmpopts.EquateEmpty()); diff != "" {
+			t.Fatalf("ParseClusterSpecifierConfig(%+v) returned expected, diff (-want +got) %v", test.rlcs, diff)
+		}
+	}
+}
+
+var configWithoutTransformationsWant = clusterspecifier.BalancerConfig{{"rls_experimental": &lbConfigJSON{
+	RouteLookupConfig: []byte(`{"grpcKeybuilders":[{"names":[{"service":"service","method":"method"}],"headers":[{"key":"k1","names":["v1"]}]}],"lookupService":"target","lookupServiceTimeout":"100s","maxAge":"60s","staleAge":"50s","cacheSizeBytes":"1000","defaultTarget":"passthrough:///default"}`),
+	ChildPolicy: []map[string]json.RawMessage{
+		{
+			"cds_experimental": []byte(`{"isDynamic":true}`),
+		},
+	},
+	ChildPolicyConfigTargetFieldName: "cluster",
+}}}