package internal

import "google.golang.org/grpc/internal"

Package internal contains gRPC-internal code, to avoid polluting the godoc of the top-level grpc package. It must not import any grpc symbols to avoid circular dependencies.

Index

Constants

const (
	// CredsBundleModeFallback switches GoogleDefaultCreds to fallback mode.
	CredsBundleModeFallback = "fallback"
	// CredsBundleModeBalancer switches GoogleDefaultCreds to grpclb balancer
	// mode.
	CredsBundleModeBalancer = "balancer"
	// CredsBundleModeBackendFromBalancer switches GoogleDefaultCreds to mode
	// that supports backend returned by grpclb balancer.
	CredsBundleModeBackendFromBalancer = "backend-from-balancer"
)
const RLSLoadBalancingPolicyName = "rls_experimental"

RLSLoadBalancingPolicyName is the name of the RLS LB policy.

It currently has an experimental suffix which would be removed once end-to-end testing of the policy is completed.

Variables

var (
	// WithBufferPool is implemented by the grpc package and returns a dial
	// option to configure a shared buffer pool for a grpc.ClientConn.
	WithBufferPool any // func (grpc.SharedBufferPool) grpc.DialOption

	// BufferPool is implemented by the grpc package and returns a server
	// option to configure a shared buffer pool for a grpc.Server.
	BufferPool any // func (grpc.SharedBufferPool) grpc.ServerOption
)
var (
	// HealthCheckFunc is used to provide client-side LB channel health checking
	HealthCheckFunc HealthChecker
	// RegisterClientHealthCheckListener is used to provide a listener for
	// updates from the client-side health checking service. It returns a
	// function that can be called to stop the health producer.
	RegisterClientHealthCheckListener any // func(ctx context.Context, sc balancer.SubConn, serviceName string, listener func(balancer.SubConnState)) func()
	// BalancerUnregister is exported by package balancer to unregister a balancer.
	BalancerUnregister func(name string)
	// KeepaliveMinPingTime is the minimum ping interval.  This must be 10s by
	// default, but tests may wish to set it lower for convenience.
	KeepaliveMinPingTime = 10 * time.Second
	// KeepaliveMinServerPingTime is the minimum ping interval for servers.
	// This must be 1s by default, but tests may wish to set it lower for
	// convenience.
	KeepaliveMinServerPingTime = time.Second
	// ParseServiceConfig parses a JSON representation of the service config.
	ParseServiceConfig any // func(string) *serviceconfig.ParseResult
	// EqualServiceConfigForTesting is for testing service config generation and
	// parsing. Both a and b should be returned by ParseServiceConfig.
	// This function compares the config without rawJSON stripped, in case the
	// there's difference in white space.
	EqualServiceConfigForTesting func(a, b serviceconfig.Config) bool
	// GetCertificateProviderBuilder returns the registered builder for the
	// given name. This is set by package certprovider for use from xDS
	// bootstrap code while parsing certificate provider configs in the
	// bootstrap file.
	GetCertificateProviderBuilder any // func(string) certprovider.Builder
	// GetXDSHandshakeInfoForTesting returns a pointer to the xds.HandshakeInfo
	// stored in the passed in attributes. This is set by
	// credentials/xds/xds.go.
	GetXDSHandshakeInfoForTesting any // func (*attributes.Attributes) *unsafe.Pointer
	// GetServerCredentials returns the transport credentials configured on a
	// gRPC server. An xDS-enabled server needs to know what type of credentials
	// is configured on the underlying gRPC server. This is set by server.go.
	GetServerCredentials any // func (*grpc.Server) credentials.TransportCredentials
	// CanonicalString returns the canonical string of the code defined here:
	// https://github.com/grpc/grpc/blob/master/doc/statuscodes.md.
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	CanonicalString any // func (codes.Code) string
	// IsRegisteredMethod returns whether the passed in method is registered as
	// a method on the server.
	IsRegisteredMethod any // func(*grpc.Server, string) bool
	// ServerFromContext returns the server from the context.
	ServerFromContext any // func(context.Context) *grpc.Server
	// AddGlobalServerOptions adds an array of ServerOption that will be
	// effective globally for newly created servers. The priority will be: 1.
	// user-provided; 2. this method; 3. default values.
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	AddGlobalServerOptions any // func(opt ...ServerOption)
	// ClearGlobalServerOptions clears the array of extra ServerOption. This
	// method is useful in testing and benchmarking.
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	ClearGlobalServerOptions func()
	// AddGlobalDialOptions adds an array of DialOption that will be effective
	// globally for newly created client channels. The priority will be: 1.
	// user-provided; 2. this method; 3. default values.
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	AddGlobalDialOptions any // func(opt ...DialOption)
	// DisableGlobalDialOptions returns a DialOption that prevents the
	// ClientConn from applying the global DialOptions (set via
	// AddGlobalDialOptions).
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	DisableGlobalDialOptions any // func() grpc.DialOption
	// ClearGlobalDialOptions clears the array of extra DialOption. This
	// method is useful in testing and benchmarking.
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	ClearGlobalDialOptions func()

	// AddGlobalPerTargetDialOptions adds a PerTargetDialOption that will be
	// configured for newly created ClientConns.
	AddGlobalPerTargetDialOptions any // func (opt any)
	// ClearGlobalPerTargetDialOptions clears the slice of global late apply
	// dial options.
	ClearGlobalPerTargetDialOptions func()

	// JoinDialOptions combines the dial options passed as arguments into a
	// single dial option.
	JoinDialOptions any // func(...grpc.DialOption) grpc.DialOption
	// JoinServerOptions combines the server options passed as arguments into a
	// single server option.
	JoinServerOptions any // func(...grpc.ServerOption) grpc.ServerOption

	// WithBinaryLogger returns a DialOption that specifies the binary logger
	// for a ClientConn.
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	WithBinaryLogger any // func(binarylog.Logger) grpc.DialOption
	// BinaryLogger returns a ServerOption that can set the binary logger for a
	// server.
	//
	// This is used in the 1.0 release of gcp/observability, and thus must not be
	// deleted or changed.
	BinaryLogger any // func(binarylog.Logger) grpc.ServerOption

	// SubscribeToConnectivityStateChanges adds a grpcsync.Subscriber to a
	// provided grpc.ClientConn.
	SubscribeToConnectivityStateChanges any // func(*grpc.ClientConn, grpcsync.Subscriber)

	// NewXDSResolverWithConfigForTesting creates a new xds resolver builder using
	// the provided xds bootstrap config instead of the global configuration from
	// the supported environment variables.  The resolver.Builder is meant to be
	// used in conjunction with the grpc.WithResolvers DialOption.
	//
	// Testing Only
	//
	// This function should ONLY be used for testing and may not work with some
	// other features, including the CSDS service.
	NewXDSResolverWithConfigForTesting any // func([]byte) (resolver.Builder, error)

	// NewXDSResolverWithClientForTesting creates a new xDS resolver builder
	// using the provided xDS client instead of creating a new one using the
	// bootstrap configuration specified by the supported environment variables.
	// The resolver.Builder is meant to be used in conjunction with the
	// grpc.WithResolvers DialOption. The resolver.Builder does not take
	// ownership of the provided xDS client and it is the responsibility of the
	// caller to close the client when no longer required.
	//
	// Testing Only
	//
	// This function should ONLY be used for testing and may not work with some
	// other features, including the CSDS service.
	NewXDSResolverWithClientForTesting any // func(xdsclient.XDSClient) (resolver.Builder, error)

	// RegisterRLSClusterSpecifierPluginForTesting registers the RLS Cluster
	// Specifier Plugin for testing purposes, regardless of the XDSRLS environment
	// variable.
	//
	// TODO: Remove this function once the RLS env var is removed.
	RegisterRLSClusterSpecifierPluginForTesting func()

	// UnregisterRLSClusterSpecifierPluginForTesting unregisters the RLS Cluster
	// Specifier Plugin for testing purposes. This is needed because there is no way
	// to unregister the RLS Cluster Specifier Plugin after registering it solely
	// for testing purposes using RegisterRLSClusterSpecifierPluginForTesting().
	//
	// TODO: Remove this function once the RLS env var is removed.
	UnregisterRLSClusterSpecifierPluginForTesting func()

	// RegisterRBACHTTPFilterForTesting registers the RBAC HTTP Filter for testing
	// purposes, regardless of the RBAC environment variable.
	//
	// TODO: Remove this function once the RBAC env var is removed.
	RegisterRBACHTTPFilterForTesting func()

	// UnregisterRBACHTTPFilterForTesting unregisters the RBAC HTTP Filter for
	// testing purposes. This is needed because there is no way to unregister the
	// HTTP Filter after registering it solely for testing purposes using
	// RegisterRBACHTTPFilterForTesting().
	//
	// TODO: Remove this function once the RBAC env var is removed.
	UnregisterRBACHTTPFilterForTesting func()

	// ORCAAllowAnyMinReportingInterval is for examples/orca use ONLY.
	ORCAAllowAnyMinReportingInterval any // func(so *orca.ServiceOptions)

	// GRPCResolverSchemeExtraMetadata determines when gRPC will add extra
	// metadata to RPCs.
	GRPCResolverSchemeExtraMetadata = "xds"

	// EnterIdleModeForTesting gets the ClientConn to enter IDLE mode.
	EnterIdleModeForTesting any // func(*grpc.ClientConn)

	// ExitIdleModeForTesting gets the ClientConn to exit IDLE mode.
	ExitIdleModeForTesting any // func(*grpc.ClientConn) error

	// ChannelzTurnOffForTesting disables the Channelz service for testing
	// purposes.
	ChannelzTurnOffForTesting func()

	// TriggerXDSResourceNotFoundForTesting causes the provided xDS Client to
	// invoke resource-not-found error for the given resource type and name.
	TriggerXDSResourceNotFoundForTesting any // func(xdsclient.XDSClient, xdsresource.Type, string) error

	// FromOutgoingContextRaw returns the un-merged, intermediary contents of
	// metadata.rawMD.
	FromOutgoingContextRaw any // func(context.Context) (metadata.MD, [][]string, bool)

	// UserSetDefaultScheme is set to true if the user has overridden the
	// default resolver scheme.
	UserSetDefaultScheme = false

	// ConnectedAddress returns the connected address for a SubConnState. The
	// address is only valid if the state is READY.
	ConnectedAddress any // func (scs SubConnState) resolver.Address

	// SetConnectedAddress sets the connected address for a SubConnState.
	SetConnectedAddress any // func(scs *SubConnState, addr resolver.Address)

	// SnapshotMetricRegistryForTesting snapshots the global data of the metric
	// registry. Returns a cleanup function that sets the metric registry to its
	// original state. Only called in testing functions.
	SnapshotMetricRegistryForTesting func() func()

	// SetDefaultBufferPoolForTesting updates the default buffer pool, for
	// testing purposes.
	SetDefaultBufferPoolForTesting any // func(mem.BufferPool)

	// SetBufferPoolingThresholdForTesting updates the buffer pooling threshold, for
	// testing purposes.
	SetBufferPoolingThresholdForTesting any // func(int)
)

