doug

xds/internal/clients/lrsclient/load_store.go

@@ -20,8 +20,8 @@
 
 package lrsclient
 
-// LoadStore keep track of the loads for multiple clusters and services that
-// are intended to be reported via LRS.
+// A LoadStore aggregates loads for multiple clusters and services that are
+// intended to be reported via LRS.
 //
 // LoadStore stores loads reported to a single LRS server. Use multiple stores
 // for multiple servers.
@@ -30,28 +30,39 @@ package lrsclient
 type LoadStore struct {
 }
 
-// PerCluster returns the PerClusterReporter for the given cluster and service.
-func (ls *LoadStore) PerCluster(clusterName, serviceName string) PerClusterReporter {
+// Stop stops the LoadStore's load reporting stream.
+func (ls *LoadStore) Stop() error {
 	panic("unimplemented")
 }
 
-// PerClusterReporter defines the methods that the LoadStore uses to track
-// per-cluster load reporting data.
-//
-// The lrsclient package provides an implementation of this which can be used
-// to push loads to the received LoadStore from the LRS client.
-type PerClusterReporter interface {
-	// CallStarted records a call started in the LoadStore.
-	CallStarted(locality string)
-	// CallFinished records a call finished in the LoadStore.
-	CallFinished(locality string, err error)
-	// CallServerLoad records the server load in the LoadStore.
-	CallServerLoad(locality, name string, val float64)
-	// CallDropped records a call dropped in the LoadStore.
-	CallDropped(category string)
+// ReporterForCluster returns the PerClusterReporter for the given cluster and
+// service.
+func (ls *LoadStore) ReporterForCluster(clusterName, serviceName string) PerClusterReporter {
+	panic("unimplemented")
 }
 
-// Stop stops the LoadStore's load reporting stream.
-func (ls *LoadStore) Stop() error {
+// PerClusterReporter records load data pertaining to a single cluster. It
+// provides methods to record call starts, finishes, server-reported loads,
+// and dropped calls.
+type PerClusterReporter struct {
+}
+
+// CallStarted records a call started in the LoadStore.
+func (p *PerClusterReporter) CallStarted(locality string) {
+	panic("unimplemented")
+}
+
+// CallFinished records a call finished in the LoadStore.
+func (p *PerClusterReporter) CallFinished(locality string, err error) {
+	panic("unimplemented")
+}
+
+// CallServerLoad records the server load in the LoadStore.
+func (p *PerClusterReporter) CallServerLoad(locality, name string, val float64) {
+	panic("unimplemented")
+}
+
+// CallDropped records a call dropped in the LoadStore.
+func (p *PerClusterReporter) CallDropped(category string) {
 	panic("unimplemented")
 }

xds/internal/clients/lrsclient/lrsclient.go

@@ -23,10 +23,6 @@
 // See: https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/load_stats/v3/lrs.proto
 package lrsclient
 
-import (
-	"google.golang.org/grpc/xds/internal/clients"
-)
-
 // LRSClient is an LRS (Load Reporting Service) client.
 type LRSClient struct {
 }
@@ -36,13 +32,17 @@ func New(config Config) (*LRSClient, error) {
 	panic("unimplemented")
 }
 
-// ReportLoad creates a new load reporting stream for the client. It creates a
-// LoadStore and return it for the caller to report loads.
-func (c *LRSClient) ReportLoad(serverConfig clients.ServerConfig) *LoadStore {
+// ReportLoad creates a new load reporting stream for the client. It creates
+// and returns a LoadStore for the caller to report loads.
+func (c *LRSClient) ReportLoad() *LoadStore {
 	panic("unimplemented")
 }
 
 // Close closes the LRS client.
+//
+// It blocks until all the in-flight load reporting streams of the LoadStore
+// are canceled and clean up the resources associated with the active
+// LoadStore.
 func (c *LRSClient) Close() error {
 	panic("unimplemented")
 }

xds/internal/clients/lrsclient/lrsconfig.go

@@ -23,8 +23,8 @@ import (
 )
 
 // Config is used to configure an LRS client. After one has been passed to the
-// LRS client's New function, it must not be modified. A Config may be reused;
-// the lrsclient package will also not modify it.
+// LRS client's New function, no part of it may modified. A Config may be
+// reused; the lrsclient package will also not modify it.
 type Config struct {
 	// Node is the identity of the client application reporting load to the
 	// LRS server.

xds/internal/clients/xdsclient/resource_type.go

@@ -20,7 +20,6 @@ package xdsclient
 
 import (
 	"google.golang.org/grpc/xds/internal/clients"
-	"google.golang.org/protobuf/types/known/anypb"
 )
 
 // ResourceType wraps all resource-type specific functionality. Each supported
@@ -32,8 +31,8 @@ type ResourceType struct {
 	// Config.
 	TypeURL string
 
-	// TypeName is the shorter representation of the TypeURL to identify the
-	// resource type. It can be used for logging/debugging purposes.
+	// TypeName is a shorter representation of the TypeURL to identify the
+	// resource type. It is used for logging/debugging purposes.
 	TypeName string
 
 	// AllResourcesRequiredInSotW indicates whether this resource type requires
@@ -50,12 +49,11 @@ type ResourceType struct {
 // Decoder wraps the resource-type specific functionality for validation
 // and deserialization.
 type Decoder interface {
-	// Decode deserializes and validates an xDS resource serialized inside the
-	// provided `Any` proto, as received from the xDS management server.
+	// Decode deserializes and validates an xDS resource as received from the
+	// xDS management server.
 	//
-	// If protobuf deserialization fails or resource validation fails,
-	// returns a non-nil error. Otherwise, returns a fully populated
-	// DecodeResult.
+	// If deserialization fails or resource validation fails, it returns a
+	// non-nil error. Otherwise, returns a fully populated DecodeResult.
 	Decode(resource any, options DecodeOptions) (*DecodeResult, error)
 }
 
@@ -66,19 +64,18 @@ type DecodeOptions struct {
 	// This contains useful data for resource validation.
 	Config *Config
 
-	// ServerConfig contains the server config (from the above bootstrap
-	// configuration) of the xDS server from which the current resource, for
-	// which Decode() is being invoked, was received.
+	// ServerConfig contains the configuration of the xDS server that provided
+	// the current resource being decoded.
 	ServerConfig *clients.ServerConfig
 }
 
 // DecodeResult is the result of a decode operation.
 type DecodeResult struct {
-	// Name is the name of the resource being watched.
+	// Name is the name of the decoded resource.
 	Name string
 
-	// Resource contains the configuration associated with the resource being
-	// watched.
+	// Resource contains the configuration associated with the decoded
+	// resource.
 	Resource ResourceData
 }
 
@@ -88,9 +85,9 @@ type DecodeResult struct {
 // received from the xDS management server.
 type ResourceData interface {
 	// RawEqual returns true if the passed in resource data is equal to that of
-	// the receiver, based on the underlying raw protobuf message.
+	// the receiver, based on the underlying raw message.
 	RawEqual(ResourceData) bool
 
-	// Raw returns the underlying raw protobuf form of the resource.
-	Raw() *anypb.Any
+	// Raw returns the underlying raw form of the resource.
+	Raw() any
 }

xds/internal/clients/xdsclient/resource_watcher.go

@@ -18,14 +18,15 @@
 
 package xdsclient
 
-// ResourceWatcher wraps the callbacks to be invoked for different events
-// corresponding to the resource being watched. gRFC A88 contains an exhaustive
-// list of what method is invoked under what conditions.
+// ResourceWatcher is notified of the resource updates and errors that are
+// received by the xDS client from the management server.
 //
-// done() in the callbacks is a function to be invoked by resource watcher
-// implementations upon completing the processing of a callback from the xDS
-// client for change and error respectively. Failure to invoke this callback
-// prevents the xDS client from reading further messages from the xDS server.
+// All methods contain a done parameter which should be called when processing
+// of the update has completed.  For example, if processing a resource requires
+// watching new resources, those watches should be completed before done is
+// called, which can happen after the ResourceWatcher method has returned.
+// Failure to call done will prevent the xDS client from providing future
+// ResourceWatcher notifications.
 type ResourceWatcher interface {
 	// ResourceChanged indicates a new version of the resource is available.
 	ResourceChanged(resourceData ResourceData, done func())
@@ -36,9 +37,9 @@ type ResourceWatcher interface {
 	ResourceError(err error, done func())
 
 	// AmbientError indicates an error occurred after a resource has been
-	// received that should not modify the use of that resource but may be
-	// provide useful information about the ambient state of the XDSClient for
-	// debugging purposes. The previous version of the resource should still be
+	// received that should not modify the use of that resource but may provide
+	// useful information about the state of the XDSClient for debugging
+	// purposes. The previous version of the resource should still be
 	// considered valid.
 	AmbientError(err error, done func())
 }

xds/internal/clients/xdsclient/xdsclient.go

@@ -18,12 +18,14 @@
  *
  */
 
-// Package xdsclient provides an xDS (Discovery Service) client.
+// Package xdsclient provides an xDS (*Discovery Service) client.
 //
 // It allows applications to:
 //   - Create xDS client instances with in-memory configurations.
 //   - Register watches for named resources.
 //   - Receive resources via an ADS (Aggregated Discovery Service) stream.
+//   - Register watches for named resources (e.g. listeners, routes, or
+//     clusters).
 //
 // This enables applications to dynamically discover and configure resources
 // such as listeners, routes, clusters, and endpoints from an xDS management

xds/internal/clients/xdsclient/xdsconfig.go

@@ -23,12 +23,12 @@ import (
 )
 
 // Config is used to configure an xDS client. After one has been passed to the
-// xDS client's New function, it must not be modified. A Config may be reused;
-// the xdsclient package will also not modify it.
+// xDS client's New function, no part of it may be modified. A Config may be
+// reused; the xdsclient package will also not modify it.
 type Config struct {
 	// Servers specifies a list of xDS management servers to connect to. The
 	// order of the servers in this list reflects the order of preference of
-	// the data returned by those servers. xDS client use the first
+	// the data returned by those servers. The xDS client uses the first
 	// available server from the list.
 	//
 	// See gRFC A71 for more details on fallback behavior when the primary
@@ -37,15 +37,15 @@ type Config struct {
 	// gRFC A71: https://github.com/grpc/proposal/blob/master/A71-xds-fallback.md
 	Servers []clients.ServerConfig
 
-	// Authorities map is used to define different authorities, in a federated
-	// setup, each with its own set of xDS management servers.
+	// Authorities defines the configuration for each xDS authority.  Federated resources
+	// will be fetched from the servers specified by the corresponding Authority.
 	Authorities map[string]Authority
 
 	// Node is the identity of the xDS client connecting to the xDS
 	// management server.
 	Node clients.Node
 
-	// TransportBuilder is used to connect to the xDS management server.
+	// TransportBuilder is used to create connections to xDS management servers.
 	TransportBuilder clients.TransportBuilder
 
 	// ResourceTypes is a map from resource type URLs to resource type
@@ -58,17 +58,11 @@ type Config struct {
 
 // Authority contains configuration for an xDS control plane authority.
 //
-// See: https://github.com/grpc/grpc/blob/master/doc/grpc_xds_bootstrap_format.md
+// See: https://www.envoyproxy.io/docs/envoy/latest/xds/core/v3/resource_locator.proto#xds-core-v3-resourcelocator
 type Authority struct {
 	// XDSServers contains the list of server configurations for this authority.
-	// The order of the servers in this list reflects the order of preference
-	// of the data returned by those servers. xDS client use the first
-	// available server from the list.
 	//
-	// See gRFC A71 for more details on fallback behavior when the primary
-	// xDS server is unavailable.
-	//
-	// gRFC A71: https://github.com/grpc/proposal/blob/master/A71-xds-fallback.md
+	// See Config.Servers for more details.
 	XDSServers []clients.ServerConfig
 
 	// Extensions can be populated with arbitrary authority-specific data to be