{
  // 使用 round_robin 负载均衡策略
  load_balancing_config: { round_robin: {} }
  // 这个方法配置适用于 "foo/bar" 方法和 service "baz"的所有方法
  method_config: {
    name: {
      service: "foo"
      method: "bar"
    }
    name: {
      service: "baz"
    }
    // 匹配方法的默认超时
    timeout: {
      seconds: 1
      nanos: 1
    }
  }
}

// A list of one or more service config choices.
// The first matching entry wins.
[
  {
    // Criteria used to select this choice.
    // If a field is absent or empty, it matches all clients.
    // All fields must match a client for this choice to be selected.
    // If any unexpected field name is present in this object, the entire
    // config is considered invalid.
    //
    // Client language(s): a list of strings (e.g., "c++", "java", "go",
    // "python", etc).  Each string is case insensitive.
    "clientLanguage": [string],
    // Percentage: integer from 0 to 100 indicating the percentage of
    // clients that should use this choice.  If present, the number must
    // match the regular expression `^0|[0-9]|[1-9][0-9]|100$`
    // All other numbers are considered invalid.
    "percentage": number,
    // Client hostname(s): a list of strings.  Each name is case 
    // sensitive and must be an exact match of the hostname according to
    // the system.
    "clientHostname": [string],

    // The service config data object for clients that match the above
    // criteria.  (The format for this object is defined in
    // https://github.com/grpc/grpc/blob/master/doc/service_config.md.)
    // If this field is not an object, or is missing, or is otherwise 
    // invalid, the entire config is considered invalid.
    "serviceConfig": object
  }
]

_grpc_config.myserver  3600  TXT "grpc_config=[{\"serviceConfig\":{\"loadBalancingPolicy\":\"round_robin\",\"methodConfig\":[{\"name\":[{\"service\":\"MyService\",\"method\":\"Foo\"}],\"waitForReady\":true}]}}]"

// Update defines a name resolution update. Notice that it is not valid having both
// empty string Addr and nil Metadata in an Update.
//
// Deprecated: please use package resolver.
type Update struct {
	// Op indicates the operation of the update.
	Op Operation
	// Addr is the updated address. It is empty string if there is no address update.
	Addr string
	// Metadata is the updated metadata. It is nil if there is no metadata update.
	// Metadata is not required for a custom naming implementation.
	Metadata interface{}
}

// Operation defines the corresponding operations for a name resolution change.
//
// Deprecated: please use package resolver.
type Operation uint8

const (
	// Add indicates a new address is added.
	Add Operation = iota
	// Delete indicates an existing address is deleted.
	Delete
)

// Resolver creates a Watcher for a target to track its resolution changes.
//
// Deprecated: please use package resolver.
type Resolver interface {
	// Resolve creates a Watcher for target.
	Resolve(target string) (Watcher, error)
}

// Watcher watches for the updates on the specified target.
//
// Deprecated: please use package resolver.
type Watcher interface {
  // Next 方法阻塞直至更新或者错误发生。
  // 可能返回一个或者多个更新。
  // 第一次调用因该得到结果的全集。
  // 当且仅当 Watcher 无法恢复时返回错误。
	Next() ([]*Update, error)
	// Close closes the Watcher.
	Close()
}

type dnsResolver struct {
   // 该解析器创建的 watcher 将使用的 DNS 服务器的轮询频率。
   freq time.Duration
}

const (
  // 默认频率是30分钟。
	defaultFreq = time.Minute * 30
)

// NewDNSResolverWithFreq 创建 DNS Resolver，用于解析 DNS 名称，并创建watcher，使用 freq 参数设置的频率来查询DNS 服务器
func NewDNSResolverWithFreq(freq time.Duration) (Resolver, error) {
	return &dnsResolver{freq: freq}, nil
}

// NewDNSResolverWithFreq 创建 DNS Resolver，用于解析 DNS 名称，并创建watcher，使用默认的频率来查询DNS 服务器
func NewDNSResolver() (Resolver, error) {
	return NewDNSResolverWithFreq(defaultFreq)
}