Functions

func NetDialerWithTCPKeepalive

func NetDialerWithTCPKeepalive() *net.Dialer

NetDialerWithTCPKeepalive returns a net.Dialer that enables TCP keepalives on the underlying connection with OS default values for keepalive parameters.

TODO: Once https://github.com/golang/go/issues/62254 lands, and the appropriate Go version becomes less than our least supported Go version, we should look into using the new API to make things more straightforward.

Types

type EnforceSubConnEmbedding

type EnforceSubConnEmbedding interface {
	// contains filtered or unexported methods
}

EnforceSubConnEmbedding is used to enforce proper SubConn implementation embedding.

type HealthChecker

type HealthChecker func(ctx context.Context, newStream func(string) (any, error), setConnectivityState func(connectivity.State, error), serviceName string) error

HealthChecker defines the signature of the client-side LB channel health checking function.

The implementation is expected to create a health checking RPC stream by calling newStream(), watch for the health status of serviceName, and report its health back by calling setConnectivityState().

The health checking protocol is defined at: https://github.com/grpc/grpc/blob/master/doc/health-checking.md

Source Files

experimental.go internal.go tcp_keepalive_unix.go

Directories

PathSynopsis
internal/adminPackage admin contains internal implementation for admin service.
internal/backoffPackage backoff implement the backoff strategy for gRPC.
internal/balancer
internal/balancer/gracefulswitchPackage gracefulswitch implements a graceful switch load balancer.
internal/balancergroupPackage balancergroup implements a utility struct to bind multiple balancers into one balancer.
internal/balancerloadPackage balancerload defines APIs to parse server loads in trailers.
internal/balancer/nopPackage nop implements a balancer with all of its balancer operations as no-ops, other than returning a Transient Failure Picker on a Client Conn update.
internal/balancer/stubPackage stub implements a balancer for testing purposes.
internal/binarylogPackage binarylog implementation binary logging as defined in https://github.com/grpc/proposal/blob/master/A16-binary-logging.md.
internal/bufferPackage buffer provides an implementation of an unbounded buffer.
internal/cachePackage cache implements caches to be used in gRPC.
internal/channelzPackage channelz defines internal APIs for enabling channelz service, entry registration/deletion, and accessing channelz data.
internal/credentialsPackage credentials defines APIs for parsing SPIFFE ID.
internal/credentials/xdsPackage xds contains non-user facing functionality of the xds credentials.
internal/envconfigPackage envconfig contains grpc settings configured by environment variables.
internal/googlecloudPackage googlecloud contains internal helpful functions for google cloud.
internal/grpclogPackage grpclog provides logging functionality for internal gRPC packages, outside of the functionality provided by the external `grpclog` package.
internal/grpcsyncPackage grpcsync implements additional synchronization primitives built upon the sync package.
internal/grpctestPackage grpctest implements testing helpers.
internal/grpcutilPackage grpcutil provides utility functions used across the gRPC codebase.
internal/hierarchyPackage hierarchy contains functions to set and get hierarchy string from addresses.
internal/idlePackage idle contains a component for managing idleness (entering and exiting) based on RPC activity.
internal/leakcheckPackage leakcheck contains functions to check leaked goroutines and buffers.
internal/metadataPackage metadata contains functions to set and get metadata from addresses.
internal/prettyPackage pretty defines helper functions to pretty-print structs for logging.
internal/profilingPackage profiling contains two logical components: buffer.go and profiling.go.
internal/profiling/bufferPackage buffer provides a high-performant lock free implementation of a circular buffer used by the profiling code.
internal/proto
internal/proto/grpc_lookup_v1
internal/proxyattributesPackage proxyattributes contains functions for getting and setting proxy attributes like the CONNECT address and user info.
internal/resolverPackage resolver provides internal resolver-related functionality.
internal/resolver/delegatingresolverPackage delegatingresolver implements a resolver capable of resolving both target URIs and proxy addresses.
internal/resolver/dnsPackage dns implements a dns resolver to be installed as the default resolver in grpc.
internal/resolver/dns/internalPackage internal contains functionality internal to the dns resolver package.
internal/resolver/passthroughPackage passthrough implements a pass-through resolver.
internal/resolver/unixPackage unix implements a resolver for unix targets.
internal/serviceconfigPackage serviceconfig contains utility functions to parse service config.
internal/statsPackage stats provides internal stats related functionality.
internal/statusPackage status implements errors returned by gRPC.
internal/stubserverPackage stubserver is a stubbable implementation of google.golang.org/grpc/interop/grpc_testing for testing purposes.
internal/syscallPackage syscall provides functionalities that grpc uses to get low-level operating system stats/info.
internal/testutilsPackage testutils contains testing helpers.
internal/testutils/fakegrpclbPackage fakegrpclb provides a fake implementation of the grpclb server.
internal/testutils/pickfirstPackage pickfirst contains helper functions to check for pickfirst load balancing of RPCs in tests.
internal/testutils/rlsPackage rls contains utilities for RouteLookupService e2e tests.
internal/testutils/roundrobinPackage roundrobin contains helper functions to check for roundrobin and weighted-roundrobin load balancing of RPCs in tests.
internal/testutils/statsPackage stats implements a TestMetricsRecorder utility.
internal/testutils/xds
internal/testutils/xds/e2ePackage e2e provides utilities for end2end testing of xDS functionality.
internal/testutils/xds/e2e/setupPackage setup implements setup helpers for xDS e2e tests.
internal/testutils/xds/fakeserverPackage fakeserver provides a fake implementation of the management server.
internal/transportPackage transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).
internal/transport/grpchttp2Package grpchttp2 defines HTTP/2 types and a framer API and implementation.
internal/transport/networktypePackage networktype declares the network type to be used in the default dialer.
internal/wrrPackage wrr contains the interface and common implementations of wrr algorithms.
internal/xdsPackage xds contains methods to Get/Set handshake cluster names.
internal/xds/bootstrapPackage bootstrap provides the functionality to initialize certain aspects of an xDS client by reading a bootstrap file.
internal/xds/bootstrap/tlscredsPackage tlscreds implements mTLS Credentials in xDS Bootstrap File.
internal/xds/matcherPackage matcher contains types that need to be shared between code under google.golang.org/grpc/xds/...
internal/xds/rbacPackage rbac provides service-level and method-level access control for a service.
Version
v1.70.0 (latest)
Published
Jan 23, 2025
Platform
linux/amd64
Imports
7 packages
Last checked
17 hours ago

Tools for package owners.