Documentation
¶
Overview ¶
Package selecthost handles host discovery via DNS SRV records, keeps track of healthy and selects the most optimal host for use.
An HTTP Transport is provided which simplifies using this package with any http client.
Index ¶
- Variables
- func JoinHostPort(host string, port string) string
- func NewTransport(selector *Selector, base http.RoundTripper) http.RoundTripper
- type Host
- type Hosts
- type Option
- func CheckConcurrency(count int) Option
- func CheckCount(count int) Option
- func CheckDelay(delay time.Duration) Option
- func CheckInterval(interval time.Duration) Option
- func CheckPath(path string) Option
- func CheckScheme(scheme string) Option
- func CheckTimeout(timeout time.Duration) Option
- func DiscoveryInterval(interval time.Duration) Option
- func Fallback(host string) Option
- func Logger(logger *zap.SugaredLogger) Option
- func Optional() Option
- func Prefer(host string) Option
- func Quick() Option
- type Results
- type Selector
- type Transport
Constants ¶
This section is empty.
Variables ¶
var ( // ErrSelectHost is the root error for all SelectHost errors ErrSelectHost = errors.New("SelectHost Error") // ErrSelectorStopped is returned when waiting for a host but the selector has been stopped. ErrSelectorStopped = fmt.Errorf("%w: selector stopped", ErrSelectHost) // ErrHostNotFound is returned when a host is not able to be determined. ErrHostNotFound = fmt.Errorf("%w: no host found", ErrSelectHost) // ErrWaitTimedout is returned when waiting for a host to be discovered. ErrWaitTimedout = fmt.Errorf("%w: timed out waiting for host", ErrSelectHost) // ErrDiscoveryTimeout is returned when the discovery process takes longer than configured timeout. ErrDiscoveryTimeout = fmt.Errorf("%w: discovery process timed out: %w", ErrSelectHost, context.DeadlineExceeded) // ErrHostCheckTimedout is returned when the host check process takes longer than configured timeout. ErrHostCheckTimedout = fmt.Errorf("%w: host check timed out: %w", ErrSelectHost, context.DeadlineExceeded) )
var ( // ErrHostRemoved is set on a host if it no longer exists in the discovered hosts. ErrHostRemoved = fmt.Errorf("%w: host removed", ErrSelectHost) )
var ( // ErrUnexpectedStatusCode is returned when a check request doesn't have 2xx status code. ErrUnexpectedStatusCode = fmt.Errorf("%w: unexpected status code", ErrSelectHost) )
Functions ¶
func JoinHostPort ¶
JoinHostPort combines host and port into a network address of the form "host:port". If host contains a colon, as found in literal IPv6 addresses, then JoinHostPort returns "[host]:port". If port is not defined, port is left out.
func NewTransport ¶
func NewTransport(selector *Selector, base http.RoundTripper) http.RoundTripper
NewTransport initialized a new Transport with the provided selector and base transport. If base is nil, the default http transport is used.
Types ¶
type Host ¶
type Host interface {
ID() string
Record() net.SRV
Host() string
Port() string
Before(h2 Host) bool
LastCheck() Results
AverageDuration() time.Duration
Err() error
// contains filtered or unexported methods
}
Host is an individual host entry.
type Option ¶
Option defines a selector option.
func CheckConcurrency ¶
CheckConcurrency defines the number of hosts which may be checked simultaneously. Default: 5
func CheckCount ¶
CheckCount defines how many checks to run on an endpoint. Default: 5
func CheckDelay ¶
CheckDelay specifies how long to wait between subsequent checks for the same host. Default: 200ms
func CheckInterval ¶
CheckInterval specifies how frequently to run host checks. Default: 1m.
func CheckScheme ¶
CheckScheme sets the uri scheme. Default is http unless discovered port is 443, https will be used then.
func CheckTimeout ¶
CheckTimeout defines the maximum time an individual check request can take. Default: 2s
func DiscoveryInterval ¶
DiscoveryInterval specifies the interval at which SRV records will be rediscovered. Default: 15m
func Fallback ¶
Fallback specifies a fallback host if no hosts are discovered or all hosts are currently failing.
func Optional ¶
func Optional() Option
Optional if no SRV record is found, the target (or fallback address) is used instead. The discovery process continues to run in the chance that SRV records are added at a later point.
type Results ¶
type Results struct {
Time time.Time
Host Host
Checks uint
TotalDuration time.Duration
Errors []error
}
Results holds host check results.
type Selector ¶
type Selector struct {
// contains filtered or unexported fields
}
Selector handles discovering SRV records, periodically polling and selecting the fastest responding endpoint.
func NewSelector ¶
NewSelector creates a new selector service handler. The target provided is automatically registered as the default fallback address.
func (*Selector) GetHost ¶
GetHost returns the active host. If the selector has not been started before, the selector is initialized. This method will block until a host is selected, initialization timeout is reached or the context is canceled.
type Transport ¶
type Transport struct {
Selector *Selector
Base http.RoundTripper
}
Transport implements http.RoundTripper handles switching the request host to a discovered host.
func (*Transport) RoundTrip ¶
RoundTrip implements http.RoundTripper. If the request host matches the selector service's target, the host is replaced with the selected host address. If the request does not match, the base transport is called for the request instead.
When the selected host is used, if the result from the base transport returns an error, the selected host is marked as having that error and a new host is immediately selected. The request however is not retried, instead the requestor must retry when appropriate.
Hosts marked with an error will get cleared upon the next successful host check cycle.
Source Files