leakybucket

README

leakybucket

Leaky bucket implementation in Go with your choice of data storage layer.

Why

Leaky buckets are useful in a number of settings, especially rate limiting.

Documentation

.

Tests

leakybucket is built and tested against Go 1.5. Ensure this is the version of Go you're running with go version. Make sure your GOPATH is set, e.g. export GOPATH=~/go. Clone the repository to $GOPATH/src/github.com/Clever/leakybucket.

If you have done all of the above, then you should be able to run

make test

Documentation

Overview

Package leakybucket provides a leaky bucket implementation with support for various backends.

Index

• Variables
• type Bucket
• type BucketState
• type Storage

Variables

var (
	// ErrorFull is returned when the amount requested to add exceeds the remaining space in the bucket.
	ErrorFull = errors.New("add exceeds free capacity")
)

Types

type Bucket

type Bucket interface {
	// Capacity of the bucket.
	Capacity() uint

	// Remaining space in the bucket.
	Remaining() uint

	// Reset returns when the bucket will be drained.
	Reset() time.Time

	// Add to the bucket. MUST return bucket state after adding, even if an error was encountered
	Add(uint) (BucketState, error)
}

Bucket interface for interacting with leaky buckets: https://en.wikipedia.org/wiki/Leaky_bucket

type BucketState

type BucketState struct {
	Capacity  uint
	Remaining uint
	Reset     time.Time
}

BucketState is a snapshot of a bucket's properties.

type Storage

type Storage interface {
	// Create a bucket with a name, capacity, and rate.
	// rate is how long it takes for full capacity to drain.
	Create(name string, capacity uint, rate time.Duration) (Bucket, error)
}

Storage interface for generating buckets keyed by a string.