blob: e83da346a5cde38a6f9fea5e3c031371eaa895e0 [file] [log] [blame]
khenaidooac637102019-01-14 15:44:34 -05001/*
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
Scott Baker8461e152019-10-01 14:44:30 -070023import (
24 "google.golang.org/grpc/serviceconfig"
25)
26
khenaidooac637102019-01-14 15:44:34 -050027var (
28 // m is a map from scheme to resolver builder.
29 m = make(map[string]Builder)
30 // defaultScheme is the default scheme to use.
31 defaultScheme = "passthrough"
32)
33
34// TODO(bar) install dns resolver in init(){}.
35
36// Register registers the resolver builder to the resolver map. b.Scheme will be
37// used as the scheme registered with this builder.
38//
39// NOTE: this function must only be called during initialization time (i.e. in
40// an init() function), and is not thread-safe. If multiple Resolvers are
41// registered with the same name, the one registered last will take effect.
42func Register(b Builder) {
43 m[b.Scheme()] = b
44}
45
46// Get returns the resolver builder registered with the given scheme.
47//
48// If no builder is register with the scheme, nil will be returned.
49func Get(scheme string) Builder {
50 if b, ok := m[scheme]; ok {
51 return b
52 }
53 return nil
54}
55
56// SetDefaultScheme sets the default scheme that will be used. The default
57// default scheme is "passthrough".
58//
59// NOTE: this function must only be called during initialization time (i.e. in
60// an init() function), and is not thread-safe. The scheme set last overrides
61// previously set values.
62func SetDefaultScheme(scheme string) {
63 defaultScheme = scheme
64}
65
66// GetDefaultScheme gets the default scheme that will be used.
67func GetDefaultScheme() string {
68 return defaultScheme
69}
70
71// AddressType indicates the address type returned by name resolution.
72type AddressType uint8
73
74const (
75 // Backend indicates the address is for a backend server.
76 Backend AddressType = iota
77 // GRPCLB indicates the address is for a grpclb load balancer.
78 GRPCLB
79)
80
81// Address represents a server the client connects to.
82// This is the EXPERIMENTAL API and may be changed or extended in the future.
83type Address struct {
84 // Addr is the server address on which a connection will be established.
85 Addr string
86 // Type is the type of this address.
87 Type AddressType
88 // ServerName is the name of this address.
89 //
90 // e.g. if Type is GRPCLB, ServerName should be the name of the remote load
91 // balancer, not the name of the backend.
92 ServerName string
93 // Metadata is the information associated with Addr, which may be used
94 // to make load balancing decision.
95 Metadata interface{}
96}
97
98// BuildOption includes additional information for the builder to create
99// the resolver.
100type BuildOption struct {
101 // DisableServiceConfig indicates whether resolver should fetch service config data.
102 DisableServiceConfig bool
103}
104
Scott Baker8461e152019-10-01 14:44:30 -0700105// State contains the current Resolver state relevant to the ClientConn.
106type State struct {
107 Addresses []Address // Resolved addresses for the target
108 // ServiceConfig is the parsed service config; obtained from
109 // serviceconfig.Parse.
110 ServiceConfig serviceconfig.Config
111
112 // TODO: add Err error
113}
114
khenaidooac637102019-01-14 15:44:34 -0500115// ClientConn contains the callbacks for resolver to notify any updates
116// to the gRPC ClientConn.
117//
118// This interface is to be implemented by gRPC. Users should not need a
119// brand new implementation of this interface. For the situations like
120// testing, the new implementation should embed this interface. This allows
121// gRPC to add new methods to this interface.
122type ClientConn interface {
Scott Baker8461e152019-10-01 14:44:30 -0700123 // UpdateState updates the state of the ClientConn appropriately.
124 UpdateState(State)
khenaidooac637102019-01-14 15:44:34 -0500125 // NewAddress is called by resolver to notify ClientConn a new list
126 // of resolved addresses.
127 // The address list should be the complete list of resolved addresses.
Scott Baker8461e152019-10-01 14:44:30 -0700128 //
129 // Deprecated: Use UpdateState instead.
khenaidooac637102019-01-14 15:44:34 -0500130 NewAddress(addresses []Address)
131 // NewServiceConfig is called by resolver to notify ClientConn a new
132 // service config. The service config should be provided as a json string.
Scott Baker8461e152019-10-01 14:44:30 -0700133 //
134 // Deprecated: Use UpdateState instead.
khenaidooac637102019-01-14 15:44:34 -0500135 NewServiceConfig(serviceConfig string)
136}
137
138// Target represents a target for gRPC, as specified in:
139// https://github.com/grpc/grpc/blob/master/doc/naming.md.
Scott Baker8461e152019-10-01 14:44:30 -0700140// It is parsed from the target string that gets passed into Dial or DialContext by the user. And
141// grpc passes it to the resolver and the balancer.
142//
143// If the target follows the naming spec, and the parsed scheme is registered with grpc, we will
144// parse the target string according to the spec. e.g. "dns://some_authority/foo.bar" will be parsed
145// into &Target{Scheme: "dns", Authority: "some_authority", Endpoint: "foo.bar"}
146//
147// If the target does not contain a scheme, we will apply the default scheme, and set the Target to
148// be the full target string. e.g. "foo.bar" will be parsed into
149// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "foo.bar"}.
150//
151// If the parsed scheme is not registered (i.e. no corresponding resolver available to resolve the
152// endpoint), we set the Scheme to be the default scheme, and set the Endpoint to be the full target
153// string. e.g. target string "unknown_scheme://authority/endpoint" will be parsed into
154// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "unknown_scheme://authority/endpoint"}.
khenaidooac637102019-01-14 15:44:34 -0500155type Target struct {
156 Scheme string
157 Authority string
158 Endpoint string
159}
160
161// Builder creates a resolver that will be used to watch name resolution updates.
162type Builder interface {
163 // Build creates a new resolver for the given target.
164 //
165 // gRPC dial calls Build synchronously, and fails if the returned error is
166 // not nil.
167 Build(target Target, cc ClientConn, opts BuildOption) (Resolver, error)
168 // Scheme returns the scheme supported by this resolver.
169 // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
170 Scheme() string
171}
172
173// ResolveNowOption includes additional information for ResolveNow.
174type ResolveNowOption struct{}
175
176// Resolver watches for the updates on the specified target.
177// Updates include address updates and service config updates.
178type Resolver interface {
179 // ResolveNow will be called by gRPC to try to resolve the target name
180 // again. It's just a hint, resolver can ignore this if it's not necessary.
181 //
182 // It could be called multiple times concurrently.
183 ResolveNow(ResolveNowOption)
184 // Close closes the resolver.
185 Close()
186}
187
188// UnregisterForTesting removes the resolver builder with the given scheme from the
189// resolver map.
190// This function is for testing only.
191func UnregisterForTesting(scheme string) {
192 delete(m, scheme)
193}