blob: 506afac88aea2446f2d77169de22d7c4e84190f3 [file] [log] [blame]
Matthias Andreas Benkard832a54e2019-01-29 09:27:38 +01001/*
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.
53// The default default scheme is "passthrough".
54func SetDefaultScheme(scheme string) {
55 defaultScheme = scheme
56}
57
58// GetDefaultScheme gets the default scheme that will be used.
59func GetDefaultScheme() string {
60 return defaultScheme
61}
62
63// AddressType indicates the address type returned by name resolution.
64type AddressType uint8
65
66const (
67 // Backend indicates the address is for a backend server.
68 Backend AddressType = iota
69 // GRPCLB indicates the address is for a grpclb load balancer.
70 GRPCLB
71)
72
73// Address represents a server the client connects to.
74// This is the EXPERIMENTAL API and may be changed or extended in the future.
75type Address struct {
76 // Addr is the server address on which a connection will be established.
77 Addr string
78 // Type is the type of this address.
79 Type AddressType
80 // ServerName is the name of this address.
81 //
82 // e.g. if Type is GRPCLB, ServerName should be the name of the remote load
83 // balancer, not the name of the backend.
84 ServerName string
85 // Metadata is the information associated with Addr, which may be used
86 // to make load balancing decision.
87 Metadata interface{}
88}
89
90// BuildOption includes additional information for the builder to create
91// the resolver.
92type BuildOption struct {
93 // DisableServiceConfig indicates whether resolver should fetch service config data.
94 DisableServiceConfig bool
95}
96
97// ClientConn contains the callbacks for resolver to notify any updates
98// to the gRPC ClientConn.
99//
100// This interface is to be implemented by gRPC. Users should not need a
101// brand new implementation of this interface. For the situations like
102// testing, the new implementation should embed this interface. This allows
103// gRPC to add new methods to this interface.
104type ClientConn interface {
105 // NewAddress is called by resolver to notify ClientConn a new list
106 // of resolved addresses.
107 // The address list should be the complete list of resolved addresses.
108 NewAddress(addresses []Address)
109 // NewServiceConfig is called by resolver to notify ClientConn a new
110 // service config. The service config should be provided as a json string.
111 NewServiceConfig(serviceConfig string)
112}
113
114// Target represents a target for gRPC, as specified in:
115// https://github.com/grpc/grpc/blob/master/doc/naming.md.
116type Target struct {
117 Scheme string
118 Authority string
119 Endpoint string
120}
121
122// Builder creates a resolver that will be used to watch name resolution updates.
123type Builder interface {
124 // Build creates a new resolver for the given target.
125 //
126 // gRPC dial calls Build synchronously, and fails if the returned error is
127 // not nil.
128 Build(target Target, cc ClientConn, opts BuildOption) (Resolver, error)
129 // Scheme returns the scheme supported by this resolver.
130 // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
131 Scheme() string
132}
133
134// ResolveNowOption includes additional information for ResolveNow.
135type ResolveNowOption struct{}
136
137// Resolver watches for the updates on the specified target.
138// Updates include address updates and service config updates.
139type Resolver interface {
140 // ResolveNow will be called by gRPC to try to resolve the target name
141 // again. It's just a hint, resolver can ignore this if it's not necessary.
142 //
143 // It could be called multiple times concurrently.
144 ResolveNow(ResolveNowOption)
145 // Close closes the resolver.
146 Close()
147}
148
149// UnregisterForTesting removes the resolver builder with the given scheme from the
150// resolver map.
151// This function is for testing only.
152func UnregisterForTesting(scheme string) {
153 delete(m, scheme)
154}