blob: 4c5423ba0fb2cc8ddaa580c79fa8388355a7f673 [file] [log] [blame]
Scott Baker2c1c4822019-10-16 11:02:41 -07001/*
2 *
3 * Copyright 2017 gRPC authors.
4 *
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
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
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.
16 *
17 */
18
19// Package resolver defines APIs for name resolution in gRPC.
20// All APIs in this package are experimental.
21package resolver
22
23import (
khenaidoo26721882021-08-11 17:42:52 -040024 "context"
25 "net"
26
27 "google.golang.org/grpc/credentials"
Scott Baker2c1c4822019-10-16 11:02:41 -070028 "google.golang.org/grpc/serviceconfig"
29)
30
31var (
32 // m is a map from scheme to resolver builder.
33 m = make(map[string]Builder)
34 // defaultScheme is the default scheme to use.
35 defaultScheme = "passthrough"
36)
37
38// TODO(bar) install dns resolver in init(){}.
39
40// Register registers the resolver builder to the resolver map. b.Scheme will be
41// used as the scheme registered with this builder.
42//
43// NOTE: this function must only be called during initialization time (i.e. in
44// an init() function), and is not thread-safe. If multiple Resolvers are
45// registered with the same name, the one registered last will take effect.
46func Register(b Builder) {
47 m[b.Scheme()] = b
48}
49
50// Get returns the resolver builder registered with the given scheme.
51//
52// If no builder is register with the scheme, nil will be returned.
53func Get(scheme string) Builder {
54 if b, ok := m[scheme]; ok {
55 return b
56 }
57 return nil
58}
59
60// SetDefaultScheme sets the default scheme that will be used. The default
61// default scheme is "passthrough".
62//
63// NOTE: this function must only be called during initialization time (i.e. in
64// an init() function), and is not thread-safe. The scheme set last overrides
65// previously set values.
66func SetDefaultScheme(scheme string) {
67 defaultScheme = scheme
68}
69
70// GetDefaultScheme gets the default scheme that will be used.
71func GetDefaultScheme() string {
72 return defaultScheme
73}
74
75// AddressType indicates the address type returned by name resolution.
76type AddressType uint8
77
78const (
79 // Backend indicates the address is for a backend server.
80 Backend AddressType = iota
81 // GRPCLB indicates the address is for a grpclb load balancer.
82 GRPCLB
83)
84
85// Address represents a server the client connects to.
86// This is the EXPERIMENTAL API and may be changed or extended in the future.
87type Address struct {
88 // Addr is the server address on which a connection will be established.
89 Addr string
90 // Type is the type of this address.
91 Type AddressType
92 // ServerName is the name of this address.
khenaidoo26721882021-08-11 17:42:52 -040093 // If non-empty, the ServerName is used as the transport certification authority for
94 // the address, instead of the hostname from the Dial target string. In most cases,
95 // this should not be set.
Scott Baker2c1c4822019-10-16 11:02:41 -070096 //
khenaidoo26721882021-08-11 17:42:52 -040097 // If Type is GRPCLB, ServerName should be the name of the remote load
Scott Baker2c1c4822019-10-16 11:02:41 -070098 // balancer, not the name of the backend.
khenaidoo26721882021-08-11 17:42:52 -040099 //
100 // WARNING: ServerName must only be populated with trusted values. It
101 // is insecure to populate it with data from untrusted inputs since untrusted
102 // values could be used to bypass the authority checks performed by TLS.
Scott Baker2c1c4822019-10-16 11:02:41 -0700103 ServerName string
104 // Metadata is the information associated with Addr, which may be used
105 // to make load balancing decision.
106 Metadata interface{}
107}
108
109// BuildOption includes additional information for the builder to create
110// the resolver.
111type BuildOption struct {
khenaidoo26721882021-08-11 17:42:52 -0400112 // DisableServiceConfig indicates whether a resolver implementation should
113 // fetch service config data.
Scott Baker2c1c4822019-10-16 11:02:41 -0700114 DisableServiceConfig bool
khenaidoo26721882021-08-11 17:42:52 -0400115 // DialCreds is the transport credentials used by the ClientConn for
116 // communicating with the target gRPC service (set via
117 // WithTransportCredentials). In cases where a name resolution service
118 // requires the same credentials, the resolver may use this field. In most
119 // cases though, it is not appropriate, and this field may be ignored.
120 DialCreds credentials.TransportCredentials
121 // CredsBundle is the credentials bundle used by the ClientConn for
122 // communicating with the target gRPC service (set via
123 // WithCredentialsBundle). In cases where a name resolution service
124 // requires the same credentials, the resolver may use this field. In most
125 // cases though, it is not appropriate, and this field may be ignored.
126 CredsBundle credentials.Bundle
127 // Dialer is the custom dialer used by the ClientConn for dialling the
128 // target gRPC service (set via WithDialer). In cases where a name
129 // resolution service requires the same dialer, the resolver may use this
130 // field. In most cases though, it is not appropriate, and this field may
131 // be ignored.
132 Dialer func(context.Context, string) (net.Conn, error)
Scott Baker2c1c4822019-10-16 11:02:41 -0700133}
134
135// State contains the current Resolver state relevant to the ClientConn.
136type State struct {
khenaidoo26721882021-08-11 17:42:52 -0400137 // Addresses is the latest set of resolved addresses for the target.
138 Addresses []Address
Scott Baker2c1c4822019-10-16 11:02:41 -0700139
khenaidoo26721882021-08-11 17:42:52 -0400140 // ServiceConfig contains the result from parsing the latest service
141 // config. If it is nil, it indicates no service config is present or the
142 // resolver does not provide service configs.
143 ServiceConfig *serviceconfig.ParseResult
Scott Baker2c1c4822019-10-16 11:02:41 -0700144}
145
146// ClientConn contains the callbacks for resolver to notify any updates
147// to the gRPC ClientConn.
148//
149// This interface is to be implemented by gRPC. Users should not need a
150// brand new implementation of this interface. For the situations like
151// testing, the new implementation should embed this interface. This allows
152// gRPC to add new methods to this interface.
153type ClientConn interface {
154 // UpdateState updates the state of the ClientConn appropriately.
155 UpdateState(State)
khenaidoo26721882021-08-11 17:42:52 -0400156 // ReportError notifies the ClientConn that the Resolver encountered an
157 // error. The ClientConn will notify the load balancer and begin calling
158 // ResolveNow on the Resolver with exponential backoff.
159 ReportError(error)
Scott Baker2c1c4822019-10-16 11:02:41 -0700160 // NewAddress is called by resolver to notify ClientConn a new list
161 // of resolved addresses.
162 // The address list should be the complete list of resolved addresses.
163 //
164 // Deprecated: Use UpdateState instead.
165 NewAddress(addresses []Address)
166 // NewServiceConfig is called by resolver to notify ClientConn a new
167 // service config. The service config should be provided as a json string.
168 //
169 // Deprecated: Use UpdateState instead.
170 NewServiceConfig(serviceConfig string)
khenaidoo26721882021-08-11 17:42:52 -0400171 // ParseServiceConfig parses the provided service config and returns an
172 // object that provides the parsed config.
173 ParseServiceConfig(serviceConfigJSON string) *serviceconfig.ParseResult
Scott Baker2c1c4822019-10-16 11:02:41 -0700174}
175
176// Target represents a target for gRPC, as specified in:
177// https://github.com/grpc/grpc/blob/master/doc/naming.md.
178// It is parsed from the target string that gets passed into Dial or DialContext by the user. And
179// grpc passes it to the resolver and the balancer.
180//
181// If the target follows the naming spec, and the parsed scheme is registered with grpc, we will
182// parse the target string according to the spec. e.g. "dns://some_authority/foo.bar" will be parsed
183// into &Target{Scheme: "dns", Authority: "some_authority", Endpoint: "foo.bar"}
184//
185// If the target does not contain a scheme, we will apply the default scheme, and set the Target to
186// be the full target string. e.g. "foo.bar" will be parsed into
187// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "foo.bar"}.
188//
189// If the parsed scheme is not registered (i.e. no corresponding resolver available to resolve the
190// endpoint), we set the Scheme to be the default scheme, and set the Endpoint to be the full target
191// string. e.g. target string "unknown_scheme://authority/endpoint" will be parsed into
192// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "unknown_scheme://authority/endpoint"}.
193type Target struct {
194 Scheme string
195 Authority string
196 Endpoint string
197}
198
199// Builder creates a resolver that will be used to watch name resolution updates.
200type Builder interface {
201 // Build creates a new resolver for the given target.
202 //
203 // gRPC dial calls Build synchronously, and fails if the returned error is
204 // not nil.
205 Build(target Target, cc ClientConn, opts BuildOption) (Resolver, error)
206 // Scheme returns the scheme supported by this resolver.
207 // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
208 Scheme() string
209}
210
211// ResolveNowOption includes additional information for ResolveNow.
212type ResolveNowOption struct{}
213
214// Resolver watches for the updates on the specified target.
215// Updates include address updates and service config updates.
216type Resolver interface {
217 // ResolveNow will be called by gRPC to try to resolve the target name
218 // again. It's just a hint, resolver can ignore this if it's not necessary.
219 //
220 // It could be called multiple times concurrently.
221 ResolveNow(ResolveNowOption)
222 // Close closes the resolver.
223 Close()
224}
225
226// UnregisterForTesting removes the resolver builder with the given scheme from the
227// resolver map.
228// This function is for testing only.
229func UnregisterForTesting(scheme string) {
230 delete(m, scheme)
231}