3 * Copyright 2018 gRPC authors.
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
27 "google.golang.org/grpc/balancer"
28 "google.golang.org/grpc/credentials"
29 "google.golang.org/grpc/grpclog"
30 "google.golang.org/grpc/internal"
31 "google.golang.org/grpc/internal/backoff"
32 "google.golang.org/grpc/internal/envconfig"
33 "google.golang.org/grpc/internal/transport"
34 "google.golang.org/grpc/keepalive"
35 "google.golang.org/grpc/resolver"
36 "google.golang.org/grpc/stats"
39 // dialOptions configure a Dial call. dialOptions are set by the DialOption
40 // values passed to Dial.
41 type dialOptions struct {
42 unaryInt UnaryClientInterceptor
43 streamInt StreamClientInterceptor
50 scChan <-chan ServiceConfig
52 copts transport.ConnectOptions
53 callOptions []CallOption
54 // This is used by v1 balancer dial option WithBalancer to support v1
55 // balancer, and also by WithBalancerName dial option.
56 balancerBuilder balancer.Builder
57 // This is to support grpclb.
58 resolverBuilder resolver.Builder
59 reqHandshake envconfig.RequireHandshakeSetting
60 channelzParentID int64
61 disableServiceConfig bool
63 disableHealthCheck bool
64 healthCheckFunc internal.HealthChecker
67 // DialOption configures how we set up the connection.
68 type DialOption interface {
72 // EmptyDialOption does not alter the dial configuration. It can be embedded in
73 // another structure to build custom dial options.
75 // This API is EXPERIMENTAL.
76 type EmptyDialOption struct{}
78 func (EmptyDialOption) apply(*dialOptions) {}
80 // funcDialOption wraps a function that modifies dialOptions into an
81 // implementation of the DialOption interface.
82 type funcDialOption struct {
86 func (fdo *funcDialOption) apply(do *dialOptions) {
90 func newFuncDialOption(f func(*dialOptions)) *funcDialOption {
91 return &funcDialOption{
96 // WithWaitForHandshake blocks until the initial settings frame is received from
97 // the server before assigning RPCs to the connection.
99 // Deprecated: this is the default behavior, and this option will be removed
100 // after the 1.18 release.
101 func WithWaitForHandshake() DialOption {
102 return newFuncDialOption(func(o *dialOptions) {
103 o.reqHandshake = envconfig.RequireHandshakeOn
107 // WithWriteBufferSize determines how much data can be batched before doing a
108 // write on the wire. The corresponding memory allocation for this buffer will
109 // be twice the size to keep syscalls low. The default value for this buffer is
112 // Zero will disable the write buffer such that each write will be on underlying
113 // connection. Note: A Send call may not directly translate to a write.
114 func WithWriteBufferSize(s int) DialOption {
115 return newFuncDialOption(func(o *dialOptions) {
116 o.copts.WriteBufferSize = s
120 // WithReadBufferSize lets you set the size of read buffer, this determines how
121 // much data can be read at most for each read syscall.
123 // The default value for this buffer is 32KB. Zero will disable read buffer for
124 // a connection so data framer can access the underlying conn directly.
125 func WithReadBufferSize(s int) DialOption {
126 return newFuncDialOption(func(o *dialOptions) {
127 o.copts.ReadBufferSize = s
131 // WithInitialWindowSize returns a DialOption which sets the value for initial
132 // window size on a stream. The lower bound for window size is 64K and any value
133 // smaller than that will be ignored.
134 func WithInitialWindowSize(s int32) DialOption {
135 return newFuncDialOption(func(o *dialOptions) {
136 o.copts.InitialWindowSize = s
140 // WithInitialConnWindowSize returns a DialOption which sets the value for
141 // initial window size on a connection. The lower bound for window size is 64K
142 // and any value smaller than that will be ignored.
143 func WithInitialConnWindowSize(s int32) DialOption {
144 return newFuncDialOption(func(o *dialOptions) {
145 o.copts.InitialConnWindowSize = s
149 // WithMaxMsgSize returns a DialOption which sets the maximum message size the
150 // client can receive.
152 // Deprecated: use WithDefaultCallOptions(MaxCallRecvMsgSize(s)) instead.
153 func WithMaxMsgSize(s int) DialOption {
154 return WithDefaultCallOptions(MaxCallRecvMsgSize(s))
157 // WithDefaultCallOptions returns a DialOption which sets the default
158 // CallOptions for calls over the connection.
159 func WithDefaultCallOptions(cos ...CallOption) DialOption {
160 return newFuncDialOption(func(o *dialOptions) {
161 o.callOptions = append(o.callOptions, cos...)
165 // WithCodec returns a DialOption which sets a codec for message marshaling and
168 // Deprecated: use WithDefaultCallOptions(ForceCodec(_)) instead.
169 func WithCodec(c Codec) DialOption {
170 return WithDefaultCallOptions(CallCustomCodec(c))
173 // WithCompressor returns a DialOption which sets a Compressor to use for
174 // message compression. It has lower priority than the compressor set by the
175 // UseCompressor CallOption.
177 // Deprecated: use UseCompressor instead.
178 func WithCompressor(cp Compressor) DialOption {
179 return newFuncDialOption(func(o *dialOptions) {
184 // WithDecompressor returns a DialOption which sets a Decompressor to use for
185 // incoming message decompression. If incoming response messages are encoded
186 // using the decompressor's Type(), it will be used. Otherwise, the message
187 // encoding will be used to look up the compressor registered via
188 // encoding.RegisterCompressor, which will then be used to decompress the
189 // message. If no compressor is registered for the encoding, an Unimplemented
190 // status error will be returned.
192 // Deprecated: use encoding.RegisterCompressor instead.
193 func WithDecompressor(dc Decompressor) DialOption {
194 return newFuncDialOption(func(o *dialOptions) {
199 // WithBalancer returns a DialOption which sets a load balancer with the v1 API.
200 // Name resolver will be ignored if this DialOption is specified.
202 // Deprecated: use the new balancer APIs in balancer package and
204 func WithBalancer(b Balancer) DialOption {
205 return newFuncDialOption(func(o *dialOptions) {
206 o.balancerBuilder = &balancerWrapperBuilder{
212 // WithBalancerName sets the balancer that the ClientConn will be initialized
213 // with. Balancer registered with balancerName will be used. This function
214 // panics if no balancer was registered by balancerName.
216 // The balancer cannot be overridden by balancer option specified by service
219 // This is an EXPERIMENTAL API.
220 func WithBalancerName(balancerName string) DialOption {
221 builder := balancer.Get(balancerName)
223 panic(fmt.Sprintf("grpc.WithBalancerName: no balancer is registered for name %v", balancerName))
225 return newFuncDialOption(func(o *dialOptions) {
226 o.balancerBuilder = builder
230 // withResolverBuilder is only for grpclb.
231 func withResolverBuilder(b resolver.Builder) DialOption {
232 return newFuncDialOption(func(o *dialOptions) {
233 o.resolverBuilder = b
237 // WithServiceConfig returns a DialOption which has a channel to read the
238 // service configuration.
240 // Deprecated: service config should be received through name resolver, as
242 // https://github.com/grpc/grpc/blob/master/doc/service_config.md
243 func WithServiceConfig(c <-chan ServiceConfig) DialOption {
244 return newFuncDialOption(func(o *dialOptions) {
249 // WithBackoffMaxDelay configures the dialer to use the provided maximum delay
250 // when backing off after failed connection attempts.
251 func WithBackoffMaxDelay(md time.Duration) DialOption {
252 return WithBackoffConfig(BackoffConfig{MaxDelay: md})
255 // WithBackoffConfig configures the dialer to use the provided backoff
256 // parameters after connection failures.
258 // Use WithBackoffMaxDelay until more parameters on BackoffConfig are opened up
260 func WithBackoffConfig(b BackoffConfig) DialOption {
261 return withBackoff(backoff.Exponential{
262 MaxDelay: b.MaxDelay,
266 // withBackoff sets the backoff strategy used for connectRetryNum after a failed
267 // connection attempt.
269 // This can be exported if arbitrary backoff strategies are allowed by gRPC.
270 func withBackoff(bs backoff.Strategy) DialOption {
271 return newFuncDialOption(func(o *dialOptions) {
276 // WithBlock returns a DialOption which makes caller of Dial blocks until the
277 // underlying connection is up. Without this, Dial returns immediately and
278 // connecting the server happens in background.
279 func WithBlock() DialOption {
280 return newFuncDialOption(func(o *dialOptions) {
285 // WithInsecure returns a DialOption which disables transport security for this
286 // ClientConn. Note that transport security is required unless WithInsecure is
288 func WithInsecure() DialOption {
289 return newFuncDialOption(func(o *dialOptions) {
294 // WithTransportCredentials returns a DialOption which configures a connection
295 // level security credentials (e.g., TLS/SSL). This should not be used together
296 // with WithCredentialsBundle.
297 func WithTransportCredentials(creds credentials.TransportCredentials) DialOption {
298 return newFuncDialOption(func(o *dialOptions) {
299 o.copts.TransportCredentials = creds
303 // WithPerRPCCredentials returns a DialOption which sets credentials and places
304 // auth state on each outbound RPC.
305 func WithPerRPCCredentials(creds credentials.PerRPCCredentials) DialOption {
306 return newFuncDialOption(func(o *dialOptions) {
307 o.copts.PerRPCCredentials = append(o.copts.PerRPCCredentials, creds)
311 // WithCredentialsBundle returns a DialOption to set a credentials bundle for
312 // the ClientConn.WithCreds. This should not be used together with
313 // WithTransportCredentials.
315 // This API is experimental.
316 func WithCredentialsBundle(b credentials.Bundle) DialOption {
317 return newFuncDialOption(func(o *dialOptions) {
318 o.copts.CredsBundle = b
322 // WithTimeout returns a DialOption that configures a timeout for dialing a
323 // ClientConn initially. This is valid if and only if WithBlock() is present.
325 // Deprecated: use DialContext and context.WithTimeout instead.
326 func WithTimeout(d time.Duration) DialOption {
327 return newFuncDialOption(func(o *dialOptions) {
332 // WithContextDialer returns a DialOption that sets a dialer to create
333 // connections. If FailOnNonTempDialError() is set to true, and an error is
334 // returned by f, gRPC checks the error's Temporary() method to decide if it
335 // should try to reconnect to the network address.
336 func WithContextDialer(f func(context.Context, string) (net.Conn, error)) DialOption {
337 return newFuncDialOption(func(o *dialOptions) {
343 internal.WithResolverBuilder = withResolverBuilder
344 internal.WithHealthCheckFunc = withHealthCheckFunc
347 // WithDialer returns a DialOption that specifies a function to use for dialing
348 // network addresses. If FailOnNonTempDialError() is set to true, and an error
349 // is returned by f, gRPC checks the error's Temporary() method to decide if it
350 // should try to reconnect to the network address.
352 // Deprecated: use WithContextDialer instead
353 func WithDialer(f func(string, time.Duration) (net.Conn, error)) DialOption {
354 return WithContextDialer(
355 func(ctx context.Context, addr string) (net.Conn, error) {
356 if deadline, ok := ctx.Deadline(); ok {
357 return f(addr, time.Until(deadline))
363 // WithStatsHandler returns a DialOption that specifies the stats handler for
364 // all the RPCs and underlying network connections in this ClientConn.
365 func WithStatsHandler(h stats.Handler) DialOption {
366 return newFuncDialOption(func(o *dialOptions) {
367 o.copts.StatsHandler = h
371 // FailOnNonTempDialError returns a DialOption that specifies if gRPC fails on
372 // non-temporary dial errors. If f is true, and dialer returns a non-temporary
373 // error, gRPC will fail the connection to the network address and won't try to
374 // reconnect. The default value of FailOnNonTempDialError is false.
376 // FailOnNonTempDialError only affects the initial dial, and does not do
377 // anything useful unless you are also using WithBlock().
379 // This is an EXPERIMENTAL API.
380 func FailOnNonTempDialError(f bool) DialOption {
381 return newFuncDialOption(func(o *dialOptions) {
382 o.copts.FailOnNonTempDialError = f
386 // WithUserAgent returns a DialOption that specifies a user agent string for all
388 func WithUserAgent(s string) DialOption {
389 return newFuncDialOption(func(o *dialOptions) {
390 o.copts.UserAgent = s
394 // WithKeepaliveParams returns a DialOption that specifies keepalive parameters
395 // for the client transport.
396 func WithKeepaliveParams(kp keepalive.ClientParameters) DialOption {
397 if kp.Time < internal.KeepaliveMinPingTime {
398 grpclog.Warningf("Adjusting keepalive ping interval to minimum period of %v", internal.KeepaliveMinPingTime)
399 kp.Time = internal.KeepaliveMinPingTime
401 return newFuncDialOption(func(o *dialOptions) {
402 o.copts.KeepaliveParams = kp
406 // WithUnaryInterceptor returns a DialOption that specifies the interceptor for
408 func WithUnaryInterceptor(f UnaryClientInterceptor) DialOption {
409 return newFuncDialOption(func(o *dialOptions) {
414 // WithStreamInterceptor returns a DialOption that specifies the interceptor for
416 func WithStreamInterceptor(f StreamClientInterceptor) DialOption {
417 return newFuncDialOption(func(o *dialOptions) {
422 // WithAuthority returns a DialOption that specifies the value to be used as the
423 // :authority pseudo-header. This value only works with WithInsecure and has no
424 // effect if TransportCredentials are present.
425 func WithAuthority(a string) DialOption {
426 return newFuncDialOption(func(o *dialOptions) {
431 // WithChannelzParentID returns a DialOption that specifies the channelz ID of
432 // current ClientConn's parent. This function is used in nested channel creation
433 // (e.g. grpclb dial).
434 func WithChannelzParentID(id int64) DialOption {
435 return newFuncDialOption(func(o *dialOptions) {
436 o.channelzParentID = id
440 // WithDisableServiceConfig returns a DialOption that causes grpc to ignore any
441 // service config provided by the resolver and provides a hint to the resolver
442 // to not fetch service configs.
443 func WithDisableServiceConfig() DialOption {
444 return newFuncDialOption(func(o *dialOptions) {
445 o.disableServiceConfig = true
449 // WithDisableRetry returns a DialOption that disables retries, even if the
450 // service config enables them. This does not impact transparent retries, which
451 // will happen automatically if no data is written to the wire or if the RPC is
452 // unprocessed by the remote server.
454 // Retry support is currently disabled by default, but will be enabled by
455 // default in the future. Until then, it may be enabled by setting the
456 // environment variable "GRPC_GO_RETRY" to "on".
458 // This API is EXPERIMENTAL.
459 func WithDisableRetry() DialOption {
460 return newFuncDialOption(func(o *dialOptions) {
461 o.disableRetry = true
465 // WithMaxHeaderListSize returns a DialOption that specifies the maximum
466 // (uncompressed) size of header list that the client is prepared to accept.
467 func WithMaxHeaderListSize(s uint32) DialOption {
468 return newFuncDialOption(func(o *dialOptions) {
469 o.copts.MaxHeaderListSize = &s
473 // WithDisableHealthCheck disables the LB channel health checking for all SubConns of this ClientConn.
475 // This API is EXPERIMENTAL.
476 func WithDisableHealthCheck() DialOption {
477 return newFuncDialOption(func(o *dialOptions) {
478 o.disableHealthCheck = true
482 // withHealthCheckFunc replaces the default health check function with the provided one. It makes
483 // tests easier to change the health check function.
485 // For testing purpose only.
486 func withHealthCheckFunc(f internal.HealthChecker) DialOption {
487 return newFuncDialOption(func(o *dialOptions) {
488 o.healthCheckFunc = f
492 func defaultDialOptions() dialOptions {
494 disableRetry: !envconfig.Retry,
495 reqHandshake: envconfig.RequireHandshake,
496 healthCheckFunc: internal.HealthCheckFunc,
497 copts: transport.ConnectOptions{
498 WriteBufferSize: defaultWriteBufSize,
499 ReadBufferSize: defaultReadBufSize,