limit

Documentation

Overview

Package limit provides rate limiting, concurrency limiting and adaptive overload protection for gofly services.

Package limit provides rate limiting, concurrency limiting and adaptive overload protection for gofly services.

Package limit provides rate limiting, concurrency limiting and adaptive overload protection for gofly services.

Package limit provides rate limiting, concurrency limiting and adaptive overload protection for gofly services.

Package limit provides rate limiting, concurrency limiting, and adaptive limiting for gofly services.

Index

• Variables
• type AdaptiveLimiter
  • func NewAdaptiveLimiter(opts ...AdaptiveLimiterOption) *AdaptiveLimiter
  • func (l *AdaptiveLimiter) Allow() (*AdaptiveToken, error)
  • func (l *AdaptiveLimiter) InFlight() int
  • func (l *AdaptiveLimiter) Limit() int
  • func (l *AdaptiveLimiter) Snapshot() AdaptiveSnapshot
• type AdaptiveLimiterOption
  • func WithAdaptiveCPUReader(reader func() int) AdaptiveLimiterOption
  • func WithAdaptiveCPUThreshold(threshold int) AdaptiveLimiterOption
  • func WithAdaptiveInitialLimit(limit int) AdaptiveLimiterOption
  • func WithAdaptiveLimitWindow(window time.Duration) AdaptiveLimiterOption
  • func WithAdaptiveLimits(minLimit, maxLimit int) AdaptiveLimiterOption
  • func WithAdaptiveMinSamples(samples int64) AdaptiveLimiterOption
  • func WithAdaptiveTargetErrorRatio(ratio float64) AdaptiveLimiterOption
  • func WithAdaptiveTargetLatency(latency time.Duration) AdaptiveLimiterOption
• type AdaptiveSnapshot
• type AdaptiveToken
  • func (t *AdaptiveToken) Done(success bool)
• type Backend
• type ConcurrencyLimiter
  • func NewConcurrency(max int) *ConcurrencyLimiter
  • func (l *ConcurrencyLimiter) Acquire(ctx context.Context) error
  • func (l *ConcurrencyLimiter) InFlight() int
  • func (l *ConcurrencyLimiter) Release()
  • func (l *ConcurrencyLimiter) TryAcquire() bool
• type DistributedPeriodLimiter
  • func NewDistributedPeriod(backend Backend, quota int, window time.Duration) *DistributedPeriodLimiter
  • func (l *DistributedPeriodLimiter) Allow(ctx context.Context, key string) (bool, error)
• type DistributedTokenLimiter
  • func NewDistributedToken(backend Backend, rate, burst int) *DistributedTokenLimiter
  • func (l *DistributedTokenLimiter) Allow(ctx context.Context, key string) (bool, error)
  • func (l *DistributedTokenLimiter) AllowN(ctx context.Context, key string, n int) (bool, error)
• type Limiter
  • func New(rate, burst int) *Limiter
  • func (l *Limiter) Allow() bool
• type SlidingWindowLimiter
  • func NewSlidingWindow(quota int, window time.Duration, buckets int) *SlidingWindowLimiter
  • func (l *SlidingWindowLimiter) Allow() bool
  • func (l *SlidingWindowLimiter) AllowN(n int) bool
  • func (l *SlidingWindowLimiter) Count() int64

Variables

var ErrBackendNil = errors.New("distributed limiter: backend is nil")

ErrBackendNil is returned when a distributed limiter is built without a backend.

var ErrLimited = errors.New("adaptive limiter rejected request")

ErrLimited is returned when the adaptive limiter rejects a request.

Types

type AdaptiveLimiter

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

AdaptiveLimiter adjusts concurrency based on observed latency, error rate and CPU usage.

func NewAdaptiveLimiter

func NewAdaptiveLimiter(opts ...AdaptiveLimiterOption) *AdaptiveLimiter

func (*AdaptiveLimiter) Allow

func (l *AdaptiveLimiter) Allow() (*AdaptiveToken, error)

func (*AdaptiveLimiter) InFlight

func (l *AdaptiveLimiter) InFlight() int

func (*AdaptiveLimiter) Limit

func (l *AdaptiveLimiter) Limit() int

func (*AdaptiveLimiter) Snapshot

func (l *AdaptiveLimiter) Snapshot() AdaptiveSnapshot

type AdaptiveLimiterOption

type AdaptiveLimiterOption func(*AdaptiveLimiter)

AdaptiveLimiterOption customises AdaptiveLimiter.

func WithAdaptiveCPUReader

func WithAdaptiveCPUReader(reader func() int) AdaptiveLimiterOption

WithAdaptiveCPUReader injects the current CPU load in millicpu notation. The limiter keeps the reader injectable so tests and hosts without a runtime CPU sampler can opt in without global state.

func WithAdaptiveCPUThreshold

func WithAdaptiveCPUThreshold(threshold int) AdaptiveLimiterOption

WithAdaptiveCPUThreshold enables CPU-aware shedding when paired with a CPU reader. The value uses millicpu notation, so 900 means 90%.

func WithAdaptiveInitialLimit

func WithAdaptiveInitialLimit(limit int) AdaptiveLimiterOption

func WithAdaptiveLimitWindow

func WithAdaptiveLimitWindow(window time.Duration) AdaptiveLimiterOption

func WithAdaptiveLimits

func WithAdaptiveLimits(minLimit, maxLimit int) AdaptiveLimiterOption

WithAdaptiveLimits sets the minimum and maximum concurrency limits.

