cmd/bpa-operator/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. 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 }