ratelimit

README

Rate Limit HTTP middleware

Golang package for rate limiting HTTP endpoints based on context and request headers.

Under development

Goals

• Simple but powerful API
• Token Bucket algorithm (rate + burst)
• Storage independent (Redis, In-Memory or any other K/V store)

License

Copyright (c) 2016 Vojtech Vitek

Licensed under the MIT License.

Documentation

Index

• func DownloadSpeed(keyFn KeyFn) *downloadBuilder
• func IP(r *http.Request) string
• func NOP(r *http.Request) string
• func Request(keyFn KeyFn) *requestBuilder
• func Throttle(limit int) func(http.Handler) http.Handler
• type KeyFn
• type TokenBucketStore

Examples

• DownloadSpeed
• Request
• Throttle

Functions

func DownloadSpeed

func DownloadSpeed(keyFn KeyFn) *downloadBuilder

Example

Watch the download speed with wget http://localhost:3333/file -q --show-progress

package main

import (
	"net/http"
	"time"

	"github.com/VojtechVitek/ratelimit"
	"github.com/VojtechVitek/ratelimit/memory"
)

func main() {
	middleware := ratelimit.DownloadSpeed(ratelimit.IP).Rate(1024, time.Second).LimitBy(memory.New())

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		http.ServeFile(w, r, "/dev/random")
	})

	http.ListenAndServe(":3333", middleware(handler))
}

func IP

func IP(r *http.Request) string

IP returns unique key per request IP.

func NOP

func NOP(r *http.Request) string

NOP returns empty key for each request.

func Request

func Request(keyFn KeyFn) *requestBuilder

Example

package main

import (
	"net/http"
	"time"

	"github.com/VojtechVitek/ratelimit"
	"github.com/VojtechVitek/ratelimit/memory"
)

func main() {
	middleware := ratelimit.Request(ratelimit.IP).Rate(30, time.Minute).LimitBy(memory.New())

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello World!"))
	})

	http.ListenAndServe(":3333", middleware(handler))
}

func Throttle

func Throttle(limit int) func(http.Handler) http.Handler

Throttle is a middleware that limits number of currently processed requests at a time.

Example

package main

import (
	"net/http"
	"time"

	"github.com/VojtechVitek/ratelimit"
)

func main() {
	middleware := ratelimit.Throttle(1)

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("working hard...\n\n"))
		if f, ok := w.(http.Flusher); ok {
			f.Flush()
		}
		time.Sleep(10 * time.Second)
		w.Write([]byte("done"))
	})

	http.ListenAndServe(":3333", middleware(handler))
}

Types

type KeyFn

type KeyFn func(r *http.Request) string

KeyFn is a function returning bucket key depending on request data.

type TokenBucketStore

type TokenBucketStore interface {
	InitRate(rate int, window time.Duration)
	Take(key string) (taken bool, remaining int, reset time.Time, err error)
}

TokenBucketStore is an interface for for any storage implementing Token Bucket algorithm.