func WithAdaptiveMinSamples

func WithAdaptiveMinSamples(samples int64) AdaptiveLimiterOption

func WithAdaptiveTargetErrorRatio

func WithAdaptiveTargetErrorRatio(ratio float64) AdaptiveLimiterOption

func WithAdaptiveTargetLatency

func WithAdaptiveTargetLatency(latency time.Duration) AdaptiveLimiterOption

type AdaptiveSnapshot

type AdaptiveSnapshot struct {
	Limit            int           `json:"limit"`
	MinLimit         int           `json:"minLimit"`
	MaxLimit         int           `json:"maxLimit"`
	InFlight         int           `json:"inFlight"`
	CPUThreshold     int           `json:"cpuThreshold,omitempty"`
	CPULoad          int           `json:"cpuLoad,omitempty"`
	Overloaded       bool          `json:"overloaded,omitempty"`
	Window           time.Duration `json:"window"`
	TargetLatency    time.Duration `json:"targetLatency"`
	TargetErrorRatio float64       `json:"targetErrorRatio"`
	Requests         int64         `json:"requests"`
	Success          int64         `json:"success"`
	Failures         int64         `json:"failures"`
	Passes           int64         `json:"passes"`
	Drops            int64         `json:"drops"`
	ErrorRatio       float64       `json:"errorRatio"`
	AverageLatency   time.Duration `json:"averageLatency"`
	PeakInFlight     int           `json:"peakInFlight"`
}

type AdaptiveToken

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

func (*AdaptiveToken) Done

func (t *AdaptiveToken) Done(success bool)

type Backend

type Backend interface {
	Eval(ctx context.Context, script string, keys []string, args ...string) (int64, error)
}

Backend is the minimal contract a distributed limiter needs: atomic Lua evaluation returning an integer reply. It is satisfied by *redis.Client.

type ConcurrencyLimiter

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

ConcurrencyLimiter bounds the number of concurrent in-flight operations.

func NewConcurrency

func NewConcurrency(max int) *ConcurrencyLimiter

NewConcurrency creates a concurrency limiter allowing max simultaneous operations.

func (*ConcurrencyLimiter) Acquire

func (l *ConcurrencyLimiter) Acquire(ctx context.Context) error

Acquire waits until a slot is available or ctx is cancelled.

func (*ConcurrencyLimiter) InFlight

func (l *ConcurrencyLimiter) InFlight() int

func (*ConcurrencyLimiter) Release

func (l *ConcurrencyLimiter) Release()

func (*ConcurrencyLimiter) TryAcquire

func (l *ConcurrencyLimiter) TryAcquire() bool

TryAcquire attempts to acquire a slot without blocking.

type DistributedPeriodLimiter

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

DistributedPeriodLimiter enforces at most Quota events per Window across all processes sharing the same Backend and key.

func NewDistributedPeriod

func NewDistributedPeriod(backend Backend, quota int, window time.Duration) *DistributedPeriodLimiter

NewDistributedPeriod creates a fixed-window distributed limiter.

func (*DistributedPeriodLimiter) Allow

func (l *DistributedPeriodLimiter) Allow(ctx context.Context, key string) (bool, error)

Allow reports whether an event identified by key is permitted in the current window. The first return reports admission; the second carries backend errors.

type DistributedTokenLimiter

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

DistributedTokenLimiter is a distributed token-bucket limiter shared across processes via a Backend.

func NewDistributedToken

func NewDistributedToken(backend Backend, rate, burst int) *DistributedTokenLimiter

NewDistributedToken creates a distributed token-bucket limiter allowing rate tokens per second with the given burst capacity.

func (*DistributedTokenLimiter) Allow

func (l *DistributedTokenLimiter) Allow(ctx context.Context, key string) (bool, error)

Allow reports whether a single token is available for key.

func (*DistributedTokenLimiter) AllowN

func (l *DistributedTokenLimiter) AllowN(ctx context.Context, key string, n int) (bool, error)

AllowN reports whether n tokens are available for key.

type Limiter

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

Limiter is a token bucket rate limiter.

func New

func New(rate, burst int) *Limiter

New creates a token bucket Limiter with the given rate and burst.

func (*Limiter) Allow

func (l *Limiter) Allow() bool

Allow returns true if a token is available.

type SlidingWindowLimiter

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

SlidingWindowLimiter enforces at most Quota events per Window using a rolling counter split into equal-sized buckets. Unlike a fixed-window counter it does not suffer from boundary bursts where up to 2*Quota events can pass around the window edge: expired buckets are continuously evicted as time advances, so the admitted rate stays close to Quota over any Window.

func NewSlidingWindow

func NewSlidingWindow(quota int, window time.Duration, buckets int) *SlidingWindowLimiter

NewSlidingWindow creates a sliding-window limiter allowing quota events per window, internally divided into buckets sub-windows for smoothing. More buckets yield a smoother approximation at the cost of more memory.

func (*SlidingWindowLimiter) Allow

func (l *SlidingWindowLimiter) Allow() bool

Allow reports whether a single event is permitted right now.

func (*SlidingWindowLimiter) AllowN

func (l *SlidingWindowLimiter) AllowN(n int) bool

AllowN reports whether n events are permitted within the current window. When admitting would exceed the quota the call returns false and consumes nothing.

func (*SlidingWindowLimiter) Count

func (l *SlidingWindowLimiter) Count() int64

Count returns the number of events counted within the current window.