Documentation
¶
Overview ¶
Package resilience provides client-side resilience primitives: circuit breaker, retry and timeout, composed as middleware around a Handler.
This package holds the imperative, code-level primitives. The sibling package pkg/resiliency builds declarative, configuration-driven policies on top of it; see that package's documentation for how the two relate.
Index ¶
- Variables
- type BreakerOption
- type BreakerRegistry
- type Handler
- type HedgeOption
- type Middleware
- func Breaker(opts ...BreakerOption) Middleware
- func Bulkhead(maxConcurrent int) Middleware
- func Chain(outer Middleware, others ...Middleware) Middleware
- func Deadline(d time.Duration) Middleware
- func Hedge(delay time.Duration, opts ...HedgeOption) Middleware
- func NopBreaker() Middleware
- func Retry(opts ...RetryOption) Middleware
- func Shedder(opts ...ShedderOption) Middleware
- func Timeout(d time.Duration) Middleware
- type RetryOption
- type ShedderOption
Constants ¶
This section is empty.
Variables ¶
var ErrBulkheadFull = errno.ErrBulkheadFull
ErrBulkheadFull is returned when the bulkhead rejects a request because its concurrency budget is exhausted. It aliases errno.ErrBulkheadFull so callers can match it with errors.Is while the sentinel stays centrally defined.
var ErrCircuitOpen = errno.ErrCircuitOpen
ErrCircuitOpen is returned when the breaker is open and rejects the request. It aliases errno.ErrCircuitOpen so callers can match it with errors.Is while the sentinel stays centrally defined.
var ErrServiceOverloaded = errno.ErrServiceOverloaded
ErrServiceOverloaded is returned when the adaptive load shedder drops a request because the service is overloaded.
Functions ¶
This section is empty.
Types ¶
type BreakerOption ¶
type BreakerOption func(*breakerConfig)
BreakerOption configures the circuit breaker.
func WithAcceptable ¶
func WithAcceptable(f func(error) bool) BreakerOption
WithAcceptable sets the predicate that classifies an error as an acceptable outcome (not a failure). Errors judged acceptable do not trip the breaker; this lets callers treat e.g. timeouts or 4xx client errors as non-failures. Default treats any non-nil error as a failure.
func WithBuckets ¶
func WithBuckets(n int) BreakerOption
WithBuckets sets the number of buckets in the window. Default 40.
func WithProbeInterval ¶
func WithProbeInterval(d time.Duration) BreakerOption
WithProbeInterval sets how often a request is force-passed while throttling, so the breaker can recover once the downstream heals. Default 1s.
func WithWindow ¶
func WithWindow(d time.Duration) BreakerOption
WithWindow sets the sliding window duration. Default 10s.
type BreakerRegistry ¶
type BreakerRegistry struct {
// contains filtered or unexported fields
}
BreakerRegistry holds named breakers so all calls to the same downstream service share a single breaker instance, rather than each call site keeping its own sliding window (which would fragment the failure signal).
func NewBreakerRegistry ¶
func NewBreakerRegistry(opts ...BreakerOption) *BreakerRegistry
NewBreakerRegistry returns a BreakerRegistry whose breakers are built from the given options. All named breakers share the same tuning; use one registry per distinct set of breaker parameters.
func (*BreakerRegistry) Do ¶
Do runs req under the named breaker, classifying results via acceptable (or the registry's default when acceptable is nil).
func (*BreakerRegistry) Get ¶
func (r *BreakerRegistry) Get(name string) *sreBreaker
Get returns the named breaker, creating it on first use.
func (*BreakerRegistry) Healthy ¶
func (r *BreakerRegistry) Healthy(name string) bool
Healthy reports whether the named breaker would currently allow a request.
func (*BreakerRegistry) NoBreakerFor ¶
func (r *BreakerRegistry) NoBreakerFor(name string)
NoBreakerFor removes the named breaker so its state is reset.
type HedgeOption ¶
type HedgeOption func(*hedgeConfig)
HedgeOption configures the Hedge middleware.
func WithBackupErrorRate ¶
func WithBackupErrorRate(rate float64) HedgeOption
WithBackupErrorRate enables adaptive throttling of backups: when the observed backup error rate reaches rate, no backup is issued (the primary is awaited instead), preventing extra load from being piled onto an already-failing downstream. rate must be in (0, 1]; a value of 0 disables the throttle.
func WithBackupMaxRetries ¶
func WithBackupMaxRetries(n int) HedgeOption
WithBackupMaxRetries sets how many backup requests to issue once the primary exceeds delay. It is clamped to [1, 2]; default 1.
type Middleware ¶
Middleware decorates a Handler.
func Breaker ¶
func Breaker(opts ...BreakerOption) Middleware
Breaker returns a middleware guarding the handler with a Google SRE sliding-window circuit breaker. It probabilistically rejects requests as the failure rate rises instead of using a hard open/close state machine, so it degrades gracefully rather than flapping.
func Bulkhead ¶
func Bulkhead(maxConcurrent int) Middleware
Bulkhead returns a middleware that isolates a downstream service by bounding the number of concurrent in-flight requests (bulkhead + semaphore patterns). When the budget is exhausted it fails fast with ErrBulkheadFull instead of queueing, so a slow or wedged downstream cannot exhaust the process and cascade failures to unrelated callers. A maxConcurrent <= 0 disables the bulkhead and lets requests through unmodified.
func Chain ¶
func Chain(outer Middleware, others ...Middleware) Middleware
Chain assembles middlewares with the first argument outermost (executed first), mirroring the middleware package convention.
func Deadline ¶
func Deadline(d time.Duration) Middleware
Deadline returns a middleware imposing the deadline (timeout) stability pattern. It bounds the handler by min(parent deadline, now+d): when the incoming context already carries an earlier deadline, that budget is propagated unchanged, so a downstream call never runs past the caller's deadline. When the deadline is the cause of failure it returns the typed errno.ErrTimeout (which still unwraps to context.DeadlineExceeded for errors.Is classification), giving both HTTP and gRPC paths a uniform timeout error.
func Hedge ¶
func Hedge(delay time.Duration, opts ...HedgeOption) Middleware
Hedge returns a middleware that issues backup (hedged) requests when the primary request does not complete within delay, returning whichever finishes first. It trades a bounded amount of extra load for lower tail latency.
Because it runs the handler concurrently, the handler must be safe to execute in parallel (idempotent and side-effect-free with respect to shared state). It is therefore suited to idempotent calls such as HTTP GET; do not wrap a handler that mutates a shared request/response object.
func NopBreaker ¶
func NopBreaker() Middleware
NopBreaker returns a middleware that never trips the circuit.
func Retry ¶
func Retry(opts ...RetryOption) Middleware
Retry returns a middleware that retries the handler with exponential backoff and jitter, following the retrier stability pattern.
func Shedder ¶
func Shedder(opts ...ShedderOption) Middleware
Shedder returns a middleware that adaptively drops requests when the service is overloaded, based on the smoothed CPU usage and the derived maximum in-flight requests (Little's law). It is an inbound overload-protection pattern; outbound resilience uses Breaker/Retry instead.
func Timeout ¶
func Timeout(d time.Duration) Middleware
Timeout returns a middleware imposing a deadline on the handler, following the deadline (timeout) stability pattern.
type RetryOption ¶
type RetryOption func(*retryConfig)
RetryOption configures the retry middleware.
func WithBackoff ¶
func WithBackoff(base, max time.Duration) RetryOption
WithBackoff sets the base and maximum backoff. Default 100ms / 1s.
func WithMaxAttempts ¶
func WithMaxAttempts(n int) RetryOption
WithMaxAttempts sets the maximum number of attempts (>=1). Default 3.
func WithMaxRetryRatio ¶
func WithMaxRetryRatio(ratio float64) RetryOption
WithMaxRetryRatio limits retried requests to a fraction of total requests (0 < ratio <= 1), protecting a downstream service from retry storms. A ratio of 0 disables the limit. Default 0 (unlimited).
func WithPerAttemptTimeout ¶
func WithPerAttemptTimeout(d time.Duration) RetryOption
WithPerAttemptTimeout imposes an independent deadline on each attempt. This differs from the Timeout middleware, which bounds the whole retry sequence.
func WithRetryable ¶
func WithRetryable(f func(error) bool) RetryOption
WithRetryable sets the predicate deciding which errors are retryable. When nil, all errors are retried.
type ShedderOption ¶
type ShedderOption func(*shedderOptions)
ShedderOption configures the adaptive load shedder.
func WithShedderBuckets ¶
func WithShedderBuckets(buckets int) ShedderOption
WithShedderBuckets sets the number of buckets in the window. Default 50.
func WithShedderCpuThreshold ¶
func WithShedderCpuThreshold(threshold int64) ShedderOption
WithShedderCpuThreshold sets the CPU threshold (per-mille, 0-1000) above which the shedder starts dropping. Default 900.
func WithShedderWindow ¶
func WithShedderWindow(window time.Duration) ShedderOption
WithShedderWindow sets the rolling window duration. Default 5s.
Source Files