resolver

type Address struct {
	// HostPort stores the host:port pair of the resolved address.
	HostPort string

	// Attributes is a collection of arbitrary key/value pairs.
	Attributes attribute.Values
}

type AddressFamilyPolicy int

type Receiver interface {
	// OnResolve is called when the set of addresses is resolved. It may be called
	// repeatedly as the set of addresses changes over time. Each call must always
	// supply the full set of resolved addresses (no deltas).
	OnResolve([]Address)
	// OnResolveError is called when resolution encounters an error. This can
	// happen at any time, including after addresses are initially resolved. But
	// the errors may be ignored after initial resolution.
	OnResolveError(error)
}

type RendezvousConfig struct {
	// NumBackends specifies the number of backends to select out of the set of
	// available hosts. This option is required.
	NumBackends int

	// SelectionKey specifies the key used to uniquely select hosts. This value
	// controls which hosts get selected, thus typically you set a unique value
	// for each program instance, using e.g. the machine host name. If not set,
	// a random string will be used.
	SelectionKey string

	// Hash provides a hash function to use. If unspecified, an implementation
	// of MurmurHash3 will be used.
	Hash hash.Hash32
}

type ResolveProber interface {
	// ResolveOnce resolves the given target name once, returning a slice of
	// addresses corresponding to the provided scheme and hostname.
	// The second return value specifies the TTL of the result, or 0 if there
	// is no known TTL value.
	//
	// The resolved addresses should have ports if it is needed for the expected
	// target network. For example, in the common case of TCP, if the provided
	// hostPort string does not contain a port, a default port should be added
	// based on the scheme.
	ResolveOnce(
		ctx context.Context,
		scheme,
		hostPort string,
	) (
		results []Address,
		ttl time.Duration,
		err error,
	)
}

type Resolver interface {
	// New creates a continuous resolver task for the given target name. When
	// the target is resolved into backend addresses, they are provided to the
	// given callback.
	//
	// As new result sets arrive (since the set of addresses may change over
	// time), the callback may be called repeatedly. Each time, the entire set
	// of addresses should be supplied.
	//
	// The resolver may report errors in addition to or instead of addresses,
	// but it should keep trying to resolve (and watch for changes), even in
	// the face of errors, until it is closed or the given context is cancelled.
	//
	// The refresh channel will receive signals from the client hinting that it
	// may need new results. For example, if the client runs out of healthy
	// hosts, it may call this method in order to try to find more healthy
	// hosts. This is particularly likely to happen during e.g. a rolling
	// deployment, wherein the entire pool of hosts could disappear within the
	// span of a TTL. This may be a no-op. The refresh channel will not be
	// closed until after Close() returns.
	//
	// The Close method on the return value should stop all goroutines and free
	// any resources before returning. After close returns, there should be no
	// subsequent calls to callbacks.
	New(
		ctx context.Context,
		scheme, hostPort string,
		receiver Receiver,
		refresh <-chan struct{},
	) io.Closer
}