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 // WithHealthCheckFunc is set by dialoptions.go 33 WithHealthCheckFunc any // func (HealthChecker) DialOption 34 // HealthCheckFunc is used to provide client-side LB channel health checking 35 HealthCheckFunc HealthChecker 36 // BalancerUnregister is exported by package balancer to unregister a balancer. 37 BalancerUnregister func(name string) 38 // KeepaliveMinPingTime is the minimum ping interval. This must be 10s by 39 // default, but tests may wish to set it lower for convenience. 40 KeepaliveMinPingTime = 10 * time.Second 41 // KeepaliveMinServerPingTime is the minimum ping interval for servers. 42 // This must be 1s by default, but tests may wish to set it lower for 43 // convenience. 44 KeepaliveMinServerPingTime = time.Second 45 // ParseServiceConfig parses a JSON representation of the service config. 46 ParseServiceConfig any // func(string) *serviceconfig.ParseResult 47 // EqualServiceConfigForTesting is for testing service config generation and 48 // parsing. Both a and b should be returned by ParseServiceConfig. 49 // This function compares the config without rawJSON stripped, in case the 50 // there's difference in white space. 51 EqualServiceConfigForTesting func(a, b serviceconfig.Config) bool 52 // GetCertificateProviderBuilder returns the registered builder for the 53 // given name. This is set by package certprovider for use from xDS 54 // bootstrap code while parsing certificate provider configs in the 55 // bootstrap file. 56 GetCertificateProviderBuilder any // func(string) certprovider.Builder 57 // GetXDSHandshakeInfoForTesting returns a pointer to the xds.HandshakeInfo 58 // stored in the passed in attributes. This is set by 59 // credentials/xds/xds.go. 60 GetXDSHandshakeInfoForTesting any // func (*attributes.Attributes) *unsafe.Pointer 61 // GetServerCredentials returns the transport credentials configured on a 62 // gRPC server. An xDS-enabled server needs to know what type of credentials 63 // is configured on the underlying gRPC server. This is set by server.go. 64 GetServerCredentials any // func (*grpc.Server) credentials.TransportCredentials 65 // CanonicalString returns the canonical string of the code defined here: 66 // https://github.com/grpc/grpc/blob/master/doc/statuscodes.md. 67 // 68 // This is used in the 1.0 release of gcp/observability, and thus must not be 69 // deleted or changed. 70 CanonicalString any // func (codes.Code) string 71 // IsRegisteredMethod returns whether the passed in method is registered as 72 // a method on the server. 73 IsRegisteredMethod any // func(*grpc.Server, string) bool 74 // ServerFromContext returns the server from the context. 75 ServerFromContext any // func(context.Context) *grpc.Server 76 // AddGlobalServerOptions adds an array of ServerOption that will be 77 // effective globally for newly created servers. The priority will be: 1. 78 // user-provided; 2. this method; 3. default values. 79 // 80 // This is used in the 1.0 release of gcp/observability, and thus must not be 81 // deleted or changed. 82 AddGlobalServerOptions any // func(opt ...ServerOption) 83 // ClearGlobalServerOptions clears the array of extra ServerOption. This 84 // method is useful in testing and benchmarking. 85 // 86 // This is used in the 1.0 release of gcp/observability, and thus must not be 87 // deleted or changed. 88 ClearGlobalServerOptions func() 89 // AddGlobalDialOptions adds an array of DialOption that will be effective 90 // globally for newly created client channels. The priority will be: 1. 91 // user-provided; 2. this method; 3. default values. 92 // 93 // This is used in the 1.0 release of gcp/observability, and thus must not be 94 // deleted or changed. 95 AddGlobalDialOptions any // func(opt ...DialOption) 96 // DisableGlobalDialOptions returns a DialOption that prevents the 97 // ClientConn from applying the global DialOptions (set via 98 // AddGlobalDialOptions). 99 // 100 // This is used in the 1.0 release of gcp/observability, and thus must not be 101 // deleted or changed. 102 DisableGlobalDialOptions any // func() grpc.DialOption 103 // ClearGlobalDialOptions clears the array of extra DialOption. This 104 // method is useful in testing and benchmarking. 105 // 106 // This is used in the 1.0 release of gcp/observability, and thus must not be 107 // deleted or changed. 108 ClearGlobalDialOptions func() 109 // JoinDialOptions combines the dial options passed as arguments into a 110 // single dial option. 111 JoinDialOptions any // func(...grpc.DialOption) grpc.DialOption 112 // JoinServerOptions combines the server options passed as arguments into a 113 // single server option. 114 JoinServerOptions any // func(...grpc.ServerOption) grpc.ServerOption 115 116 // WithBinaryLogger returns a DialOption that specifies the binary logger 117 // for a ClientConn. 118 // 119 // This is used in the 1.0 release of gcp/observability, and thus must not be 120 // deleted or changed. 121 WithBinaryLogger any // func(binarylog.Logger) grpc.DialOption 122 // BinaryLogger returns a ServerOption that can set the binary logger for a 123 // server. 124 // 125 // This is used in the 1.0 release of gcp/observability, and thus must not be 126 // deleted or changed. 127 BinaryLogger any // func(binarylog.Logger) grpc.ServerOption 128 129 // SubscribeToConnectivityStateChanges adds a grpcsync.Subscriber to a provided grpc.ClientConn 130 SubscribeToConnectivityStateChanges any // func(*grpc.ClientConn, grpcsync.Subscriber) 131 132 // NewXDSResolverWithConfigForTesting creates a new xds resolver builder using 133 // the provided xds bootstrap config instead of the global configuration from 134 // the supported environment variables. The resolver.Builder is meant to be 135 // used in conjunction with the grpc.WithResolvers DialOption. 136 // 137 // Testing Only 138 // 139 // This function should ONLY be used for testing and may not work with some 140 // other features, including the CSDS service. 141 NewXDSResolverWithConfigForTesting any // func([]byte) (resolver.Builder, error) 142 143 // RegisterRLSClusterSpecifierPluginForTesting registers the RLS Cluster 144 // Specifier Plugin for testing purposes, regardless of the XDSRLS environment 145 // variable. 146 // 147 // TODO: Remove this function once the RLS env var is removed. 148 RegisterRLSClusterSpecifierPluginForTesting func() 149 150 // UnregisterRLSClusterSpecifierPluginForTesting unregisters the RLS Cluster 151 // Specifier Plugin for testing purposes. This is needed because there is no way 152 // to unregister the RLS Cluster Specifier Plugin after registering it solely 153 // for testing purposes using RegisterRLSClusterSpecifierPluginForTesting(). 154 // 155 // TODO: Remove this function once the RLS env var is removed. 156 UnregisterRLSClusterSpecifierPluginForTesting func() 157 158 // RegisterRBACHTTPFilterForTesting registers the RBAC HTTP Filter for testing 159 // purposes, regardless of the RBAC environment variable. 160 // 161 // TODO: Remove this function once the RBAC env var is removed. 162 RegisterRBACHTTPFilterForTesting func() 163 164 // UnregisterRBACHTTPFilterForTesting unregisters the RBAC HTTP Filter for 165 // testing purposes. This is needed because there is no way to unregister the 166 // HTTP Filter after registering it solely for testing purposes using 167 // RegisterRBACHTTPFilterForTesting(). 168 // 169 // TODO: Remove this function once the RBAC env var is removed. 170 UnregisterRBACHTTPFilterForTesting func() 171 172 // ORCAAllowAnyMinReportingInterval is for examples/orca use ONLY. 173 ORCAAllowAnyMinReportingInterval any // func(so *orca.ServiceOptions) 174 175 // GRPCResolverSchemeExtraMetadata determines when gRPC will add extra 176 // metadata to RPCs. 177 GRPCResolverSchemeExtraMetadata string = "xds" 178 179 // EnterIdleModeForTesting gets the ClientConn to enter IDLE mode. 180 EnterIdleModeForTesting any // func(*grpc.ClientConn) 181 182 // ExitIdleModeForTesting gets the ClientConn to exit IDLE mode. 183 ExitIdleModeForTesting any // func(*grpc.ClientConn) error 184 185 ChannelzTurnOffForTesting func() 186 187 // TriggerXDSResourceNameNotFoundForTesting triggers the resource-not-found 188 // error for a given resource type and name. This is usually triggered when 189 // the associated watch timer fires. For testing purposes, having this 190 // function makes events more predictable than relying on timer events. 191 TriggerXDSResourceNameNotFoundForTesting any // func(func(xdsresource.Type, string), string, string) error 192 193 // TriggerXDSResourceNameNotFoundClient invokes the testing xDS Client 194 // singleton to invoke resource not found for a resource type name and 195 // resource name. 196 TriggerXDSResourceNameNotFoundClient any // func(string, string) error 197 198 // FromOutgoingContextRaw returns the un-merged, intermediary contents of metadata.rawMD. 199 FromOutgoingContextRaw any // func(context.Context) (metadata.MD, [][]string, bool) 200 201 // UserSetDefaultScheme is set to true if the user has overridden the default resolver scheme. 202 UserSetDefaultScheme bool = false 203 ) 204 205 // HealthChecker defines the signature of the client-side LB channel health checking function. 206 // 207 // The implementation is expected to create a health checking RPC stream by 208 // calling newStream(), watch for the health status of serviceName, and report 209 // it's health back by calling setConnectivityState(). 210 // 211 // The health checking protocol is defined at: 212 // https://github.com/grpc/grpc/blob/master/doc/health-checking.md 213 type HealthChecker func(ctx context.Context, newStream func(string) (any, error), setConnectivityState func(connectivity.State, error), serviceName string) error 214 215 const ( 216 // CredsBundleModeFallback switches GoogleDefaultCreds to fallback mode. 217 CredsBundleModeFallback = "fallback" 218 // CredsBundleModeBalancer switches GoogleDefaultCreds to grpclb balancer 219 // mode. 220 CredsBundleModeBalancer = "balancer" 221 // CredsBundleModeBackendFromBalancer switches GoogleDefaultCreds to mode 222 // that supports backend returned by grpclb balancer. 223 CredsBundleModeBackendFromBalancer = "backend-from-balancer" 224 ) 225 226 // RLSLoadBalancingPolicyName is the name of the RLS LB policy. 227 // 228 // It currently has an experimental suffix which would be removed once 229 // end-to-end testing of the policy is completed. 230 const RLSLoadBalancingPolicyName = "rls_experimental" 231