tollbooth

README

Tollbooth

This is a generic middleware to rate-limit HTTP requests.

NOTE: This library is considered finished, any new activities are probably centered around thirdparty modules.

Five Minutes Tutorial

TTL is the interval when emiting a token.
max is the capacity of the token bucket, generally larger than time.Second/TTL.

package main

import (
    "github.com/wallstreetcn/tollbooth"
    "net/http"
    "time"
)

func HelloHandler(w http.ResponseWriter, req *http.Request) {
    w.Write([]byte("Hello, World!"))
}

func main() {
    // Create a request limiter per handler.
    http.Handle("/", tollbooth.LimitFuncHandler(tollbooth.NewLimiter(1, time.Second), HelloHandler))
    http.ListenAndServe(":12345", nil)
}

Features

1. Rate-limit by request's remote IP, path, methods, custom headers, & basic auth usernames.
   Register API limit for the specified path and method using regexp.

   limiter := tollbooth.NewLimiter(1, time.Second)
   
   // Configure list of places to look for IP address.
   // By default it's: "RemoteAddr", "X-Forwarded-For", "X-Real-IP"
   // If your application is behind a proxy, set "X-Forwarded-For" first.
   limiter.IPLookups = []string{"RemoteAddr", "X-Forwarded-For", "X-Real-IP"}
   
   // Limit only GET and POST requests.
   limiter.Methods = []string{"GET", "POST"}
   
   // Limit request headers containing certain values.
   // Typically, you prefetched these values from the database.
   limiter.Headers = []string{"X-Access-Token"}
   
   // Limit based on basic auth usernames.
   // Typically, you prefetched these values from the database.
   limiter.BasicAuthUsers = []string{"bob", "joe", "wallstreetcn"}
   
   // Rate-Limit the expensive API with 1 ops/min.
   tollbooth.RegisterAPI("/some-expensive-api", "POST", 1, time.Minute)
   

2. Each request handler can be rate-limited individually.

3. Compose your own middleware by using LimitByKeys().

4. Tollbooth does not require external storage since it uses an algorithm called Token Bucket (Go library: golang.org/x/time/rate).

Benchmark

Use single redis on MacBook Pro (Retina, 13-inch, Late 2013), CPU 2.4 GHz Intel Core i5, Memory 8 GB 1600 MHz DDR3.

$ go test -bench=.                                                                                                                                  ⬡ 4.4.5 [±master ●]
BenchmarkLimitByKeys-4                     20000            143600 ns/op
BenchmarkBuildKeys-4                     2000000               735 ns/op
BenchmarkBuildKeysWithLongKey-4          2000000               634 ns/op
PASS
ok      github.com/wallstreetcn/tollbooth       9.024s

Other Web Frameworks

Support for other web frameworks are defined under /thirdparty directory.

Documentation

Overview

Package tollbooth provides rate-limiting logic to HTTP request handler.

Index

• func BuildKeys(limiter *config.Limiter, r *http.Request) [][]string
• func LimitByKeys(limiter *config.Limiter, keys []string, limitVal *config.LimitValue) *errors.HTTPError
• func LimitByRequest(limiter *config.Limiter, r *http.Request) *errors.HTTPError
• func LimitFuncHandler(limiter *config.Limiter, nextFunc func(http.ResponseWriter, *http.Request)) http.Handler
• func LimitHandler(limiter *config.Limiter, next http.Handler) http.Handler
• func NewLimiter(max int64, ttl time.Duration, conf *rate.ConfigRedis) *config.Limiter
• func RegisterAPI(path string, method string, max int64, duration time.Duration)
• func Reset()
• func SetResponseHeaders(limiter *config.Limiter, w http.ResponseWriter)

Functions

func BuildKeys

func BuildKeys(limiter *config.Limiter, r *http.Request) [][]string

BuildKeys generates a slice of keys to rate-limit by given config and request structs.

func LimitByKeys

func LimitByKeys(limiter *config.Limiter, keys []string, limitVal *config.LimitValue) *errors.HTTPError

LimitByKeys keeps track number of request made by keys separated by pipe. It returns HTTPError when limit is exceeded.

func LimitByRequest

func LimitByRequest(limiter *config.Limiter, r *http.Request) *errors.HTTPError

LimitByRequest builds keys based on http.Request struct, loops through all the keys, and check if any one of them returns HTTPError.

func LimitFuncHandler

func LimitFuncHandler(limiter *config.Limiter, nextFunc func(http.ResponseWriter, *http.Request)) http.Handler

LimitFuncHandler is a middleware that performs rate-limiting given request handler function.

func LimitHandler

func LimitHandler(limiter *config.Limiter, next http.Handler) http.Handler

LimitHandler is a middleware that performs rate-limiting given http.Handler struct.

func NewLimiter

func NewLimiter(max int64, ttl time.Duration, conf *rate.ConfigRedis) *config.Limiter

NewLimiter is a convenience function to config.NewLimiter.

func RegisterAPI

func RegisterAPI(path string, method string, max int64, duration time.Duration)

RegisterAPI registers rate limit for the specified API.

func Reset

func Reset()

Reset resets the rate limit settings.

func SetResponseHeaders

func SetResponseHeaders(limiter *config.Limiter, w http.ResponseWriter)

SetResponseHeaders configures X-Rate-Limit-Limit and X-Rate-Limit-Duration.