Documentation
¶
Overview ¶
Package balancer provides client-side load balancing as HTTP middleware.
It distributes requests across multiple backend endpoints using pluggable strategies (round-robin, weighted, failover) with optional health checking.
Usage ¶
mw, closer := balancer.Transport(
[]balancer.Endpoint{
{URL: "http://backend1:8080"},
{URL: "http://backend2:8080"},
},
balancer.WithStrategy(balancer.RoundRobin()),
balancer.WithHealthCheck(5 * time.Second),
)
defer closer.Close()
transport := mw(http.DefaultTransport)
Strategies ¶
- RoundRobin — cycles through healthy endpoints
- Weighted — distributes based on endpoint Weight field
- Failover — prefers primary, falls back to secondaries
Health checking ¶
When enabled, a background goroutine periodically probes each endpoint. The returned Closer must be closed to stop the health checker goroutine. In httpx.Client, this is handled by Client.Close().
Sentinel errors ¶
ErrNoHealthy is returned when no healthy endpoints are available.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoHealthy = errors.New("httpx: no healthy endpoints available")
ErrNoHealthy is returned when no healthy endpoints are available.
Functions ¶
This section is empty.
Types ¶
type Closer ¶
type Closer struct {
// contains filtered or unexported fields
}
Closer can be used to shut down resources associated with a balancer transport (e.g. background health checker goroutines).
func Transport ¶
func Transport(endpoints []Endpoint, opts ...Option) (middleware.Middleware, *Closer)
Transport returns a middleware that load-balances requests across the provided endpoints using the configured strategy.
For each request the middleware picks an endpoint via the strategy, replaces the request URL scheme and host with the endpoint's URL, and forwards the request to the underlying RoundTripper.
If active health checking is enabled (WithHealthCheck), a background goroutine periodically probes endpoints. Otherwise all endpoints are assumed healthy.
type HealthChecker ¶
type HealthChecker struct {
// contains filtered or unexported fields
}
HealthChecker periodically probes endpoints to determine their health status.
func (*HealthChecker) Healthy ¶
func (h *HealthChecker) Healthy(endpoints []Endpoint) []Endpoint
Healthy returns the subset of endpoints that are currently healthy.
func (*HealthChecker) IsHealthy ¶
func (h *HealthChecker) IsHealthy(ep Endpoint) bool
IsHealthy reports whether the given endpoint is currently healthy.
func (*HealthChecker) Start ¶
func (h *HealthChecker) Start(endpoints []Endpoint)
Start begins the background health checking loop for the given endpoints. An initial probe is run synchronously so that unhealthy endpoints are detected before the first request.
func (*HealthChecker) Stop ¶
func (h *HealthChecker) Stop()
Stop terminates the background health checking goroutine and waits for it to finish.
type HealthOption ¶
type HealthOption func(*HealthChecker)
HealthOption configures the HealthChecker.
func WithHealthInterval ¶
func WithHealthInterval(d time.Duration) HealthOption
WithHealthInterval sets the interval between health check probes. Default is 10 seconds.
func WithHealthPath ¶
func WithHealthPath(path string) HealthOption
WithHealthPath sets the HTTP path to probe for health checks. Default is "/health".
func WithHealthTimeout ¶
func WithHealthTimeout(d time.Duration) HealthOption
WithHealthTimeout sets the timeout for each health check request. Default is 5 seconds.
type Option ¶
type Option func(*options)
Option configures the load balancer transport.
func WithHealthCheck ¶
func WithHealthCheck(opts ...HealthOption) Option
WithHealthCheck enables active health checking of endpoints.
func WithStrategy ¶
WithStrategy sets the endpoint selection strategy. If not specified, RoundRobin is used.
type Strategy ¶
Strategy selects an endpoint from the list of healthy endpoints.
func Failover ¶
func Failover() Strategy
Failover returns a strategy that always picks the first healthy endpoint. If the primary endpoint is unhealthy, it falls back to the next available healthy endpoint in order.
func RoundRobin ¶
func RoundRobin() Strategy
RoundRobin returns a strategy that cycles through healthy endpoints sequentially using an atomic counter.
func WeightedRandom ¶
func WeightedRandom() Strategy
WeightedRandom returns a strategy that selects endpoints randomly, weighted by each endpoint's Weight field. Endpoints with Weight <= 0 are treated as having a weight of 1.
Source Files