ratelimit

README

ratelimit

A Caddy v2 extension to apply rate-limiting for HTTP requests.

Installation

$ xcaddy build --with github.com/RussellLuo/caddy-ext/ratelimit

Caddyfile Syntax

rate_limit [<matcher>] <key> <rate> [<zone_size> [<reject_status>]]

Parameters:

• <key>: The variable used to differentiate one client from another. Currently supported variables (Caddy shorthand placeholders):
  • {path.<var>}
  • {query.<var>}
  • {header.<VAR>}
  • {cookie.<var>}
  • {body.<var>} (requires the requestbodyvar extension)
  • {remote.host} (ignores the X-Forwarded-For header)
  • {remote.port}
  • {remote.ip} (prefers the first IP in the X-Forwarded-For header)
  • {remote.host_prefix.<bits>} (CIDR block version of {remote.host})
  • {remote.ip_prefix.<bits>} (CIDR block version of {remote.ip})
• <rate>: The request rate limit (per key value) specified in requests per second (r/s) or requests per minute (r/m).
• <zone_size>: The size (i.e. the number of key values) of the LRU zone that keeps states of these key values. Defaults to 10,000.
• <reject_status>: The HTTP status code of the response when a client exceeds the rate limit. Defaults to 429 (Too Many Requests).

Example

With the following Caddyfile:

localhost:8080 {
    route /foo {
        rate_limit {query.id} 2r/m

        respond 200
    }
}

You can apply the rate of 2 requests per minute to the path /foo, and Caddy will respond with status code 429 when a client exceeds:

$ curl -w "%{http_code}" 'https://localhost:8080/foo?id=1'
200
$ curl -w "%{http_code}" 'https://localhost:8080/foo?id=1'
200
$ curl -w "%{http_code}" 'https://localhost:8080/foo?id=1'
429

An extra request with other value for the request parameter id will not be limited:

$ curl -w "%{http_code}" 'https://localhost:8080/foo?id=2'
200

Documentation

Index

• type RateLimit
  • func (RateLimit) CaddyModule() caddy.ModuleInfo
  • func (rl *RateLimit) Cleanup() error
  • func (rl *RateLimit) Provision(ctx caddy.Context) (err error)
  • func (rl *RateLimit) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (rl *RateLimit) UnmarshalCaddyfile(d *caddyfile.Dispenser) (err error)
  • func (rl *RateLimit) Validate() error
• type Var
  • func ParseVar(s string) (*Var, error)
  • func (v *Var) Evaluate(r *http.Request) (value string, err error)
• type Zone
  • func NewZone(size int, rateSize time.Duration, rateLimit int64) (*Zone, error)
  • func (z *Zone) Allow(key string) bool
  • func (z *Zone) Purge()
  • func (z *Zone) RateLimitPolicyHeader() string

Types

type RateLimit

type RateLimit struct {
	// The variable used to differentiate one client from another.
	//
	// Currently supported variables:
	//
	// - `{path.<var>}`
	// - `{query.<var>}`
	// - `{header.<VAR>}`
	// - `{cookie.<var>}`
	// - `{body.<var>}` (requires the [requestbodyvar](https://github.com/RussellLuo/caddy-ext/tree/master/requestbodyvar) extension)
	// - `{remote.host}` (ignores the `X-Forwarded-For` header)
	// - `{remote.port}`
	// - `{remote.ip}` (prefers the first IP in the `X-Forwarded-For` header)
	// - `{remote.host_prefix.<bits>}` (CIDR block version of `{remote.host}`)
	// - `{remote.ip_prefix.<bits>}` (CIDR block version of `{remote.ip}`)
	Key string `json:"key,omitempty"`

	// The request rate limit (per key value) specified in requests
	// per second (r/s) or requests per minute (r/m).
	Rate string `json:"rate,omitempty"`

	// The size (i.e. the number of key values) of the LRU zone that
	// keeps states of these key values. Defaults to 10,000.
	ZoneSize int `json:"zone_size,omitempty"`

	// The HTTP status code of the response when a client exceeds the rate.
	// Defaults to 429 (Too Many Requests).
	RejectStatusCode int `json:"reject_status,omitempty"`
	// contains filtered or unexported fields
}

RateLimit implements a handler for rate-limiting.

If a client exceeds the rate limit, an HTTP error with status `<reject_status>` will be returned. This error can be handled using the conventional error handlers. See [handle_errors](https://caddyserver.com/docs/caddyfile/directives/handle_errors) for how to set up error handlers.

func (RateLimit) CaddyModule

func (RateLimit) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*RateLimit) Cleanup

func (rl *RateLimit) Cleanup() error

Cleanup cleans up the resources made by rl during provisioning.

func (*RateLimit) Provision

func (rl *RateLimit) Provision(ctx caddy.Context) (err error)

Provision implements caddy.Provisioner.

func (*RateLimit) ServeHTTP

func (rl *RateLimit) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*RateLimit) UnmarshalCaddyfile

func (rl *RateLimit) UnmarshalCaddyfile(d *caddyfile.Dispenser) (err error)

func (*RateLimit) Validate

func (rl *RateLimit) Validate() error

Validate implements caddy.Validator.

type Var

type Var struct {
	Raw  string
	Name string
	Bits int
}

func ParseVar

func ParseVar(s string) (*Var, error)

ParseVar transforms shorthand variables into Caddy-style placeholders.

Examples for shorthand variables:

- `{path.<var>}` - `{query.<var>}` - `{header.<VAR>}` - `{cookie.<var>}` - `{body.<var>}` - `{remote.host}` - `{remote.port}` - `{remote.ip}` - `{remote.host_prefix.<bits>}` - `{remote.ip_prefix.<bits>}`

func (*Var) Evaluate

func (v *Var) Evaluate(r *http.Request) (value string, err error)

type Zone

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

func NewZone

func NewZone(size int, rateSize time.Duration, rateLimit int64) (*Zone, error)

func (*Zone) Allow

func (z *Zone) Allow(key string) bool

func (*Zone) Purge

func (z *Zone) Purge()

Purge is used to completely clear the zone.

func (*Zone) RateLimitPolicyHeader

func (z *Zone) RateLimitPolicyHeader() string