keyrate

README

keyrate

A rate.Limiter per key with bounded retention.

KeyLimiter lazily creates a golang.org/x/time/rate.Limiter for each key and keeps limiters in an internal two-generation map to avoid unbounded growth when the set of keys is large and mostly ephemeral.

Limiters are created on demand and are retained for approximately two swap intervals. Swap interval is equal to the duration provided to NewKeyLimiter, but never less than 5 seconds.

l := keyrate.NewKeyLimiter[string](5*time.Minute, 5, 1<<12)

if !l.Allow("12345") {
    // ...
}

See GoDoc for reference

Documentation

Overview

Package keyrate provides a rate.Limiter per key with bounded retention.

KeyLimiter lazily creates a golang.org/x/time/rate.Limiter for each key and keeps limiters in an internal two-generation map. The active generation is stored in cur; the previous generation is kept in prev and discarded on the next swap. This provides a simple, allocation-friendly way to avoid unbounded growth when the set of keys is large and mostly ephemeral.

KeyLimiter is safe for concurrent use.

Index

• type KeyLimiter
  • func NewKeyLimiter[K comparable](dur time.Duration, burst int, avgUnique int) *KeyLimiter[K]
  • func (l *KeyLimiter[K]) Allow(key K) bool
  • func (l *KeyLimiter[K]) AllowN(key K, t time.Time, n int) bool
  • func (l *KeyLimiter[K]) Burst(key K) int
  • func (l *KeyLimiter[K]) Limit(key K) rate.Limit
  • func (l *KeyLimiter[K]) Reserve(key K) *rate.Reservation
  • func (l *KeyLimiter[K]) ReserveN(key K, t time.Time, n int) *rate.Reservation
  • func (l *KeyLimiter[K]) Tokens(key K) float64
  • func (l *KeyLimiter[K]) TokensAt(key K, t time.Time) float64
  • func (l *KeyLimiter[K]) Wait(key K, ctx context.Context) (err error)
  • func (l *KeyLimiter[K]) WaitN(key K, ctx context.Context, n int) (err error)

Types

type KeyLimiter

type KeyLimiter[K comparable] struct {
	// contains filtered or unexported fields
}

KeyLimiter provides a per-key token-bucket limiter.

All exported methods delegate to the underlying per-key *rate.Limiter. Limiters are created lazily and reused across swaps while the key remains active.

func NewKeyLimiter

func NewKeyLimiter[K comparable](dur time.Duration, burst int, avgUnique int) *KeyLimiter[K]

NewKeyLimiter returns a KeyLimiter that applies the same rate limit to each key.

The dur parameter is interpreted as the minimum time between events for a single key (i.e. one token is added every dur); burst specifies the maximum burst size for that key, following the semantics of x/time/rate.

Limiters are created on demand and are retained for approximately two swap intervals. Swap interval is equal to dur.

If dur is negative it is treated as zero. A zero dur results in an unlimited limiter (rate.Inf) for each key.

func (*KeyLimiter[K]) Allow

func (l *KeyLimiter[K]) Allow(key K) bool

func (*KeyLimiter[K]) AllowN

func (l *KeyLimiter[K]) AllowN(key K, t time.Time, n int) bool

func (*KeyLimiter[K]) Burst

func (l *KeyLimiter[K]) Burst(key K) int

func (*KeyLimiter[K]) Limit

func (l *KeyLimiter[K]) Limit(key K) rate.Limit

func (*KeyLimiter[K]) Reserve

func (l *KeyLimiter[K]) Reserve(key K) *rate.Reservation

func (*KeyLimiter[K]) ReserveN

func (l *KeyLimiter[K]) ReserveN(key K, t time.Time, n int) *rate.Reservation

func (*KeyLimiter[K]) Tokens

func (l *KeyLimiter[K]) Tokens(key K) float64

func (*KeyLimiter[K]) TokensAt

func (l *KeyLimiter[K]) TokensAt(key K, t time.Time) float64

func (*KeyLimiter[K]) Wait

func (l *KeyLimiter[K]) Wait(key K, ctx context.Context) (err error)

func (*KeyLimiter[K]) WaitN

func (l *KeyLimiter[K]) WaitN(key K, ctx context.Context, n int) (err error)