ratelimit

Documentation

Overview

Package ratelimit implements rate limiting functionality for the proxy.

It provides per process rate limiting. It can be configured globally, or based on routes. Rate limiting can be lookuped based on HTTP headers like X-Forwarded-For or Authorization.

Lookuper Type - Authorization Header

This lookuper will use the content of the Authorization header to calculate rate limiting. This will work for Bearer tokens or Basic Auth without change of the rate limiter configuration.

Lookuper Type - X-Forwarded-For Header

This lookuper will use the remote IP of the origin request to calculate rate limiting. If there is no such header it will use the remote IP of the request. This is the default Lookuper and may be the one most users want to use.

Usage

When imported as a package, the Registry can be used to hold the rate limiters and their settings. On a higher level, rate limiter settings can be simply passed to skipper as part of the skipper.Options object, or defined as command line flags.

The following command starts skipper with default X-Forwarded-For Lookuper, that will start to rate limit after 5 requests within 60s from the same client

% skipper -ratelimits type=local,max-hits=5,time-window=60s

The following configuration will rate limit /foo after 2 requests within 90s from the same requester and all other requests after 20 requests within 60s from the same client

% cat ratelimit.eskip
foo: Path("/foo") -> localRatelimit(2,"1m30s") -> "http://www.example.org/foo"
rest: Path("/") -> localRatelimit(20,"1m") -> "http://www.example.net/"
% skipper -enable-ratelimits -routes-file=ratelimit.eskip

The following configuration will rate limit requests after 100 requests within 1 minute with the same Authorization Header

% cat ratelimit-auth.eskip
all: Path("/") -> localRatelimit(100,"1m","auth") -> "http://www.example.org/"
% skipper -enable-ratelimits -routes-file=ratelimit-auth.eskip

Rate limiter settings can be applied globally via command line flags or within routing settings.

Settings - Type

Defines the type of the rate limiter, which right now only allows to be "local". In case of a skipper swarm or service mesh this would be an interesting configuration option, for example "global" or "dc".

Settings - MaxHits

Defines the maximum number of requests per user within a TimeWindow.

Settings - TimeWindow

Defines the time window until rate limits will be enforced, if maximum number of requests are exceeded. This is defined as a string representation of Go's time.Duration, e.g. 1m30s.

Settings - Lookuper

Defines an optional configuration to choose which Header should be used to group client requests. It accepts the default "x-forwarded-for" or "auth"

HTTP Response

In case of rate limiting, the HTTP response status will be 429 Too Many Requests, and a header will be set which shows the maximum requests per hour (based on RFC 6585):

X-Rate-Limit: 6000

Registry

The active rate limiters are stored in a registry. They are created based on routes or command line flags. The registry synchronizes access to the shared rate limiters. A registry has default settings that it will apply and that it will use the disable rate limiter in case it's not defined in the configuration or not global enabled.

Index

• Constants
• type AuthLookuper
  • func NewAuthLookuper() AuthLookuper
  • func (_ AuthLookuper) Lookup(req *http.Request) string
• type Lookuper
• type Ratelimit
  • func (l *Ratelimit) Allow(s string) bool
  • func (l *Ratelimit) Close()
• type Registry
  • func NewRegistry(settings ...Settings) *Registry
  • func (r *Registry) Check(req *http.Request) (Settings, bool)
  • func (r *Registry) Get(s Settings) *Ratelimit
• type SameBucketLookuper
  • func NewSameBucketLookuper() SameBucketLookuper
  • func (_ SameBucketLookuper) Lookup(req *http.Request) string
• type Settings
  • func (s Settings) Empty() bool
  • func (s Settings) String() string
• type Type
• type XForwardedForLookuper
  • func NewXForwardedForLookuper() XForwardedForLookuper
  • func (_ XForwardedForLookuper) Lookup(req *http.Request) string

Constants

const (
	// Header is
	Header = "X-Rate-Limit"
	// ServiceRatelimitName is the name of the Ratelimit filter, which will be shown in log
	ServiceRatelimitName = "ratelimit"
	// LocalRatelimitName is the name of the LocalRatelimit filter, which will be shown in log
	LocalRatelimitName = "localRatelimit"
	// DisableRatelimitName is the name of the DisableRatelimit, which will be shown in log
	DisableRatelimitName = "disableRatelimit"
)

