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

xds/bootstrap/bootstrap.go

@@ -0,0 +1,102 @@
+/*
+ *
+ * Copyright 2022 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 bootstrap provides the functionality to register possible options
+// for aspects of the xDS client through the bootstrap file.
+//
+// # Experimental
+//
+// Notice: This package is EXPERIMENTAL and may be changed or removed
+// in a later release.
+package bootstrap
+
+import (
+	"encoding/json"
+
+	"google.golang.org/grpc/credentials"
+)
+
+// channelCredsRegistry is a map from channel credential type name to
+// ChannelCredential builder.
+var channelCredsRegistry = make(map[string]ChannelCredentials)
+
+// callCredsRegistry is a map from call credential type name to
+// ChannelCredential builder.
+var callCredsRegistry = make(map[string]CallCredentials)
+
+// ChannelCredentials interface encapsulates a credentials.Bundle builder
+// that can be used for communicating with the xDS Management server.
+type ChannelCredentials interface {
+	// Build returns a credential bundle associated with this credential, and a
+	// function to clean up any additional resources associated with this bundle
+	// when it is no longer needed.
+	Build(config json.RawMessage) (credentials.Bundle, func(), error)
+	// Name returns the credential name associated with this credential.
+	Name() string
+}
+
+// RegisterChannelCredentials registers ChannelCredentials used for connecting
+// to the xDS management server.
+//
+// NOTE: this function must only be called during initialization time (i.e. in
+// an init() function), and is not thread-safe. If multiple credentials are
+// registered with the same name, the one registered last will take effect.
+func RegisterChannelCredentials(c ChannelCredentials) {
+	channelCredsRegistry[c.Name()] = c
+}
+
+// GetChannelCredentials returns the credentials associated with a given name.
+// If no credentials are registered with the name, nil will be returned.
+func GetChannelCredentials(name string) ChannelCredentials {
+	if c, ok := channelCredsRegistry[name]; ok {
+		return c
+	}
+
+	return nil
+}
+
+// CallCredentials interface encapsulates a credentials.PerRPCCredentials
+// builder that can be used for communicating with the xDS Management server.
+type CallCredentials interface {
+	// Build returns a PerRPCCredentials created from the provided
+	// configuration, and a function to clean up any additional resources
+	// associated with them when they are no longer needed.
+	Build(config json.RawMessage) (credentials.PerRPCCredentials, func(), error)
+	// Name returns the credential name associated with this credential.
+	Name() string
+}
+
+// RegisterCallCredentials registers CallCredentials used for connecting
+// to the xDS management server.
+//
+// NOTE: this function must only be called during initialization time (i.e. in
+// an init() function), and is not thread-safe. If multiple credentials are
+// registered with the same name, the one registered last will take effect.
+func RegisterCallCredentials(c CallCredentials) {
+	callCredsRegistry[c.Name()] = c
+}
+
+// GetCallCredentials returns the credentials associated with a given name.
+// If no credentials are registered with the name, nil will be returned.
+func GetCallCredentials(name string) CallCredentials {
+	if c, ok := callCredsRegistry[name]; ok {
+		return c
+	}
+
+	return nil
+}

xds/bootstrap/bootstrap_test.go

@@ -0,0 +1,119 @@
+/*
+ *
+ * Copyright 2022 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 bootstrap
+
+import (
+	"encoding/json"
+	"testing"
+
+	"google.golang.org/grpc/credentials"
+)
+
+const testCredsBuilderName = "test_creds"
+
+var builder = &testCredsBuilder{}
+
+func init() {
+	RegisterChannelCredentials(builder)
+}
+
+type testCredsBuilder struct {
+	config json.RawMessage
+}
+
+func (t *testCredsBuilder) Build(config json.RawMessage) (credentials.Bundle, func(), error) {
+	t.config = config
+	return nil, nil, nil
+}
+
+func (t *testCredsBuilder) Name() string {
+	return testCredsBuilderName
+}
+
+func TestRegisterNew(t *testing.T) {
+	c := GetChannelCredentials(testCredsBuilderName)
+	if c == nil {
+		t.Fatalf("GetCredentials(%q) credential = nil", testCredsBuilderName)
+	}
+
+	const sampleConfig = "sample_config"
+	rawMessage := json.RawMessage(sampleConfig)
+	if _, _, err := c.Build(rawMessage); err != nil {
+		t.Errorf("Build(%v) error = %v, want nil", rawMessage, err)
+	}
+
+	if got, want := string(builder.config), sampleConfig; got != want {
+		t.Errorf("Build config = %v, want %v", got, want)
+	}
+}
+
+func TestChannelCredsBuilders(t *testing.T) {
+	tests := []struct {
+		typename string
+		builder  ChannelCredentials
+	}{
+		{"google_default", &googleDefaultCredsBuilder{}},
+		{"insecure", &insecureCredsBuilder{}},
+		{"tls", &tlsCredsBuilder{}},
+	}
+
+	for _, test := range tests {
+		t.Run(test.typename, func(t *testing.T) {
+			if got, want := test.builder.Name(), test.typename; got != want {
+				t.Errorf("%T.Name = %v, want %v", test.builder, got, want)
+			}
+
+			bundle, stop, err := test.builder.Build(nil)
+			if err != nil {
+				t.Fatalf("%T.Build failed: %v", test.builder, err)
+			}
+			if bundle == nil {
+				t.Errorf("%T.Build returned nil bundle, expected non-nil", test.builder)
+			}
+			stop()
+		})
+	}
+}
+
+func TestJWTCallCredsBuilder(t *testing.T) {
+	builder := &jwtCallCredsBuilder{}
+	config := json.RawMessage(`{"jwt_token_file":"/path/to/token.jwt"}`)
+
+	creds, stop, err := builder.Build(config)
+	if err != nil {
+		t.Fatalf("Build(%s) failed: %v", config, err)
+	}
+	defer stop()
+	if creds == nil {
+		t.Errorf("Build(%s) returned nil creds, expected non-nil", config)
+	}
+}
+
+func TestTlsCredsBuilder(t *testing.T) {
+	tls := &tlsCredsBuilder{}
+	_, stop, err := tls.Build(json.RawMessage(`{}`))
+	if err != nil {
+		t.Fatalf("tls.Build() failed with error %s when expected to succeed", err)
+	}
+	defer stop()
+
+	if _, stop, err := tls.Build(json.RawMessage(`{"ca_certificate_file":"/ca_certificates.pem","refresh_interval": "asdf"}`)); err == nil {
+		defer stop()
+		t.Errorf("tls.Build() succeeded with an invalid refresh interval, when expected to fail")
+	}
+}

xds/bootstrap/credentials.go

@@ -0,0 +1,85 @@
+/*
+ *
+ * Copyright 2024 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 bootstrap
+
+import (
+	"encoding/json"
+
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/credentials/google"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/grpc/internal/xds/bootstrap/jwtcreds"
+	"google.golang.org/grpc/internal/xds/bootstrap/tlscreds"
+)
+
+func init() {
+	RegisterChannelCredentials(&insecureCredsBuilder{})
+	RegisterChannelCredentials(&googleDefaultCredsBuilder{})
+	RegisterChannelCredentials(&tlsCredsBuilder{})
+
+	RegisterCallCredentials(&jwtCallCredsBuilder{})
+}
+
+// insecureCredsBuilder implements the `ChannelCredentials` interface defined in
+// package `xds/bootstrap` and encapsulates an insecure credential.
+type insecureCredsBuilder struct{}
+
+func (i *insecureCredsBuilder) Build(json.RawMessage) (credentials.Bundle, func(), error) {
+	return insecure.NewBundle(), func() {}, nil
+}
+
+func (i *insecureCredsBuilder) Name() string {
+	return "insecure"
+}
+
+// tlsCredsBuilder implements the `ChannelCredentials` interface defined in
+// package `xds/bootstrap` and encapsulates a TLS credential.
+type tlsCredsBuilder struct{}
+
+func (t *tlsCredsBuilder) Build(config json.RawMessage) (credentials.Bundle, func(), error) {
+	return tlscreds.NewBundle(config)
+}
+
+func (t *tlsCredsBuilder) Name() string {
+	return "tls"
+}
+
+// googleDefaultCredsBuilder implements the `ChannelCredentials` interface defined in
+// package `xds/bootstrap` and encapsulates a Google Default credential.
+type googleDefaultCredsBuilder struct{}
+
+func (d *googleDefaultCredsBuilder) Build(json.RawMessage) (credentials.Bundle, func(), error) {
+	return google.NewDefaultCredentials(), func() {}, nil
+}
+
+func (d *googleDefaultCredsBuilder) Name() string {
+	return "google_default"
+}
+
+// jwtCallCredsBuilder implements the `CallCredentials` interface defined in
+// package `xds/bootstrap` and encapsulates JWT call credentials.
+type jwtCallCredsBuilder struct{}
+
+func (j *jwtCallCredsBuilder) Build(configJSON json.RawMessage) (credentials.PerRPCCredentials, func(), error) {
+	return jwtcreds.NewCallCredentials(configJSON)
+}
+
+func (j *jwtCallCredsBuilder) Name() string {
+	return "jwt_token_file"
+}