loadbalancer

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 := dnssrv.NewPublisher("foosvc.internal.domain", 5*time.Second, fooFactory, logger)
	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

• Variables
• func Retry(max int, timeout time.Duration, lb LoadBalancer) endpoint.Endpoint
• type Factory
• type LoadBalancer
• type Publisher
• type Random
  • func NewRandom(p Publisher, seed int64) *Random
  • func (r *Random) Endpoint() (endpoint.Endpoint, error)
• type RoundRobin
  • func NewRoundRobin(p Publisher) *RoundRobin
  • func (rr *RoundRobin) Endpoint() (endpoint.Endpoint, error)

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.

var ErrPublisherStopped = errors.New("publisher stopped")

ErrPublisherStopped is returned by publishers when the underlying implementation has been terminated and can no longer serve requests.

Functions

func Retry

func Retry(max int, timeout time.Duration, lb LoadBalancer) endpoint.Endpoint

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 Factory

type Factory func(instance string) (endpoint.Endpoint, error)

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

type LoadBalancer interface {
	Endpoint() (endpoint.Endpoint, error)
}

LoadBalancer describes something that can yield endpoints for a remote service method.

type Publisher

type Publisher interface {
	Endpoints() ([]endpoint.Endpoint, error)
}

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.

func NewRandom

func NewRandom(p Publisher, seed int64) *Random

NewRandom returns a new Random load balancer.

func (*Random) Endpoint

func (r *Random) Endpoint() (endpoint.Endpoint, error)

Endpoint implements the LoadBalancer interface.

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.

func (*RoundRobin) Endpoint

func (rr *RoundRobin) Endpoint() (endpoint.Endpoint, error)

Endpoint implements the LoadBalancer interface.