ratelimiter

README

Go Rate Limiter

Rate limiting examples in Golang.

$ go get github.com/jpg013/ratelimiter

Throttle Rate Limiter

func main() {
	r, err := ratelimiter.NewThrottleRateLimiter(&ratelimiter.Config{
		Throttle: 1 * time.Second,
	})

	if err != nil {
		panic(err)
	}

	doWork(r, 10)
}

func doWork(r RateLimiter, workerCount int) {
	var wg sync.WaitGroup
	rand.Seed(time.Now().UnixNano())

	doWork := func(id int) {
		// Acquire a rate limit token
		token, err := r.Acquire()
		fmt.Printf("Rate Limit Token acquired %s...\n", token.ID)
		if err != nil {
			panic(err)
		}
		// Simulate some work
		n := rand.Intn(5)
		fmt.Printf("Worker %d Sleeping %d seconds...\n", id, n)
		time.Sleep(time.Duration(n) * time.Second)
		fmt.Printf("Worker %d Done\n", id)
		r.Release(token)
		wg.Done()
	}

	// Spin up a 10 workers that need a rate limit resource
	for i := 0; i < workerCount; i++ {
		wg.Add(1)
		go doWork(i)
	}

	wg.Wait()
}

Max Concurrency Rate Limiter

func main() {
	r, err := ratelimiter.NewMaxConcurrencyRateLimiter(&ratelimiter.Config{
		Limit:            4,
		TokenResetsAfter: 10 * time.Second,
	})

	if err != nil {
		panic(err)
	}

	doWork(r, 10)
}

Fixed Window Rate Limiter

func main() {
	r, err := ratelimiter.NewFixedWindowRateLimiter(&ratelimiter.Config{
		Limit:         5,
		FixedInterval: 15 * time.Second,
	})

	if err != nil {
		panic(err)
	}

	doWork(r, 10)
}

Documentation

Index

• Constants
• Variables
• func DoWork(r RateLimiter, workerCount int)
• type Config
• type FixedWindowInterval
• type Manager
  • func NewManager(conf *Config) *Manager
  • func (m *Manager) Acquire() (*Token, error)
  • func (m *Manager) Release(t *Token)
• type RateLimiter
  • func NewFixedWindowRateLimiter(conf *Config) (RateLimiter, error)
  • func NewMaxConcurrencyRateLimiter(conf *Config) (RateLimiter, error)
  • func NewThrottleRateLimiter(conf *Config) (RateLimiter, error)
• type Token
  • func NewToken() *Token
  • func (t *Token) IsExpired() bool
  • func (t *Token) NeedReset(resetAfter time.Duration) bool

Constants

const MaxInt = int(MaxUint >> 1)

MaxInt holds the maximum int value

const MaxUint = ^uint(0)

MaxUint holds the maximum unsigned int value

Variables

var (
	ErrInvalidLimit           = errors.New("Limit must be greater than zero")
	ErrInvalidInterval        = errors.New("Interval must be greater than zero")
	ErrTokenFactoryNotDefined = errors.New("Token factory must be defined")
)

Errors used throughout the codebase

Functions

func DoWork

func DoWork(r RateLimiter, workerCount int)

Types

type Config

type Config struct {
	// Limit determines how many rate limit tokens can be active at a time
	Limit int

	// FixedInterval sets the fixed time window for a Fixed Window Rate Limiter
	FixedInterval time.Duration

	// Throttle is the min time between requests for a Throttle Rate Limiter
	Throttle time.Duration

	// TokenResetsAfter is the maximum amount of time a token can live before being
	// forcefully released - if set to zero time then the token may live forever
	TokenResetsAfter time.Duration
}

Config represents a rate limiter config object

type FixedWindowInterval

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

FixedWindowInterval represents a fixed window of time with a start / end time

type Manager

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

Manager implements a rate limiter interface.

func NewManager

func NewManager(conf *Config) *Manager

NewManager creates a manager type

func (*Manager) Acquire

func (m *Manager) Acquire() (*Token, error)

Acquire is called to acquire a new token

func (*Manager) Release

func (m *Manager) Release(t *Token)

Release is called to release an active token

type RateLimiter

type RateLimiter interface {
	Acquire() (*Token, error)
	Release(*Token)
}

RateLimiter defines two methods for acquiring and releasing tokens

func NewFixedWindowRateLimiter

func NewFixedWindowRateLimiter(conf *Config) (RateLimiter, error)

NewFixedWindowRateLimiter returns a fixed window rate limiter

func NewMaxConcurrencyRateLimiter

func NewMaxConcurrencyRateLimiter(conf *Config) (RateLimiter, error)

NewMaxConcurrencyRateLimiter returns a max concurrency rate limiter

func NewThrottleRateLimiter

func NewThrottleRateLimiter(conf *Config) (RateLimiter, error)

NewThrottleRateLimiter returns a throttle rate limiter

type Token

type Token struct {
	// The unique token ID
	ID string

	// The time at which the token was created
	CreatedAt time.Time

	// Defines the min amount of time the token must live before being released
	ExpiresAt time.Time
}

Token represents a Rate Limit Token

func NewToken

func NewToken() *Token

NewToken creates a new token

func (*Token) IsExpired

func (t *Token) IsExpired() bool

IsExpired returns true if current time is greater than expiration time

func (*Token) NeedReset

func (t *Token) NeedReset(resetAfter time.Duration) bool

NeedReset returns true if elapsed time since token was created is greater than provided reset duration