loadbalancer

Documentation

Overview

Package loadbalancer provides pluggable strategies for distributing requests across multiple GreptimeDB endpoints.

Index

• type HealthReporter
• type OutlierDetector
  • func NewOutlierDetector(opts OutlierDetectorOptions) *OutlierDetector
  • func (o *OutlierDetector) Pick(endpoints []string) string
  • func (o *OutlierDetector) ReportFailure(endpoint string)
  • func (o *OutlierDetector) ReportSuccess(endpoint string)
  • func (o *OutlierDetector) Select(endpoints []string, exclude map[string]struct{}) string
• type OutlierDetectorOptions
• type Picker
  • func NewRandom() Picker
  • func NewRoundRobin() Picker
• type Selector
  • func AsSelector(p Picker) Selector

Types

type HealthReporter

type HealthReporter interface {
	ReportSuccess(endpoint string)
	ReportFailure(endpoint string)
}

HealthReporter is an optional interface a Picker may implement to learn endpoint health from call outcomes. The client invokes ReportFailure on transport-level endpoint failures and ReportSuccess when an endpoint answers (including server business errors — the endpoint is alive and routing correctly). A healthy frontend must never be ejected for a datanode-side condition.

type OutlierDetector

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

OutlierDetector wraps a base Picker and removes endpoints that fail ConsecutiveFailures times in a row from the candidate set for a back-off window. Health is fed by ReportSuccess / ReportFailure from call outcomes. Ejection is time-based and re-admission is lazy (checked against the clock at Select time, no background timers). If every endpoint is ejected it falls open to the full set so writes never hard-stall on a transient cluster-wide failure. Safe for concurrent use.

A stateful detector instance keys health by endpoint address and must not be shared across clients configured with different endpoint sets.

func NewOutlierDetector

func NewOutlierDetector(opts OutlierDetectorOptions) *OutlierDetector

NewOutlierDetector returns a health-aware Selector with Envoy-style consecutive-failure outlier ejection.

func (*OutlierDetector) Pick

func (o *OutlierDetector) Pick(endpoints []string) string

Pick selects among the currently-healthy endpoints without exclusion.

func (*OutlierDetector) ReportFailure

func (o *OutlierDetector) ReportFailure(endpoint string)

ReportFailure records a transport-level failure for endpoint and ejects it once the consecutive-failure threshold is crossed.

func (*OutlierDetector) ReportSuccess

func (o *OutlierDetector) ReportSuccess(endpoint string)

ReportSuccess clears any failure streak for endpoint and re-admits it.

func (*OutlierDetector) Select

func (o *OutlierDetector) Select(endpoints []string, exclude map[string]struct{}) string

Select returns a healthy, non-excluded endpoint chosen by the base picker.

type OutlierDetectorOptions

type OutlierDetectorOptions struct {
	// Base chooses among the currently-healthy peers. Defaults to NewRandom().
	Base Picker
	// ConsecutiveFailures is the number of back-to-back endpoint failures
	// before an endpoint is ejected from selection. Defaults to 5.
	ConsecutiveFailures int
	// BaseEjection is the first ejection duration; it doubles on each
	// re-ejection up to MaxEjection. Defaults to 30s.
	BaseEjection time.Duration
	// MaxEjection caps a single ejection duration. Defaults to 300s.
	MaxEjection time.Duration
	// contains filtered or unexported fields
}

OutlierDetectorOptions configures NewOutlierDetector. Zero-value fields take the documented defaults.

type Picker

type Picker interface {
	Pick(endpoints []string) string
}

Picker selects one endpoint from the given slice per call. Implementations must be safe for concurrent use. Callers must pass a non-empty slice; behavior on an empty slice is undefined and the built-in pickers will panic.

func NewRandom

func NewRandom() Picker

NewRandom returns a stateless Picker that uniformly picks an endpoint at random on every call. This is the default strategy.

func NewRoundRobin

func NewRoundRobin() Picker

NewRoundRobin returns a Picker that rotates through endpoints in order. Safe for concurrent use via an atomic counter.

type Selector

type Selector interface {
	Select(endpoints []string, exclude map[string]struct{}) string
}

Selector picks one endpoint per call, honoring an exclude set so a retry loop can steer away from peers already tried and failed in the current sequence. Exclusion is best-effort: a selector must fall open to the full set rather than fail when every endpoint is excluded, because a retry against the least-bad peer beats no retry at all.

A Picker that also implements Selector is used directly by the client; otherwise AsSelector wraps it. NewOutlierDetector implements both Picker (so it can be passed to Config.WithLoadBalancer) and Selector.

func AsSelector

func AsSelector(p Picker) Selector

AsSelector adapts a Picker into a Selector. A Picker that already implements Selector is returned unchanged; otherwise it is wrapped so exclude is honored by pre-filtering the candidate list before delegating to Pick.