resilience

package
v1.4.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package resilience provides circuit breakers, retry logic, bulkheading, request coalescing, and graceful drain for the gateway proxy pipeline.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CoalesceKey

func CoalesceKey(r *http.Request, targetURL string) (string, bool)

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

func (b *Bulkhead) Acquire(ctx context.Context, targetID string) (release func(), err error)

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.

func (*Bulkhead) Remove

func (b *Bulkhead) Remove(targetID string)

Remove cleans up the semaphore for a target that's been deregistered.

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) Get

func (m *CBManager) Get(targetID string) bastion.Breaker

Get returns the circuit breaker for a target, creating one if necessary.

func (*CBManager) GetWithConfig

func (m *CBManager) GetWithConfig(targetID string, cfg *bastion.CBConfig) bastion.Breaker

GetWithConfig returns a circuit breaker with a per-route config override.

func (*CBManager) Remove

func (m *CBManager) Remove(targetID string)

Remove removes a circuit breaker for a target.

func (*CBManager) Reset

func (m *CBManager) Reset(targetID string) bool

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

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

type CoalescedResponse struct {
	StatusCode int
	Header     http.Header
	Body       []byte
}

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL