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.