const (
	DefaultMaxhits       = 20
	DefaultTimeWindow    = 1 * time.Second
	DefaultCleanInterval = 60 * time.Second
)

Types

type AuthLookuper

type AuthLookuper struct{}

AuthLookuper implements Lookuper interface and will select a bucket by Authorization header.

func NewAuthLookuper

func NewAuthLookuper() AuthLookuper

NewAuthLookuper returns an empty AuthLookuper

func (AuthLookuper) Lookup

func (_ AuthLookuper) Lookup(req *http.Request) string

Lookup returns the content of the Authorization header.

type Lookuper

type Lookuper interface {
	// Lookup is used to get the string which is used to define
	// how the bucket of a ratelimiter looks like, which is used
	// to decide to ratelimit or not. For example you can use the
	// X-Forwarded-For Header if you want to rate limit based on
	// source ip behind a proxy/loadbalancer or the Authorization
	// Header for request per token or user.
	Lookup(*http.Request) string
}

Lookuper makes it possible to be more flexible for ratelimiting.

type Ratelimit

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

Ratelimit is a proxy objects that delegates to implemetations and stores settings for the ratelimiter

func (*Ratelimit) Allow

func (l *Ratelimit) Allow(s string) bool

Allow returns true if the s is not ratelimited, false if it is ratelimited

func (*Ratelimit) Close

func (l *Ratelimit) Close()

Close will stop a cleanup goroutines in underlying implementation.

type Registry

type Registry struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Registry objects hold the active ratelimiters, ensure synchronized access to them, apply default settings and recycle the idle ratelimiters.

func NewRegistry

func NewRegistry(settings ...Settings) *Registry

NewRegistry initializes a registry with the provided default settings.

func (*Registry) Check

func (r *Registry) Check(req *http.Request) (Settings, bool)

Check returns Settings used and false in case of request is ratelimitted and false otherwise.

func (*Registry) Get

func (r *Registry) Get(s Settings) *Ratelimit

Get returns a Ratelimit instance for provided Settings

type SameBucketLookuper

type SameBucketLookuper struct{}

SameBucketLookuper implements Lookuper interface and will always match to the same bucket.

func NewSameBucketLookuper

func NewSameBucketLookuper() SameBucketLookuper

NewSameBucketLookuper returns a SameBucketLookuper.

func (SameBucketLookuper) Lookup

func (_ SameBucketLookuper) Lookup(req *http.Request) string

Lookup will always return "s" to select the same bucket.

type Settings

type Settings struct {
	Type          Type
	Lookuper      Lookuper
	Host          string
	MaxHits       int
	TimeWindow    time.Duration
	CleanInterval time.Duration
}

Settings configures the chosen rate limiter

func (Settings) Empty

func (s Settings) Empty() bool

func (Settings) String

func (s Settings) String() string

type Type

type Type int

Type defines the type of the used breaker: consecutive, rate or disabled.

const (
	// NoRatelimit is not used
	NoRatelimit Type = iota
	// ServiceRatelimit is used to have a simple rate limit for a
	// backend service, which is calculated and measured within
	// each instance
	ServiceRatelimit
	// LocalRatelimit is used to have a simple local rate limit
	// per user for a backend, which is calculated and measured
	// within each instance
	LocalRatelimit
	// DisableRatelimit is used to disable rate limit
	DisableRatelimit
)

type XForwardedForLookuper

type XForwardedForLookuper struct{}

XForwardedForLookuper implements Lookuper interface and will select a bucket by X-Forwarded-For header or clientIP.

func NewXForwardedForLookuper

func NewXForwardedForLookuper() XForwardedForLookuper

NewXForwardedForLookuper returns an empty XForwardedForLookuper

func (XForwardedForLookuper) Lookup

func (_ XForwardedForLookuper) Lookup(req *http.Request) string

Lookup returns the content of the X-Forwarded-For header or the clientIP if not set.