Documentation
¶
Overview ¶
Package resilience provides circuit breakers, retry logic, bulkheading, request coalescing, and graceful drain for the gateway proxy pipeline.
Index ¶
- func CoalesceKey(r *http.Request, targetURL string) (string, bool)
- func WriteCoalescedResponse(w http.ResponseWriter, cr *CoalescedResponse)
- type Bulkhead
- type BulkheadConfig
- type CBManager
- func (m *CBManager) Get(targetID string) bastion.Breaker
- func (m *CBManager) GetWithConfig(targetID string, cfg *bastion.CBConfig) bastion.Breaker
- func (m *CBManager) Remove(targetID string)
- func (m *CBManager) Reset(targetID string) bool
- func (m *CBManager) SetOnStateChange(fn func(targetID string, from, to bastion.CircuitState))
- func (m *CBManager) Snapshots() []bastion.CircuitBreakerSnapshot
- type CircuitBreaker
- func (cb *CircuitBreaker) Allow() bool
- func (cb *CircuitBreaker) RecordFailure()
- func (cb *CircuitBreaker) RecordSuccess()
- func (cb *CircuitBreaker) ReleaseProbe()
- func (cb *CircuitBreaker) Reset()
- func (cb *CircuitBreaker) SetOnStateChange(fn func(targetID string, from, to bastion.CircuitState))
- func (cb *CircuitBreaker) Snapshot() bastion.CircuitBreakerSnapshot
- func (cb *CircuitBreaker) State() bastion.CircuitState
- type CircuitBreakerMetrics
- type CircuitBreakerMode
- type CoalescedResponse
- type CoalescerConfig
- type DrainConfig
- type EnhancedCBConfig
- type RequestCoalescer
- type RequestDrainer
- type RetryExecutor
- type SlidingWindowCircuitBreaker
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CoalesceKey ¶
CoalesceKey generates a coalescing key from a request. Only GET and HEAD requests are coalesced.
func WriteCoalescedResponse ¶
func WriteCoalescedResponse(w http.ResponseWriter, cr *CoalescedResponse)
WriteCoalescedResponse writes a coalesced response to an http.ResponseWriter.
Types ¶
type Bulkhead ¶
type Bulkhead struct {
// contains filtered or unexported fields
}
Bulkhead limits concurrency to individual upstream targets, preventing one misbehaving upstream from consuming all goroutines.
func NewBulkhead ¶
func NewBulkhead(config BulkheadConfig) *Bulkhead
NewBulkhead creates a new bulkhead limiter.
func (*Bulkhead) Acquire ¶
Acquire attempts to acquire a concurrency slot for the given target. It returns a release function and nil error on success. If the bulkhead is full and the wait queue is also full, it returns a non-nil error.
func (*Bulkhead) AcquireHTTP ¶
func (b *Bulkhead) AcquireHTTP(w http.ResponseWriter, r *http.Request, targetID string) (release func(), ok bool)
AcquireHTTP is a convenience wrapper that writes a 503 on failure.
type BulkheadConfig ¶
type BulkheadConfig struct {
// Enabled enables bulkhead concurrency limiting.
Enabled bool `json:"enabled" yaml:"enabled"`
// MaxConcurrent is the maximum concurrent requests per upstream target.
MaxConcurrent int `json:"maxConcurrent" yaml:"max_concurrent"`
// MaxWaitQueue is the maximum number of requests waiting for a slot.
// When exceeded, requests are rejected immediately with 503.
MaxWaitQueue int `json:"maxWaitQueue" yaml:"max_wait_queue"`
}
BulkheadConfig configures per-upstream concurrency limiting.
type CBManager ¶
type CBManager struct {
// contains filtered or unexported fields
}
CBManager manages circuit breakers for all targets.
func NewCBManager ¶
func NewCBManager(config bastion.CircuitBreakerConfig) *CBManager
NewCBManager creates a new circuit breaker manager.
func (*CBManager) GetWithConfig ¶
GetWithConfig returns a circuit breaker with a per-route config override.
func (*CBManager) Reset ¶
Reset closes the breaker for targetID. It reports false when no breaker exists for that id, so a caller can tell a reset from a typo.
func (*CBManager) SetOnStateChange ¶
func (m *CBManager) SetOnStateChange(fn func(targetID string, from, to bastion.CircuitState))
SetOnStateChange sets the global state change callback.
func (*CBManager) Snapshots ¶
func (m *CBManager) Snapshots() []bastion.CircuitBreakerSnapshot
Snapshots returns every breaker's state, sorted by target id.
type CircuitBreaker ¶
type CircuitBreaker struct {
// contains filtered or unexported fields
}
CircuitBreaker implements a per-target circuit breaker with three states.
func NewCircuitBreaker ¶
func NewCircuitBreaker(targetID string, config bastion.CircuitBreakerConfig) *CircuitBreaker
NewCircuitBreaker creates a new circuit breaker for a target.
func (*CircuitBreaker) Allow ¶
func (cb *CircuitBreaker) Allow() bool
Allow checks if a request is allowed through the circuit breaker.
func (*CircuitBreaker) RecordFailure ¶
func (cb *CircuitBreaker) RecordFailure()
RecordFailure records a failed request.
func (*CircuitBreaker) RecordSuccess ¶
func (cb *CircuitBreaker) RecordSuccess()
RecordSuccess records a successful request.
func (*CircuitBreaker) ReleaseProbe ¶
func (cb *CircuitBreaker) ReleaseProbe()
ReleaseProbe hands back a half-open probe slot for a request that neither succeeded nor failed, such as one answered with a 5xx. Without it the slot stays spent and a half-open breaker can end up refusing forever.
func (*CircuitBreaker) Reset ¶
func (cb *CircuitBreaker) Reset()
Reset resets the circuit breaker to closed state.
func (*CircuitBreaker) SetOnStateChange ¶
func (cb *CircuitBreaker) SetOnStateChange(fn func(targetID string, from, to bastion.CircuitState))
SetOnStateChange sets the state change callback.
func (*CircuitBreaker) Snapshot ¶
func (cb *CircuitBreaker) Snapshot() bastion.CircuitBreakerSnapshot
Snapshot returns a copy of the breaker's state. An open breaker whose reset timeout has elapsed reports half_open, matching State().
func (*CircuitBreaker) State ¶
func (cb *CircuitBreaker) State() bastion.CircuitState
State returns the current circuit state.
type CircuitBreakerMetrics ¶
type CircuitBreakerMetrics struct {
State bastion.CircuitState `json:"state"`
FailureRate float64 `json:"failureRate"`
SlowRate float64 `json:"slowRate"`
TotalCount int `json:"totalCount"`
}
CircuitBreakerMetrics holds observable metrics for a circuit breaker.
type CircuitBreakerMode ¶
type CircuitBreakerMode string
CircuitBreakerMode defines how failures are measured.
const ( // CBModeCount trips the breaker after N consecutive failures (default). CBModeCount CircuitBreakerMode = "count" // CBModeRate trips the breaker when failure percentage exceeds threshold // within a sliding window. CBModeRate CircuitBreakerMode = "rate" )
type CoalescedResponse ¶
CoalescedResponse holds a captured HTTP response for coalescing.
type CoalescerConfig ¶
type CoalescerConfig struct {
// Enabled enables request coalescing for identical concurrent GET requests.
Enabled bool `json:"enabled" yaml:"enabled"`
}
CoalescerConfig configures request coalescing.
type DrainConfig ¶
type DrainConfig struct {
// Enabled enables graceful draining.
Enabled bool `json:"enabled" yaml:"enabled"`
// Timeout is the maximum time to wait for in-flight requests to complete.
Timeout time.Duration `json:"timeout" yaml:"timeout"`
}
DrainConfig configures graceful request draining on shutdown.
type EnhancedCBConfig ¶
type EnhancedCBConfig struct {
bastion.CircuitBreakerConfig
// Mode determines how failures are evaluated ("count" or "rate").
Mode CircuitBreakerMode `json:"mode" yaml:"mode"`
// FailureRateThreshold is the failure percentage (0-100) that triggers
// the breaker in "rate" mode.
FailureRateThreshold float64 `json:"failureRateThreshold" yaml:"failure_rate_threshold"`
// MinRequestsInWindow is the minimum number of requests needed in the
// sliding window before the failure rate is evaluated.
MinRequestsInWindow int `json:"minRequestsInWindow" yaml:"min_requests_in_window"`
// SlowCallDurationThreshold defines a request as "slow" if it exceeds
// this duration.
SlowCallDurationThreshold time.Duration `json:"slowCallDurationThreshold" yaml:"slow_call_duration_threshold"`
// SlowCallRateThreshold is the percentage (0-100) of slow calls that
// triggers the breaker.
SlowCallRateThreshold float64 `json:"slowCallRateThreshold" yaml:"slow_call_rate_threshold"`
}
EnhancedCBConfig extends CircuitBreakerConfig with advanced options.
type RequestCoalescer ¶
type RequestCoalescer struct {
// contains filtered or unexported fields
}
RequestCoalescer deduplicates identical concurrent GET requests to the same upstream using a singleflight-style pattern.
func NewRequestCoalescer ¶
func NewRequestCoalescer(config CoalescerConfig) *RequestCoalescer
NewRequestCoalescer creates a new request coalescer.
func (*RequestCoalescer) Do ¶
func (rc *RequestCoalescer) Do(key string, doFn func() (*http.Response, error)) (*CoalescedResponse, error)
Do coalesces identical GET requests. If a request with the same key is already in-flight, this blocks until that request completes and returns the same response. The doFn is only called once per unique key.
type RequestDrainer ¶
type RequestDrainer struct {
// contains filtered or unexported fields
}
RequestDrainer tracks in-flight requests and supports graceful draining on shutdown. When draining begins, new requests are rejected with 503 while existing requests are allowed to complete up to the drain timeout.
func NewRequestDrainer ¶
func NewRequestDrainer(config DrainConfig) *RequestDrainer
NewRequestDrainer creates a new request drainer.
func (*RequestDrainer) Acquire ¶
func (d *RequestDrainer) Acquire() bool
Acquire registers an in-flight request. Returns false if the gateway is draining and the request should be rejected.
func (*RequestDrainer) Drain ¶
func (d *RequestDrainer) Drain(ctx context.Context) error
Drain initiates graceful draining. It blocks until all in-flight requests complete or the drain timeout is reached. Returns a context error if the timeout was exceeded.
func (*RequestDrainer) InFlight ¶
func (d *RequestDrainer) InFlight() int64
InFlight returns the number of in-flight requests.
func (*RequestDrainer) IsDraining ¶
func (d *RequestDrainer) IsDraining() bool
IsDraining returns true if the gateway is in drain mode.
func (*RequestDrainer) Release ¶
func (d *RequestDrainer) Release()
Release marks an in-flight request as completed.
type RetryExecutor ¶
type RetryExecutor struct {
// contains filtered or unexported fields
}
RetryExecutor manages retry logic for proxy requests.
func NewRetryExecutor ¶
func NewRetryExecutor(config bastion.RetryConfig) *RetryExecutor
NewRetryExecutor creates a new retry executor.
func (*RetryExecutor) Delay ¶
func (re *RetryExecutor) Delay(attempt int, routeConfig *bastion.RetryConfig) time.Duration
Delay returns the delay before the next retry attempt.
func (*RetryExecutor) ShouldRetry ¶
func (re *RetryExecutor) ShouldRetry(method string, statusCode int, attempt int, routeConfig *bastion.RetryConfig) bool
ShouldRetry determines if a request should be retried.
type SlidingWindowCircuitBreaker ¶
type SlidingWindowCircuitBreaker struct {
*CircuitBreaker
// contains filtered or unexported fields
}
SlidingWindowCircuitBreaker extends CircuitBreaker with failure-rate and slow-call detection using a sliding window.
func NewSlidingWindowCircuitBreaker ¶
func NewSlidingWindowCircuitBreaker(targetID string, config EnhancedCBConfig) *SlidingWindowCircuitBreaker
NewSlidingWindowCircuitBreaker creates an enhanced circuit breaker with sliding window failure-rate and slow-call detection.
func (*SlidingWindowCircuitBreaker) Metrics ¶
func (cb *SlidingWindowCircuitBreaker) Metrics() CircuitBreakerMetrics
Metrics returns the current circuit breaker metrics.
func (*SlidingWindowCircuitBreaker) RecordResult ¶
func (cb *SlidingWindowCircuitBreaker) RecordResult(failed bool, latency time.Duration)
RecordResult records a request outcome with latency tracking.