resolver.go 5.1 KB

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