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

internal/xds/clients/config.go

@@ -0,0 +1,140 @@
+/*
+ *
+ * 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 clients provides implementations of the clients to interact with
+// xDS and LRS servers.
+//
+// # xDS Client
+//
+// The xDS client allows applications to:
+//   - Create client instances with in-memory configurations.
+//   - Register watches for named resources.
+//   - Receive resources via the ADS (Aggregated Discovery Service) stream.
+//
+// This enables applications to dynamically discover and configure resources
+// such as listeners, routes, clusters, and endpoints from an xDS management
+// server.
+//
+// # LRS Client
+//
+// The LRS (Load Reporting Service) client allows applications to report load
+// data to an LRS server via the LRS stream. This data can be used for
+// monitoring, traffic management, and other purposes.
+//
+// # Experimental
+//
+// NOTICE: This package is EXPERIMENTAL and may be changed or removed
+// in a later release.
+package clients
+
+// ServerIdentifier holds identifying information for connecting to an xDS
+// management or LRS server.
+type ServerIdentifier struct {
+	// ServerURI is the target URI of the server.
+	ServerURI string
+
+	// Extensions can be populated with arbitrary data to be passed to the
+	// TransportBuilder and/or xDS Client's ResourceType implementations.
+	// This field can be used to provide additional configuration or context
+	// specific to the user's needs.
+	//
+	// The xDS and LRS clients do not interpret the contents of this field.
+	// It is the responsibility of the user's custom TransportBuilder and/or
+	// ResourceType implementations to handle and interpret these extensions.
+	//
+	// For example, a custom TransportBuilder might use this field to
+	// configure a specific security credentials.
+	//
+	// Extensions may be any type that is comparable, as they are used as map
+	// keys internally. If Extensions are not able to be used as a map key,
+	// the client may panic.
+	//
+	// See: https://go.dev/ref/spec#Comparison_operators
+	//
+	// Any equivalent extensions in all ServerIdentifiers present in a single
+	// client's configuration should have the same value. Not following this
+	// restriction may result in excess resource usage.
+	Extensions any
+}
+
+// Node represents the identity of the xDS client, allowing xDS and LRS servers
+// to identify the source of xDS requests.
+type Node struct {
+	// ID is a string identifier of the application.
+	ID string
+	// Cluster is the name of the cluster the application belongs to.
+	Cluster string
+	// Locality is the location of the application including region, zone,
+	// sub-zone.
+	Locality Locality
+	// Metadata provides additional context about the application by associating
+	// arbitrary key-value pairs with it.
+	Metadata any
+	// UserAgentName is the user agent name of application.
+	UserAgentName string
+	// UserAgentVersion is the user agent version of application.
+	UserAgentVersion string
+}
+
+// Locality represents the location of the xDS client application.
+type Locality struct {
+	// Region is the region of the xDS client application.
+	Region string
+	// Zone is the area within a region.
+	Zone string
+	// SubZone is the further subdivision within a zone.
+	SubZone string
+}
+
+// MetricsReporter is used by the XDSClient to report metrics.
+type MetricsReporter interface {
+	// ReportMetric reports a metric. The metric will be one of the predefined
+	// set of types depending on the client (XDSClient or LRSClient).
+	//
+	// Each client will produce different metrics. Please see the client's
+	// documentation for a list of possible metrics events.
+	ReportMetric(metric any)
+
+	// RegisterAsyncReporter registers a reporter to produce metric values for
+	// the set of metrics supported by the client. See the metrics sub-package
+	// for the specific client (e.g. internal/xds/clients/xdsclient/metrics/metrics.go)
+	// for the list of supported metrics. The returned function must be called
+	// when the metrics are no longer needed, which will remove the reporter.
+	// The function is expected to be idempotent.
+	//
+	// Once the returned cancel function is called, the Report method on the
+	// registered reporter is guaranteed not to be called again.
+	RegisterAsyncReporter(reporter AsyncReporter) func()
+}
+
+// AsyncReporter records metrics asynchronously.
+// Implementations must be concurrent-safe.
+// The metric will be recorded once per collection cycle, rather than every time
+// its value changes.
+type AsyncReporter interface {
+	// Report records metric values using the provided recorder.
+	Report(AsyncMetricsRecorder) error
+}
+
+// AsyncMetricsRecorder is a recorder for async metrics (i.e the metric will be
+// recorded once per collection cycle, rather than every time its value changes).
+type AsyncMetricsRecorder interface {
+	// ReportMetric reports a metric. The metric will be one of the predefined
+	// set of types in the internal/xds/clients/xdsclient/metrics/metrics.go file.
+	ReportMetric(metric any)
+}