README
¶
package loadbalancer
package loadbalancer provides a client-side load balancer abstraction.
A publisher is responsible for emitting the most recent set of endpoints for a single logical service. Publishers exist for static endpoints, and endpoints discovered via periodic DNS SRV lookups on a single logical name. Consul and etcd publishers are planned.
Different load balancers are implemented on top of publishers. Go kit currently provides random and round-robin load balancers. Smarter behaviors, e.g. load balancing based on underlying endpoint priority/weight, is planned.
Rationale
TODO
Usage
In your client, construct a publisher for a specific remote service, and pass it to a load balancer. Then, request an endpoint from the load balancer whenever you need to make a request to that remote service.
import (
"github.com/go-kit/kit/loadbalancer"
"github.com/go-kit/kit/loadbalancer/dnssrv"
)
func main() {
// Construct a load balancer for foosvc, which gets foosvc instances by
// polling a specific DNS SRV name.
p, err := dnssrv.NewPublisher("foosvc.internal.domain", 5*time.Second, fooFactory, logger)
if err != nil {
panic(err)
}
lb := loadbalancer.NewRoundRobin(p)
// Get a new endpoint from the load balancer.
endpoint, err := lb.Endpoint()
if err != nil {
panic(err)
}
// Use the endpoint to make a request.
response, err := endpoint(ctx, request)
}
func fooFactory(instance string) (endpoint.Endpoint, error) {
// Convert an instance (host:port) to an endpoint, via a defined transport binding.
}
It's also possible to wrap a load balancer with a retry strategy, so that it can be used as an endpoint directly. This may make load balancers more convenient to use, at the cost of fine-grained control of failures.
func main() {
p := dnssrv.NewPublisher("foosvc.internal.domain", 5*time.Second, fooFactory, logger)
lb := loadbalancer.NewRoundRobin(p)
endpoint := loadbalancer.Retry(3, 5*time.Seconds, lb)
response, err := endpoint(ctx, request) // requests will be automatically load balanced
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoEndpoints = errors.New("no endpoints available")
ErrNoEndpoints is returned when a load balancer (or one of its components) has no endpoints to return. In a request lifecycle, this is usually a fatal error.
Functions ¶
func Retry ¶
Retry wraps the load balancer to make it behave like a simple endpoint. Requests to the endpoint will be automatically load balanced via the load balancer. Requests that return errors will be retried until they succeed, up to max times, or until the timeout is elapsed, whichever comes first.
Types ¶
type EndpointCache ¶
type EndpointCache struct {
// contains filtered or unexported fields
}
EndpointCache caches endpoints that need to be deallocated when they're no longer useful. Clients update the cache by providing a current set of instance strings. The cache converts each instance string to an endpoint and a closer via the factory function.
Instance strings are assumed to be unique and are used as keys. Endpoints that were in the previous set of instances and are not in the current set are considered invalid and closed.
EndpointCache is designed to be used in your publisher implementation.
func NewEndpointCache ¶
func NewEndpointCache(f Factory, logger log.Logger) *EndpointCache
NewEndpointCache produces a new EndpointCache, ready for use. Instance strings will be converted to endpoints via the provided factory function. The logger is used to log errors.
func (*EndpointCache) Endpoints ¶
func (t *EndpointCache) Endpoints() ([]endpoint.Endpoint, error)
Endpoints returns the current set of endpoints in undefined order. Satisfies Publisher interface.
func (*EndpointCache) Replace ¶
func (t *EndpointCache) Replace(instances []string)
Replace replaces the current set of endpoints with endpoints manufactured by the passed instances. If the same instance exists in both the existing and new sets, it's left untouched.
type Factory ¶
Factory is a function that converts an instance string, e.g. a host:port, to a usable endpoint. Factories are used by load balancers to convert instances returned by Publishers (typically host:port strings) into endpoints. Users are expected to provide their own factory functions that assume specific transports, or can deduce transports by parsing the instance string.
type LoadBalancer ¶
LoadBalancer describes something that can yield endpoints for a remote service method.
type Publisher ¶
Publisher describes something that provides a set of identical endpoints. Different publisher implementations exist for different kinds of service discovery systems.
type Random ¶
type Random struct {
// contains filtered or unexported fields
}
Random is a completely stateless load balancer that chooses a random endpoint to return each time.
type RoundRobin ¶
type RoundRobin struct {
// contains filtered or unexported fields
}
RoundRobin is a simple load balancer that returns each of the published endpoints in sequence.
func NewRoundRobin ¶
func NewRoundRobin(p Publisher) *RoundRobin
NewRoundRobin returns a new RoundRobin load balancer.
Source Files
Directories