Documentation
¶
Overview ¶
Package balancer implements load balancing strategies for upstream selection.
Index ¶
- type Balancer
- type Grouped
- func (g *Grouped) Done(target string)
- func (g *Grouped) Next() string
- func (g *Grouped) NextKeyed(key string) string
- func (g *Grouped) SetFallback(enabled bool)
- func (g *Grouped) SwapGroupedTargets(groups map[string][]string)
- func (g *Grouped) SwapTargets(targets []string)
- func (g *Grouped) Targets() []string
- type KeyedBalancer
- type LeastConn
- type Random
- type RoundRobin
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Balancer ¶
type Balancer interface {
// Next returns the next target address.
// For connection-tracking strategies (e.g. LeastConn), this also
// marks the target as having one more active connection.
// Returns "" if the pool is empty.
Next() string
// Done signals that a request/connection to the given target has finished.
// This is a no-op for strategies that don't track active connections.
Done(target string)
// SwapTargets atomically replaces the target pool.
// Active connections tracked by Done() are reset.
SwapTargets(targets []string)
// Targets returns a copy of the current target pool.
Targets() []string
}
Balancer selects a target from a pool of upstreams.
type Grouped ¶
type Grouped struct {
// contains filtered or unexported fields
}
Grouped wraps a balancing strategy and provides per-key target pools. In flat mode (via SwapTargets), all requests use the inner balancer. In grouped mode (via SwapGroupedTargets), each key has its own sub-balancer.
When fallback is enabled, NextKeyed picks a random target from all groups if the requested key has no matching group (or the group is empty).
func NewGrouped ¶
NewGrouped creates a grouped balancer wrapping an inner flat balancer. The strategy name is used to create per-key sub-balancers.
func (*Grouped) Done ¶
Done decrements the active connection counter for the target. Checks grouped sub-balancers first, then falls back to the inner balancer.
func (*Grouped) Next ¶
Next delegates to the inner flat balancer. When the inner pool is empty and fallback is enabled, picks a random target from all grouped targets.
func (*Grouped) NextKeyed ¶
NextKeyed selects a target from the sub-pool matching the key. Falls back to the inner balancer if no groups are configured or key is empty. When fallback is enabled, picks a random target from all groups if the key has no matching group or the matched group's pool is empty.
func (*Grouped) SetFallback ¶ added in v0.35.0
SetFallback enables or disables random fallback across all groups. When enabled, NextKeyed picks a random target from all groups if the requested key has no matching group or the group pool is empty.
func (*Grouped) SwapGroupedTargets ¶
SwapGroupedTargets atomically replaces the per-key target pools. Existing sub-balancers for unchanged keys are reused (preserving connection tracking state for leastconn).
func (*Grouped) SwapTargets ¶
SwapTargets replaces the flat target pool and clears any grouped state.
type KeyedBalancer ¶
type KeyedBalancer interface {
Balancer
NextKeyed(key string) string
SwapGroupedTargets(groups map[string][]string)
}
KeyedBalancer extends Balancer with key-based target selection. Used by grouped balancers where the key (e.g., a domain wildcard capture) determines which sub-pool of targets to pick from.
type LeastConn ¶
type LeastConn struct {
// contains filtered or unexported fields
}
LeastConn routes to the target with the fewest active connections. When multiple targets share the minimum, the first one found is selected.
func NewLeastConn ¶
NewLeastConn creates a least-connections balancer.
func (*LeastConn) Conns ¶
Conns returns the current active connection count for a target. Intended for testing and diagnostics only.
func (*LeastConn) Next ¶
Next returns the target with the fewest active connections and atomically increments its counter.
func (*LeastConn) SwapTargets ¶
SwapTargets atomically replaces the target pool. Active connection counts are reset to zero.
type Random ¶
type Random struct {
// contains filtered or unexported fields
}
Random selects a target at random.
func (*Random) SwapTargets ¶
type RoundRobin ¶
type RoundRobin struct {
// contains filtered or unexported fields
}
RoundRobin distributes requests evenly across targets in order.
func NewRoundRobin ¶
func NewRoundRobin(targets []string) *RoundRobin
NewRoundRobin creates a round-robin balancer.
func (*RoundRobin) Done ¶
func (rr *RoundRobin) Done(string)
func (*RoundRobin) Next ¶
func (rr *RoundRobin) Next() string
func (*RoundRobin) SwapTargets ¶
func (rr *RoundRobin) SwapTargets(targets []string)
func (*RoundRobin) Targets ¶
func (rr *RoundRobin) Targets() []string
Source Files