rate

Documentation

Overview

Package rate implements rate limiter for Iris client requests. Example can be found at: _examples/request-ratelimit/main.go.

Index

• Constants
• func Every(interval time.Duration) float64
• func Limit(limit float64, burst int, options ...Option) context.Handler
• func SetIdentifier(ctx *context.Context, key string)
• type Client
  • func Get(ctx *context.Context) *Client
  • func (c *Client) DurationFromTokens(tokens float64) time.Duration
  • func (c *Client) LastSeen() time.Time
  • func (c *Client) TokensFromDuration(d time.Duration) float64
• type Limiter
  • func (l *Limiter) Purge(condition func(*Client) bool)
• type Option
  • func ClientData(clientDataFunc func(ctx *context.Context) interface{}) Option
  • func ExceedHandler(handler context.Handler) Option
  • func PurgeEvery(every time.Duration, maxLifetime time.Duration) Option

Constants

const Inf = math.MaxFloat64

Inf is the infinite rate limit; it allows all events (even if burst is zero).

Functions

func Every

func Every(interval time.Duration) float64

Every converts a minimum time interval between events to a limit. Usage: Limit(Every(1*time.Minute), 3, options...)

func Limit

func Limit(limit float64, burst int, options ...Option) context.Handler

Limit returns a new rate limiter handler that allows requests up to rate "limit" and permits bursts of at most "burst" tokens. See `rate.SetKey(ctx, key string)` and `rate.Get` too.

E.g. Limit(1, 5) to allow 1 request per second, with a maximum burst size of 5.

See `ExceedHandler`, `ClientData` and `PurgeEvery` for the available "options".

func SetIdentifier

func SetIdentifier(ctx *context.Context, key string)

SetIdentifier can be called manually from a handler or a middleare to change the identifier per client. The default key for a client is its Remote IP.

Types

type Client

type Client struct {
	ID      string
	Data    interface{}
	Limiter *rate.Limiter
	// contains filtered or unexported fields
}

Client holds some request information and the rate limiter itself. It can be retrieved by the `Get` package-level function. It can be used to manually add RateLimit response headers.

func Get

func Get(ctx *context.Context) *Client

Get returns the current rate limited `Client`. Use it when you want to log or add response headers based on the current request limitation.

You can read more about X-RateLimit response headers at: https://tools.ietf.org/id/draft-polli-ratelimit-headers-00.html. A good example of that is the GitHub API itself: https://developer.github.com/v3/#rate-limiting

func (*Client) DurationFromTokens

func (c *Client) DurationFromTokens(tokens float64) time.Duration

DurationFromTokens is a unit conversion function from the number of tokens to the duration of time it takes to accumulate them at a rate of limit tokens per second.

func (*Client) LastSeen

func (c *Client) LastSeen() time.Time

LastSeen reports the last Client's visit.

func (*Client) TokensFromDuration

func (c *Client) TokensFromDuration(d time.Duration) float64

TokensFromDuration is a unit conversion function from a time duration to the number of tokens which could be accumulated during that duration at a rate of limit tokens per second.

type Limiter

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

Limiter is featured with the necessary functions to limit requests per second. It has a single exported method `Purge` which helps to manually remove old clients from the memory. Limiter is not exposed by a function, callers should use it inside an `Option` for the `Limit` package-level function.

func (*Limiter) Purge

func (l *Limiter) Purge(condition func(*Client) bool)

Purge removes client entries from the memory based on the given "condition".

type Option

type Option func(*Limiter)

Option declares a function which can be passed on `Limit` package-level to modify its internal fields. Available Options are: * ExceedHandler * ClientData * PurgeEvery

func ClientData

func ClientData(clientDataFunc func(ctx *context.Context) interface{}) Option

ClientData is an `Option` that can be passed at the `Limit` package-level function. It accepts a function which provides the Iris Context and should return custom data that will be stored to the Client and be retrieved as `Get(ctx).Client.Data` later on.

func ExceedHandler

func ExceedHandler(handler context.Handler) Option

ExceedHandler is an `Option` that can be passed at the `Limit` package-level function. It accepts a handler that will be executed every time a client tries to reach a page/resource which is not accessible for that moment.

func PurgeEvery

func PurgeEvery(every time.Duration, maxLifetime time.Duration) Option

PurgeEvery is an `Option` that can be passed at the `Limit` package-level function. This function will check for old entries and remove them.

E.g. Limit(..., PurgeEvery(time.Minute, 5*time.Minute)) to check every 1 minute if a client's last visit was 5 minutes ago ("old" entry) and remove it from the memory.