cluster

Documentation

Overview

Package cluster provides an elastic peer discovery and gossip layer. Proposer and acceptor nodes join the same cluster and know about each other.

Index

• func CalculateAdvertiseIP(bindHost, advertiseHost string, resolver Resolver, logger log.Logger) (net.IP, error)
• func ParseAddr(addr string, defaultPort int) (network, address, host string, port int, err error)
• type HostPorts
  • func CalculateHostPorts(bindAddr, advertiseAddr string, defaultClusterPort int, clusterPeers []string, ...) (res HostPorts, err error)
• type NodeType
• type Peer
  • func NewPeer(bindAddr string, bindPort int, advertiseAddr string, advertisePort int, ...) (*Peer, error)
  • func (p *Peer) ClusterSize() int
  • func (p *Peer) Current(t NodeType) []string
  • func (p *Peer) Leave(timeout time.Duration) error
  • func (p *Peer) Name() string
  • func (p *Peer) State() map[string]interface{}
• type Resolver

Functions

func CalculateAdvertiseIP

func CalculateAdvertiseIP(bindHost, advertiseHost string, resolver Resolver, logger log.Logger) (net.IP, error)

CalculateAdvertiseIP deduces the best IP on which to advertise our API based on a user-provided bind host and advertise host. This code lifts some logic out of the memberlist internals, and augments it with extra logic to resolve hostnames. (Memberlist demands pure IPs.)

func ParseAddr

func ParseAddr(addr string, defaultPort int) (network, address, host string, port int, err error)

ParseAddr liberally accepts a wide variety of addr formats, along with a default port, and returns a well-defined network, address, host, and port.

"udp://host:1234", 80 => udp, host:1234, host, 1234
"host:1234", 80       => tcp, host:1234, host, 1234
"host", 80            => tcp, host:80,   host, 80

Types

type HostPorts

type HostPorts struct {
	BindHost      string
	BindPort      int
	AdvertiseHost string
	AdvertisePort int
}

HostPorts are deduced via CalculateHostPorts.

func CalculateHostPorts

func CalculateHostPorts(bindAddr, advertiseAddr string, defaultClusterPort int, clusterPeers []string, logger log.Logger) (res HostPorts, err error)

CalculateHostPorts will take a user-specified cluster bind address (required) and explicit advertise address (optional), along with a default port for cluster communications (required) and a set of cluster peer host:ports (optional), and deduce the best concrete hosts and ports to bind to and advertise within the cluster, suitable for passing to memberlist. We also figures out some notices and warnings along the way, and log them to the passed logger.

type NodeType

type NodeType string

NodeType enumerates the types of nodes in the cluster.

const (
	// NodeTypeProposer is a proposer node.
	NodeTypeProposer NodeType = "proposer"

	// NodeTypeAcceptor is an acceptor node.
	NodeTypeAcceptor NodeType = "acceptor"
)

type Peer

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

Peer represents this node in the cluster.

func NewPeer

func NewPeer(
	bindAddr string, bindPort int,
	advertiseAddr string, advertisePort int,
	existing []string,
	t NodeType, apiPort int,
	logger log.Logger,
) (*Peer, error)

NewPeer creates or joins a cluster with the existing peers. We will listen for cluster communications on the bind addr:port. We advertise a NodeType API, reachable on apiPort.

If advertiseAddr is not empty, we will advertise ourself as reachable for cluster communications on that address; otherwise, memberlist will extract the IP from the bound addr:port and advertise on that.

func (*Peer) ClusterSize

func (p *Peer) ClusterSize() int

ClusterSize returns the total size of the cluster from this node's perspective.

func (*Peer) Current

func (p *Peer) Current(t NodeType) []string

Current API host:ports for the given type of node.

func (*Peer) Leave

func (p *Peer) Leave(timeout time.Duration) error

Leave the cluster, waiting up to timeout.

func (*Peer) Name

func (p *Peer) Name() string

Name returns the unique ID of this peer in the cluster.

func (*Peer) State

func (p *Peer) State() map[string]interface{}

State returns a JSON-serializable dump of cluster state. Useful for debug.

type Resolver

type Resolver interface {
	LookupIPAddr(ctx context.Context, address string) ([]net.IPAddr, error)
}

Resolver models net.DefaultResolver.