ratelimit

README

ratelimit

This is a fork of: https://github.com/RussellLuo/caddy-ext

All rights belong to the original fork and the only reason this fork exist is to move the contents of github.com/RussellLuo/caddy-ext/tree/master/ratelimit to the top level of a repositoy.

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 <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}
  • {remote.port}
  • {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. 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 another 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 Zone
  • func NewZone(size int, rateSize time.Duration, rateLimit int64) (*Zone, error)
  • func (z *Zone) Allow(key string) bool
  • func (z *Zone) Purge()

Types

type RateLimit

type RateLimit struct {
	Key              string `json:"key,omitempty"`
	Rate             string `json:"rate,omitempty"`
	ZoneSize         int    `json:"zone_size,omitempty"`
	RejectStatusCode int    `json:"reject_status,omitempty"`
	// contains filtered or unexported fields
}

RateLimit implements a handler for rate-limiting.

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 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.