tollbooth

package module
v0.0.0-...-605330a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2016 License: MIT Imports: 7 Imported by: 0

README

GoDoc license

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

Constants

This section is empty.

Variables

This section is empty.

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

Types

This section is empty.

Directories

Path Synopsis
Package config provides data structure to configure rate-limiter.
Package config provides data structure to configure rate-limiter.
Package errors provide data structure for errors.
Package errors provide data structure for errors.
Package libstring provides various string related functions.
Package libstring provides various string related functions.
thirdparty

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL