1/*
  2 * Copyright 2016 gRPC authors.
  3 *
  4 * Licensed under the Apache License, Version 2.0 (the "License");
  5 * you may not use this file except in compliance with the License.
  6 * You may obtain a copy of the License at
  7 *
  8 *     http://www.apache.org/licenses/LICENSE-2.0
  9 *
 10 * Unless required by applicable law or agreed to in writing, software
 11 * distributed under the License is distributed on an "AS IS" BASIS,
 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 * See the License for the specific language governing permissions and
 14 * limitations under the License.
 15 *
 16 */
 17
 18// Package internal contains gRPC-internal code, to avoid polluting
 19// the godoc of the top-level grpc package.  It must not import any grpc
 20// symbols to avoid circular dependencies.
 21package internal
 22
 23import (
 24	"context"
 25	"time"
 26
 27	"google.golang.org/grpc/connectivity"
 28	"google.golang.org/grpc/serviceconfig"
 29)
 30
 31var (
 32	// HealthCheckFunc is used to provide client-side LB channel health checking
 33	HealthCheckFunc HealthChecker
 34	// RegisterClientHealthCheckListener is used to provide a listener for
 35	// updates from the client-side health checking service. It returns a
 36	// function that can be called to stop the health producer.
 37	RegisterClientHealthCheckListener any // func(ctx context.Context, sc balancer.SubConn, serviceName string, listener func(balancer.SubConnState)) func()
 38	// BalancerUnregister is exported by package balancer to unregister a balancer.
 39	BalancerUnregister func(name string)
 40	// KeepaliveMinPingTime is the minimum ping interval.  This must be 10s by
 41	// default, but tests may wish to set it lower for convenience.
 42	KeepaliveMinPingTime = 10 * time.Second
 43	// KeepaliveMinServerPingTime is the minimum ping interval for servers.
 44	// This must be 1s by default, but tests may wish to set it lower for
 45	// convenience.
 46	KeepaliveMinServerPingTime = time.Second
 47	// ParseServiceConfig parses a JSON representation of the service config.
 48	ParseServiceConfig any // func(string) *serviceconfig.ParseResult
 49	// EqualServiceConfigForTesting is for testing service config generation and
 50	// parsing. Both a and b should be returned by ParseServiceConfig.
 51	// This function compares the config without rawJSON stripped, in case the
 52	// there's difference in white space.
 53	EqualServiceConfigForTesting func(a, b serviceconfig.Config) bool
 54	// GetCertificateProviderBuilder returns the registered builder for the
 55	// given name. This is set by package certprovider for use from xDS
 56	// bootstrap code while parsing certificate provider configs in the
 57	// bootstrap file.
 58	GetCertificateProviderBuilder any // func(string) certprovider.Builder
 59	// GetXDSHandshakeInfoForTesting returns a pointer to the xds.HandshakeInfo
 60	// stored in the passed in attributes. This is set by
 61	// credentials/xds/xds.go.
 62	GetXDSHandshakeInfoForTesting any // func (*attributes.Attributes) *unsafe.Pointer
 63	// GetServerCredentials returns the transport credentials configured on a
 64	// gRPC server. An xDS-enabled server needs to know what type of credentials
 65	// is configured on the underlying gRPC server. This is set by server.go.
 66	GetServerCredentials any // func (*grpc.Server) credentials.TransportCredentials
 67	// MetricsRecorderForServer returns the MetricsRecorderList derived from a
 68	// server's stats handlers.
 69	MetricsRecorderForServer any // func (*grpc.Server) estats.MetricsRecorder
 70	// CanonicalString returns the canonical string of the code defined here:
 71	// https://github.com/grpc/grpc/blob/master/doc/statuscodes.md.
 72	//
 73	// This is used in the 1.0 release of gcp/observability, and thus must not be
 74	// deleted or changed.
 75	CanonicalString any // func (codes.Code) string
 76	// IsRegisteredMethod returns whether the passed in method is registered as
 77	// a method on the server.
 78	IsRegisteredMethod any // func(*grpc.Server, string) bool
 79	// ServerFromContext returns the server from the context.
 80	ServerFromContext any // func(context.Context) *grpc.Server
 81	// AddGlobalServerOptions adds an array of ServerOption that will be
 82	// effective globally for newly created servers. The priority will be: 1.
 83	// user-provided; 2. this method; 3. default values.
 84	//
 85	// This is used in the 1.0 release of gcp/observability, and thus must not be
 86	// deleted or changed.
 87	AddGlobalServerOptions any // func(opt ...ServerOption)
 88	// ClearGlobalServerOptions clears the array of extra ServerOption. This
 89	// method is useful in testing and benchmarking.
 90	//
 91	// This is used in the 1.0 release of gcp/observability, and thus must not be
 92	// deleted or changed.
 93	ClearGlobalServerOptions func()
 94	// AddGlobalDialOptions adds an array of DialOption that will be effective
 95	// globally for newly created client channels. The priority will be: 1.
 96	// user-provided; 2. this method; 3. default values.
 97	//
 98	// This is used in the 1.0 release of gcp/observability, and thus must not be
 99	// deleted or changed.
100	AddGlobalDialOptions any // func(opt ...DialOption)
101	// DisableGlobalDialOptions returns a DialOption that prevents the
102	// ClientConn from applying the global DialOptions (set via
103	// AddGlobalDialOptions).
104	//
105	// This is used in the 1.0 release of gcp/observability, and thus must not be
106	// deleted or changed.
107	DisableGlobalDialOptions any // func() grpc.DialOption
108	// ClearGlobalDialOptions clears the array of extra DialOption. This
109	// method is useful in testing and benchmarking.
110	//
111	// This is used in the 1.0 release of gcp/observability, and thus must not be
112	// deleted or changed.
113	ClearGlobalDialOptions func()
114
115	// AddGlobalPerTargetDialOptions adds a PerTargetDialOption that will be
116	// configured for newly created ClientConns.
117	AddGlobalPerTargetDialOptions any // func (opt any)
118	// ClearGlobalPerTargetDialOptions clears the slice of global late apply
119	// dial options.
120	ClearGlobalPerTargetDialOptions func()
121
122	// JoinDialOptions combines the dial options passed as arguments into a
123	// single dial option.
124	JoinDialOptions any // func(...grpc.DialOption) grpc.DialOption
125	// JoinServerOptions combines the server options passed as arguments into a
126	// single server option.
127	JoinServerOptions any // func(...grpc.ServerOption) grpc.ServerOption
128
129	// WithBinaryLogger returns a DialOption that specifies the binary logger
130	// for a ClientConn.
131	//
132	// This is used in the 1.0 release of gcp/observability, and thus must not be
133	// deleted or changed.
134	WithBinaryLogger any // func(binarylog.Logger) grpc.DialOption
135	// BinaryLogger returns a ServerOption that can set the binary logger for a
136	// server.
137	//
138	// This is used in the 1.0 release of gcp/observability, and thus must not be
139	// deleted or changed.
140	BinaryLogger any // func(binarylog.Logger) grpc.ServerOption
141
142	// SubscribeToConnectivityStateChanges adds a grpcsync.Subscriber to a
143	// provided grpc.ClientConn.
144	SubscribeToConnectivityStateChanges any // func(*grpc.ClientConn, grpcsync.Subscriber)
145
146	// NewXDSResolverWithConfigForTesting creates a new xds resolver builder using
147	// the provided xds bootstrap config instead of the global configuration from
148	// the supported environment variables.  The resolver.Builder is meant to be
149	// used in conjunction with the grpc.WithResolvers DialOption.
150	//
151	// Testing Only
152	//
153	// This function should ONLY be used for testing and may not work with some
154	// other features, including the CSDS service.
155	NewXDSResolverWithConfigForTesting any // func([]byte) (resolver.Builder, error)
156
157	// NewXDSResolverWithPoolForTesting creates a new xDS resolver builder
158	// using the provided xDS pool instead of creating a new one using the
159	// bootstrap configuration specified by the supported environment variables.
160	// The resolver.Builder is meant to be used in conjunction with the
161	// grpc.WithResolvers DialOption. The resolver.Builder does not take
162	// ownership of the provided xDS client and it is the responsibility of the
163	// caller to close the client when no longer required.
164	//
165	// Testing Only
166	//
167	// This function should ONLY be used for testing and may not work with some
168	// other features, including the CSDS service.
169	NewXDSResolverWithPoolForTesting any // func(*xdsclient.Pool) (resolver.Builder, error)
170
171	// NewXDSResolverWithClientForTesting creates a new xDS resolver builder
172	// using the provided xDS client instead of creating a new one using the
173	// bootstrap configuration specified by the supported environment variables.
174	// The resolver.Builder is meant to be used in conjunction with the
175	// grpc.WithResolvers DialOption. The resolver.Builder does not take
176	// ownership of the provided xDS client and it is the responsibility of the
177	// caller to close the client when no longer required.
178	//
179	// Testing Only
180	//
181	// This function should ONLY be used for testing and may not work with some
182	// other features, including the CSDS service.
183	NewXDSResolverWithClientForTesting any // func(xdsclient.XDSClient) (resolver.Builder, error)
184
185	// RegisterRLSClusterSpecifierPluginForTesting registers the RLS Cluster
186	// Specifier Plugin for testing purposes, regardless of the XDSRLS environment
187	// variable.
188	//
189	// TODO: Remove this function once the RLS env var is removed.
190	RegisterRLSClusterSpecifierPluginForTesting func()
191
192	// UnregisterRLSClusterSpecifierPluginForTesting unregisters the RLS Cluster
193	// Specifier Plugin for testing purposes. This is needed because there is no way
194	// to unregister the RLS Cluster Specifier Plugin after registering it solely
195	// for testing purposes using RegisterRLSClusterSpecifierPluginForTesting().
196	//
197	// TODO: Remove this function once the RLS env var is removed.
198	UnregisterRLSClusterSpecifierPluginForTesting func()
199
200	// RegisterRBACHTTPFilterForTesting registers the RBAC HTTP Filter for testing
201	// purposes, regardless of the RBAC environment variable.
202	//
203	// TODO: Remove this function once the RBAC env var is removed.
204	RegisterRBACHTTPFilterForTesting func()
205
206	// UnregisterRBACHTTPFilterForTesting unregisters the RBAC HTTP Filter for
207	// testing purposes. This is needed because there is no way to unregister the
208	// HTTP Filter after registering it solely for testing purposes using
209	// RegisterRBACHTTPFilterForTesting().
210	//
211	// TODO: Remove this function once the RBAC env var is removed.
212	UnregisterRBACHTTPFilterForTesting func()
213
214	// ORCAAllowAnyMinReportingInterval is for examples/orca use ONLY.
215	ORCAAllowAnyMinReportingInterval any // func(so *orca.ServiceOptions)
216
217	// GRPCResolverSchemeExtraMetadata determines when gRPC will add extra
218	// metadata to RPCs.
219	GRPCResolverSchemeExtraMetadata = "xds"
220
221	// EnterIdleModeForTesting gets the ClientConn to enter IDLE mode.
222	EnterIdleModeForTesting any // func(*grpc.ClientConn)
223
224	// ExitIdleModeForTesting gets the ClientConn to exit IDLE mode.
225	ExitIdleModeForTesting any // func(*grpc.ClientConn) error
226
227	// ChannelzTurnOffForTesting disables the Channelz service for testing
228	// purposes.
229	ChannelzTurnOffForTesting func()
230
231	// TriggerXDSResourceNotFoundForTesting causes the provided xDS Client to
232	// invoke resource-not-found error for the given resource type and name.
233	TriggerXDSResourceNotFoundForTesting any // func(xdsclient.XDSClient, xdsresource.Type, string) error
234
235	// FromOutgoingContextRaw returns the un-merged, intermediary contents of
236	// metadata.rawMD.
237	FromOutgoingContextRaw any // func(context.Context) (metadata.MD, [][]string, bool)
238
239	// UserSetDefaultScheme is set to true if the user has overridden the
240	// default resolver scheme.
241	UserSetDefaultScheme = false
242
243	// ConnectedAddress returns the connected address for a SubConnState. The
244	// address is only valid if the state is READY.
245	ConnectedAddress any // func (scs SubConnState) resolver.Address
246
247	// SetConnectedAddress sets the connected address for a SubConnState.
248	SetConnectedAddress any // func(scs *SubConnState, addr resolver.Address)
249
250	// SnapshotMetricRegistryForTesting snapshots the global data of the metric
251	// registry. Returns a cleanup function that sets the metric registry to its
252	// original state. Only called in testing functions.
253	SnapshotMetricRegistryForTesting func() func()
254
255	// SetDefaultBufferPoolForTesting updates the default buffer pool, for
256	// testing purposes.
257	SetDefaultBufferPoolForTesting any // func(mem.BufferPool)
258
259	// SetBufferPoolingThresholdForTesting updates the buffer pooling threshold, for
260	// testing purposes.
261	SetBufferPoolingThresholdForTesting any // func(int)
262)
263
264// HealthChecker defines the signature of the client-side LB channel health
265// checking function.
266//
267// The implementation is expected to create a health checking RPC stream by
268// calling newStream(), watch for the health status of serviceName, and report
269// its health back by calling setConnectivityState().
270//
271// The health checking protocol is defined at:
272// https://github.com/grpc/grpc/blob/master/doc/health-checking.md
273type HealthChecker func(ctx context.Context, newStream func(string) (any, error), setConnectivityState func(connectivity.State, error), serviceName string) error
274
275const (
276	// CredsBundleModeFallback switches GoogleDefaultCreds to fallback mode.
277	CredsBundleModeFallback = "fallback"
278	// CredsBundleModeBalancer switches GoogleDefaultCreds to grpclb balancer
279	// mode.
280	CredsBundleModeBalancer = "balancer"
281	// CredsBundleModeBackendFromBalancer switches GoogleDefaultCreds to mode
282	// that supports backend returned by grpclb balancer.
283	CredsBundleModeBackendFromBalancer = "backend-from-balancer"
284)
285
286// RLSLoadBalancingPolicyName is the name of the RLS LB policy.
287//
288// It currently has an experimental suffix which would be removed once
289// end-to-end testing of the policy is completed.
290const RLSLoadBalancingPolicyName = "rls_experimental"
291
292// EnforceSubConnEmbedding is used to enforce proper SubConn implementation
293// embedding.
294type EnforceSubConnEmbedding interface {
295	enforceSubConnEmbedding()
296}
297
298// EnforceClientConnEmbedding is used to enforce proper ClientConn implementation
299// embedding.
300type EnforceClientConnEmbedding interface {
301	enforceClientConnEmbedding()
302}