ratelimiter

Documentation

Overview

Package ratelimiter implements two common rate limiters; queue and token/leaky bucket.

Index

• Constants
• func Copy(ctx context.Context, dst io.Writer, src io.Reader, opts ...CopyOption) (written int64, err error)
• type CopyOption
  • func OptCopyBuffer(buf []byte) CopyOption
  • func OptCopyChunkSize(cs int) CopyOption
  • func OptCopyOnWrite(handler func(bytesWritten int, elapsed time.Duration)) CopyOption
  • func OptCopyRateBytes(b int64) CopyOption
  • func OptCopyRateQuantum(q time.Duration) CopyOption
• type CopyOptions
• type LeakyBucket
  • func NewLeakyBucket(numActions int, quantum time.Duration) *LeakyBucket
  • func (lb *LeakyBucket) Check(id string) bool
• type Queue
  • func NewQueue(numberOfActions int, quantum time.Duration) *Queue
  • func (q *Queue) Check(id string) bool
• type RateLimiter
• type Token
• type Wait
  • func (w Wait) Calculate(actions int64, quantum time.Duration) time.Duration
  • func (w Wait) Wait(ctx context.Context, actions int64, quantum time.Duration) error
  • func (w Wait) WaitTimer(ctx context.Context, actions int64, quantum time.Duration, after *time.Timer) error

Constants

const (
	// DefaultCopyChunkSizeBytes is the write chunk size in bytes.
	DefaultCopyChunkSizeBytes = 32 * 1024
)

Functions

func Copy

func Copy(ctx context.Context, dst io.Writer, src io.Reader, opts ...CopyOption) (written int64, err error)

Copy copies from the src reader to the dst writer.

Types

type CopyOption

type CopyOption func(*CopyOptions)

CopyOption mutates CopyOptions.

func OptCopyBuffer

func OptCopyBuffer(buf []byte) CopyOption

OptCopyBuffer sets the buffer for the copy.

func OptCopyChunkSize

func OptCopyChunkSize(cs int) CopyOption

OptCopyChunkSize sets the quantum portion of the rate.

func OptCopyOnWrite

func OptCopyOnWrite(handler func(bytesWritten int, elapsed time.Duration)) CopyOption

OptCopyOnWrite sets the on write handler for the copy.

func OptCopyRateBytes

func OptCopyRateBytes(b int64) CopyOption

OptCopyRateBytes sets the bytes portion of the rate.

func OptCopyRateQuantum

func OptCopyRateQuantum(q time.Duration) CopyOption

OptCopyRateQuantum sets the quantum portion of the rate.

type CopyOptions

type CopyOptions struct {
	RateBytes   int64
	RateQuantum time.Duration
	ChunkSize   int
	Buffer      []byte
	OnWrite     func(int, time.Duration)
}

CopyOptions are options for the throttled copy.

type LeakyBucket

type LeakyBucket struct {
	NumActions int
	Quantum    time.Duration
	Tokens     map[string]*Token
	Now        func() time.Time
}

LeakyBucket implements the token bucket rate limiting algorithm.

func NewLeakyBucket

func NewLeakyBucket(numActions int, quantum time.Duration) *LeakyBucket

NewLeakyBucket returns a new token bucket rate limiter. The rate is formed by `numActions` and `quantum`; the resulting rate is numActions/quantum.

func (*LeakyBucket) Check

func (lb *LeakyBucket) Check(id string) bool

Check returns true if an id has exceeded the rate limit, and false otherwise.

type Queue

type Queue struct {
	NumberOfActions int
	Quantum         time.Duration
	Limits          map[string]collections.Queue[any]
	Now             func() time.Time
}

Queue is a simple implementation of a rate checker.

func NewQueue

func NewQueue(numberOfActions int, quantum time.Duration) *Queue

NewQueue returns a new queue based rate limiter.

func (*Queue) Check

func (q *Queue) Check(id string) bool

Check returns true if it has been called NumberOfActions times or more in Quantum or smaller duration.

type RateLimiter

type RateLimiter interface {
	// Check returns for a given id `true` if that id is _above_ the rate limit, and false otherwise.
	Check(string) bool
}

RateLimiter is a type that can be used as a rate limiter.

type Token

type Token struct {
	Count float64   // the rate adjusted count; initialize at max*rate, remove rate tokens per call
	Last  time.Time // last is used to calculate the elapsed, and subsequently the rate
}

Token is an individual id's work.

type Wait

type Wait struct {
	NumberOfActions int64
	Quantum         time.Duration
}

Wait is a type that allows you to throttle actions with sleeps based on a desired rate.

func (Wait) Calculate

func (w Wait) Calculate(actions int64, quantum time.Duration) time.Duration

Calculate takes the observed rate and the desired rate, and returns a quantum to sleep for that adjusts the observed rate to match the desired rate.

If the observed rate is _lower_ than the desired rate, the returned value will be negative and you're free to ignore it.

If the observed rate is _higher_ than the desired rate, a positive duration will be returned which you can pass to a `time.Sleep(...)` or similar.

The wait quantum is derrived from the following algebraic steps (where ? is what we're solving for):

pb/(pq+?) = rb/rq
1/(pq+?) = rb/pb*rq
pq+? = (pb*rq)/rb
? = ((pb*rq)/rb) - pq

func (Wait) Wait

func (w Wait) Wait(ctx context.Context, actions int64, quantum time.Duration) error

Wait waits for a calculated throttling time based on the input options.

func (Wait) WaitTimer

func (w Wait) WaitTimer(ctx context.Context, actions int64, quantum time.Duration, after *time.Timer) error

WaitTimer waits with a given (re-used) timer reference.