func (r *dnsResolver) Resolve(target string) (Watcher, error) {
	host, port, err := parseTarget(target)
	if err != nil {
		return nil, err
	}

  // 尝试一下检测host是不是一个IP地址
	if net.ParseIP(host) != nil {
    // 如果是IP地址，不用做dns解析，走 ipWatcher
		ipWatcher := &ipWatcher{
			updateChan: make(chan *Update, 1),
		}
		host, _ = formatIP(host)
		ipWatcher.updateChan <- &Update{Op: Add, Addr: host + ":" + port}
		return ipWatcher, nil
	}

  // 如果host不是IP地址，则走 dnsWatcher
	ctx, cancel := context.WithCancel(context.Background())
	return &dnsWatcher{
		r:      r,
		host:   host,
		port:   port,
		ctx:    ctx,
		cancel: cancel,
		t:      time.NewTimer(0),
	}, nil
}

// parseTarget takes the user input target string, returns formatted host and port info.
// If target doesn't specify a port, set the port to be the defaultPort.
// If target is in IPv6 format and host-name is enclosed in square brackets, brackets
// are stripped when setting the host.
// examples:
// target: "www.google.com" returns host: "www.google.com", port: "443"
// target: "ipv4-host:80" returns host: "ipv4-host", port: "80"
// target: "[ipv6-host]" returns host: "ipv6-host", port: "443"
// target: ":80" returns host: "localhost", port: "80"
// target: ":" returns host: "localhost", port: "443"
func parseTarget(target string) (host, port string, err error) {
   if target == "" {
      return "", "", errMissingAddr
   }

   if ip := net.ParseIP(target); ip != nil {
      // target is an IPv4 or IPv6(without brackets) address
      return target, defaultPort, nil
   }
   if host, port, err := net.SplitHostPort(target); err == nil {
      // target has port, i.e ipv4-host:port, [ipv6-host]:port, host-name:port
      if host == "" {
         // Keep consistent with net.Dial(): If the host is empty, as in ":80", the local system is assumed.
         host = "localhost"
      }
      if port == "" {
         // If the port field is empty(target ends with colon), e.g. "[::1]:", defaultPort is used.
         port = defaultPort
      }
      return host, port, nil
   }
   if host, port, err := net.SplitHostPort(target + ":" + defaultPort); err == nil {
      // target doesn't have port
      return host, port, nil
   }
   return "", "", fmt.Errorf("invalid target address %v", target)
}

func formatIP(addr string) (addrIP string, ok bool) {
   ip := net.ParseIP(addr)
   if ip == nil {
      return "", false
   }
   if ip.To4() != nil {
      return addr, true
   }
   return "[" + addr + "]", true
}

type ipWatcher struct {
   updateChan chan *Update
}

func (i *ipWatcher) Next() ([]*Update, error) {
   u, ok := <-i.updateChan
   if !ok {
      return nil, errWatcherClose
   }
   return []*Update{u}, nil
}

// Close closes the ipWatcher.
func (i *ipWatcher) Close() {
   close(i.updateChan)
}

if net.ParseIP(host) != nil {
	ipWatcher := &ipWatcher{
		// 构建update channel，缓存大小为1
		updateChan: make(chan *Update, 1),
	}
  // 格式化IP地址
	host, _ = formatIP(host)
  // 往 updateChan 中发一个Update：操作为Add，Addr为IP地址+端口
	ipWatcher.updateChan <- &Update{Op: Add, Addr: host + ":" + port}
	return ipWatcher, nil
}

// dnsWatcher watches for the name resolution update for a specific target
type dnsWatcher struct {
   r    *dnsResolver
   host string
   port string
   // The latest resolved address set
   curAddrs map[string]*Update
   ctx      context.Context
   cancel   context.CancelFunc
   t        *time.Timer
}

func (w *dnsWatcher) Next() ([]*Update, error) {
   for {
      select {
      case <-w.ctx.Done():
         return nil, errWatcherClose
      case <-w.t.C:
      }
      result := w.lookup()
     // 下一次 lookup 应该在 w.r.freq 定义的间隔之后发生
      w.t.Reset(w.r.freq)
      if len(result) > 0 {
         return result, nil
      }
   }
}

func (w *dnsWatcher) Close() {
   w.cancel()
}

func (w *dnsWatcher) lookup() []*Update {
   newAddrs := w.lookupSRV()
   if newAddrs == nil {
      // If failed to get any balancer address (either no corresponding SRV for the
      // target, or caused by failure during resolution/parsing of the balancer target),
      // return any A record info available.
      newAddrs = w.lookupHost()
   }
   result := w.compileUpdate(newAddrs)
   w.curAddrs = newAddrs
   return result
}

