balancers

package module

v1.0.1 Latest Latest Go to latest Published: Jun 13, 2019 License: MIT Imports: 7 Imported by: 0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/olivere/balancers

Links

Open Source Insights

README ¶

Balancers

Balancers provides implementations of HTTP load-balancers.

What does it do?

Balancers gives you a http.Client from net/http that rewrites your requests' scheme, host, and userinfo according to the rules of a balancer. A balancer is simply an algorithm to pick the host for the next request a http.Client.

How does it work?

Suppose you have a cluster of two servers (on two different URLs) and you want to load balance between them. A very simple implementation can be done with the round-robin scheduling algorithm. Round-robin iterates through the list of available hosts and restarts at the first when the end is reached. Here's some code that illustrates that:

// Get a balancer that performs round-robin scheduling between two servers.
balancer, err := roundrobin.NewBalancerFromURL("https://server1.com", "https://server2.com")

// Get a HTTP client based on that balancer.
client := balancers.NewClient(balancer)

// Now request some data. The scheme, host, and user info will be rewritten
// by the balancer; you'll never get data from http://example.com, only data
// from http://server1.com or http://server2.com.
client.Get("http://example.com/path1?foo=bar") // rewritten to https://server1.com/path1?foo=bar
client.Get("http://example.com/path1?foo=bar") // rewritten to https://server2.com/path1?foo=bar
client.Get("http://example.com/path1?foo=bar") // rewritten to https://server1.com/path1?foo=bar
client.Get("/path1?foo=bar")                   // rewritten to https://server2.com/path1?foo=bar

Status

The current state of Balancers is a proof-of-concept. It didn't touch production systems yet.

Credits

Thanks a lot for the great folks working on Go.

LICENSE

MIT-LICENSE. See LICENSE or the LICENSE file provided in the repository for details.

Documentation ¶

Overview ¶

Package balancers provides implementations of HTTP load-balancers.

It has two key interfaces: A Balancer is the implementation of a load-balancer that chooses from a set of Connections.

You can e.g. use the balancer from the roundrobin package to rewrite HTTP requests and use URLs from a given set of HTTP connections.

Suppose you have a cluster of two servers (on two different URLs) and you want to load-balance between the two in a round-robin fashion, you can use code like this:

balancer, err := roundrobin.NewBalancerFromURL("https://server1.com", "https://server2.com")
...
// Get a HTTP client for the roundrobin balancer.
client := balancer.Client()
...
client.Get("http://example.com/path1?foo=bar") // will rewrite URL to https://server1.com/path1?foo=bar
client.Get("http://example.com/path1?foo=bar") // will rewrite URL to https://server2.com/path1?foo=bar
client.Get("http://example.com/path1?foo=bar") // will rewrite URL to https://server1.com/path1?foo=bar
client.Get("/path1?foo=bar") // will rewrite URL to https://server2.com/path1?foo=bar

Most of the code here is taken from the Google OAuth2 client library at https://github.com/golang/oauth2, especially https://github.com/golang/oauth2/blob/master/transport.go.

Index ¶

Constants
Variables
func NewClient(b Balancer) *http.Client
type Balancer
type Connection
type HttpConnection
- func NewHttpConnection(url *url.URL) *HttpConnection
type Transport
- func (t *Transport) CancelRequest(r *http.Request)
- func (t *Transport) RoundTrip(r *http.Request) (*http.Response, error)

Constants ¶

View Source

const (
	// Version is the current version of this package.
	Version = "1.0.0"
)

Variables ¶

View Source

var (
	// UserAgent is sent with all heartbeat requests.
	UserAgent = "balancers/" + Version + " (" + runtime.GOOS + "-" + runtime.GOARCH + ")"

	// DefaultHeartbeatDuration is the default time between heartbeat messages.
	DefaultHeartbeatDuration = 30 * time.Second
)

View Source

var ErrNoConn = errors.New("no connection")

ErrNoConn must be returned when a Balancer does not find a (non-broken) connection.

Functions ¶

func NewClient ¶

func NewClient(b Balancer) *http.Client

NewClient returns a http Client that applies a certain scheduling algorithm (like round-robin) to load balance between several HTTP servers.

Types ¶

type Balancer ¶

type Balancer interface {
	// Get returns a connection that can be used for the next request.
	Get() (Connection, error)

	// Connections is the list of available connections.
	Connections() []Connection
}

Balancer holds a list of connections to hosts.

type Connection ¶

type Connection interface {
	// URL to the host.
	URL() *url.URL
	// IsBroken must return true if the connection to URL is currently not available.
	IsBroken() bool
}

Connection is a single connection to a host. It is defined by a URL. It also maintains state in the form that a connection can be broken. TODO(oe) Not sure if this abstraction is necessary.

type HttpConnection ¶

type HttpConnection struct {
	sync.Mutex
	// contains filtered or unexported fields
}

HttpConnection is a HTTP connection to a host. It implements the Connection interface and can be used by balancer implementations.

func NewHttpConnection ¶

func NewHttpConnection(url *url.URL) *HttpConnection

NewHttpConnection creates a new HTTP connection to the given URL.

func (*HttpConnection) Close ¶

func (c *HttpConnection) Close() error

Close this connection.

func (*HttpConnection) HeartbeatDuration ¶

func (c *HttpConnection) HeartbeatDuration(d time.Duration) *HttpConnection

HeartbeatDuration sets the duration in which the connection is checked.

func (*HttpConnection) IsBroken ¶

func (c *HttpConnection) IsBroken() bool

IsBroken returns true if the HTTP connection is currently broken.

func (*HttpConnection) URL ¶

func (c *HttpConnection) URL() *url.URL

URL returns the URL of the HTTP connection.

type Transport ¶

type Transport struct {
	Base http.RoundTripper
	// contains filtered or unexported fields
}

Transport implements a http Transport for a HTTP load balancer.

func (*Transport) CancelRequest ¶

func (t *Transport) CancelRequest(r *http.Request)

CancelRequest cancels the given request (if canceling is available).

func (*Transport) RoundTrip ¶

func (t *Transport) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip is the core of the balancers package. It accepts a request, replaces host, scheme, and port with the URl provided by the balancer, executes it and returns the response to the caller.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
roundrobin

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL