blob: e73a00d59b0056bfaab12a15886ab23fd9ecedc9 [file] [log] [blame]
khenaidoo5fc5cea2021-08-11 17:39:16 -04001/*
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 (
24 "context"
25 "net"
khenaidoo5cb0d402021-12-08 14:09:16 -050026 "net/url"
khenaidoo5fc5cea2021-08-11 17:39:16 -040027
28 "google.golang.org/grpc/attributes"
29 "google.golang.org/grpc/credentials"
30 "google.golang.org/grpc/serviceconfig"
31)
32
33var (
34 // m is a map from scheme to resolver builder.
35 m = make(map[string]Builder)
36 // defaultScheme is the default scheme to use.
37 defaultScheme = "passthrough"
38)
39
40// TODO(bar) install dns resolver in init(){}.
41
42// Register registers the resolver builder to the resolver map. b.Scheme will be
43// used as the scheme registered with this builder.
44//
45// NOTE: this function must only be called during initialization time (i.e. in
46// an init() function), and is not thread-safe. If multiple Resolvers are
47// registered with the same name, the one registered last will take effect.
48func Register(b Builder) {
49 m[b.Scheme()] = b
50}
51
52// Get returns the resolver builder registered with the given scheme.
53//
54// If no builder is register with the scheme, nil will be returned.
55func Get(scheme string) Builder {
56 if b, ok := m[scheme]; ok {
57 return b
58 }
59 return nil
60}
61
62// SetDefaultScheme sets the default scheme that will be used. The default
63// default scheme is "passthrough".
64//
65// NOTE: this function must only be called during initialization time (i.e. in
66// an init() function), and is not thread-safe. The scheme set last overrides
67// previously set values.
68func SetDefaultScheme(scheme string) {
69 defaultScheme = scheme
70}
71
72// GetDefaultScheme gets the default scheme that will be used.
73func GetDefaultScheme() string {
74 return defaultScheme
75}
76
77// AddressType indicates the address type returned by name resolution.
78//
79// Deprecated: use Attributes in Address instead.
80type AddressType uint8
81
82const (
83 // Backend indicates the address is for a backend server.
84 //
85 // Deprecated: use Attributes in Address instead.
86 Backend AddressType = iota
87 // GRPCLB indicates the address is for a grpclb load balancer.
88 //
89 // Deprecated: to select the GRPCLB load balancing policy, use a service
90 // config with a corresponding loadBalancingConfig. To supply balancer
91 // addresses to the GRPCLB load balancing policy, set State.Attributes
92 // using balancer/grpclb/state.Set.
93 GRPCLB
94)
95
96// Address represents a server the client connects to.
97//
Joey Armstrongba3d9d12024-01-15 14:22:11 -050098// # Experimental
khenaidoo5fc5cea2021-08-11 17:39:16 -040099//
100// Notice: This type is EXPERIMENTAL and may be changed or removed in a
101// later release.
102type Address struct {
103 // Addr is the server address on which a connection will be established.
104 Addr string
105
106 // ServerName is the name of this address.
107 // If non-empty, the ServerName is used as the transport certification authority for
108 // the address, instead of the hostname from the Dial target string. In most cases,
109 // this should not be set.
110 //
111 // If Type is GRPCLB, ServerName should be the name of the remote load
112 // balancer, not the name of the backend.
113 //
114 // WARNING: ServerName must only be populated with trusted values. It
115 // is insecure to populate it with data from untrusted inputs since untrusted
116 // values could be used to bypass the authority checks performed by TLS.
117 ServerName string
118
119 // Attributes contains arbitrary data about this address intended for
khenaidoo5cb0d402021-12-08 14:09:16 -0500120 // consumption by the SubConn.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400121 Attributes *attributes.Attributes
122
khenaidoo5cb0d402021-12-08 14:09:16 -0500123 // BalancerAttributes contains arbitrary data about this address intended
124 // for consumption by the LB policy. These attribes do not affect SubConn
125 // creation, connection establishment, handshaking, etc.
126 BalancerAttributes *attributes.Attributes
127
khenaidoo5fc5cea2021-08-11 17:39:16 -0400128 // Type is the type of this address.
129 //
130 // Deprecated: use Attributes instead.
131 Type AddressType
132
133 // Metadata is the information associated with Addr, which may be used
134 // to make load balancing decision.
135 //
136 // Deprecated: use Attributes instead.
137 Metadata interface{}
138}
139
khenaidoo5cb0d402021-12-08 14:09:16 -0500140// Equal returns whether a and o are identical. Metadata is compared directly,
141// not with any recursive introspection.
142func (a *Address) Equal(o Address) bool {
143 return a.Addr == o.Addr && a.ServerName == o.ServerName &&
144 a.Attributes.Equal(o.Attributes) &&
145 a.BalancerAttributes.Equal(o.BalancerAttributes) &&
146 a.Type == o.Type && a.Metadata == o.Metadata
147}
148
khenaidoo5fc5cea2021-08-11 17:39:16 -0400149// BuildOptions includes additional information for the builder to create
150// the resolver.
151type BuildOptions struct {
152 // DisableServiceConfig indicates whether a resolver implementation should
153 // fetch service config data.
154 DisableServiceConfig bool
155 // DialCreds is the transport credentials used by the ClientConn for
156 // communicating with the target gRPC service (set via
157 // WithTransportCredentials). In cases where a name resolution service
158 // requires the same credentials, the resolver may use this field. In most
159 // cases though, it is not appropriate, and this field may be ignored.
160 DialCreds credentials.TransportCredentials
161 // CredsBundle is the credentials bundle used by the ClientConn for
162 // communicating with the target gRPC service (set via
163 // WithCredentialsBundle). In cases where a name resolution service
164 // requires the same credentials, the resolver may use this field. In most
165 // cases though, it is not appropriate, and this field may be ignored.
166 CredsBundle credentials.Bundle
167 // Dialer is the custom dialer used by the ClientConn for dialling the
168 // target gRPC service (set via WithDialer). In cases where a name
169 // resolution service requires the same dialer, the resolver may use this
170 // field. In most cases though, it is not appropriate, and this field may
171 // be ignored.
172 Dialer func(context.Context, string) (net.Conn, error)
173}
174
175// State contains the current Resolver state relevant to the ClientConn.
176type State struct {
177 // Addresses is the latest set of resolved addresses for the target.
178 Addresses []Address
179
180 // ServiceConfig contains the result from parsing the latest service
181 // config. If it is nil, it indicates no service config is present or the
182 // resolver does not provide service configs.
183 ServiceConfig *serviceconfig.ParseResult
184
185 // Attributes contains arbitrary data about the resolver intended for
186 // consumption by the load balancing policy.
187 Attributes *attributes.Attributes
188}
189
190// ClientConn contains the callbacks for resolver to notify any updates
191// to the gRPC ClientConn.
192//
193// This interface is to be implemented by gRPC. Users should not need a
194// brand new implementation of this interface. For the situations like
195// testing, the new implementation should embed this interface. This allows
196// gRPC to add new methods to this interface.
197type ClientConn interface {
198 // UpdateState updates the state of the ClientConn appropriately.
199 UpdateState(State) error
200 // ReportError notifies the ClientConn that the Resolver encountered an
201 // error. The ClientConn will notify the load balancer and begin calling
202 // ResolveNow on the Resolver with exponential backoff.
203 ReportError(error)
204 // NewAddress is called by resolver to notify ClientConn a new list
205 // of resolved addresses.
206 // The address list should be the complete list of resolved addresses.
207 //
208 // Deprecated: Use UpdateState instead.
209 NewAddress(addresses []Address)
210 // NewServiceConfig is called by resolver to notify ClientConn a new
211 // service config. The service config should be provided as a json string.
212 //
213 // Deprecated: Use UpdateState instead.
214 NewServiceConfig(serviceConfig string)
215 // ParseServiceConfig parses the provided service config and returns an
216 // object that provides the parsed config.
217 ParseServiceConfig(serviceConfigJSON string) *serviceconfig.ParseResult
218}
219
220// Target represents a target for gRPC, as specified in:
221// https://github.com/grpc/grpc/blob/master/doc/naming.md.
khenaidoo5cb0d402021-12-08 14:09:16 -0500222// It is parsed from the target string that gets passed into Dial or DialContext
223// by the user. And gRPC passes it to the resolver and the balancer.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400224//
khenaidoo5cb0d402021-12-08 14:09:16 -0500225// If the target follows the naming spec, and the parsed scheme is registered
226// with gRPC, we will parse the target string according to the spec. If the
227// target does not contain a scheme or if the parsed scheme is not registered
228// (i.e. no corresponding resolver available to resolve the endpoint), we will
229// apply the default scheme, and will attempt to reparse it.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400230//
khenaidoo5cb0d402021-12-08 14:09:16 -0500231// Examples:
khenaidoo5fc5cea2021-08-11 17:39:16 -0400232//
Joey Armstrongba3d9d12024-01-15 14:22:11 -0500233// - "dns://some_authority/foo.bar"
234// Target{Scheme: "dns", Authority: "some_authority", Endpoint: "foo.bar"}
235// - "foo.bar"
236// Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "foo.bar"}
237// - "unknown_scheme://authority/endpoint"
238// Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "unknown_scheme://authority/endpoint"}
khenaidoo5fc5cea2021-08-11 17:39:16 -0400239type Target struct {
khenaidoo5cb0d402021-12-08 14:09:16 -0500240 // Deprecated: use URL.Scheme instead.
241 Scheme string
242 // Deprecated: use URL.Host instead.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400243 Authority string
khenaidoo5cb0d402021-12-08 14:09:16 -0500244 // Deprecated: use URL.Path or URL.Opaque instead. The latter is set when
245 // the former is empty.
246 Endpoint string
247 // URL contains the parsed dial target with an optional default scheme added
248 // to it if the original dial target contained no scheme or contained an
249 // unregistered scheme. Any query params specified in the original dial
250 // target can be accessed from here.
251 URL url.URL
khenaidoo5fc5cea2021-08-11 17:39:16 -0400252}
253
254// Builder creates a resolver that will be used to watch name resolution updates.
255type Builder interface {
256 // Build creates a new resolver for the given target.
257 //
258 // gRPC dial calls Build synchronously, and fails if the returned error is
259 // not nil.
260 Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
261 // Scheme returns the scheme supported by this resolver.
262 // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
263 Scheme() string
264}
265
266// ResolveNowOptions includes additional information for ResolveNow.
267type ResolveNowOptions struct{}
268
269// Resolver watches for the updates on the specified target.
270// Updates include address updates and service config updates.
271type Resolver interface {
272 // ResolveNow will be called by gRPC to try to resolve the target name
273 // again. It's just a hint, resolver can ignore this if it's not necessary.
274 //
275 // It could be called multiple times concurrently.
276 ResolveNow(ResolveNowOptions)
277 // Close closes the resolver.
278 Close()
279}
280
281// UnregisterForTesting removes the resolver builder with the given scheme from the
282// resolver map.
283// This function is for testing only.
284func UnregisterForTesting(scheme string) {
285 delete(m, scheme)
286}