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.
21 package internal
22 23 import (
24 "context"
25 "time"
26 27 "google.golang.org/grpc/connectivity"
28 "google.golang.org/grpc/serviceconfig"
29 )
30 31 var (
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 // ORCAAllowAnyMinReportingInterval is for examples/orca use ONLY.
186 ORCAAllowAnyMinReportingInterval any // func(so *orca.ServiceOptions)
187 188 // GRPCResolverSchemeExtraMetadata determines when gRPC will add extra
189 // metadata to RPCs.
190 GRPCResolverSchemeExtraMetadata = "xds"
191 192 // EnterIdleModeForTesting gets the ClientConn to enter IDLE mode.
193 EnterIdleModeForTesting any // func(*grpc.ClientConn)
194 195 // ExitIdleModeForTesting gets the ClientConn to exit IDLE mode.
196 ExitIdleModeForTesting any // func(*grpc.ClientConn) error
197 198 // ChannelzTurnOffForTesting disables the Channelz service for testing
199 // purposes.
200 ChannelzTurnOffForTesting func()
201 202 // TriggerXDSResourceNotFoundForTesting causes the provided xDS Client to
203 // invoke resource-not-found error for the given resource type and name.
204 TriggerXDSResourceNotFoundForTesting any // func(xdsclient.XDSClient, xdsresource.Type, string) error
205 206 // FromOutgoingContextRaw returns the un-merged, intermediary contents of
207 // metadata.rawMD.
208 FromOutgoingContextRaw any // func(context.Context) (metadata.MD, [][]string, bool)
209 210 // UserSetDefaultScheme is set to true if the user has overridden the
211 // default resolver scheme.
212 UserSetDefaultScheme = false
213 214 // ConnectedAddress returns the connected address for a SubConnState. The
215 // address is only valid if the state is READY.
216 ConnectedAddress any // func (scs SubConnState) resolver.Address
217 218 // SetConnectedAddress sets the connected address for a SubConnState.
219 SetConnectedAddress any // func(scs *SubConnState, addr resolver.Address)
220 221 // SnapshotMetricRegistryForTesting snapshots the global data of the metric
222 // registry. Returns a cleanup function that sets the metric registry to its
223 // original state. Only called in testing functions.
224 SnapshotMetricRegistryForTesting func() func()
225 226 // SetDefaultBufferPoolForTesting updates the default buffer pool, for
227 // testing purposes.
228 SetDefaultBufferPoolForTesting any // func(mem.BufferPool)
229 230 // SetBufferPoolingThresholdForTesting updates the buffer pooling threshold, for
231 // testing purposes.
232 SetBufferPoolingThresholdForTesting any // func(int)
233 234 // TimeAfterFunc is used to create timers. During tests the function is
235 // replaced to track allocated timers and fail the test if a timer isn't
236 // cancelled.
237 TimeAfterFunc = func(d time.Duration, f func()) Timer {
238 return time.AfterFunc(d, f)
239 }
240 241 // NewStreamWaitingForResolver is a test hook that is triggered when a
242 // new stream blocks while waiting for name resolution. This can be
243 // used in tests to synchronize resolver updates and avoid race conditions.
244 // When set, the function will be called before the stream enters
245 // the blocking state.
246 NewStreamWaitingForResolver = func() {}
247 248 // AddressToTelemetryLabels is an xDS-provided function to extract telemetry
249 // labels from a resolver.Address. Callers must assert its type before calling.
250 AddressToTelemetryLabels any // func(addr resolver.Address) map[string]string
251 )
252 253 // HealthChecker defines the signature of the client-side LB channel health
254 // checking function.
255 //
256 // The implementation is expected to create a health checking RPC stream by
257 // calling newStream(), watch for the health status of serviceName, and report
258 // its health back by calling setConnectivityState().
259 //
260 // The health checking protocol is defined at:
261 // https://github.com/grpc/grpc/blob/master/doc/health-checking.md
262 type HealthChecker func(ctx context.Context, newStream func(string) (any, error), setConnectivityState func(connectivity.State, error), serviceName string) error
263 264 const (
265 // CredsBundleModeFallback switches GoogleDefaultCreds to fallback mode.
266 CredsBundleModeFallback = "fallback"
267 // CredsBundleModeBalancer switches GoogleDefaultCreds to grpclb balancer
268 // mode.
269 CredsBundleModeBalancer = "balancer"
270 // CredsBundleModeBackendFromBalancer switches GoogleDefaultCreds to mode
271 // that supports backend returned by grpclb balancer.
272 CredsBundleModeBackendFromBalancer = "backend-from-balancer"
273 )
274 275 // RLSLoadBalancingPolicyName is the name of the RLS LB policy.
276 //
277 // It currently has an experimental suffix which would be removed once
278 // end-to-end testing of the policy is completed.
279 const RLSLoadBalancingPolicyName = "rls_experimental"
280 281 // EnforceSubConnEmbedding is used to enforce proper SubConn implementation
282 // embedding.
283 type EnforceSubConnEmbedding interface {
284 enforceSubConnEmbedding()
285 }
286 287 // EnforceClientConnEmbedding is used to enforce proper ClientConn implementation
288 // embedding.
289 type EnforceClientConnEmbedding interface {
290 enforceClientConnEmbedding()
291 }
292 293 // Timer is an interface to allow injecting different time.Timer implementations
294 // during tests.
295 type Timer interface {
296 Stop() bool
297 }
298