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 balancing strategies are implemented on top of publishers. Go kit currently provides random and round-robin semantics. Smarter behaviors, e.g. load balancing based on underlying endpoint priority/weight, is planned.

Rationale

TODO

Usage

In your client, define a publisher, wrap it with a balancing strategy, and pass it to a retry strategy, which returns an endpoint. Use that endpoint to make requests, or wrap it with other value-add middleware.

func main() {
	var (
		fooPublisher = loadbalancer.NewDNSSRVPublisher("foo.mynet.local", 5*time.Second, makeEndpoint)
		fooBalancer  = loadbalancer.RoundRobin(mysvcPublisher)
		fooEndpoint  = loadbalancer.Retry(3, time.Second, fooBalancer)
	)
	http.HandleFunc("/", handle(fooEndpoint))
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func makeEndpoint(hostport string) endpoint.Endpoint {
	// Convert a host:port to a endpoint via your defined transport.
}

func handle(foo endpoint.Endpoint) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// foo is usable as a load-balanced remote endpoint.
	}
}

Documentation

Index

• Variables
• func Retry(max int, timeout time.Duration, lb LoadBalancer) endpoint.Endpoint
• type LoadBalancer
  • func Random(p Publisher) LoadBalancer
  • func RoundRobin(p Publisher) LoadBalancer
• type Publisher
  • func NewDNSSRVPublisher(name string, ttl time.Duration, ...) Publisher
• type StaticPublisher
  • func NewStaticPublisher(endpoints []endpoint.Endpoint) *StaticPublisher
  • func (p *StaticPublisher) Replace(endpoints []endpoint.Endpoint)
  • func (p *StaticPublisher) Stop()
  • func (p *StaticPublisher) Subscribe(c chan<- []endpoint.Endpoint)
  • func (p *StaticPublisher) Unsubscribe(c chan<- []endpoint.Endpoint)
• type Strategy

Variables

var ErrNoEndpoints = errors.New("no endpoints available")

ErrNoEndpoints is returned by a strategy when there are no endpoints available.

var ErrNoEndpointsAvailable = errors.New("no endpoints available")

ErrNoEndpointsAvailable is given by a load balancer when no endpoints are available to be returned.

Functions

func Retry

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

Retry yields an endpoint that takes endpoints from the load balancer. Invocations that return errors will be retried until they succeed, up to max times, or until the timeout is elapsed, whichever comes first.

Types

type LoadBalancer

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

LoadBalancer yields endpoints one-by-one.

func Random

func Random(p Publisher) LoadBalancer

Random returns a load balancer that yields random endpoints.

func RoundRobin

func RoundRobin(p Publisher) LoadBalancer

RoundRobin returns a load balancer that yields endpoints in sequence.

type Publisher

type Publisher interface {
	Subscribe(chan<- []endpoint.Endpoint)
	Unsubscribe(chan<- []endpoint.Endpoint)
	Stop()
}

Publisher produces endpoints.

func NewDNSSRVPublisher

func NewDNSSRVPublisher(name string, ttl time.Duration, makeEndpoint func(hostport string) endpoint.Endpoint) Publisher

NewDNSSRVPublisher returns a publisher that resolves the SRV name every ttl, and

type StaticPublisher

type StaticPublisher struct {
	// contains filtered or unexported fields
}

StaticPublisher holds a static set of endpoints.

func NewStaticPublisher

func NewStaticPublisher(endpoints []endpoint.Endpoint) *StaticPublisher

NewStaticPublisher returns a publisher that yields a static set of endpoints, which can be completely replaced.

func (*StaticPublisher) Replace

func (p *StaticPublisher) Replace(endpoints []endpoint.Endpoint)

Replace replaces the endpoints and notifies all subscribers.

func (*StaticPublisher) Stop

func (p *StaticPublisher) Stop()

Stop implements Publisher, but is a no-op.

func (*StaticPublisher) Subscribe

func (p *StaticPublisher) Subscribe(c chan<- []endpoint.Endpoint)

Subscribe implements Publisher.

func (*StaticPublisher) Unsubscribe

func (p *StaticPublisher) Unsubscribe(c chan<- []endpoint.Endpoint)

Unsubscribe implements Publisher.

type Strategy

type Strategy interface {
	Next() (endpoint.Endpoint, error)
	Stop()
}

Strategy yields endpoints to consumers according to some algorithm.