diff --git a/docs/api/middleware/adaptor.md b/docs/api/middleware/adaptor.md index 7e73dd4705..64df229ce2 100644 --- a/docs/api/middleware/adaptor.md +++ b/docs/api/middleware/adaptor.md @@ -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 diff --git a/docs/api/middleware/basicauth.md b/docs/api/middleware/basicauth.md index 268f5b246e..0e90eafed0 100644 --- a/docs/api/middleware/basicauth.md +++ b/docs/api/middleware/basicauth.md @@ -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 @@ -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 diff --git a/docs/api/middleware/cache.md b/docs/api/middleware/cache.md index 99dd833c5f..3a87306d3b 100644 --- a/docs/api/middleware/cache.md +++ b/docs/api/middleware/cache.md @@ -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
@@ -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 diff --git a/docs/api/middleware/compress.md b/docs/api/middleware/compress.md index 6066ac7246..f284f5e92c 100644 --- a/docs/api/middleware/compress.md +++ b/docs/api/middleware/compress.md @@ -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 @@ -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 diff --git a/docs/api/middleware/cors.md b/docs/api/middleware/cors.md index 8a76def1eb..af9b8c5f2b 100644 --- a/docs/api/middleware/cors.md +++ b/docs/api/middleware/cors.md @@ -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 @@ -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 diff --git a/docs/api/middleware/csrf.md b/docs/api/middleware/csrf.md index d0452a8ece..e588b51762 100644 --- a/docs/api/middleware/csrf.md +++ b/docs/api/middleware/csrf.md @@ -1,8 +1,9 @@ --- id: csrf -title: CSRF --- +# CSRF + CSRF middleware for [Fiber](https://github.com/gofiber/fiber) that provides [Cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection by passing a csrf token via cookies. This cookie value will be used to compare against the client csrf token on requests, other than those defined as "safe" by RFC7231 \(GET, HEAD, OPTIONS, or TRACE\). When the csrf token is invalid, this middleware will return the `fiber.ErrForbidden` error. CSRF Tokens are generated on GET requests. You can retrieve the CSRF token with `c.Locals(contextKey)`, where `contextKey` is the string you set in the config (see Custom Config below). @@ -53,85 +54,28 @@ KeyLookup will be ignored if Extractor is explicitly set. ## 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 - - // KeyLookup is a string in the form of ":" that is used - // to create an Extractor that extracts the token from the request. - // Possible values: - // - "header:" - // - "query:" - // - "param:" - // - "form:" - // - "cookie:" - // - // Ignored if an Extractor is explicitly set. - // - // Optional. Default: "header:X-CSRF-Token" - KeyLookup string - - // Name of the session cookie. This cookie will store session key. - // Optional. Default value "csrf_". - CookieName string - - // Domain of the CSRF cookie. - // Optional. Default value "". - CookieDomain string - - // Path of the CSRF cookie. - // Optional. Default value "". - CookiePath string - - // Indicates if CSRF cookie is secure. - // Optional. Default value false. - CookieSecure bool - - // Indicates if CSRF cookie is HTTP only. - // Optional. Default value false. - CookieHTTPOnly bool - - // Indicates if CSRF cookie is requested by SameSite. - // Optional. Default value "Lax". - CookieSameSite string - - // Decides whether cookie should last for only the browser sesison. - // Ignores Expiration if set to true - CookieSessionOnly bool - - // Expiration is the duration before csrf token will expire - // - // Optional. Default: 1 * time.Hour - Expiration time.Duration - - // Store is used to store the state of the middleware - // - // Optional. Default: memory.New() - Storage fiber.Storage - - // Context key to store generated CSRF token into context. - // If left empty, token will not be stored in context. - // - // Optional. Default: "" - ContextKey string - - // KeyGenerator creates a new CSRF token - // - // Optional. Default: utils.UUID - KeyGenerator func() string - - // Extractor returns the csrf token - // - // If set this will be used in place of an Extractor based on KeyLookup. - // - // Optional. Default will create an Extractor based on KeyLookup. - Extractor func(c *fiber.Ctx) (string, error) -} -``` +### Config + +| Property | Type | Description | Default | +|:------------------|:-----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| KeyLookup | `string` | KeyLookup is a string in the form of ":" that is used to create an Extractor that extracts the token from the request. Possible values: "header:", "query:", "param:", "form:", "cookie:". Ignored if an Extractor is explicitly set. | "header:X-CSRF-Token" | +| CookieName | `string` | Name of the session cookie. This cookie will store the session key. | "csrf_" | +| CookieDomain | `string` | Domain of the CSRF cookie. | "" | +| CookiePath | `string` | Path of the CSRF cookie. | "" | +| CookieSecure | `bool` | Indicates if the CSRF cookie is secure. | false | +| CookieHTTPOnly | `bool` | Indicates if the CSRF cookie is HTTP-only. | false | +| CookieSameSite | `string` | Value of SameSite cookie. | "Lax" | +| CookieSessionOnly | `bool` | Decides whether the cookie should last for only the browser session. Ignores Expiration if set to true. | false | +| Expiration | `time.Duration` | Expiration is the duration before the CSRF token will expire. | 1 * time.Hour | +| Storage | `fiber.Storage` | Store is used to store the state of the middleware. | memory.New() | +| ContextKey | `string` | Context key to store the generated CSRF token into the context. If left empty, the token will not be stored in the context. | "" | +| KeyGenerator | `func() string` | KeyGenerator creates a new CSRF token. | utils.UUID | +| CookieExpires | `time.Duration` (Deprecated) | Deprecated: Please use Expiration. | 0 | +| Cookie | `*fiber.Cookie` (Deprecated) | Deprecated: Please use Cookie* related fields. | nil | +| TokenLookup | `string` (Deprecated) | Deprecated: Please use KeyLookup. | "" | +| ErrorHandler | `fiber.ErrorHandler` | ErrorHandler is executed when an error is returned from fiber.Handler. | DefaultErrorHandler | +| Extractor | `func(*fiber.Ctx) (string, error)` | Extractor returns the CSRF token. If set, this will be used in place of an Extractor based on KeyLookup. | Extractor based on KeyLookup | ## Default Config diff --git a/docs/api/middleware/earlydata.md b/docs/api/middleware/earlydata.md index 6b83f1214f..50e5bb174c 100644 --- a/docs/api/middleware/earlydata.md +++ b/docs/api/middleware/earlydata.md @@ -1,8 +1,9 @@ --- id: earlydata -title: EarlyData --- +# EarlyData + The Early Data middleware for [Fiber](https://github.com/gofiber/fiber) adds support for TLS 1.3's early data ("0-RTT") feature. Citing [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446#section-2-3), when a client and server share a PSK, TLS 1.3 allows clients to send data on the first flight ("early data") to speed up the request, effectively reducing the regular 1-RTT request to a 0-RTT request. @@ -48,30 +49,12 @@ app.Use(earlydata.New(earlydata.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 - - // IsEarlyData returns whether the request is an early-data request. - // - // Optional. Default: a function which checks if the "Early-Data" request header equals "1". - IsEarlyData func(c *fiber.Ctx) bool - - // AllowEarlyData returns whether the early-data request should be allowed or rejected. - // - // Optional. Default: a function which rejects the request on unsafe and allows the request on safe HTTP request methods. - AllowEarlyData func(c *fiber.Ctx) bool - - // Error is returned in case an early-data request is rejected. - // - // Optional. Default: fiber.ErrTooEarly. - Error error -} -``` +| Property | Type | Description | Default | +|:---------------|:------------------------|:-------------------------------------------------------------------------------------|:-------------------------------------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| IsEarlyData | `func(*fiber.Ctx) bool` | IsEarlyData returns whether the request is an early-data request. | Function checking if "Early-Data" header equals "1" | +| AllowEarlyData | `func(*fiber.Ctx) bool` | AllowEarlyData returns whether the early-data request should be allowed or rejected. | Function rejecting on unsafe and allowing safe methods | +| Error | `error` | Error is returned in case an early-data request is rejected. | `fiber.ErrTooEarly` | ## Default Config @@ -96,4 +79,4 @@ const ( DefaultHeaderName = "Early-Data" DefaultHeaderTrueValue = "1" ) -``` \ No newline at end of file +``` diff --git a/docs/api/middleware/encryptcookie.md b/docs/api/middleware/encryptcookie.md index 594df96389..743578bd87 100644 --- a/docs/api/middleware/encryptcookie.md +++ b/docs/api/middleware/encryptcookie.md @@ -1,8 +1,9 @@ --- id: encryptcookie -title: Encrypt Cookie --- +# Encrypt Cookie + Encrypt middleware for [Fiber](https://github.com/gofiber/fiber) which encrypts cookie values. Note: this middleware does not encrypt cookie names. ## Signatures @@ -54,36 +55,13 @@ app.Post("/", 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 - - // Array of cookie keys that should not be encrypted. - // - // Optional. Default: ["csrf_"] - Except []string - - // Base64 encoded unique key to encode & decode cookies. - // - // Required. The key should be 32 bytes of random data in base64-encoded form. - // You may run `openssl rand -base64 32` or use `encryptcookie.GenerateKey()` to generate a new key. - Key string - - // Custom function to encrypt cookies. - // - // Optional. Default: EncryptCookie - Encryptor func(decryptedString, key string) (string, error) - - // Custom function to decrypt cookies. - // - // Optional. Default: DecryptCookie - Decryptor func(encryptedString, key string) (string, error) -} -``` +| Property | Type | Description | Default | +|:----------|:----------------------------------------------------|:----------------------------------------------------------------------------------------------------|:-----------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| Except | `[]string` | Array of cookie keys that should not be encrypted. | `[]` | +| Key | `string` | Base64 encoded unique key to encode & decode cookies. Required. Key length should be 32 characters. | (No default, required field) | +| Encryptor | `func(decryptedString, key string) (string, error)` | Custom function to encrypt cookies. | `EncryptCookie` | +| Decryptor | `func(encryptedString, key string) (string, error)` | Custom function to decrypt cookies. | `DecryptCookie` | ## Default Config diff --git a/docs/api/middleware/envvar.md b/docs/api/middleware/envvar.md index 592a502df4..1d9f474297 100644 --- a/docs/api/middleware/envvar.md +++ b/docs/api/middleware/envvar.md @@ -1,8 +1,9 @@ --- id: envvar -title: EnvVar --- +# EnvVar + EnvVar middleware for [Fiber](https://github.com/gofiber/fiber) that can be used to expose environment variables with various options. ## Signatures @@ -56,16 +57,10 @@ Http response contract: ## Config -```go -// Config defines the config for middleware. -type Config struct { - // ExportVars specifies the environment variables that should export - ExportVars map[string]string - // ExcludeVars specifies the environment variables that should not export - ExcludeVars map[string]string -} - -``` +| Property | Type | Description | Default | +|:------------|:--------------------|:-----------------------------------------------------------------------------|:--------| +| ExportVars | `map[string]string` | ExportVars specifies the environment variables that should be exported. | `nil` | +| ExcludeVars | `map[string]string` | ExcludeVars specifies the environment variables that should not be exported. | `nil` | ## Default Config diff --git a/docs/api/middleware/etag.md b/docs/api/middleware/etag.md index b9df4e93fe..24be273021 100644 --- a/docs/api/middleware/etag.md +++ b/docs/api/middleware/etag.md @@ -1,8 +1,9 @@ --- id: etag -title: ETag --- +# ETag + ETag middleware for [Fiber](https://github.com/gofiber/fiber) that lets caches be more efficient and save bandwidth, as a web server does not need to resend a full response if the content has not changed. ## Signatures @@ -46,25 +47,10 @@ 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 - - // Weak indicates that a weak validator is used. Weak etags are easy - // to generate, but are far less useful for comparisons. Strong - // validators are ideal for comparisons but can be very difficult - // to generate efficiently. Weak ETag values of two representations - // of the same resources might be semantically equivalent, but not - // byte-for-byte identical. This means weak etags prevent caching - // when byte range requests are used, but strong etags mean range - // requests can still be cached. - Weak bool -} -``` +| Property | Type | Description | Default | +|:---------|:------------------------|:-------------------------------------------------------------------------------------------------------------------|:--------| +| Weak | `bool` | Weak indicates that a weak validator is used. Weak etags are easy to generate but are less useful for comparisons. | `false` | +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | ## Default Config diff --git a/docs/api/middleware/expvar.md b/docs/api/middleware/expvar.md index c2023fbb33..900850e364 100644 --- a/docs/api/middleware/expvar.md +++ b/docs/api/middleware/expvar.md @@ -1,8 +1,9 @@ --- id: expvar -title: ExpVar --- +# ExpVar + Expvar middleware for [Fiber](https://github.com/gofiber/fiber) that serves via its HTTP server runtime exposed variants in the JSON format. The package is typically only imported for the side effect of registering its HTTP handlers. The handled path is `/debug/vars`. ## Signatures @@ -58,15 +59,9 @@ curl 127.0.0.1:3000/debug/vars?r=c ## 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 -} -``` +| Property | Type | Description | Default | +|:---------|:------------------------|:--------------------------------------------------------------------|:--------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | ## Default Config diff --git a/docs/api/middleware/favicon.md b/docs/api/middleware/favicon.md index 39432d45b9..3fea8b129a 100644 --- a/docs/api/middleware/favicon.md +++ b/docs/api/middleware/favicon.md @@ -1,8 +1,9 @@ --- id: favicon -title: Favicon --- +# Favicon + Favicon middleware for [Fiber](https://github.com/gofiber/fiber) that ignores favicon requests or caches a provided icon in memory to improve performance by skipping disk access. User agents request favicon.ico frequently and indiscriminately, so you may wish to exclude these requests from your logs by using this middleware before your logger middleware. :::note @@ -41,36 +42,13 @@ app.Use(favicon.New(favicon.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 - - // File holds the path to an actual favicon that will be cached - // - // Optional. Default: "" - File string - - // URL for favicon handler - // - // Optional. Default: "/favicon.ico" - URL string - - // FileSystem is an optional alternate filesystem to search for the favicon in. - // An example of this could be an embedded or network filesystem - // - // Optional. Default: nil - FileSystem http.FileSystem - - // CacheControl defines how the Cache-Control header in the response should be set - // - // Optional. Default: "public, max-age=31536000" - CacheControl string -} -``` +| Property | Type | Description | Default | +|:-------------|:------------------------|:---------------------------------------------------------------------------------|:---------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| File | `string` | File holds the path to an actual favicon that will be cached. | "" | +| URL | `string` | URL for favicon handler. | "/favicon.ico" | +| FileSystem | `http.FileSystem` | FileSystem is an optional alternate filesystem to search for the favicon in. | `nil` | +| CacheControl | `string` | CacheControl defines how the Cache-Control header in the response should be set. | "public, max-age=31536000" | ## Default Config diff --git a/docs/api/middleware/filesystem.md b/docs/api/middleware/filesystem.md index 86bc585cfc..38e3622db7 100644 --- a/docs/api/middleware/filesystem.md +++ b/docs/api/middleware/filesystem.md @@ -1,8 +1,9 @@ --- id: filesystem -title: FileSystem --- +# FileSystem + Filesystem middleware for [Fiber](https://github.com/gofiber/fiber) that enables you to serve files from a directory. :::caution @@ -228,56 +229,16 @@ func main() { ## 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 - - // Root is a FileSystem that provides access - // to a collection of files and directories. - // - // Required. Default: nil - Root http.FileSystem `json:"-"` - - // PathPrefix defines a prefix to be added to a filepath when - // reading a file from the FileSystem. - // - // Use when using Go 1.16 embed.FS - // - // Optional. Default "" - PathPrefix string `json:"path_prefix"` - - // Enable directory browsing. - // - // Optional. Default: false - Browse bool `json:"browse"` - - // Index file for serving a directory. - // - // Optional. Default: "index.html" - Index string `json:"index"` - - // The value for the Cache-Control HTTP-header - // that is set on the file response. MaxAge is defined in seconds. - // - // Optional. Default value 0. - MaxAge int `json:"max_age"` - - // File to return if path is not found. Useful for SPA's. - // - // Optional. Default: "" - NotFoundFile string `json:"not_found_file"` - - // The value for the Content-Type HTTP-header - // that is set on the file response - // - // Optional. Default: "" - ContentTypeCharset string `json:"content_type_charset"` -} -``` +| Property | Type | Description | Default | +|:-------------------|:------------------------|:------------------------------------------------------------------------------------------------------------|:-------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| Root | `http.FileSystem` | Root is a FileSystem that provides access to a collection of files and directories. | `nil` | +| PathPrefix | `string` | PathPrefix defines a prefix to be added to a filepath when reading a file from the FileSystem. | "" | +| Browse | `bool` | Enable directory browsing. | `false` | +| Index | `string` | Index file for serving a directory. | "index.html" | +| MaxAge | `int` | The value for the Cache-Control HTTP-header that is set on the file response. MaxAge is defined in seconds. | 0 | +| NotFoundFile | `string` | File to return if the path is not found. Useful for SPA's. | "" | +| ContentTypeCharset | `string` | The value for the Content-Type HTTP-header that is set on the file response. | "" | ## Default Config diff --git a/docs/api/middleware/helmet.md b/docs/api/middleware/helmet.md index 1392c5879b..0835f31166 100644 --- a/docs/api/middleware/helmet.md +++ b/docs/api/middleware/helmet.md @@ -1,8 +1,9 @@ --- id: helmet -title: Helmet --- +# Helmet + Helmet middleware helps secure your apps by setting various HTTP headers. ## Signatures @@ -41,83 +42,26 @@ curl -I http://localhost:3000 ## Config -```go -// Config defines the config for middleware. -type Config struct { - // Next defines a function to skip middleware. - // Optional. Default: nil - Next func(*fiber.Ctx) bool - - // XSSProtection - // Optional. Default value "0". - XSSProtection string - - // ContentTypeNosniff - // Optional. Default value "nosniff". - ContentTypeNosniff string - - // XFrameOptions - // Optional. Default value "SAMEORIGIN". - // Possible values: "SAMEORIGIN", "DENY", "ALLOW-FROM uri" - XFrameOptions string - - // HSTSMaxAge - // Optional. Default value 0. - HSTSMaxAge int - - // HSTSExcludeSubdomains - // Optional. Default value false. - HSTSExcludeSubdomains bool - - // ContentSecurityPolicy - // Optional. Default value "". - ContentSecurityPolicy string - - // CSPReportOnly - // Optional. Default value false. - CSPReportOnly bool - - // HSTSPreloadEnabled - // Optional. Default value false. - HSTSPreloadEnabled bool - - // ReferrerPolicy - // Optional. Default value "ReferrerPolicy". - ReferrerPolicy string - - // Permissions-Policy - // Optional. Default value "". - PermissionPolicy string - - // Cross-Origin-Embedder-Policy - // Optional. Default value "require-corp". - CrossOriginEmbedderPolicy string - - // Cross-Origin-Opener-Policy - // Optional. Default value "same-origin". - CrossOriginOpenerPolicy string - - // Cross-Origin-Resource-Policy - // Optional. Default value "same-origin". - CrossOriginResourcePolicy string - - // Origin-Agent-Cluster - // Optional. Default value "?1". - OriginAgentCluster string - - // X-DNS-Prefetch-Control - // Optional. Default value "off". - XDNSPrefetchControl string - - // X-Download-Options - // Optional. Default value "noopen". - XDownloadOptions string - - // X-Permitted-Cross-Domain-Policies - // Optional. Default value "none". - XPermittedCrossDomain string -} -``` +| Property | Type | Description | Default | +|:--------------------------|:------------------------|:--------------------------------------------|:-----------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip middleware. | `nil` | +| XSSProtection | `string` | XSSProtection | "0" | +| ContentTypeNosniff | `string` | ContentTypeNosniff | "nosniff" | +| XFrameOptions | `string` | XFrameOptions | "SAMEORIGIN" | +| HSTSMaxAge | `int` | HSTSMaxAge | 0 | +| HSTSExcludeSubdomains | `bool` | HSTSExcludeSubdomains | false | +| ContentSecurityPolicy | `string` | ContentSecurityPolicy | "" | +| CSPReportOnly | `bool` | CSPReportOnly | false | +| HSTSPreloadEnabled | `bool` | HSTSPreloadEnabled | false | +| ReferrerPolicy | `string` | ReferrerPolicy | "ReferrerPolicy" | +| PermissionPolicy | `string` | Permissions-Policy | "" | +| CrossOriginEmbedderPolicy | `string` | Cross-Origin-Embedder-Policy | "require-corp" | +| CrossOriginOpenerPolicy | `string` | Cross-Origin-Opener-Policy | "same-origin" | +| CrossOriginResourcePolicy | `string` | Cross-Origin-Resource-Policy | "same-origin" | +| OriginAgentCluster | `string` | Origin-Agent-Cluster | "?1" | +| XDNSPrefetchControl | `string` | X-DNS-Prefetch-Control | "off" | +| XDownloadOptions | `string` | X-Download-Options | "noopen" | +| XPermittedCrossDomain | `string` | X-Permitted-Cross-Domain-Policies | "none" | ## Default Config diff --git a/docs/api/middleware/idempotency.md b/docs/api/middleware/idempotency.md index dc0cda8a15..bab7c0e450 100644 --- a/docs/api/middleware/idempotency.md +++ b/docs/api/middleware/idempotency.md @@ -1,8 +1,9 @@ --- id: idempotency -title: Idempotency --- +# Idempotency + 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. Refer to https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header-02 for a better understanding. @@ -43,44 +44,15 @@ app.Use(idempotency.New(idempotency.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: a function which skips the middleware on safe HTTP request method. - Next func(c *fiber.Ctx) bool - - // Lifetime is the maximum lifetime of an idempotency key. - // - // Optional. Default: 30 * time.Minute - Lifetime time.Duration - - // KeyHeader is the name of the header that contains the idempotency key. - // - // Optional. Default: X-Idempotency-Key - KeyHeader string - // KeyHeaderValidate defines a function to validate the syntax of the idempotency header. - // - // Optional. Default: a function which ensures the header is 36 characters long (the size of an UUID). - KeyHeaderValidate func(string) error - - // KeepResponseHeaders is a list of headers that should be kept from the original response. - // - // Optional. Default: nil (to keep all headers) - KeepResponseHeaders []string - - // Lock locks an idempotency key. - // - // Optional. Default: an in-memory locker for this process only. - Lock Locker - - // Storage stores response data by idempotency key. - // - // Optional. Default: an in-memory storage for this process only. - Storage fiber.Storage -} -``` +| Property | Type | Description | Default | +|:--------------------|:------------------------|:-----------------------------------------------------------------------------------------|:-------------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | A function for safe methods | +| Lifetime | `time.Duration` | Lifetime is the maximum lifetime of an idempotency key. | 30 * time.Minute | +| KeyHeader | `string` | KeyHeader is the name of the header that contains the idempotency key. | "X-Idempotency-Key" | +| KeyHeaderValidate | `func(string) error` | KeyHeaderValidate defines a function to validate the syntax of the idempotency header. | A function for UUID validation | +| KeepResponseHeaders | `[]string` | KeepResponseHeaders is a list of headers that should be kept from the original response. | nil (keep all headers) | +| Lock | `Locker` | Lock locks an idempotency key. | An in-memory locker | +| Storage | `fiber.Storage` | Storage stores response data by idempotency key. | An in-memory storage | ## Default Config diff --git a/docs/api/middleware/keyauth.md b/docs/api/middleware/keyauth.md index 786d16fd3d..d95f2998e4 100644 --- a/docs/api/middleware/keyauth.md +++ b/docs/api/middleware/keyauth.md @@ -1,8 +1,9 @@ --- id: keyauth -title: Keyauth --- +# Keyauth + Key auth middleware provides a key based authentication. ## Signatures @@ -212,45 +213,15 @@ curl --header "Authorization: Bearer my-super-secret-key" http://localhost:3000 ## Config -```go -// Config defines the config for middleware. -type Config struct { - // Next defines a function to skip middleware. - // Optional. Default: nil - Next func(*fiber.Ctx) bool - - // SuccessHandler defines a function which is executed for a valid key. - // Optional. Default: nil - SuccessHandler fiber.Handler - - // ErrorHandler defines a function which is executed for an invalid key. - // It may be used to define a custom error. - // Optional. Default: 401 Invalid or expired key - ErrorHandler fiber.ErrorHandler - - // KeyLookup is a string in the form of ":" that is used - // to extract key from the request. - // Optional. Default value "header:Authorization". - // Possible values: - // - "header:" - // - "query:" - // - "form:" - // - "param:" - // - "cookie:" - KeyLookup string - - // AuthScheme to be used in the Authorization header. - // Optional. Default value "Bearer". - AuthScheme string - - // Validator is a function to validate key. - Validator func(*fiber.Ctx, string) (bool, error) - - // Context key to store the bearertoken from the token into context. - // Optional. Default: "token". - ContextKey string -} -``` +| Property | Type | Description | Default | +|:---------------|:-----------------------------------------|:-----------------------------------------------------------------------------------------------------|:------------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| SuccessHandler | `fiber.Handler` | SuccessHandler defines a function which is executed for a valid key. | `nil` | +| ErrorHandler | `fiber.ErrorHandler` | ErrorHandler defines a function which is executed for an invalid key. | `401 Invalid or expired key` | +| KeyLookup | `string` | KeyLookup is a string in the form of ":" that is used to extract key from the request. | "header:Authorization" | +| AuthScheme | `string` | AuthScheme to be used in the Authorization header. | "Bearer" | +| Validator | `func(*fiber.Ctx, string) (bool, error)` | Validator is a function to validate the key. | A function for key validation | +| ContextKey | `string` | Context key to store the bearer token from the token into context. | "token" | ## Default Config diff --git a/docs/api/middleware/limiter.md b/docs/api/middleware/limiter.md index 5a88d69f4a..8a48cbd14b 100644 --- a/docs/api/middleware/limiter.md +++ b/docs/api/middleware/limiter.md @@ -1,8 +1,9 @@ --- id: limiter -title: Limiter --- +# Limiter + 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. :::note @@ -75,59 +76,20 @@ rate = weightOfPreviousWindpw + current window's amount request. ## 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 - - // Max number of recent connections during `Duration` seconds before sending a 429 response - // - // Default: 5 - Max int - - // KeyGenerator allows you to generate custom keys, by default c.IP() is used - // - // Default: func(c *fiber.Ctx) string { - // return c.IP() - // } - KeyGenerator func(*fiber.Ctx) string - - // Expiration is the time on how long to keep records of requests in memory - // - // Default: 1 * time.Minute - Expiration time.Duration - - // LimitReached is called when a request hits the limit - // - // Default: func(c *fiber.Ctx) error { - // return c.SendStatus(fiber.StatusTooManyRequests) - // } - LimitReached fiber.Handler - - // When set to true, requests with StatusCode >= 400 won't be counted. - // - // Default: false - SkipFailedRequests bool - - // When set to true, requests with StatusCode < 400 won't be counted. - // - // Default: false - SkipSuccessfulRequests bool - - // Store is used to store the state of the middleware - // - // Default: an in memory store for this process only - Storage fiber.Storage - - // LimiterMiddleware is the struct that implements limiter middleware. - // - // Default: a new Fixed Window Rate Limiter - LimiterMiddleware LimiterHandler -} -``` +| 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 | +| 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`. @@ -160,4 +122,4 @@ storage := sqlite3.New() // From github.com/gofiber/storage/sqlite3 app.Use(limiter.New(limiter.Config{ Storage: storage, })) -``` \ No newline at end of file +``` diff --git a/docs/api/middleware/logger.md b/docs/api/middleware/logger.md index 7b00ff3589..a01e9bd54c 100644 --- a/docs/api/middleware/logger.md +++ b/docs/api/middleware/logger.md @@ -1,8 +1,9 @@ --- id: logger -title: Logger --- +# Logger + Logger middleware for [Fiber](https://github.com/gofiber/fiber) that logs HTTP request/response details. ## Signatures @@ -88,61 +89,24 @@ app.Use(logger.New(logger.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 - - // Done is a function that is called after the log string for a request is written to Output, - // and pass the log string as parameter. - // - // Optional. Default: nil - Done func(c *fiber.Ctx, logString []byte) - - // tagFunctions defines the custom tag action - // - // Optional. Default: map[string]LogFunc - CustomTags map[string]LogFunc - - // Format defines the logging tags - // - // Optional. Default: [${time}] ${status} - ${latency} ${method} ${path}\n - Format string - - // TimeFormat https://programming.guide/go/format-parse-string-time-date-example.html - // - // Optional. Default: 15:04:05 - TimeFormat string - - // TimeZone can be specified, such as "UTC" and "America/New_York" and "Asia/Chongqing", etc - // - // Optional. Default: "Local" - TimeZone string - - // TimeInterval is the delay before the timestamp is updated - // - // Optional. Default: 500 * time.Millisecond - TimeInterval time.Duration - - // Output is a writer where logs are written - // - // Default: os.Stdout - Output io.Writer - - // DisableColors defines if the logs output should be colorized - // - // Default: false - DisableColors bool - - enableColors bool - enableLatency bool - timeZoneLocation *time.Location -} -type LogFunc func(buf logger.Buffer, c *fiber.Ctx, data *logger.Data, extraParam string) (int, error) -``` + +### Config + +| Property | Type | Description | Default | +|:-----------------|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| Done | `func(*fiber.Ctx, []byte)` | Done is a function that is called after the log string for a request is written to Output, and pass the log string as parameter. | `nil` | +| CustomTags | `map[string]LogFunc` | tagFunctions defines the custom tag action. | `map[string]LogFunc` | +| Format | `string` | Format defines the logging tags. | `[${time}] ${status} - ${latency} ${method} ${path}\n` | +| TimeFormat | `string` | TimeFormat defines the time format for log timestamps. | `15:04:05` | +| TimeZone | `string` | TimeZone can be specified, such as "UTC" and "America/New_York" and "Asia/Chongqing", etc | `"Local"` | +| TimeInterval | `time.Duration` | TimeInterval is the delay before the timestamp is updated. | `500 * time.Millisecond` | +| Output | `io.Writer` | Output is a writer where logs are written. | `os.Stdout` | +| DisableColors | `bool` | DisableColors defines if the logs output should be colorized. | `false` | +| enableColors | `bool` | Internal field for enabling colors in the log output. (This is not a user-configurable field) | - | +| enableLatency | `bool` | Internal field for enabling latency measurement in logs. (This is not a user-configurable field) | - | +| timeZoneLocation | `*time.Location` | Internal field for the time zone location. (This is not a user-configurable field) | - | + ## Default Config ```go var ConfigDefault = Config{ diff --git a/docs/api/middleware/monitor.md b/docs/api/middleware/monitor.md index 0c13509a29..cbac367ce4 100644 --- a/docs/api/middleware/monitor.md +++ b/docs/api/middleware/monitor.md @@ -1,8 +1,9 @@ --- id: monitor -title: Monitor --- +# Monitor + Monitor middleware for [Fiber](https://github.com/gofiber/fiber) that reports server metrics, inspired by [express-status-monitor](https://github.com/RafalWilinski/express-status-monitor) :::caution @@ -48,47 +49,15 @@ You can also access the API endpoint with ## Config -```go -// Config defines the config for middleware. -type Config struct { - // Metrics page title - // - // Optional. Default: "Fiber Monitor" - Title string - - // Refresh period - // - // Optional. Default: 3 seconds - Refresh time.Duration - - // Whether the service should expose only the monitoring API. - // - // Optional. Default: false - APIOnly bool - - // Next defines a function to skip this middleware when returned true. - // - // Optional. Default: nil - Next func(c *fiber.Ctx) bool - - // Custom HTML Code to Head Section(Before End) - // - // Optional. Default: empty - CustomHead string - - // FontURL for specify font resource path or URL . also you can use relative path - // - // Optional. Default: https://fonts.googleapis.com/css2?family=Roboto:wght@400;900&display=swap - FontURL string - - // ChartJsURL for specify ChartJS library path or URL . also you can use relative path - // - // Optional. Default: https://cdn.jsdelivr.net/npm/chart.js@2.9/dist/Chart.bundle.min.js - ChartJsURL string - - index string -} -``` +| Property | Type | Description | Default | +|:-----------|:------------------------|:--------------------------------------------------------------------|:----------------------------------------------------------------------------| +| Title | `string` | Metrics page title | "Fiber Monitor" | +| Refresh | `time.Duration` | Refresh period | 3 seconds | +| APIOnly | `bool` | Whether the service should expose only the monitoring API | false | +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| CustomHead | `string` | Custom HTML Code to Head Section(Before End) | empty | +| FontURL | `string` | FontURL for specify font resource path or URL | "https://fonts.googleapis.com/css2?family=Roboto:wght@400;900&display=swap" | +| ChartJsURL | `string` | ChartJsURL for specify ChartJS library path or URL | "https://cdn.jsdelivr.net/npm/chart.js@2.9/dist/Chart.bundle.min.js" | ## Default Config diff --git a/docs/api/middleware/pprof.md b/docs/api/middleware/pprof.md index e716a4f78d..c4808f2c1d 100644 --- a/docs/api/middleware/pprof.md +++ b/docs/api/middleware/pprof.md @@ -1,8 +1,9 @@ --- id: pprof -title: Pprof --- +# Pprof + Pprof middleware for [Fiber](https://github.com/gofiber/fiber) that serves via its HTTP server runtime profiling data in the format expected by the pprof visualization tool. The package is typically only imported for the side effect of registering its HTTP handlers. The handled paths all begin with /debug/pprof/. ## Signatures @@ -38,22 +39,10 @@ app.Use(pprof.New(pprof.Config{Prefix: "/endpoint-prefix"})) ## 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 - - // Prefix defines a URL prefix added before "/debug/pprof". - // Note that it should start with (but not end with) a slash. - // Example: "/federated-fiber" - // - // Optional. Default: "" - Prefix string -} -``` +| Property | Type | Description | Default | +|:---------|:------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------|:--------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| Prefix | `string` | Prefix defines a URL prefix added before "/debug/pprof". Note that it should start with (but not end with) a slash. Example: "/federated-fiber" | "" | ## Default Config diff --git a/docs/api/middleware/proxy.md b/docs/api/middleware/proxy.md index 4395a2554b..fd0db609d9 100644 --- a/docs/api/middleware/proxy.md +++ b/docs/api/middleware/proxy.md @@ -1,8 +1,9 @@ --- id: proxy -title: Proxy --- +# Proxy + Proxy middleware for [Fiber](https://github.com/gofiber/fiber) that allows you to proxy requests to multiple servers. ## Signatures @@ -140,55 +141,17 @@ app.Use(proxy.BalancerForward([]string{ ## 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 - - // Servers defines a list of :// HTTP servers, - // - // which are used in a round-robin manner. - // i.e.: "https://foobar.com, http://www.foobar.com" - // - // Required - Servers []string - - // ModifyRequest allows you to alter the request - // - // Optional. Default: nil - ModifyRequest fiber.Handler - - // ModifyResponse allows you to alter the response - // - // Optional. Default: nil - ModifyResponse fiber.Handler - - // Timeout is the request timeout used when calling the proxy client - // - // Optional. Default: 1 second - Timeout time.Duration - - // Per-connection buffer size for requests' reading. - // This also limits the maximum header size. - // Increase this buffer if your clients send multi-KB RequestURIs - // and/or multi-KB headers (for example, BIG cookies). - ReadBufferSize int - - // Per-connection buffer size for responses' writing. - WriteBufferSize int - - // tls config for the http client. - TlsConfig *tls.Config - - // Client is custom client when client config is complex. - // Note that Servers, Timeout, WriteBufferSize, ReadBufferSize and TlsConfig - // will not be used if the client are set. - Client *fasthttp.LBClient -} -``` +| Property | Type | Description | Default | +|:----------------|:-----------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| Servers | `[]string` | Servers defines a list of :// HTTP servers, which are used in a round-robin manner. i.e.: "https://foobar.com, http://www.foobar.com" | (Required) | +| ModifyRequest | `fiber.Handler` | ModifyRequest allows you to alter the request. | `nil` | +| ModifyResponse | `fiber.Handler` | ModifyResponse allows you to alter the response. | `nil` | +| Timeout | `time.Duration` | Timeout is the request timeout used when calling the proxy client. | 1 second | +| ReadBufferSize | `int` | Per-connection buffer size for requests' reading. This also limits the maximum header size. Increase this buffer if your clients send multi-KB RequestURIs and/or multi-KB headers (for example, BIG cookies). | (Not specified) | +| WriteBufferSize | `int` | Per-connection buffer size for responses' writing. | (Not specified) | +| TlsConfig | `*tls.Config` (or `*fasthttp.TLSConfig` in v3) | TLS config for the HTTP client. | `nil` | +| Client | `*fasthttp.LBClient` | Client is a custom client when client config is complex. | `nil` | ## Default Config diff --git a/docs/api/middleware/recover.md b/docs/api/middleware/recover.md index 9388ff2156..81f67fddbc 100644 --- a/docs/api/middleware/recover.md +++ b/docs/api/middleware/recover.md @@ -1,8 +1,9 @@ --- id: recover -title: Recover --- +# Recover + Recover middleware for [Fiber](https://github.com/gofiber/fiber) that recovers from panics anywhere in the stack chain and handles the control to the centralized [ErrorHandler](https://docs.gofiber.io/guide/error-handling). ## Signatures @@ -36,25 +37,11 @@ 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 - - // EnableStackTrace enables handling stack trace - // - // Optional. Default: false - EnableStackTrace bool - - // StackTraceHandler defines a function to handle stack trace - // - // Optional. Default: defaultStackTraceHandler - StackTraceHandler func(c *fiber.Ctx, e interface{}) -} -``` +| Property | Type | Description | Default | +|:------------------|:--------------------------------|:--------------------------------------------------------------------|:-------------------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| EnableStackTrace | `bool` | EnableStackTrace enables handling stack trace. | `false` | +| StackTraceHandler | `func(*fiber.Ctx, interface{})` | StackTraceHandler defines a function to handle stack trace. | defaultStackTraceHandler | ## Default Config diff --git a/docs/api/middleware/redirect.md b/docs/api/middleware/redirect.md index ebb47c844b..762aa0b5d3 100644 --- a/docs/api/middleware/redirect.md +++ b/docs/api/middleware/redirect.md @@ -1,8 +1,9 @@ --- id: redirect -title: Redirect --- +# Redirect + Redirection middleware for Fiber. ## Signatures @@ -52,30 +53,11 @@ curl http://localhost:3000/old/hello ## Config -```go -// Config defines the config for middleware. -type Config struct { - // Filter defines a function to skip middleware. - // Optional. Default: nil - Next func(*fiber.Ctx) bool - - // Rules defines the URL path rewrite rules. The values captured in asterisk can be - // retrieved by index e.g. $1, $2 and so on. - // Required. Example: - // "/old": "/new", - // "/api/*": "/$1", - // "/js/*": "/public/javascripts/$1", - // "/users/*/orders/*": "/user/$1/order/$2", - Rules map[string]string - - // The status code when redirecting - // This is ignored if Redirect is disabled - // Optional. Default: 302 (fiber.StatusFound) - StatusCode int - - rulesRegex map[*regexp.Regexp]string -} -``` +| Property | Type | Description | Default | +|:-----------|:------------------------|:---------------------------------------------------------------------------------------------------------------------------|:-----------------------| +| Next | `func(*fiber.Ctx) bool` | Filter defines a function to skip middleware. | `nil` | +| Rules | `map[string]string` | Rules defines the URL path rewrite rules. The values captured in asterisk can be retrieved by index e.g. $1, $2 and so on. | Required | +| StatusCode | `int` | The status code when redirecting. This is ignored if Redirect is disabled. | 302 Temporary Redirect | ## Default Config diff --git a/docs/api/middleware/requestid.md b/docs/api/middleware/requestid.md index aafbd1799e..200ebf4bdd 100644 --- a/docs/api/middleware/requestid.md +++ b/docs/api/middleware/requestid.md @@ -1,8 +1,9 @@ --- id: requestid -title: RequestID --- +# RequestID + RequestID middleware for [Fiber](https://github.com/gofiber/fiber) that adds an indentifier to the response. ## Signatures @@ -39,31 +40,12 @@ app.Use(requestid.New(requestid.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 - - // Header is the header key where to get/set the unique request ID - // - // Optional. Default: "X-Request-ID" - Header string - - // Generator defines a function to generate the unique identifier. - // - // Optional. Default: utils.UUID - Generator func() string - - // ContextKey defines the key used when storing the request ID in - // the locals for a specific request. - // - // Optional. Default: requestid - ContextKey interface{} -} -``` +| Property | Type | Description | Default | +|:-----------|:------------------------|:--------------------------------------------------------------------------------------------------|:---------------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | +| Header | `string` | Header is the header key where to get/set the unique request ID. | "X-Request-ID" | +| Generator | `func() string` | Generator defines a function to generate the unique identifier. | utils.UUID | +| ContextKey | `interface{}` | ContextKey defines the key used when storing the request ID in the locals for a specific request. | "requestid" | ## Default Config The default config uses a fast UUID generator which will expose the number of diff --git a/docs/api/middleware/rewrite.md b/docs/api/middleware/rewrite.md index 7111cbdde5..fd59595841 100644 --- a/docs/api/middleware/rewrite.md +++ b/docs/api/middleware/rewrite.md @@ -1,10 +1,10 @@ --- id: rewrite -title: Rewrite --- -Rewrite middleware rewrites the URL path based on provided rules. It can be helpful for backward compatibility or just creating cleaner and more descriptive links. +# Rewrite +Rewrite middleware rewrites the URL path based on provided rules. It can be helpful for backward compatibility or just creating cleaner and more descriptive links. ## Signatures @@ -12,6 +12,13 @@ Rewrite middleware rewrites the URL path based on provided rules. It can be help func New(config ...Config) fiber.Handler ``` +## Config + +| Property | Type | Description | Default | +|:---------|:------------------------|:-----------------------------------------------------------------------------------------------------|:-----------| +| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip middleware. | `nil` | +| Rules | `map[string]string` | Rules defines the URL path rewrite rules. The values captured in asterisk can be retrieved by index. | (Required) | + ### Examples ```go package main diff --git a/docs/api/middleware/session.md b/docs/api/middleware/session.md index f27eaf42bc..22c93feb3b 100644 --- a/docs/api/middleware/session.md +++ b/docs/api/middleware/session.md @@ -1,8 +1,9 @@ --- id: session -title: Session --- +# Session + Session middleware for [Fiber](https://github.com/gofiber/fiber). :::note @@ -86,62 +87,19 @@ app.Get("/", func(c *fiber.Ctx) error { ## Config -```go -// Config defines the config for middleware. -type Config struct { - // Allowed session duration - // Optional. Default value 24 * time.Hour - Expiration time.Duration - - // Storage interface to store the session data - // Optional. Default value memory.New() - Storage fiber.Storage - - // KeyLookup is a string in the form of ":" that is used - // to extract session id from the request. - // Possible values: "header:", "query:" or "cookie:" - // Optional. Default value "cookie:session_id". - KeyLookup string - - // Domain of the CSRF cookie. - // Optional. Default value "". - CookieDomain string - - // Path of the CSRF cookie. - // Optional. Default value "". - CookiePath string - - // Indicates if CSRF cookie is secure. - // Optional. Default value false. - CookieSecure bool - - // Indicates if CSRF cookie is HTTP only. - // Optional. Default value false. - CookieHTTPOnly bool - - // Value of SameSite cookie. - // Optional. Default value "Lax". - CookieSameSite string - - // Decides whether cookie should last for only the browser sesison. - // Ignores Expiration if set to true - // Optional. Default value false. - CookieSessionOnly bool - - // KeyGenerator generates the session key. - // Optional. Default value utils.UUIDv4 - KeyGenerator func() string - - // Deprecated: Please use KeyLookup - CookieName string - - // Source defines where to obtain the session id - source Source - - // The session name - sessionName string -} -``` +| Property | Type | Description | Default | +|:------------------------|:----------------|:------------------------------------------------------------------------------------------------------------|:----------------------| +| Expiration | `time.Duration` | Allowed session duration. | `24 * time.Hour` | +| Storage | `fiber.Storage` | Storage interface to store the session data. | `memory.New()` | +| KeyLookup | `string` | KeyLookup is a string in the form of ":" that is used to extract session id from the request. | `"cookie:session_id"` | +| CookieDomain | `string` | Domain of the cookie. | `""` | +| CookiePath | `string` | Path of the cookie. | `""` | +| CookieSecure | `bool` | Indicates if cookie is secure. | `false` | +| CookieHTTPOnly | `bool` | Indicates if cookie is HTTP only. | `false` | +| CookieSameSite | `string` | Value of SameSite cookie. | `"Lax"` | +| CookieSessionOnly | `bool` | Decides whether cookie should last for only the browser session. Ignores Expiration if set to true. | `false` | +| KeyGenerator | `func() string` | KeyGenerator generates the session key. | `utils.UUIDv4` | +| CookieName (Deprecated) | `string` | Deprecated: Please use KeyLookup. The session name. | `""` | ## Default Config @@ -176,4 +134,4 @@ store := session.New(session.Config{ }) ``` -To use the store, see the [Examples](#examples). \ No newline at end of file +To use the store, see the [Examples](#examples). diff --git a/docs/api/middleware/skip.md b/docs/api/middleware/skip.md index 820c7b2c38..0923bd0ee2 100644 --- a/docs/api/middleware/skip.md +++ b/docs/api/middleware/skip.md @@ -1,8 +1,9 @@ --- id: skip -title: Skip --- +# Skip + Skip middleware for [Fiber](https://github.com/gofiber/fiber) that skips a wrapped handler if a predicate is true. ## Signatures @@ -43,4 +44,4 @@ func BasicHandler(ctx *fiber.Ctx) error { :::tip app.Use will handle requests from any route, and any method. In the example above, it will only skip if the method is GET. -::: \ No newline at end of file +::: diff --git a/docs/api/middleware/timeout.md b/docs/api/middleware/timeout.md index 36db36f3bb..5fdf18d527 100644 --- a/docs/api/middleware/timeout.md +++ b/docs/api/middleware/timeout.md @@ -1,8 +1,9 @@ --- id: timeout -title: Timeout --- +# Timeout + There exist two distinct implementations of timeout middleware [Fiber](https://github.com/gofiber/fiber). **New** diff --git a/middleware/session/config.go b/middleware/session/config.go index 62a80279ff..fe74132f5c 100644 --- a/middleware/session/config.go +++ b/middleware/session/config.go @@ -26,19 +26,19 @@ type Config struct { // Optional. Default value "cookie:session_id". KeyLookup string - // Domain of the CSRF cookie. + // Domain of the cookie. // Optional. Default value "". CookieDomain string - // Path of the CSRF cookie. + // Path of the cookie. // Optional. Default value "". CookiePath string - // Indicates if CSRF cookie is secure. + // Indicates if cookie is secure. // Optional. Default value false. CookieSecure bool - // Indicates if CSRF cookie is HTTP only. + // Indicates if cookie is HTTP only. // Optional. Default value false. CookieHTTPOnly bool