ratelimit

README

go-ratelimit - Simple wrapper around golang.org/x/time/rate

What is it?

Token bucket ratelimiter for golang; it wraps the Limiter in golang.org/x/time/rate. It implements global and per-host rate limits. It uses an LRU cache to cache the most frequently used per-host limiters.

Documentation

Overview

Package ratelimit wraps the Limiter from golang.org/x/time/rate and creates a simple interface for global and per-host limits.

Usage:

// Ratelimit globally to 1000 req/s, per-host to 5 req/s and cache
// latest 30000 per-host limits
rl = ratelimit.New(1000, 5, 30000)

....
if !rl.Allow() {
   dropConnection(conn)
}

if  !rl.AllowHost(conn.RemoteAddr()) {
   dropConnection(conn)
}

Index

• type Limiter
  • func New(g, p, cachesize int) (*Limiter, error)
  • func (r *Limiter) Allow() bool
  • func (r *Limiter) AllowHost(a net.Addr) bool
  • func (r Limiter) String() string
  • func (r *Limiter) Wait(ctx context.Context) error
  • func (r *Limiter) WaitHost(ctx context.Context, a net.Addr) error

Types

type Limiter

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

Limiter controls how frequently events are allowed to happen globally or per-host. It uses a token-bucket limiter for the global limit and instantiates a token-bucket limiter for every unique host. The number of per-host limiters is limited to an upper bound ("cache size").

A negative rate limit means "no limit" and a zero rate limit means "Infinite".

func New

func New(g, p, cachesize int) (*Limiter, error)

Create a new token bucket rate limiter that limits globally at 'g' requests/sec and per-host at 'p' requests/sec; It remembers the rate of the 'cachesize' most recent hosts (and their limits). The burst rates are pre-configured to be: Global burst limit: 3 * b; Per host burst limit: 2 * p

func (*Limiter) Allow

func (r *Limiter) Allow() bool

Allow returns true if the global rate limit can consume 1 token and false otherwise. Use this if you intend to drop/skip events that exceed a configured global rate limit, otherwise, use Wait().

func (*Limiter) AllowHost

func (r *Limiter) AllowHost(a net.Addr) bool

AllowHost returns true if the per-host rate limit for host 'a' can consume 1 token and false otherwise. Use this if you intend to drop/skip events that exceed a configured global rate limit, otherwise, use WaitHost().

func (Limiter) String

func (r Limiter) String() string

String returns a printable representation of the limiter

func (*Limiter) Wait

func (r *Limiter) Wait(ctx context.Context) error

Wait blocks until the ratelimiter permits the configured global rate limit. It returns an error if the burst exceeds the configured limit or the context is cancelled.

func (*Limiter) WaitHost

func (r *Limiter) WaitHost(ctx context.Context, a net.Addr) error

WaitHost blocks until the ratelimiter permits the configured per-host rate limit from host 'a'. It returns an error if the burst exceeds the configured limit or the context is cancelled.