]>
Commit | Line | Data |
---|---|---|
107c1cdb ND |
1 | /* |
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. | |
21 | package resolver | |
22 | ||
23 | var ( | |
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. | |
38 | func 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. | |
45 | func 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. | |
58 | func SetDefaultScheme(scheme string) { | |
59 | defaultScheme = scheme | |
60 | } | |
61 | ||
62 | // GetDefaultScheme gets the default scheme that will be used. | |
63 | func GetDefaultScheme() string { | |
64 | return defaultScheme | |
65 | } | |
66 | ||
67 | // AddressType indicates the address type returned by name resolution. | |
68 | type AddressType uint8 | |
69 | ||
70 | const ( | |
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. | |
79 | type 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. | |
96 | type 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. | |
108 | type 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. | |
120 | type 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. | |
127 | type 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. | |
139 | type ResolveNowOption struct{} | |
140 | ||
141 | // Resolver watches for the updates on the specified target. | |
142 | // Updates include address updates and service config updates. | |
143 | type 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. | |
156 | func UnregisterForTesting(scheme string) { | |
157 | delete(m, scheme) | |
158 | } |