httplimit

Documentation

Overview

Package httplimit provides middleware for rate limiting HTTP handlers.

The implementation is designed to work with Go's built-in http.Handler and http.HandlerFunc interfaces, so it will also work with any popular web frameworks that support middleware with these properties.

Index

• Constants
• type KeyFunc
  • func IPKeyFunc(headers ...string) KeyFunc
• type Middleware
  • func NewMiddleware(s limiter.Store, f KeyFunc) (*Middleware, error)
  • func (m *Middleware) Handle(next http.Handler) http.Handler

Constants

const (
	// HeaderRateLimitLimit, HeaderRateLimitRemaining, and HeaderRateLimitReset
	// are the recommended return header values from IETF on rate limiting. Reset
	// is in UTC time.
	HeaderRateLimitLimit     = "X-RateLimit-Limit"
	HeaderRateLimitRemaining = "X-RateLimit-Remaining"
	HeaderRateLimitReset     = "X-RateLimit-Reset"

	// HeaderRetryAfter is the header used to indicate when a client should retry
	// requests (when the rate limit expires), in UTC time.
	HeaderRetryAfter = "Retry-After"
)

Types

type KeyFunc

type KeyFunc func(r *http.Request) (string, error)

KeyFunc is a function that accepts an http request and returns a string key that uniquely identifies this request for the purpose of rate limiting.

KeyFuncs are called on each request, so be mindful of performance and implement caching where possible. If a KeyFunc returns an error, the HTTP handler will return Internal Server Error and will NOT take from the limiter store.

func IPKeyFunc

func IPKeyFunc(headers ...string) KeyFunc

IPKeyFunc returns a function that keys data based on the incoming requests IP address. By default this uses the RemoteAddr, but you can also specify a list of headers which will be checked for an IP address first (e.g. "X-Forwarded-For"). Headers are retrieved using Header.Get(), which means they are case insensitive.

type Middleware

type Middleware struct {
	// contains filtered or unexported fields
}

Middleware is a handler/mux that can wrap other middlware to implement HTTP rate limiting. It can rate limit based on an arbitrary KeyFunc, and supports anything that implements limiter.StoreWithContext.

func NewMiddleware

func NewMiddleware(s limiter.Store, f KeyFunc) (*Middleware, error)

NewMiddleware creates a new middleware suitable for use as an HTTP handler. This function returns an error if either the Store or KeyFunc are nil.

func (*Middleware) Handle

func (m *Middleware) Handle(next http.Handler) http.Handler

Handle returns the HTTP handler as a middleware. This handler calls Take() on the store and sets the common rate limiting headers. If the take is successful, the remaining middleware is called. If take is unsuccessful, the middleware chain is halted and the function renders a 429 to the caller with metadata about when it's safe to retry.