rate

package
v14.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: BSD-3-Clause, BSD-3-Clause Imports: 6 Imported by: 0

README

Request Rate Limiting Middleware for Iris

This middleware caps how fast a client may send requests. It uses a token bucket per client: requests spend tokens, the bucket refills at the rate you set, and a request that finds it empty is rejected. The bucket's size is what lets a client burst above the steady rate for a short while.

Installation

To use the rate middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v14/middleware/rate"

Usage

Basic Setup

To use the rate limiter, you need to create an Iris application and register the middleware. Below is an example of how to set up the rate limiter:

package main

import (
	"time"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	limit := rate.Limit(1, 5, rate.Options{
		PurgeEvery:       time.Minute,
		PurgeMaxLifetime: 5 * time.Minute,
	})
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}

This example allows 1 request per second with a maximum burst size of 5. It also purges old entries every minute if they haven't been seen for 5 minutes.

Using rate.Every Helper

This example demonstrates how to use the rate.Every helper to set up a rate limiter:

package main

import (
	"time"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Use rate.Every helper to set up the rate limiter.
	limit := rate.Limit(rate.Every(time.Minute), 5, rate.Options{})
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}
Using API Key for Rate Limiting

This example demonstrates how to set up a rate limiter that uses an API key instead of the client's remote IP address:

package main

import (
	"time"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/rate"
	"github.com/kataras/iris/v14/rest/errors"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Use API key for rate limiting.
	app.Use(useAPIKey)

	limit := rate.Limit(rate.Every(time.Minute), 300, rate.Options{
		PurgeEvery:       5 * time.Minute,
		PurgeMaxLifetime: 15 * time.Minute,
	})
	app.Use(limit)

	app.Get("/list", list)

	app.Listen(":8080")
}

func useAPIKey(ctx iris.Context) {
	apiKey := ctx.Header("X-API-Key")
	if apiKey == "" {
		// The error code carries the 403 and stops the chain.
		errors.PermissionDenied.Message(ctx, "the X-API-Key header is required")
		return
	}

	rate.SetIdentifier(ctx, apiKey)
	ctx.Next()
}

func list(ctx iris.Context) {
	ctx.JSON(iris.Map{"key": "value"})
}
Custom Exceed Handler

This example demonstrates how to set a custom handler to be executed when the rate limit is exceeded:

package main

import (
	"time"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/rate"
	"github.com/kataras/iris/v14/rest/errors"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Set a custom exceed handler. errors.DefaultRateLimitExceededHandler is
	// the canonical one: 429 RESOURCE_EXHAUSTED with the wait in the detail.
	limit := rate.Limit(1, 5, rate.Options{
		ExceedHandler: func(ctx iris.Context) {
			errors.ResourceExhausted.Messagef(ctx, "slow down, %s", rate.Get(ctx).Delay)
		},
	})
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}
Custom Client Data

This example demonstrates how to store custom data for each client:

package main

import (
	"time"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/rate"
)

func main() {
	app := iris.New()
	app.Logger().SetLevel("debug")

	// Store custom data for each client.
	limit := rate.Limit(1, 5, rate.Options{
		ClientData: func(ctx iris.Context) any {
			return ctx.RemoteAddr()
		},
	})
	app.Use(limit)

	app.Get("/", index)
	app.Get("/other", other)

	app.Listen(":8080")
}

func index(ctx iris.Context) {
	ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
	ctx.HTML("<h1>Other Page</h1>")
}
Explanation
  • Rate Limiting: The rate.Limit function is used to create a new rate limiter. It takes three parameters:

    • limit: The maximum number of requests allowed per second.
    • burst: The maximum burst size.
    • opts: a rate.Options value with the optional ExceedHandler, ClientData, PurgeEvery and PurgeMaxLifetime fields. The zero value is valid.

    There is always a purger, because a limiter without one grows forever: every new client identifier allocates an entry that is never reclaimed. PurgeEvery (how often to sweep, one minute by default) and PurgeMaxLifetime (how long an idle client is kept, derived from the rate by default) are independent, so setting one alone leaves the other at its default.

    rate.New(limit, burst, opts) returns the *rate.Limiter object instead of a handler, so that you can Stop its background purge goroutine; register limiter.Handler(). rate.Limit is the one-liner for a limiter that lives as long as the process.

  • Token Bucket Algorithm: This algorithm controls the rate of requests by maintaining a bucket of tokens. Each request consumes a token, and tokens are added to the bucket at a fixed rate. If the bucket is empty, the request is denied.

Token Bucket Algorithm

The token bucket algorithm is a simple and efficient way to control the rate of requests. It works as follows:

  1. Initialization: A bucket is initialized with a certain number of tokens.
  2. Token Addition: Tokens are added to the bucket at a fixed rate.
  3. Request Handling: Each request consumes a token. If the bucket is empty, the request is denied.
  4. Burst Handling: The bucket can hold a maximum number of tokens, allowing for bursts of traffic.

