rl

README

rl

rl is a rate limit middleware for multiple limit rules.

Usage

Prepare an instance that implements rl.Limiter interface.

Then, generate the middleware ( func(next http.Handler) http.Handler ) with rl.New

package main

import (
    "log"
    "net/http"

    "github.com/2manymws/rl"
)

func main() {
    r := http.NewServeMux()
    r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello World"))
    })

    var l rl.Limiter = newMyLimiter()
    m := rl.New(l)

    log.Fatal(http.ListenAndServe(":8080", m(r)))
}

Rate limiting approach

rl uses the Sliding Window Counter pattern same as go-chi/httprate.

• https://blog.cloudflare.com/counting-things-a-lot-of-different-things/
• https://www.figma.com/blog/an-alternative-approach-to-rate-limiting/

Reference

• go-chi/httprate
  • Most of rl's rate limit implementations refer to httprate. Thanks for the simple and clean implementation!

Documentation

Index

• Variables
• func New(limiters ...Limiter) func(next http.Handler) http.Handler
• type Context
  • func (e *Context) Error() string
• type Counter
• type Limiter
• type Rule

Variables

var ErrRateLimitExceeded error = errors.New("rate limit exceeded")

Functions

func New

func New(limiters ...Limiter) func(next http.Handler) http.Handler

New returns a new rate limiter middleware. The order of the limitters should be arranged in **reverse** order of Limitter with strict rate limit to return appropriate X-RateLimit-* headers to the client.

Types

type Context

type Context struct {
	StatusCode         int
	Err                error
	Limiter            *limiter
	RequestLimit       int
	WindowLen          time.Duration
	RateLimitRemaining int
	RateLimitReset     int
	Next               http.Handler
	Key                string
	// contains filtered or unexported fields
}

Context is the error returned by the middleware.

func (*Context) Error

func (e *Context) Error() string

Error returns the error message.

type Counter

type Counter interface {
	// Get returns the current count for the key and window
	Get(key string, window time.Time) (count int, err error) //nostyle:getters
	// Increment increments the count for the key and window
	Increment(key string, currWindow time.Time) error
}

type Limiter

type Limiter interface {
	// Name returns the name of the limiter
	Name() string
	// Rule returns the key and rate limit rule for the request
	Rule(r *http.Request) (rule *Rule, err error)
	// ShouldSetXRateLimitHeaders returns true if the X-RateLimit-* headers should be set
	ShouldSetXRateLimitHeaders(*Context) bool
	// OnRequestLimit returns the handler to be called when the rate limit is exceeded
	OnRequestLimit(*Context) http.HandlerFunc
}

type Rule

type Rule struct {
	// Key for the rate limit
	Key string
	// ReqLimit is the request limit for the window
	// If ReqLimit is negative, the limiter is skipped
	ReqLimit int
	// WindowLen is the length of the window
	WindowLen time.Duration
	// IgnoreAfter is true if skip all limiters after this limiter
	IgnoreAfter bool
}

Rule is a rate limit rule