func (w *dnsWatcher) lookupSRV() map[string]*Update {
   newAddrs := make(map[string]*Update)
   _, srvs, err := lookupSRV(w.ctx, "grpclb", "tcp", w.host)
   if err != nil {
      grpclog.Infof("grpc: failed dns SRV record lookup due to %v.\n", err)
      return nil
   }
   for _, s := range srvs {
      lbAddrs, err := lookupHost(w.ctx, s.Target)
      if err != nil {
         grpclog.Warningf("grpc: failed load balancer address dns lookup due to %v.\n", err)
         continue
      }
      for _, a := range lbAddrs {
         a, ok := formatIP(a)
         if !ok {
            grpclog.Errorf("grpc: failed IP parsing due to %v.\n", err)
            continue
         }
         addr := a + ":" + strconv.Itoa(int(s.Port))
         newAddrs[addr] = &Update{Addr: addr,
            Metadata: AddrMetadataGRPCLB{AddrType: GRPCLB, ServerName: s.Target}}
      }
   }
   return newAddrs
}

func (w *dnsWatcher) lookupHost() map[string]*Update {
   newAddrs := make(map[string]*Update)
   addrs, err := lookupHost(w.ctx, w.host)
   if err != nil {
      grpclog.Warningf("grpc: failed dns A record lookup due to %v.\n", err)
      return nil
   }
   for _, a := range addrs {
      a, ok := formatIP(a)
      if !ok {
         grpclog.Errorf("grpc: failed IP parsing due to %v.\n", err)
         continue
      }
      addr := a + ":" + w.port
      newAddrs[addr] = &Update{Addr: addr}
   }
   return newAddrs
}

var (
   // m is a map from scheme to resolver builder.
   m = make(map[string]Builder)
)

// Register registers the resolver builder to the resolver map. b.Scheme will be
// used as the scheme registered with this builder.
//
// NOTE: this function must only be called during initialization time (i.e. in
// an init() function), and is not thread-safe. If multiple Resolvers are
// registered with the same name, the one registered last will take effect.
func Register(b Builder) {
	m[b.Scheme()] = b
}

// Get returns the resolver builder registered with the given scheme.
//
// If no builder is register with the scheme, nil will be returned.
func Get(scheme string) Builder {
	if b, ok := m[scheme]; ok {
		return b
	}
	return nil
}

var (
   // defaultScheme is the default scheme to use.
   defaultScheme = "passthrough"
)

// SetDefaultScheme sets the default scheme that will be used. The default
// default scheme is "passthrough".
//
// NOTE: this function must only be called during initialization time (i.e. in
// an init() function), and is not thread-safe. The scheme set last overrides
// previously set values.
func SetDefaultScheme(scheme string) {
	defaultScheme = scheme
}

// GetDefaultScheme gets the default scheme that will be used.
func GetDefaultScheme() string {
	return defaultScheme
}

// This is the EXPERIMENTAL API and may be changed or extended in the future.
type Address struct {
   // Addr is the server address on which a connection will be established.
   Addr string

   // ServerName is the name of this address.
   // If non-empty, the ServerName is used as the transport certification authority for
   // the address, instead of the hostname from the Dial target string. In most cases,
   // this should not be set.
   //
   // If Type is GRPCLB, ServerName should be the name of the remote load
   // balancer, not the name of the backend.
   //
   // WARNING: ServerName must only be populated with trusted values. It
   // is insecure to populate it with data from untrusted inputs since untrusted
   // values could be used to bypass the authority checks performed by TLS.
   ServerName string

   // Attributes contains arbitrary data about this address intended for
   // consumption by the load balancing policy.
   Attributes *attributes.Attributes

   // Type is the type of this address.
   //
   // Deprecated: use Attributes instead.
   Type AddressType

   // Metadata is the information associated with Addr, which may be used
   // to make load balancing decision.
   //
   // Deprecated: use Attributes instead.
   Metadata interface{}
}

// Attributes是一个不可变的结构体，用于存储和检索通用键/值对。 key必须是可哈希的，用户应该为key定义自己的类型。
type Attributes struct {
   m map[interface{}]interface{}
}

