balancer

README

balancer   

Connection balancer library for Go

To install:

go get github.com/getlantern/balancer

For docs:

godoc github.com/getlantern/balancer

Documentation

Overview

package balancer provides weighted round-robin load balancing of network connections with the ability to specify quality of service (QOS) levels.

Index

• type Balancer
  • func New(dialers ...*Dialer) *Balancer
  • func (b *Balancer) AllAuthTokens() []string
  • func (b *Balancer) Close()
  • func (b *Balancer) Dial(network, addr string) (net.Conn, error)
  • func (b *Balancer) DialQOS(network, addr string, targetQOS int) (net.Conn, error)
• type Dialer

Types

type Balancer

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

Balancer balances connections established by one or more Dialers.

func New

func New(dialers ...*Dialer) *Balancer

New creates a new Balancer using the supplied Dialers.

func (*Balancer) AllAuthTokens

func (b *Balancer) AllAuthTokens() []string

AllAuthTokens() returns a list of all auth tokens for all dialers on this balancer.

func (*Balancer) Close

func (b *Balancer) Close()

Close closes this Balancer, stopping all background processing. You must call Close to avoid leaking goroutines.

func (*Balancer) Dial

func (b *Balancer) Dial(network, addr string) (net.Conn, error)

Dial is like DialQOS with a targetQOS of 0.

func (*Balancer) DialQOS

func (b *Balancer) DialQOS(network, addr string, targetQOS int) (net.Conn, error)

DialQOS dials network, addr using one of the currently active configured Dialers. It attempts to use a Dialer whose QOS is higher than targetQOS, but will use the highest QOS Dialer(s) if none meet targetQOS. When multiple Dialers meet the targetQOS, load is distributed amongst them randomly based on their relative Weights.

If a Dialer fails to connect, Dial will keep falling back through the remaining Dialers until it either manages to connect, or runs out of dialers in which case it returns an error.

type Dialer

type Dialer struct {
	// Label: optional label with which to tag this dialer for debug logging.
	Label string

	// Weight: determines how often this Dialer is used relative to the other
	// Dialers on the balancer.
	Weight int

	// QOS: identifies the quality of service provided by this dialer. Higher
	// numbers equal higher quality. "Quality" in this case is loosely defined,
	// but can mean things such as reliability, speed, etc.
	QOS int

	// Dial: this function dials the given network, addr.
	Dial func(network, addr string) (net.Conn, error)

	// OnClose: (optional) callback for when this dialer is stopped.
	OnClose func()

	// Check: (optional) - When dialing fails, this Dialer is deactivated (taken
	// out of rotation). Check is a function that's used periodically after a
	// failed dial to check whether or not Dial works again. As soon as there is
	// a successful check, this Dialer will be activated (put back in rotation).
	//
	// If Check is not specified, a default Check will be used that makes an
	// HTTP request to http://www.google.com/humans.txt using this Dialer.
	//
	// Checks are scheduled at exponentially increasing intervals that are
	// capped at 1 minute.
	Check func() bool

	// Determines wheter a dialer can be trusted with unencrypted traffic.
	Trusted bool

	AuthToken string
}

Dialer captures the configuration for dialing arbitrary addresses.