Skip to content

Commit

Permalink
improved the config section of the middleware readme´s (#2552)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ReneWerner87
ReneWerner87 authored Jul 24, 2023
1 parent 5d74725 commit 51ea636
Show file tree
Hide file tree
Showing 29 changed files with 303 additions and 960 deletions.
3 changes: 2 additions & 1 deletion docs/api/middleware/adaptor.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
id: adaptor
title: Adaptor
---

# Adaptor

Converter for net/http handlers to/from Fiber request handlers, special thanks to [@arsmn](https://github.com/arsmn)!

## Signatures
Expand Down
58 changes: 11 additions & 47 deletions docs/api/middleware/basicauth.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
id: basicauth
title: BasicAuth
---

# BasicAuth

Basic Authentication middleware for [Fiber](https://github.com/gofiber/fiber) that provides an HTTP basic authentication. It calls the next handler for valid credentials and [401 Unauthorized](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) or a custom response for missing or invalid credentials.

## Signatures
Expand Down Expand Up @@ -59,52 +60,15 @@ app.Use(basicauth.New(basicauth.Config{

## Config

```go
// Config defines the config for middleware.
type Config struct {
// Next defines a function to skip this middleware when returned true.
//
// Optional. Default: nil
Next func(c *fiber.Ctx) bool

// Users defines the allowed credentials
//
// Required. Default: map[string]string{}
Users map[string]string

// Realm is a string to define realm attribute of BasicAuth.
// the realm identifies the system to authenticate against
// and can be used by clients to save credentials
//
// Optional. Default: "Restricted".
Realm string

// Authorizer defines a function you can pass
// to check the credentials however you want.
// It will be called with a username and password
// and is expected to return true or false to indicate
// that the credentials were approved or not.
//
// Optional. Default: nil.
Authorizer func(string, string) bool

// Unauthorized defines the response body for unauthorized responses.
// By default it will return with a 401 Unauthorized and the correct WWW-Auth header
//
// Optional. Default: nil
Unauthorized fiber.Handler

// ContextUser is the key to store the username in Locals
//
// Optional. Default: "username"
ContextUsername string

// ContextPass is the key to store the password in Locals
//
// Optional. Default: "password"
ContextPassword string
}
```
| Property | Type | Description | Default |
|:----------------|:----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------|
| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` |
| Users | `map[string]string` | Users defines the allowed credentials. | `map[string]string{}` |
| Realm | `string` | Realm is a string to define the realm attribute of BasicAuth. The realm identifies the system to authenticate against and can be used by clients to save credentials. | `"Restricted"` |
| Authorizer | `func(string, string) bool` | Authorizer defines a function to check the credentials. It will be called with a username and password and is expected to return true or false to indicate approval. | `nil` |
| Unauthorized | `fiber.Handler` | Unauthorized defines the response body for unauthorized responses. | `nil` |
| ContextUsername | `string` | ContextUsername is the key to store the username in Locals. | `"username"` |
| ContextPassword | `string` | ContextPassword is the key to store the password in Locals. | `"password"` |

## Default Config

Expand Down
78 changes: 16 additions & 62 deletions docs/api/middleware/cache.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
id: cache
title: Cache
---

# Cache

Cache middleware for [Fiber](https://github.com/gofiber/fiber) designed to intercept responses and cache them. This middleware will cache the `Body`, `Content-Type` and `StatusCode` using the `c.Path()` as unique identifier. Special thanks to [@codemicro](https://github.com/codemicro/fiber-cache) for creating this middleware for Fiber core!

Request Directives<br />
Expand Down Expand Up @@ -63,67 +64,20 @@ app.Get("/", func(c *fiber.Ctx) error {

## Config

```go
// Config defines the config for middleware.
type Config struct {
// Next defines a function to skip this middleware when returned true.
//
// Optional. Default: nil
Next func(c *fiber.Ctx) bool

// Expiration is the time that an cached response will live
//
// Optional. Default: 1 * time.Minute
Expiration time.Duration

// CacheHeader header on response header, indicate cache status, with the following possible return value
//
// hit, miss, unreachable
//
// Optional. Default: X-Cache
CacheHeader string

// CacheControl enables client side caching if set to true
//
// Optional. Default: false
CacheControl bool

// Key allows you to generate custom keys, by default c.Path() is used
//
// Default: func(c *fiber.Ctx) string {
// return utils.CopyString(c.Path())
// }
KeyGenerator func(*fiber.Ctx) string

// allows you to generate custom Expiration Key By Key, default is Expiration (Optional)
//
// Default: nil
ExpirationGenerator func(*fiber.Ctx, *Config) time.Duration

// Store is used to store the state of the middleware
//
// Default: an in memory store for this process only
Storage fiber.Storage

// allows you to store additional headers generated by next middlewares & handler
//
// Default: false
StoreResponseHeaders bool

// Max number of bytes of response bodies simultaneously stored in cache. When limit is reached,
// entries with the nearest expiration are deleted to make room for new.
// 0 means no limit
//
// Default: 0
MaxBytes uint

// You can specify HTTP methods to cache.
// The middleware just caches the routes of its methods in this slice.
//
// Default: []string{fiber.MethodGet, fiber.MethodHead}
Methods []string
}
```
| Property | Type | Description | Default |
|:---------------------|:------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------|
| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` |
| Expiration | `time.Duration` | Expiration is the time that a cached response will live. | `1 * time.Minute` |
| CacheHeader | `string` | CacheHeader is the header on the response header that indicates the cache status, with the possible return values "hit," "miss," or "unreachable." | `X-Cache` |
| CacheControl | `bool` | CacheControl enables client-side caching if set to true. | `false` |
| KeyGenerator | `func(*fiber.Ctx) string` | Key allows you to generate custom keys. | `func(c *fiber.Ctx) string { return utils.CopyString(c.Path()) }` |
| ExpirationGenerator | `func(*fiber.Ctx, *cache.Config) time.Duration` | ExpirationGenerator allows you to generate custom expiration keys based on the request. | `nil` |
| Storage | `fiber.Storage` | Store is used to store the state of the middleware. | In-memory store |
| Store (Deprecated) | `fiber.Storage` | Deprecated: Use Storage instead. | In-memory store |
| Key (Deprecated) | `func(*fiber.Ctx) string` | Deprecated: Use KeyGenerator instead. | `nil` |
| StoreResponseHeaders | `bool` | StoreResponseHeaders allows you to store additional headers generated by next middlewares & handler. | `false` |
| MaxBytes | `uint` | MaxBytes is the maximum number of bytes of response bodies simultaneously stored in cache. | `0` (No limit) |
| Methods | `[]string` | Methods specifies the HTTP methods to cache. | `[]string{fiber.MethodGet, fiber.MethodHead}` |

## Default Config

Expand Down
34 changes: 15 additions & 19 deletions docs/api/middleware/compress.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
id: compress
title: Compress
---

# Compress

Compression middleware for [Fiber](https://github.com/gofiber/fiber) that will compress the response using `gzip`, `deflate` and `brotli` compression depending on the [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header.

## Signatures
Expand Down Expand Up @@ -44,24 +45,19 @@ app.Use(compress.New(compress.Config{

## Config

```go
// Config defines the config for middleware.
type Config struct {
// Next defines a function to skip this middleware when returned true.
//
// Optional. Default: nil
Next func(c *fiber.Ctx) bool

// Level determines the compression algoritm
//
// Optional. Default: LevelDefault
// LevelDisabled: -1
// LevelDefault: 0
// LevelBestSpeed: 1
// LevelBestCompression: 2
Level int
}
```
### Config

| Property | Type | Description | Default |
|:---------|:------------------------|:--------------------------------------------------------------------|:-------------------|
| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` |
| Level | `Level` | Level determines the compression algorithm. | `LevelDefault (0)` |

Possible values for the "Level" field are:

- `LevelDisabled (-1)`: Compression is disabled.
- `LevelDefault (0)`: Default compression level.
- `LevelBestSpeed (1)`: Best compression speed.
- `LevelBestCompression (2)`: Best compression.

## Default Config

Expand Down
68 changes: 12 additions & 56 deletions docs/api/middleware/cors.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
id: cors
title: CORS
---

# CORS

CORS middleware for [Fiber](https://github.com/gofiber/fiber) that can be used to enable [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) with various options.

## Signatures
Expand Down Expand Up @@ -53,61 +54,16 @@ app.Use(cors.New(cors.Config{

## Config

```go
// Config defines the config for middleware.
type Config struct {
// Next defines a function to skip this middleware when returned true.
//
// Optional. Default: nil
Next func(c *fiber.Ctx) bool

// AllowOriginsFunc defines a function that will set the 'access-control-allow-origin'
// response header to the 'origin' request header when returned true.
//
// Note: Using this feature is discouraged in production and it's best practice to explicitly
// set CORS origins via 'AllowOrigins'
//
// Optional. Default: nil
AllowOriginsFunc func(origin string) bool

// AllowOrigin defines a list of origins that may access the resource.
//
// Optional. Default value "*"
AllowOrigins string

// AllowMethods defines a list methods allowed when accessing the resource.
// This is used in response to a preflight request.
//
// Optional. Default value "GET,POST,HEAD,PUT,DELETE,PATCH"
AllowMethods string

// AllowHeaders defines a list of request headers that can be used when
// making the actual request. This is in response to a preflight request.
//
// Optional. Default value "".
AllowHeaders string

// AllowCredentials indicates whether or not the response to the request
// can be exposed when the credentials flag is true. When used as part of
// a response to a preflight request, this indicates whether or not the
// actual request can be made using credentials.
//
// Optional. Default value false.
AllowCredentials bool

// ExposeHeaders defines a whitelist headers that clients are allowed to
// access.
//
// Optional. Default value "".
ExposeHeaders string

// MaxAge indicates how long (in seconds) the results of a preflight request
// can be cached.
//
// Optional. Default value 0.
MaxAge int
}
```
| Property | Type | Description | Default |
|:-----------------|:---------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------|
| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` |
| AllowOriginsFunc | `func(origin string) bool` | AllowOriginsFunc defines a function that will set the 'access-control-allow-origin' response header to the 'origin' request header when returned true. | `nil` |
| AllowOrigins | `string` | AllowOrigin defines a list of origins that may access the resource. | `"*"` |
| AllowMethods | `string` | AllowMethods defines a list methods allowed when accessing the resource. This is used in response to a preflight request. | `"GET,POST,HEAD,PUT,DELETE,PATCH"` |
| AllowHeaders | `string` | AllowHeaders defines a list of request headers that can be used when making the actual request. This is in response to a preflight request. | `""` |
| AllowCredentials | `bool` | AllowCredentials indicates whether or not the response to the request can be exposed when the credentials flag is true. | `false` |
| ExposeHeaders | `string` | ExposeHeaders defines a whitelist headers that clients are allowed to access. | `""` |
| MaxAge | `int` | MaxAge indicates how long (in seconds) the results of a preflight request can be cached. | `0` |

## Default Config

Expand Down
Loading

0 comments on commit 51ea636

Please sign in to comment.