type Builder interface {
   // Build creates a new resolver for the given target.
   //
   // gRPC dial calls Build synchronously, and fails if the returned error is
   // not nil.
   Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
   // Scheme returns the scheme supported by this resolver.
   // Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
   Scheme() string
}

// Target represents a target for gRPC, as specified in:
// https://github.com/grpc/grpc/blob/master/doc/naming.md.
// It is parsed from the target string that gets passed into Dial or DialContext by the user. And
// grpc passes it to the resolver and the balancer.
//
// If the target follows the naming spec, and the parsed scheme is registered with grpc, we will
// parse the target string according to the spec. e.g. "dns://some_authority/foo.bar" will be parsed
// into &Target{Scheme: "dns", Authority: "some_authority", Endpoint: "foo.bar"}
//
// If the target does not contain a scheme, we will apply the default scheme, and set the Target to
// be the full target string. e.g. "foo.bar" will be parsed into
// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "foo.bar"}.
//
// If the parsed scheme is not registered (i.e. no corresponding resolver available to resolve the
// endpoint), we set the Scheme to be the default scheme, and set the Endpoint to be the full target
// string. e.g. target string "unknown_scheme://authority/endpoint" will be parsed into
// &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "unknown_scheme://authority/endpoint"}.
type Target struct {
   Scheme    string
   Authority string
   Endpoint  string
}

// ClientConn contains the callbacks for resolver to notify any updates
// to the gRPC ClientConn.
//
// This interface is to be implemented by gRPC. Users should not need a
// brand new implementation of this interface. For the situations like
// testing, the new implementation should embed this interface. This allows
// gRPC to add new methods to this interface.
type ClientConn interface {
   // UpdateState updates the state of the ClientConn appropriately.
   UpdateState(State)
   // ReportError notifies the ClientConn that the Resolver encountered an
   // error.  The ClientConn will notify the load balancer and begin calling
   // ResolveNow on the Resolver with exponential backoff.
   ReportError(error)
   // NewAddress is called by resolver to notify ClientConn a new list
   // of resolved addresses.
   // The address list should be the complete list of resolved addresses.
   //
   // Deprecated: Use UpdateState instead.
   NewAddress(addresses []Address)
   // NewServiceConfig is called by resolver to notify ClientConn a new
   // service config. The service config should be provided as a json string.
   //
   // Deprecated: Use UpdateState instead.
   NewServiceConfig(serviceConfig string)
   // ParseServiceConfig parses the provided service config and returns an
   // object that provides the parsed config.
   ParseServiceConfig(serviceConfigJSON string) *serviceconfig.ParseResult
}

type BuildOptions struct {
   // DisableServiceConfig 指示resolver的实现是否要获取service config数据
   DisableServiceConfig bool
   // DialCreds is the transport credentials used by the ClientConn for
   // communicating with the target gRPC service (set via
   // WithTransportCredentials). In cases where a name resolution service
   // requires the same credentials, the resolver may use this field. In most
   // cases though, it is not appropriate, and this field may be ignored.
   DialCreds credentials.TransportCredentials
   // CredsBundle is the credentials bundle used by the ClientConn for
   // communicating with the target gRPC service (set via
   // WithCredentialsBundle). In cases where a name resolution service
   // requires the same credentials, the resolver may use this field. In most
   // cases though, it is not appropriate, and this field may be ignored.
   CredsBundle credentials.Bundle
   // Dialer is the custom dialer used by the ClientConn for dialling the
   // target gRPC service (set via WithDialer). In cases where a name
   // resolution service requires the same dialer, the resolver may use this
   // field. In most cases though, it is not appropriate, and this field may
   // be ignored.
   Dialer func(context.Context, string) (net.Conn, error)
}

type Resolver interface {
   // ResolveNow 将被 gRPC 调用来尝试再次解析目标名称。
   // 这仅仅是一个提示（hint），resolver 可以忽略它，如果没有必要。
   // 可以并发的多次调用。
   ResolveNow(ResolveNowOptions)
   // Close closes the resolver.
   Close()
}

// ResolveNowOptions includes additional information for ResolveNow.
type ResolveNowOptions struct{}

const scheme = "passthrough"

type passthroughBuilder struct{}

func (*passthroughBuilder) Build(target resolver.Target, cc resolver.ClientConn, opts resolver.BuildOptions) (resolver.Resolver, error) {
   r := &passthroughResolver{
      target: target,
      cc:     cc,
   }
   r.start()
   return r, nil
}

