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

package main

import (
    "github.com/didip/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.

   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 = make(map[string][]string)
   limiter.Headers["X-Access-Token"] = []string{"abc123", "xyz098"}
   
   // Limit based on basic auth usernames.
   // Typically, you prefetched these values from the database.
   limiter.BasicAuthUsers = []string{"bob", "joe", "didip"}
   

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).

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) *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) *config.Limiter
• 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) *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) *config.Limiter

NewLimiter is a convenience function to config.NewLimiter.

func SetResponseHeaders

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

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