blob: fe14b2fb9826641c0dcaa4e9bad6ba165217e71a [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -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 (
Arjun E K57a7fcb2020-01-30 06:44:45 +000024 "context"
25 "net"
26
27 "google.golang.org/grpc/attributes"
28 "google.golang.org/grpc/credentials"
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070029 "google.golang.org/grpc/serviceconfig"
30)
31
32var (
33 // m is a map from scheme to resolver builder.
34 m = make(map[string]Builder)
35 // defaultScheme is the default scheme to use.
36 defaultScheme = "passthrough"
37)
38
39// TODO(bar) install dns resolver in init(){}.
40
41// Register registers the resolver builder to the resolver map. b.Scheme will be
42// used as the scheme registered with this builder.
43//
44// NOTE: this function must only be called during initialization time (i.e. in
45// an init() function), and is not thread-safe. If multiple Resolvers are
46// registered with the same name, the one registered last will take effect.
47func Register(b Builder) {
48 m[b.Scheme()] = b
49}
50
51// Get returns the resolver builder registered with the given scheme.
52//
53// If no builder is register with the scheme, nil will be returned.
54func Get(scheme string) Builder {
55 if b, ok := m[scheme]; ok {
56 return b
57 }
58 return nil
59}
60
61// SetDefaultScheme sets the default scheme that will be used. The default
62// default scheme is "passthrough".
63//
64// NOTE: this function must only be called during initialization time (i.e. in
65// an init() function), and is not thread-safe. The scheme set last overrides
66// previously set values.
67func SetDefaultScheme(scheme string) {
68 defaultScheme = scheme
69}
70
71// GetDefaultScheme gets the default scheme that will be used.
72func GetDefaultScheme() string {
73 return defaultScheme
74}
75
76// AddressType indicates the address type returned by name resolution.
Arjun E K57a7fcb2020-01-30 06:44:45 +000077//
78// Deprecated: use Attributes in Address instead.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070079type AddressType uint8
80
81const (
82 // Backend indicates the address is for a backend server.
Arjun E K57a7fcb2020-01-30 06:44:45 +000083 //
84 // Deprecated: use Attributes in Address instead.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070085 Backend AddressType = iota
86 // GRPCLB indicates the address is for a grpclb load balancer.
Arjun E K57a7fcb2020-01-30 06:44:45 +000087 //
88 // Deprecated: use Attributes in Address instead.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070089 GRPCLB
90)
91
92// Address represents a server the client connects to.
93// This is the EXPERIMENTAL API and may be changed or extended in the future.
94type Address struct {
95 // Addr is the server address on which a connection will be established.
96 Addr string
Arjun E K57a7fcb2020-01-30 06:44:45 +000097
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070098 // ServerName is the name of this address.
Arjun E K57a7fcb2020-01-30 06:44:45 +000099 // If non-empty, the ServerName is used as the transport certification authority for
100 // the address, instead of the hostname from the Dial target string. In most cases,
101 // this should not be set.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700102 //
Arjun E K57a7fcb2020-01-30 06:44:45 +0000103 // If Type is GRPCLB, ServerName should be the name of the remote load
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700104 // balancer, not the name of the backend.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000105 //
106 // WARNING: ServerName must only be populated with trusted values. It
107 // is insecure to populate it with data from untrusted inputs since untrusted
108 // values could be used to bypass the authority checks performed by TLS.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700109 ServerName string
Arjun E K57a7fcb2020-01-30 06:44:45 +0000110
111 // Attributes contains arbitrary data about this address intended for
112 // consumption by the load balancing policy.
113 Attributes *attributes.Attributes
114
115 // Type is the type of this address.
116 //
117 // Deprecated: use Attributes instead.
118 Type AddressType
119
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700120 // Metadata is the information associated with Addr, which may be used
121 // to make load balancing decision.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000122 //
123 // Deprecated: use Attributes instead.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700124 Metadata interface{}
125}
126
Arjun E K57a7fcb2020-01-30 06:44:45 +0000127// BuildOptions includes additional information for the builder to create
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700128// the resolver.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000129type BuildOptions struct {
130 // DisableServiceConfig indicates whether a resolver implementation should
131 // fetch service config data.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700132 DisableServiceConfig bool
Arjun E K57a7fcb2020-01-30 06:44:45 +0000133 // DialCreds is the transport credentials used by the ClientConn for
134 // communicating with the target gRPC service (set via
135 // WithTransportCredentials). In cases where a name resolution service
136 // requires the same credentials, the resolver may use this field. In most
137 // cases though, it is not appropriate, and this field may be ignored.
138 DialCreds credentials.TransportCredentials
139 // CredsBundle is the credentials bundle used by the ClientConn for
140 // communicating with the target gRPC service (set via
141 // WithCredentialsBundle). In cases where a name resolution service
142 // requires the same credentials, the resolver may use this field. In most
143 // cases though, it is not appropriate, and this field may be ignored.
144 CredsBundle credentials.Bundle
145 // Dialer is the custom dialer used by the ClientConn for dialling the
146 // target gRPC service (set via WithDialer). In cases where a name
147 // resolution service requires the same dialer, the resolver may use this
148 // field. In most cases though, it is not appropriate, and this field may
149 // be ignored.
150 Dialer func(context.Context, string) (net.Conn, error)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700151}
152
153// State contains the current Resolver state relevant to the ClientConn.
154type State struct {
Arjun E K57a7fcb2020-01-30 06:44:45 +0000155 // Addresses is the latest set of resolved addresses for the target.
156 Addresses []Address
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700157
Arjun E K57a7fcb2020-01-30 06:44:45 +0000158 // ServiceConfig contains the result from parsing the latest service
159 // config. If it is nil, it indicates no service config is present or the
160 // resolver does not provide service configs.
161 ServiceConfig *serviceconfig.ParseResult
162
163 // Attributes contains arbitrary data about the resolver intended for
164 // consumption by the load balancing policy.
165 Attributes *attributes.Attributes
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700166}
167
168// ClientConn contains the callbacks for resolver to notify any updates
169// to the gRPC ClientConn.
170//
171// This interface is to be implemented by gRPC. Users should not need a
172// brand new implementation of this interface. For the situations like
173// testing, the new implementation should embed this interface. This allows
174// gRPC to add new methods to this interface.
175type ClientConn interface {
176 // UpdateState updates the state of the ClientConn appropriately.
177 UpdateState(State)
Arjun E K57a7fcb2020-01-30 06:44:45 +0000178 // ReportError notifies the ClientConn that the Resolver encountered an
179 // error. The ClientConn will notify the load balancer and begin calling
180 // ResolveNow on the Resolver with exponential backoff.
181 ReportError(error)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700182 // NewAddress is called by resolver to notify ClientConn a new list
183 // of resolved addresses.
184 // The address list should be the complete list of resolved addresses.
185 //
186 // Deprecated: Use UpdateState instead.
187 NewAddress(addresses []Address)
188 // NewServiceConfig is called by resolver to notify ClientConn a new
189 // service config. The service config should be provided as a json string.
190 //
191 // Deprecated: Use UpdateState instead.
192 NewServiceConfig(serviceConfig string)
Arjun E K57a7fcb2020-01-30 06:44:45 +0000193 // ParseServiceConfig parses the provided service config and returns an
194 // object that provides the parsed config.
195 ParseServiceConfig(serviceConfigJSON string) *serviceconfig.ParseResult
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700196}
197
198// Target represents a target for gRPC, as specified in:
199// https://github.com/grpc/grpc/blob/master/doc/naming.md.
200// It is parsed from the target string that gets passed into Dial or DialContext by the user. And
201// grpc passes it to the resolver and the balancer.
202//
203// If the target follows the naming spec, and the parsed scheme is registered with grpc, we will
204// parse the target string according to the spec. e.g. "dns://some_authority/foo.bar" will be parsed
205// into &Target{Scheme: "dns", Authority: "some_authority", Endpoint: "foo.bar"}
206//
207// If the target does not contain a scheme, we will apply the default scheme, and set the Target to
208// be the full target string. e.g. "foo.bar" will be parsed into
209// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "foo.bar"}.
210//
211// If the parsed scheme is not registered (i.e. no corresponding resolver available to resolve the
212// endpoint), we set the Scheme to be the default scheme, and set the Endpoint to be the full target
213// string. e.g. target string "unknown_scheme://authority/endpoint" will be parsed into
214// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "unknown_scheme://authority/endpoint"}.
215type Target struct {
216 Scheme string
217 Authority string
218 Endpoint string
219}
220
221// Builder creates a resolver that will be used to watch name resolution updates.
222type Builder interface {
223 // Build creates a new resolver for the given target.
224 //
225 // gRPC dial calls Build synchronously, and fails if the returned error is
226 // not nil.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000227 Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700228 // Scheme returns the scheme supported by this resolver.
229 // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
230 Scheme() string
231}
232
Arjun E K57a7fcb2020-01-30 06:44:45 +0000233// ResolveNowOptions includes additional information for ResolveNow.
234type ResolveNowOptions struct{}
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700235
236// Resolver watches for the updates on the specified target.
237// Updates include address updates and service config updates.
238type Resolver interface {
239 // ResolveNow will be called by gRPC to try to resolve the target name
240 // again. It's just a hint, resolver can ignore this if it's not necessary.
241 //
242 // It could be called multiple times concurrently.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000243 ResolveNow(ResolveNowOptions)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700244 // Close closes the resolver.
245 Close()
246}
247
248// UnregisterForTesting removes the resolver builder with the given scheme from the
249// resolver map.
250// This function is for testing only.
251func UnregisterForTesting(scheme string) {
252 delete(m, scheme)
253}