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

     1  ---
     2  id: idempotency
     3  title: Idempotency
     4  ---
     5  
     6  Idempotency middleware for [Fiber](https://github.com/gofiber/fiber) allows for fault-tolerant APIs where duplicate requests — for example due to networking issues on the client-side — do not erroneously cause the same action performed multiple times on the server-side.
     7  
     8  Refer to https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header-02 for a better understanding.
     9  
    10  ## Signatures
    11  
    12  ```go
    13  func New(config ...Config) fiber.Handler
    14  ```
    15  
    16  ## Examples
    17  
    18  Import the middleware package that is part of the Fiber web framework
    19  
    20  ```go
    21  import (
    22  	"github.com/gofiber/fiber/v2"
    23  	"github.com/gofiber/fiber/v2/middleware/idempotency"
    24  )
    25  ```
    26  
    27  After you initiate your Fiber app, you can use the following possibilities:
    28  
    29  ### Default Config
    30  
    31  ```go
    32  app.Use(idempotency.New())
    33  ```
    34  
    35  ### Custom Config
    36  
    37  ```go
    38  app.Use(idempotency.New(idempotency.Config{
    39  	Lifetime: 42 * time.Minute,
    40  	// ...
    41  }))
    42  ```
    43  
    44  ### Config
    45  
    46  ```go
    47  // Config defines the config for middleware.
    48  type Config struct {
    49  	// Next defines a function to skip this middleware when returned true.
    50  	//
    51  	// Optional. Default: a function which skips the middleware on safe HTTP request method.
    52  	Next func(c *fiber.Ctx) bool
    53  
    54  	// Lifetime is the maximum lifetime of an idempotency key.
    55  	//
    56  	// Optional. Default: 30 * time.Minute
    57  	Lifetime time.Duration
    58  
    59  	// KeyHeader is the name of the header that contains the idempotency key.
    60  	//
    61  	// Optional. Default: X-Idempotency-Key
    62  	KeyHeader string
    63  	// KeyHeaderValidate defines a function to validate the syntax of the idempotency header.
    64  	//
    65  	// Optional. Default: a function which ensures the header is 36 characters long (the size of an UUID).
    66  	KeyHeaderValidate func(string) error
    67  
    68  	// KeepResponseHeaders is a list of headers that should be kept from the original response.
    69  	//
    70  	// Optional. Default: nil (to keep all headers)
    71  	KeepResponseHeaders []string
    72  
    73  	// Lock locks an idempotency key.
    74  	//
    75  	// Optional. Default: an in-memory locker for this process only.
    76  	Lock Locker
    77  
    78  	// Storage stores response data by idempotency key.
    79  	//
    80  	// Optional. Default: an in-memory storage for this process only.
    81  	Storage fiber.Storage
    82  }
    83  ```
    84  
    85  ## Default Config
    86  
    87  ```go
    88  var ConfigDefault = Config{
    89  	Next: func(c *fiber.Ctx) bool {
    90  		// Skip middleware if the request was done using a safe HTTP method
    91  		return fiber.IsMethodSafe(c.Method())
    92  	},
    93  
    94  	Lifetime: 30 * time.Minute,
    95  
    96  	KeyHeader: "X-Idempotency-Key",
    97  	KeyHeaderValidate: func(k string) error {
    98  		if l, wl := len(k), 36; l != wl { // UUID length is 36 chars
    99  			return fmt.Errorf("%w: invalid length: %d != %d", ErrInvalidIdempotencyKey, l, wl)
   100  		}
   101  
   102  		return nil
   103  	},
   104  
   105  	KeepResponseHeaders: nil,
   106  
   107  	Lock: nil, // Set in configDefault so we don't allocate data here.
   108  
   109  	Storage: nil, // Set in configDefault so we don't allocate data here.
   110  }
   111  ```