For more details, refer to the Wikipedia article on Token Bucket.

For more examples and detailed usage, refer to the official Iris documentation.

Documentation

Overview

Package rate implements a token-bucket rate limiter for incoming requests, one bucket per client.

Its entry point is New(limit, burst, Options), which returns a *Limiter rather than a Handler: the limiter owns a background purge goroutine and must be stopped with Stop when it is no longer needed, and it exposes the clients map to `Get`. Register `Limiter.Handler()` on a Router or a Route, or use the `Limit` one-liner when the limiter lives for the whole process.

Example can be found at: _examples/06-middleware/rate-limit/main.go.

Index

Constants

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

Variables

View Source
var DefaultExceedHandler = func(ctx *context.Context) {
	ctx.StopWithStatus(429)
}

DefaultExceedHandler is the default handler which is being used when Options.ExceedHandler is not set. It stops the execution with status code 429 (Too Many Requests).

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, opts Options) 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.SetIdentifier(ctx, key string)` and `rate.Get` too.

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

It is shorthand for New(limit, burst, opts).Handler(): the Limiter itself is discarded and its purge goroutine runs for the lifetime of the process, which is correct for process-lifetime middleware. Use `New` when the limiter must be stopped, e.g. on tests or reloadable configurations.

func RegisterExceedHandler

func RegisterExceedHandler(router router.Router, handler context.Handler)

RegisterExceedHandler sets a middleware which sets the exceed "handler" for the current Router. The "handler" will be executed every time a client tries to reach a page/resource which is not accessible for that moment.

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    any
	Limiter *rate.Limiter

	// Delay indicates, when the limit was exceeded, how long the client must
	// wait before the resource becomes available again.
	//
	// Read it through RetryDelay: this value is written under mu by whichever
	// request hit the limit, and a Client is shared by every concurrent
	// request from the same identifier.
	Delay time.Duration
	// 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) RetryDelay

func (c *Client) RetryDelay() time.Duration

RetryDelay returns how long the client must wait before the resource becomes available again, or zero when the last request was not rate limited.

Use this instead of reading the Delay field directly: a Client is shared by every concurrent request from the same identifier, and Delay is written under the client's mutex. Reading it unlocked - which is what building "X-RateLimit-*" headers from rate.Get(ctx).Delay does - is a data race.

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 is created through the `New` package-level function (or, indirectly, through `Limit`). Register its `Handler` and call `Stop` when the limiter is no longer needed, to release its background purge goroutine.

func New

func New(limit float64, burst int, opts Options) *Limiter

New returns a new Limiter which allows requests up to rate "limit" and permits bursts of at most "burst" tokens. Register its `Handler` and call `Stop` when the limiter is no longer needed. See `Limit` for the one-liner version and `Options` for the optional configuration.

func (*Limiter) Handler

func (l *Limiter) Handler() context.Handler

Handler returns the limiter's middleware handler, ready to be registered on a Router or a Route.

func (*Limiter) Purge

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

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

func (*Limiter) Stop

func (l *Limiter) Stop()

Stop terminates the limiter's background purge goroutine and waits for it to exit; after Stop returns no purge runs anymore (already-stored clients remain until garbage collected with the Limiter itself). It is safe to call Stop more than once and from concurrent goroutines.

type Options

type Options struct {
	// ExceedHandler is executed every time a client tries to reach a
	// page/resource which is not accessible for that moment.
	// This sets the handler for all requests. To override it for the requests of
	// a specific Router, use the `RegisterExceedHandler` package-level function.
	//
	// Defaults to DefaultExceedHandler, which stops with 429 (Too Many Requests).
	ExceedHandler context.Handler

	// ClientData provides custom data that will be stored on the Client and can
	// be retrieved as `Get(ctx).Data` later on.
	//
	// Defaults to nil.
	ClientData func(ctx *context.Context) any

	// PurgeEvery is how often old client entries are checked and removed,
	// e.g. PurgeEvery: time.Minute and PurgeMaxLifetime: 5*time.Minute to check
	// every minute whether a client's last visit was 5 minutes ago and drop it
	// from the memory.
	//
	// Defaults to one minute. There is always a purger, because a limiter
	// without one grows forever - see the note in `New`.
	//
	// PurgeEvery and PurgeMaxLifetime are independent: setting one alone leaves
	// the other at its default.
	PurgeEvery time.Duration
	// PurgeMaxLifetime is how long a client entry with no request is kept.
	//
	// Defaults to a value derived from the rate, long enough that dropping an
	// entry can never hand a client a burst it had not already earned.
	// See PurgeEvery.
	PurgeMaxLifetime time.Duration
}

Options holds the optional configuration of a Limiter. The zero value is valid and uses the documented defaults.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL