lb

Documentation

Index

• type GeoLocator
  • func NewSimpleGeoLocator() GeoLocator
• type HealthCheckConfig
  • func DefaultHealthCheckConfig() HealthCheckConfig
• type HealthChecker
  • func NewHealthChecker(config HealthCheckConfig, balancer LoadBalancer) HealthChecker
• type LoadBalancer
  • func NewConsistentHashBalancer(replicas int, store NodeStore) LoadBalancer
  • func NewGeoProximityBalancer(locator GeoLocator, fallback LoadBalancer, store NodeStore) LoadBalancer
  • func NewLeastConnectionsBalancer(store NodeStore) LoadBalancer
  • func NewStickyLoadBalancer(ttl time.Duration, fallback LoadBalancer, store SessionStore) LoadBalancer
• type LoadBalancerConfig
  • func DefaultLoadBalancerConfig() LoadBalancerConfig
• type NodeHealth
• type NodeInfo
• type NodeStore
  • func NewInMemoryNodeStore() NodeStore
• type SessionStore
  • func NewInMemorySessionStore() SessionStore
• type StickySessionConfig
• type Strategy

Types

type GeoLocator

type GeoLocator interface {
	// GetLocation returns lat/long for user/IP
	GetLocation(ctx context.Context, userID string, metadata map[string]any) (lat, long float64, err error)
}

GeoLocator determines geographic location.

func NewSimpleGeoLocator

func NewSimpleGeoLocator() GeoLocator

NewSimpleGeoLocator creates a simple geo locator.

type HealthCheckConfig

type HealthCheckConfig struct {
	Enabled       bool
	Interval      time.Duration
	Timeout       time.Duration
	FailThreshold int
	PassThreshold int
}

HealthCheckConfig configures health checking.

func DefaultHealthCheckConfig

func DefaultHealthCheckConfig() HealthCheckConfig

DefaultHealthCheckConfig returns default health check configuration.

type HealthChecker

type HealthChecker interface {
	// Check performs health check
	Check(ctx context.Context, node *NodeInfo) error

	// Start begins periodic health checks
	Start(ctx context.Context)

	// Stop stops health checks
	Stop(ctx context.Context)

	// RegisterNode adds node to health monitoring
	RegisterNode(node *NodeInfo)

	// UnregisterNode removes node from health monitoring
	UnregisterNode(nodeID string)
}

HealthChecker performs health checks on nodes.

func NewHealthChecker

func NewHealthChecker(config HealthCheckConfig, balancer LoadBalancer) HealthChecker

NewHealthChecker creates a health checker.

type LoadBalancer

type LoadBalancer interface {
	// SelectNode chooses node for new connection
	SelectNode(ctx context.Context, userID string, metadata map[string]any) (*NodeInfo, error)

	// GetNode returns node for existing connection
	GetNode(ctx context.Context, connID string) (*NodeInfo, error)

	// RegisterNode adds node to pool
	RegisterNode(ctx context.Context, node *NodeInfo) error

	// UnregisterNode removes node
	UnregisterNode(ctx context.Context, nodeID string) error

	// Health checks node health
	Health(ctx context.Context, nodeID string) error

	// GetNodes returns all registered nodes
	GetNodes(ctx context.Context) ([]*NodeInfo, error)

	// GetHealthyNodes returns only healthy nodes
	GetHealthyNodes(ctx context.Context) ([]*NodeInfo, error)
}

LoadBalancer selects nodes for connections.

func NewConsistentHashBalancer

func NewConsistentHashBalancer(replicas int, store NodeStore) LoadBalancer

NewConsistentHashBalancer creates a consistent hash load balancer.

func NewGeoProximityBalancer

func NewGeoProximityBalancer(locator GeoLocator, fallback LoadBalancer, store NodeStore) LoadBalancer

NewGeoProximityBalancer creates a geographic proximity load balancer.

func NewLeastConnectionsBalancer

func NewLeastConnectionsBalancer(store NodeStore) LoadBalancer

NewLeastConnectionsBalancer creates a least connections load balancer.

func NewStickyLoadBalancer

func NewStickyLoadBalancer(ttl time.Duration, fallback LoadBalancer, store SessionStore) LoadBalancer

NewStickyLoadBalancer creates a sticky session load balancer.

type LoadBalancerConfig

type LoadBalancerConfig struct {
	Strategy      Strategy
	HealthCheck   HealthCheckConfig
	StickySession StickySessionConfig
}

LoadBalancerConfig configures load balancing.

func DefaultLoadBalancerConfig

func DefaultLoadBalancerConfig() LoadBalancerConfig

DefaultLoadBalancerConfig returns default configuration.

type NodeHealth

type NodeHealth struct {
	NodeID            string
	Healthy           bool
	LastCheck         time.Time
	ConsecutiveFails  int
	ConsecutivePasses int
	TotalFailures     int
}

NodeHealth represents node health status.

type NodeInfo

type NodeInfo struct {
	ID       string
	Address  string
	Port     int
	Weight   int
	Metadata map[string]any

	// Geographic info
	Region    string
	Zone      string
	Latitude  float64
	Longitude float64

	// Health info
	Healthy         bool
	LastHealthCheck time.Time
	FailureCount    int

	// Load info
	ConnectionCount int
	CPU             float64
	Memory          float64
}

NodeInfo represents a server node.

type NodeStore

type NodeStore interface {
	// Save stores node info
	Save(ctx context.Context, node *NodeInfo) error

	// Get retrieves node info
	Get(ctx context.Context, nodeID string) (*NodeInfo, error)

	// List lists all nodes
	List(ctx context.Context) ([]*NodeInfo, error)

	// Delete removes node
	Delete(ctx context.Context, nodeID string) error

	// UpdateHealth updates node health status
	UpdateHealth(ctx context.Context, nodeID string, healthy bool) error

	// UpdateConnectionCount updates connection count
	UpdateConnectionCount(ctx context.Context, nodeID string, count int) error
}

NodeStore persists node information.

func NewInMemoryNodeStore

func NewInMemoryNodeStore() NodeStore

NewInMemoryNodeStore creates an in-memory node store.

type SessionStore

type SessionStore interface {
	// Set creates session affinity
	Set(ctx context.Context, userID, nodeID string, ttl time.Duration) error

	// Get retrieves session affinity
	Get(ctx context.Context, userID string) (string, error)

	// Delete removes session affinity
	Delete(ctx context.Context, userID string) error
}

SessionStore persists session affinity.

func NewInMemorySessionStore

func NewInMemorySessionStore() SessionStore

NewInMemorySessionStore creates an in-memory session store.

type StickySessionConfig

type StickySessionConfig struct {
	Enabled    bool
	TTL        time.Duration
	CookieName string
}

StickySessionConfig configures sticky sessions.

type Strategy

type Strategy string

Strategy defines load balancing strategy.

const (
	StrategyRoundRobin       Strategy = "round_robin"
	StrategyLeastConnections Strategy = "least_connections"
	StrategyConsistentHash   Strategy = "consistent_hash"
	StrategySticky           Strategy = "sticky"
	StrategyWeighted         Strategy = "weighted"
	StrategyGeoProximity     Strategy = "geo_proximity"
)