ratelimit

README

ratelimit

ratelimit is a go server to provide a rate limiter where the developer sends request with a key, count, limit and duration and gets a success or failure response back.

Definitions:

key: Any string that represents the resource you want to limit
count: Amount of resource to consume
limit: Maximum amount of resource that can be consumed
duration: Time window in which the limits will apply. See http://golang.org/pkg/time/#ParseDuration for formatting.

Requirements:

• GOPATH environment variable
• go 1.2

Installation:

To install ratelimitd run:
go get github.com/ctulek/ratelimit/ratelimitd

Make sure that $GOPATH/bin is included in your PATH

Usage:

• To start server:
  ratelimitd
• Server will start listening on port 9090. If you want to change the default port try:
  ratelimitd --port={PORT}
• To start server with Memcache backend:
  ratelimitd --memcache=localhost:11211
• To start server with Redis backend:
  ratelimitd --redis=localhost:6379

Examples:

Consuming Keys:####

Request:
curl -i -s -X POST "http://localhost:9090/?key=testkey&count=1&limit=10&duration=30s"
Response:

  HTTP/1.1 200 OK
  Content-Type: text/plain; charset=utf-8
  Content-Length: 2
  Date: Thu, 31 Oct 2013 03:58:41 GMT
  
  3

Reaching to Limit

Request:
curl -i -s -X POST "http://localhost:9090/?key=testkey&count=1&limit=10&duration=30s"
Response:

  HTTP/1.1 405 Method Not Allowed
  Content-Type: text/plain; charset=utf-8
  Content-Length: 14
  Date: Thu, 31 Oct 2013 04:03:39 GMT
  
  Limit reached

Resetting

Request:
curl -i -s -X DELETE "http://localhost:9090/?key=testkey"
Response:

  HTTP/1.1 200 OK
  Content-Type: text/plain; charset=utf-8
  Content-Length: 2
  Date: Thu, 31 Oct 2013 03:58:41 GMT
  

Getting Usage Value Only

Request:
curl -i -s -X GET "http://localhost:9090/?key=testkey"
Response:

  HTTP/1.1 200 OK
  Content-Type: text/plain; charset=utf-8
  Content-Length: 2
  Date: Thu, 31 Oct 2013 03:58:41 GMT
  
  3

Documentation

Index

• Constants
• Variables
• func NewMemcacheClient(host string) *memcache.Client
• func NewRedisConnectionPool(host string, poolSize int) *redis.Pool
• type DummyStorage
  • func NewDummyStorage() *DummyStorage
  • func (d *DummyStorage) Delete(key string) error
  • func (d *DummyStorage) Get(key string) (*TokenBucket, error)
  • func (d *DummyStorage) Set(key string, bucket *TokenBucket, _ time.Duration) error
• type HttpServer
  • func NewHttpServer(limiter Limiter, logger *log.Logger) *HttpServer
  • func (s *HttpServer) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type Limiter
• type MemcacheStorage
  • func NewMemcacheStorage(client *memcache.Client, prefix string) *MemcacheStorage
  • func (ms *MemcacheStorage) Delete(key string) error
  • func (ms *MemcacheStorage) Get(key string) (*TokenBucket, error)
  • func (ms *MemcacheStorage) Set(key string, bucket *TokenBucket, duration time.Duration) error
• type RedisStorage
  • func NewRedisStorage(pool *redis.Pool, prefix string) *RedisStorage
  • func (rs *RedisStorage) Delete(key string) error
  • func (rs *RedisStorage) Get(key string) (*TokenBucket, error)
  • func (rs *RedisStorage) Set(key string, bucket *TokenBucket, duration time.Duration) error
• type SingleThreadLimiter
  • func NewSingleThreadLimiter(storage Storage) *SingleThreadLimiter
  • func (l *SingleThreadLimiter) Delete(key string) error
  • func (l *SingleThreadLimiter) Get(key string) (int64, error)
  • func (l *SingleThreadLimiter) Post(key string, count, limit int64, duration time.Duration) (int64, error)
  • func (l *SingleThreadLimiter) Start()
  • func (l *SingleThreadLimiter) Stop()
