cslb

README

cslb

Client-Side Load Balancer

This Project is in early developing state

Feature

• Multiple client-side load balancing solutions support
  • Round-Robin DNS
  • SRV DNS
  • Static Node List
• Multiple distributing strategies
  • Round-Robin
  • Weighted Round-Robin
  • Hashed
• Exile unhealthy node
• Node list TTL

Usage

Example:

package main

import (
	"log"
	
	"github.com/RangerCD/cslb"
)

func main() {
	lb := cslb.NewLoadBalancer(
		cslb.NewRRDNSService([]string{"example.com"}, true, true), 
		cslb.NewRoundRobinStrategy(),
	)

	log.Println(lb.Next()) // IP 1
	log.Println(lb.Next()) // IP 2
}

Documentation

Index

• Constants
• Variables
• func NewHashedStrategy(hashFunc HashFunc) *hashedStrategy
• func NewRRDNSService(hostnames []string, ipv4 bool, ipv6 bool) *rrDNSService
• func NewRoundRobinStrategy() *roundRobinStrategy
• func NewStaticService(nodes []Node) *staticService
• type Group
  • func NewGroup(maxNodeCount int) *Group
  • func (g *Group) Exile(node Node) bool
  • func (g *Group) Get() []Node
  • func (g *Group) GetCurrentCount() int64
  • func (g *Group) GetNode(key string) Node
  • func (g *Group) GetOriginalCount() int64
  • func (g *Group) Set(nodes []Node)
• type HashFunc
• type LoadBalancer
  • func NewLoadBalancer(service Service, strategy Strategy, option ...LoadBalancerOption) *LoadBalancer
  • func (lb *LoadBalancer) Next() (Node, error)
  • func (lb *LoadBalancer) NextFor(input interface{}) (Node, error)
  • func (lb *LoadBalancer) NodeFailed(node Node)
• type LoadBalancerOption
• type Metrics
  • func NewMetrics(maxNodeFailedRatio float64, minSampleSize int) *Metrics
  • func (m *Metrics) GetNodeFailedRatio(node Node) (float64, error)
  • func (m *Metrics) NodeFailedInc(node Node)
  • func (m *Metrics) NodeInc(node Node)
  • func (m *Metrics) ResetAllNodes()
  • func (m *Metrics) ResetNode(node Node)
• type Node
• type Service
• type Strategy

Constants

const (
	NodeFailedKey = "node-failed."
	RefreshKey    = "refresh"
)

const (
	TTLUnlimited time.Duration = math.MaxInt64 // Never expire
	TTLNone      time.Duration = 0             // Refresh after every Next()

	HealthyNodeMustAll float64 = 1.0
	HealthyNodeAny     float64 = 0.0

	NodeFailedUnlimited float64 = 1.0
	NodeFailedAny       float64 = 0.0
)

const (
	DefaultMinSampleSize = 10
)

const (
	NodeCountUnlimited = (1<<bits.UintSize)/2 - 1
)

Variables

var (
	SampleNotEnoughError = errors.New("sample not enough")
	InvalidRatioError    = errors.New("invalid ratio error")
)

var (
	DefaultLoadBalancerOption = LoadBalancerOption{
		MaxNodeCount:        NodeCountUnlimited,
		TTL:                 TTLUnlimited,
		MinHealthyNodeRatio: HealthyNodeAny,
		MaxNodeFailedRatio:  NodeFailedUnlimited,
		MinSampleSize:       DefaultMinSampleSize,
	}
)

Functions

func NewHashedStrategy

func NewHashedStrategy(hashFunc HashFunc) *hashedStrategy

func NewRRDNSService

func NewRRDNSService(hostnames []string, ipv4 bool, ipv6 bool) *rrDNSService

NewRRDNSService is for Round-robin DNS load balancing solution. Usually multiple A or AAAA records are associated with single hostname. Node type: *net.IPAddr

For example:

Hostname www.a.com
  |- A 1.2.3.4
  |- A 2.3.4.5
  |- A 3.4.5.6
  ...

Everytime a client wants to send a request, one of these A records will be chosen to establish connection.

func NewRoundRobinStrategy

func NewRoundRobinStrategy() *roundRobinStrategy

func NewStaticService

func NewStaticService(nodes []Node) *staticService

NewStaticService represents a simple static list of Node Node type: node.Node

Types

type Group

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

func NewGroup

func NewGroup(maxNodeCount int) *Group

func (*Group) Exile

func (g *Group) Exile(node Node) bool

func (*Group) Get

func (g *Group) Get() []Node

func (*Group) GetCurrentCount

func (g *Group) GetCurrentCount() int64

func (*Group) GetNode

func (g *Group) GetNode(key string) Node

func (*Group) GetOriginalCount

func (g *Group) GetOriginalCount() int64

func (*Group) Set

func (g *Group) Set(nodes []Node)

type HashFunc

type HashFunc func(interface{}) (uint64, error)

type LoadBalancer

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

func NewLoadBalancer

func NewLoadBalancer(service Service, strategy Strategy, option ...LoadBalancerOption) *LoadBalancer

func (*LoadBalancer) Next

func (lb *LoadBalancer) Next() (Node, error)

func (*LoadBalancer) NextFor

func (lb *LoadBalancer) NextFor(input interface{}) (Node, error)

func (*LoadBalancer) NodeFailed

func (lb *LoadBalancer) NodeFailed(node Node)

type LoadBalancerOption

type LoadBalancerOption struct {
	// LoadBalancer will keep MaxNodeCount nodes in Next() result set
	// Please notice that refresh or exile will change the result set
	// Number of connections might be greater than this value, if any pre-connected node has been excluded in newer
	// result set, but no new connection will be established to these nodes
	MaxNodeCount int

	// Cache TTL
	TTL time.Duration

	// Refresh when healthy node ratio is below MinHealthyNodeRatio
	MinHealthyNodeRatio float64

	// Node will be exiled if (failed / total) > MaxNodeFailedRatio
	MaxNodeFailedRatio float64

	// At least MinSampleSize times a node has been returned through Next(), this node can be count for exile.
	MinSampleSize int
}

type Metrics

type Metrics struct {
	MinSampleSize int
	// contains filtered or unexported fields
}

func NewMetrics

func NewMetrics(maxNodeFailedRatio float64, minSampleSize int) *Metrics

NewMetrics initializes a Metrics instance, it might return nil if it's unnecessary or invalid

func (*Metrics) GetNodeFailedRatio

func (m *Metrics) GetNodeFailedRatio(node Node) (float64, error)

func (*Metrics) NodeFailedInc

func (m *Metrics) NodeFailedInc(node Node)

func (*Metrics) NodeInc

func (m *Metrics) NodeInc(node Node)

func (*Metrics) ResetAllNodes

func (m *Metrics) ResetAllNodes()

func (*Metrics) ResetNode

func (m *Metrics) ResetNode(node Node)

type Node

type Node interface {
	fmt.Stringer
}

type Service

type Service interface {
	// Nodes returns a new slice of available node
	Nodes() []Node
	// Refresh updates nodes
	Refresh()
	// NodeFailedCallbackFunc returns a callback function which will be triggered in another go routine when certain
	// node exiled by LoadBalancer
	NodeFailedCallbackFunc() func(node Node)
}

Service represents a group of nodes provide identical functionality, cluster as a logical service This type should be thread safe

type Strategy

type Strategy interface {
	// SetNodes update saved nodes
	SetNodes(nodes []Node)
	// Next returns a node address
	Next() (Node, error)
	// NextFor returns a node address assigned to request
	NextFor(interface{}) (Node, error)
}

Strategy controls how the nodes are chosen This type should be thread safe