vendor/google.golang.org/grpc/resolver/resolver.go

   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.
  33 // b.Scheme will be used as the scheme registered with this builder.
  34 func Register(b Builder) {
  35         m[b.Scheme()] = b
  36 }
  37
  38 // Get returns the resolver builder registered with the given scheme.
  39 // If no builder is register with the scheme, the default scheme will
  40 // be used.
  41 // If the default scheme is not modified, "dns" will be the default
  42 // scheme, and the preinstalled dns resolver will be used.
  43 // If the default scheme is modified, and a resolver is registered with
  44 // the scheme, that resolver will be returned.
  45 // If the default scheme is modified, and no resolver is registered with
  46 // the scheme, nil will be returned.
  47 func Get(scheme string) Builder {
  48         if b, ok := m[scheme]; ok {
  49                 return b
  50         }
  51         if b, ok := m[defaultScheme]; ok {
  52                 return b
  53         }
  54         return nil
  55 }
  56
  57 // SetDefaultScheme sets the default scheme that will be used.
  58 // The default default scheme is "dns".
  59 func SetDefaultScheme(scheme string) {
  60         defaultScheme = scheme
  61 }
  62
  63 // AddressType indicates the address type returned by name resolution.
  64 type AddressType uint8
  65
  66 const (
  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.
  75 type 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         // It's the name of the grpc load balancer, which will be used for authentication.
  82         ServerName string
  83         // Metadata is the information associated with Addr, which may be used
  84         // to make load balancing decision.
  85         Metadata interface{}
  86 }
  87
  88 // BuildOption includes additional information for the builder to create
  89 // the resolver.
  90 type BuildOption struct {
  91 }
  92
  93 // ClientConn contains the callbacks for resolver to notify any updates
  94 // to the gRPC ClientConn.
  95 type ClientConn interface {
  96         // NewAddress is called by resolver to notify ClientConn a new list
  97         // of resolved addresses.
  98         // The address list should be the complete list of resolved addresses.
  99         NewAddress(addresses []Address)
 100         // NewServiceConfig is called by resolver to notify ClientConn a new
 101         // service config. The service config should be provided as a json string.
 102         NewServiceConfig(serviceConfig string)
 103 }
 104
 105 // Target represents a target for gRPC, as specified in:
 106 // https://github.com/grpc/grpc/blob/master/doc/naming.md.
 107 type Target struct {
 108         Scheme    string
 109         Authority string
 110         Endpoint  string
 111 }
 112
 113 // Builder creates a resolver that will be used to watch name resolution updates.
 114 type Builder interface {
 115         // Build creates a new resolver for the given target.
 116         //
 117         // gRPC dial calls Build synchronously, and fails if the returned error is
 118         // not nil.
 119         Build(target Target, cc ClientConn, opts BuildOption) (Resolver, error)
 120         // Scheme returns the scheme supported by this resolver.
 121         // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
 122         Scheme() string
 123 }
 124
 125 // ResolveNowOption includes additional information for ResolveNow.
 126 type ResolveNowOption struct{}
 127
 128 // Resolver watches for the updates on the specified target.
 129 // Updates include address updates and service config updates.
 130 type Resolver interface {
 131         // ResolveNow will be called by gRPC to try to resolve the target name again.
 132         // It's just a hint, resolver can ignore this if it's not necessary.
 133         ResolveNow(ResolveNowOption)
 134         // Close closes the resolver.
 135         Close()
 136 }
 137
 138 // UnregisterForTesting removes the resolver builder with the given scheme from the
 139 // resolver map.
 140 // This function is for testing only.
 141 func UnregisterForTesting(scheme string) {
 142         delete(m, scheme)
 143 }