github.com/gofiber/fiber/v2@v2.47.0/docs/api/middleware/limiter.md (about)

     1  ---
     2  id: limiter
     3  title: Limiter
     4  ---
     5  
     6  Limiter middleware for [Fiber](https://github.com/gofiber/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.
     7  
     8  :::note
     9  This middleware uses our [Storage](https://github.com/gofiber/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.
    10  :::
    11  
    12  :::note
    13  This module does not share state with other processes/servers by default.
    14  :::
    15  
    16  ## Signatures
    17  
    18  ```go
    19  func New(config ...Config) fiber.Handler
    20  ```
    21  
    22  ## Examples
    23  
    24  Import the middleware package that is part of the Fiber web framework
    25  
    26  ```go
    27  import (
    28    "github.com/gofiber/fiber/v2"
    29    "github.com/gofiber/fiber/v2/middleware/limiter"
    30  )
    31  ```
    32  
    33  After you initiate your Fiber app, you can use the following possibilities:
    34  
    35  ```go
    36  // Initialize default config
    37  app.Use(limiter.New())
    38  
    39  // Or extend your config for customization
    40  app.Use(limiter.New(limiter.Config{
    41      Next: func(c *fiber.Ctx) bool {
    42          return c.IP() == "127.0.0.1"
    43      },
    44      Max:          20,
    45      Expiration:     30 * time.Second,
    46      KeyGenerator:          func(c *fiber.Ctx) string {
    47          return c.Get("x-forwarded-for")
    48      },
    49      LimitReached: func(c *fiber.Ctx) error {
    50          return c.SendFile("./toofast.html")
    51      },
    52      Storage: myCustomStorage{},
    53  }))
    54  ```
    55  
    56  ## Sliding window
    57  
    58  Instead of using the standard fixed window algorithm, you can enable the [sliding window](https://en.wikipedia.org/wiki/Sliding_window_protocol) algorithm.
    59  
    60  A example of such configuration is:
    61  
    62  ```go
    63  app.Use(limiter.New(limiter.Config{
    64      Max:            20,
    65      Expiration:     30 * time.Second,
    66      LimiterMiddleware: limiter.SlidingWindow{},
    67  }))
    68  ```
    69  
    70  This means that every window will take into account the previous window(if there was any). The given formula for the rate is:
    71  ```
    72  weightOfPreviousWindpw = previous window's amount request * (whenNewWindow / Expiration)
    73  rate = weightOfPreviousWindpw + current window's amount request.
    74  ```
    75  
    76  ## Config
    77  
    78  ```go
    79  // Config defines the config for middleware.
    80  type Config struct {
    81      // Next defines a function to skip this middleware when returned true.
    82      //
    83      // Optional. Default: nil
    84      Next func(c *fiber.Ctx) bool
    85  
    86  	// Max number of recent connections during `Duration` seconds before sending a 429 response
    87      //
    88      // Default: 5
    89      Max int
    90  
    91      // KeyGenerator allows you to generate custom keys, by default c.IP() is used
    92      //
    93      // Default: func(c *fiber.Ctx) string {
    94      //   return c.IP()
    95      // }
    96      KeyGenerator func(*fiber.Ctx) string
    97  
    98      // Expiration is the time on how long to keep records of requests in memory
    99      //
   100      // Default: 1 * time.Minute
   101      Expiration time.Duration
   102  
   103      // LimitReached is called when a request hits the limit
   104      //
   105      // Default: func(c *fiber.Ctx) error {
   106      //   return c.SendStatus(fiber.StatusTooManyRequests)
   107      // }
   108      LimitReached fiber.Handler
   109  
   110      // When set to true, requests with StatusCode >= 400 won't be counted.
   111      //
   112      // Default: false
   113      SkipFailedRequests bool
   114  
   115      // When set to true, requests with StatusCode < 400 won't be counted.
   116      //
   117      // Default: false
   118      SkipSuccessfulRequests bool
   119  
   120      // Store is used to store the state of the middleware
   121      //
   122      // Default: an in memory store for this process only
   123      Storage fiber.Storage
   124  
   125      // LimiterMiddleware is the struct that implements limiter middleware.
   126      //
   127      // Default: a new Fixed Window Rate Limiter
   128      LimiterMiddleware LimiterHandler
   129  }
   130  ```
   131  
   132  :::note
   133  A custom store can be used if it implements the `Storage` interface - more details and an example can be found in `store.go`.
   134  :::
   135  
   136  ## Default Config
   137  
   138  ```go
   139  var ConfigDefault = Config{
   140      Max:        5,
   141      Expiration: 1 * time.Minute,
   142      KeyGenerator: func(c *fiber.Ctx) string {
   143          return c.IP()
   144      },
   145      LimitReached: func(c *fiber.Ctx) error {
   146          return c.SendStatus(fiber.StatusTooManyRequests)
   147      },
   148      SkipFailedRequests: false,
   149      SkipSuccessfulRequests: false,
   150      LimiterMiddleware: FixedWindow{},
   151  }
   152  ```
   153  
   154  ### Custom Storage/Database
   155  
   156  You can use any storage from our [storage](https://github.com/gofiber/storage/) package.
   157  
   158  ```go
   159  storage := sqlite3.New() // From github.com/gofiber/storage/sqlite3
   160  app.Use(limiter.New(limiter.Config{
   161  	Storage: storage,
   162  }))
   163  ```