6.2 KiB

Raw Blame History

id
limiter

Limiter

Limiter middleware for Fiber that is used to limit repeat requests to public APIs and/or endpoints such as password reset. It is also useful for API clients, web crawling, or other tasks that need to be throttled.

:::note This middleware uses our Storage package to support various databases through a single interface. The default configuration for this middleware saves data to memory, see the examples below for other databases. :::

:::note This module does not share state with other processes/servers by default. :::

Signatures

func New(config ...Config) fiber.Handler

Examples

Import the middleware package that is part of the Fiber web framework

import (
    "github.com/gofiber/fiber/v3"
    "github.com/gofiber/fiber/v3/middleware/limiter"
)

After you initiate your Fiber app, you can use the following possibilities:

// Initialize default config
app.Use(limiter.New())

// Or extend your config for customization
app.Use(limiter.New(limiter.Config{
    Next: func(c fiber.Ctx) bool {
        return c.IP() == "127.0.0.1"
    },
    Max:          20,
    MaxFunc: func(c fiber.Ctx) int {
      return 20
    },
    Expiration:     30 * time.Second,
    KeyGenerator:          func(c fiber.Ctx) string {
        return c.Get("x-forwarded-for")
    },
    LimitReached: func(c fiber.Ctx) error {
        return c.SendFile("./toofast.html")
    },
    Storage: myCustomStorage{},
}))

Sliding window

Instead of using the standard fixed window algorithm, you can enable the sliding window algorithm.

A example of such configuration is:

app.Use(limiter.New(limiter.Config{
    Max:            20,
    Expiration:     30 * time.Second,
    LimiterMiddleware: limiter.SlidingWindow{},
}))

This means that every window will consider the previous window (if there was any). The given formula for the rate is:

weightOfPreviousWindow = previous window's amount request * (whenNewWindow / Expiration)
rate = weightOfPreviousWindow + current window's amount request.

Dynamic limit

You can also calculate the limit dynamically using the MaxFunc parameter. It's a function that receives the request's context as a parameter and allow you to calculate a different limit for each request separately.

Example:

app.Use(limiter.New(limiter.Config{
    MaxFunc:  func(c fiber.Ctx) int {
      return getUserLimit(ctx.Param("id"))
    },
    Expiration:     30 * time.Second,
}))

Config

Property	Type	Description	Default
Next	`func(fiber.Ctx) bool`	Next defines a function to skip this middleware when returned true.	`nil`
Max	`int`	Max number of recent connections during `Expiration` seconds before sending a 429 response.	5
MaxFunc	`func(fiber.Ctx) int`	A function to calculate the max number of recent connections during `Expiration` seconds before sending a 429 response.	A function which returns the cfg.Max
KeyGenerator	`func(fiber.Ctx) string`	KeyGenerator allows you to generate custom keys, by default c.IP() is used.	A function using c.IP() as the default
Expiration	`time.Duration`	Expiration is the time on how long to keep records of requests in memory.	1 * time.Minute
LimitReached	`fiber.Handler`	LimitReached is called when a request hits the limit.	A function sending 429 response
SkipFailedRequests	`bool`	When set to true, requests with StatusCode >= 400 won't be counted.	false
SkipSuccessfulRequests	`bool`	When set to true, requests with StatusCode < 400 won't be counted.	false
Storage	`fiber.Storage`	Store is used to store the state of the middleware.	An in-memory store for this process only
LimiterMiddleware	`LimiterHandler`	LimiterMiddleware is the struct that implements a limiter middleware.	A new Fixed Window Rate Limiter
Duration (Deprecated)	`time.Duration`	Deprecated: Use Expiration instead	-
Store (Deprecated)	`fiber.Storage`	Deprecated: Use Storage instead	-
Key (Deprecated)	`func(fiber.Ctx) string`	Deprecated: Use KeyGenerator instead	-

:::note A custom store can be used if it implements the Storage interface - more details and an example can be found in store.go. :::

Default Config

var ConfigDefault = Config{
    Max:        5,
    MaxFunc: func(c fiber.Ctx) int {
      return 5
    },
    Expiration: 1 * time.Minute,
    KeyGenerator: func(c fiber.Ctx) string {
        return c.IP()
    },
    LimitReached: func(c fiber.Ctx) error {
        return c.SendStatus(fiber.StatusTooManyRequests)
    },
    SkipFailedRequests: false,
    SkipSuccessfulRequests: false,
    LimiterMiddleware: FixedWindow{},
}

Custom Storage/Database

You can use any storage from our storage package.

storage := sqlite3.New() // From github.com/gofiber/storage/sqlite3

app.Use(limiter.New(limiter.Config{
    Storage: storage,
}))

6.2 KiB Raw Blame History