blob: 145cf477edb09bfa11741540f6565bf30f7e1989 [file] [log] [blame]
Scott Baker2d897982019-09-24 11:50:08 -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
23var (
24 // m is a map from scheme to resolver builder.
25 m = make(map[string]Builder)
26 // defaultScheme is the default scheme to use.
27 defaultScheme = "passthrough"
28)
29
30// TODO(bar) install dns resolver in init(){}.
31
32// Register registers the resolver builder to the resolver map. b.Scheme will be
33// used as the scheme registered with this builder.
34//
35// NOTE: this function must only be called during initialization time (i.e. in
36// an init() function), and is not thread-safe. If multiple Resolvers are
37// registered with the same name, the one registered last will take effect.
38func Register(b Builder) {
39 m[b.Scheme()] = b
40}
41
42// Get returns the resolver builder registered with the given scheme.
43//
44// If no builder is register with the scheme, nil will be returned.
45func Get(scheme string) Builder {
46 if b, ok := m[scheme]; ok {
47 return b
48 }
49 return nil
50}
51
52// SetDefaultScheme sets the default scheme that will be used. The default
53// default scheme is "passthrough".
54//
55// NOTE: this function must only be called during initialization time (i.e. in
56// an init() function), and is not thread-safe. The scheme set last overrides
57// previously set values.
58func SetDefaultScheme(scheme string) {
59 defaultScheme = scheme
60}
61
62// GetDefaultScheme gets the default scheme that will be used.
63func GetDefaultScheme() string {
64 return defaultScheme
65}
66
67// AddressType indicates the address type returned by name resolution.
68type AddressType uint8
69
70const (
71 // Backend indicates the address is for a backend server.
72 Backend AddressType = iota
73 // GRPCLB indicates the address is for a grpclb load balancer.
74 GRPCLB
75)
76
77// Address represents a server the client connects to.
78// This is the EXPERIMENTAL API and may be changed or extended in the future.
79type Address struct {
80 // Addr is the server address on which a connection will be established.
81 Addr string
82 // Type is the type of this address.
83 Type AddressType
84 // ServerName is the name of this address.
85 //
86 // e.g. if Type is GRPCLB, ServerName should be the name of the remote load
87 // balancer, not the name of the backend.
88 ServerName string
89 // Metadata is the information associated with Addr, which may be used
90 // to make load balancing decision.
91 Metadata interface{}
92}
93
94// BuildOption includes additional information for the builder to create
95// the resolver.
96type BuildOption struct {
97 // DisableServiceConfig indicates whether resolver should fetch service config data.
98 DisableServiceConfig bool
99}
100
101// ClientConn contains the callbacks for resolver to notify any updates
102// to the gRPC ClientConn.
103//
104// This interface is to be implemented by gRPC. Users should not need a
105// brand new implementation of this interface. For the situations like
106// testing, the new implementation should embed this interface. This allows
107// gRPC to add new methods to this interface.
108type ClientConn interface {
109 // NewAddress is called by resolver to notify ClientConn a new list
110 // of resolved addresses.
111 // The address list should be the complete list of resolved addresses.
112 NewAddress(addresses []Address)
113 // NewServiceConfig is called by resolver to notify ClientConn a new
114 // service config. The service config should be provided as a json string.
115 NewServiceConfig(serviceConfig string)
116}
117
118// Target represents a target for gRPC, as specified in:
119// https://github.com/grpc/grpc/blob/master/doc/naming.md.
120type Target struct {
121 Scheme string
122 Authority string
123 Endpoint string
124}
125
126// Builder creates a resolver that will be used to watch name resolution updates.
127type Builder interface {
128 // Build creates a new resolver for the given target.
129 //
130 // gRPC dial calls Build synchronously, and fails if the returned error is
131 // not nil.
132 Build(target Target, cc ClientConn, opts BuildOption) (Resolver, error)
133 // Scheme returns the scheme supported by this resolver.
134 // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
135 Scheme() string
136}
137
138// ResolveNowOption includes additional information for ResolveNow.
139type ResolveNowOption struct{}
140
141// Resolver watches for the updates on the specified target.
142// Updates include address updates and service config updates.
143type Resolver interface {
144 // ResolveNow will be called by gRPC to try to resolve the target name
145 // again. It's just a hint, resolver can ignore this if it's not necessary.
146 //
147 // It could be called multiple times concurrently.
148 ResolveNow(ResolveNowOption)
149 // Close closes the resolver.
150 Close()
151}
152
153// UnregisterForTesting removes the resolver builder with the given scheme from the
154// resolver map.
155// This function is for testing only.
156func UnregisterForTesting(scheme string) {
157 delete(m, scheme)
158}