func (*passthroughBuilder) Scheme() string {
   return scheme
}

func (r *passthroughResolver) start() {
   r.cc.UpdateState(resolver.State{Addresses: []resolver.Address{{Addr: r.target.Endpoint}}})
}

func (*passthroughResolver) ResolveNow(o resolver.ResolveNowOptions) {}

func (*passthroughResolver) Close() {}

func init() {
   resolver.Register(&passthroughBuilder{})
}

// 配合 passthrough.go
import _ "google.golang.org/grpc/internal/resolver/passthrough" // import for side effects after package was moved

// InitialState adds initial state to the resolver so that UpdateState doesn't
// need to be explicitly called after Dial.
func (r *Resolver) InitialState(s resolver.State) {
	r.bootstrapState = &s
}

// Build returns itself for Resolver, because it's both a builder and a resolver.
func (r *Resolver) Build(target resolver.Target, cc resolver.ClientConn, opts resolver.BuildOptions) (resolver.Resolver, error) {
   r.CC = cc
   if r.bootstrapState != nil {
      r.UpdateState(*r.bootstrapState)
   }
   return r, nil
}

// Build creates and starts a DNS resolver that watches the name resolution of the target.
func (b *dnsBuilder) Build(target resolver.Target, cc resolver.ClientConn, opts resolver.BuildOptions) (resolver.Resolver, error) {
   host, port, err := parseTarget(target.Endpoint, defaultPort)
   if err != nil {
      return nil, err
   }

   // IP address.
   if ipAddr, ok := formatIP(host); ok {
      addr := []resolver.Address{{Addr: ipAddr + ":" + port}}
      cc.UpdateState(resolver.State{Addresses: addr})
      return deadResolver{}, nil
   }

   // DNS address (non-IP).
   ctx, cancel := context.WithCancel(context.Background())
   d := &dnsResolver{
      host:                 host,
      port:                 port,
      ctx:                  ctx,
      cancel:               cancel,
      cc:                   cc,
      rn:                   make(chan struct{}, 1),
      disableServiceConfig: opts.DisableServiceConfig,
   }

   if target.Authority == "" {
      d.resolver = defaultResolver
   } else {
      d.resolver, err = customAuthorityResolver(target.Authority)
      if err != nil {
         return nil, err
      }
   }

   d.wg.Add(1)
   go d.watcher()
   d.ResolveNow(resolver.ResolveNowOptions{})
   return d, nil
}

// dnsResolver watches for the name resolution update for a non-IP target.
type dnsResolver struct {
   host     string
   port     string
   resolver netResolver
   ctx      context.Context
   cancel   context.CancelFunc
   cc       resolver.ClientConn
   // rn channel is used by ResolveNow() to force an immediate resolution of the target.
   rn chan struct{}
   // wg is used to enforce Close() to return after the watcher() goroutine has finished.
   // Otherwise, data race will be possible. [Race Example] in dns_resolver_test we
   // replace the real lookup functions with mocked ones to facilitate testing.
   // If Close() doesn't wait for watcher() goroutine finishes, race detector sometimes
   // will warns lookup (READ the lookup function pointers) inside watcher() goroutine
   // has data race with replaceNetFunc (WRITE the lookup function pointers).
   wg                   sync.WaitGroup
   disableServiceConfig bool
}

// ResolveNow invoke an immediate resolution of the target that this dnsResolver watches.
func (d *dnsResolver) ResolveNow(resolver.ResolveNowOptions) {
   select {
   case d.rn <- struct{}{}:
   default:
   }
}

// Close closes the dnsResolver.
func (d *dnsResolver) Close() {
   d.cancel()
   d.wg.Wait()
}

func (d *dnsResolver) watcher() {
   defer d.wg.Done()
   for {
      select {
      case <-d.ctx.Done():
         return
      case <-d.rn:
      }

      state, err := d.lookup()
      if err != nil {
         d.cc.ReportError(err)
      } else {
         d.cc.UpdateState(*state)
      }

      // Sleep to prevent excessive re-resolutions. Incoming resolution requests
      // will be queued in d.rn.
      t := time.NewTimer(minDNSResRate)
      select {
      case <-t.C:
      case <-d.ctx.Done():
         t.Stop()
         return
      }
   }
}