• type Storage
• type TokenBucket
  • func NewTokenBucket(limit float64, duration time.Duration) *TokenBucket
  • func (bucket *TokenBucket) Consume(count float64) error
  • func (bucket *TokenBucket) GetAdjustedUsage(now time.Time) float64

Constants

const (
	GET = iota
	POST
	DELETE
)

Variables

var (
	ErrKeyEmpty     = errors.New("Key cannot be empty")
	ErrCountZero    = errors.New("Count should be greater than zero")
	ErrLimitZero    = errors.New("Limit should be greater than zero")
	ErrCountLimit   = errors.New("Limit should be greater than count")
	ErrZeroDuration = errors.New("Duration cannot be zero")
)

var (
	ErrLimitReached = errors.New("Limit reached")
)

var (
	ErrNotFound = errors.New("Not found")
)

Functions

func NewMemcacheClient

func NewMemcacheClient(host string) *memcache.Client

func NewRedisConnectionPool

func NewRedisConnectionPool(host string, poolSize int) *redis.Pool

Types

type DummyStorage

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

func NewDummyStorage

func NewDummyStorage() *DummyStorage

func (*DummyStorage) Delete

func (d *DummyStorage) Delete(key string) error

func (*DummyStorage) Get

func (d *DummyStorage) Get(key string) (*TokenBucket, error)

func (*DummyStorage) Set

func (d *DummyStorage) Set(key string, bucket *TokenBucket, _ time.Duration) error

type HttpServer

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

func NewHttpServer

func NewHttpServer(limiter Limiter, logger *log.Logger) *HttpServer

func (*HttpServer) ServeHTTP

func (s *HttpServer) ServeHTTP(w http.ResponseWriter, req *http.Request)

type Limiter

type Limiter interface {
	Get(key string) (int64, error)
	Post(key string, count int64, limit int64, duration time.Duration) (int64, error)
	Delete(key string) error
}

type MemcacheStorage

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

func NewMemcacheStorage

func NewMemcacheStorage(client *memcache.Client, prefix string) *MemcacheStorage

func (*MemcacheStorage) Delete

func (ms *MemcacheStorage) Delete(key string) error

func (*MemcacheStorage) Get

func (ms *MemcacheStorage) Get(key string) (*TokenBucket, error)

func (*MemcacheStorage) Set

func (ms *MemcacheStorage) Set(key string, bucket *TokenBucket, duration time.Duration) error

type RedisStorage

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

func NewRedisStorage

func NewRedisStorage(pool *redis.Pool, prefix string) *RedisStorage

func (*RedisStorage) Delete

func (rs *RedisStorage) Delete(key string) error

func (*RedisStorage) Get

func (rs *RedisStorage) Get(key string) (*TokenBucket, error)

func (*RedisStorage) Set

func (rs *RedisStorage) Set(key string, bucket *TokenBucket, duration time.Duration) error

type SingleThreadLimiter

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

func NewSingleThreadLimiter

func NewSingleThreadLimiter(storage Storage) *SingleThreadLimiter

func (*SingleThreadLimiter) Delete

func (l *SingleThreadLimiter) Delete(key string) error

func (*SingleThreadLimiter) Get

func (l *SingleThreadLimiter) Get(key string) (int64, error)

func (*SingleThreadLimiter) Post

func (l *SingleThreadLimiter) Post(key string, count, limit int64, duration time.Duration) (int64, error)

func (*SingleThreadLimiter) Start

func (l *SingleThreadLimiter) Start()

func (*SingleThreadLimiter) Stop

func (l *SingleThreadLimiter) Stop()

type Storage

type Storage interface {
	Get(key string) (*TokenBucket, error)
	Set(key string, bucket *TokenBucket, expire time.Duration) error
	Delete(key string) error
}

type TokenBucket

type TokenBucket struct {
	Used           float64
	LastAccessTime time.Time
	Limit          float64
	Duration       time.Duration
}

func NewTokenBucket

func NewTokenBucket(limit float64, duration time.Duration) *TokenBucket

func (*TokenBucket) Consume

func (bucket *TokenBucket) Consume(count float64) error

func (*TokenBucket) GetAdjustedUsage

func (bucket *TokenBucket) GetAdjustedUsage(now time.Time) float64