Sync docs for release https://github.com/gofiber/fiber/releases/tag/v3.4.0

Author: github-actions[bot]

versioned_docs/version-v3.x/addon/retry.md

@@ -107,6 +107,11 @@ type Config struct {
     //
     // Optional. Default: 10
     MaxRetryCount int
+
+    // currentInterval tracks the current waiting time.
+    //
+    // Optional. Default: 1 * time.Second
+    currentInterval time.Duration
 }
 ```
 

versioned_docs/version-v3.x/api/app.md

@@ -157,6 +157,7 @@ type Register interface {
     Options(handler any, handlers ...any) Register
     Trace(handler any, handlers ...any) Register
     Patch(handler any, handlers ...any) Register
+    Query(handler any, handlers ...any) Register
 
     Add(methods []string, handler any, handlers ...any) Register
 

versioned_docs/version-v3.x/api/constants.md

@@ -1150,7 +1150,11 @@ By default, `c.IP()` returns the remote IP address from the TCP connection. When
 
 **Important:** You must enable `TrustProxy` and configure trusted proxy IPs to prevent header spoofing. Simply setting `ProxyHeader` alone will not work.
 
-**Note:** When using a proxy header such as `X-Forwarded-For`, `c.IP()` returns the raw header value unless [`EnableIPValidation`](fiber.md#enableipvalidation) is enabled. For `X-Forwarded-For`, this raw value may be a comma-separated list of IPs; enable `EnableIPValidation` if you need `c.IP()` to return a single, validated client IP.
+**Note:** When using a proxy header such as `X-Forwarded-For`, `c.IP()` returns the raw header value unless [`EnableIPValidation`](fiber.md#enableipvalidation) is enabled.
+
+**Chain parsing with `EnableIPValidation`:** For `X-Forwarded-For`, the raw value is a comma-separated chain that grows from left to right as the request passes through each proxy. With validation enabled, `c.IP()` walks the chain from right to left, skipping every IP that matches the configured `TrustProxyConfig` (exact IPs, CIDR ranges, loopback, private or link-local) and returns the first non-trusted IP it finds. This matches the behavior recommended by [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For#selecting_an_ip_address) and the convention used by Nginx (`set_real_ip_from` + `real_ip_recursive`), Apache `mod_remoteip`, and Envoy (`xff_num_trusted_hops`).
+
+If every IP in the chain matches the trusted set, the leftmost IP is returned as a fallback. If the chain is empty, `c.IP()` falls back to the TCP remote address.
 :::
 
 #### Configuration for apps behind a reverse proxy
@@ -1564,7 +1568,11 @@ app.Get("/", func(c fiber.Ctx) error {
 
 ### Protocol
 
-Contains the request protocol string: `http` or `https` for **TLS** requests.
+Returns the HTTP protocol version of the request: `HTTP/1.1` or `HTTP/2`.
+
+:::info
+To get the request scheme (`http` or `https`), use [`Scheme`](#scheme) instead.
+:::
 
 ```go title="Signature"
 func (c fiber.Ctx) Protocol() string
@@ -1574,7 +1582,7 @@ func (c fiber.Ctx) Protocol() string
 // GET http://example.com
 
 app.Get("/", func(c fiber.Ctx) error {
-  c.Protocol() // "http"
+  c.Protocol() // "HTTP/1.1"
 
   // ...
 })
@@ -1828,7 +1836,7 @@ app.Post("/", func(c fiber.Ctx) error {
 })
 ```
 
-### Schema
+### Scheme
 
 Contains the request protocol string: `http` or `https` for TLS requests.
 
@@ -1837,14 +1845,14 @@ Please use [`Config.TrustProxy`](fiber.md#trustproxy) to prevent header spoofing
 :::
 
 ```go title="Signature"
-func (c fiber.Ctx) Schema() string
+func (c fiber.Ctx) Scheme() string
 ```
 
 ```go title="Example"
 // GET http://example.com
 
 app.Get("/", func(c fiber.Ctx) error {
-  c.Schema() // "http"
+  c.Scheme() // "http"
 
   // ...
 })
@@ -1860,7 +1868,7 @@ func (c fiber.Ctx) Secure() bool
 
 ```go title="Example"
 // Secure() method is equivalent to:
-c.Protocol() == "https"
+c.Scheme() == "https"
 ```
 
 ### Stale

versioned_docs/version-v3.x/api/ctx.md

@@ -120,7 +120,9 @@ app.Listen(":8080", fiber.ListenConfig{
 | <Reference id="ShutdownTimeout">ShutdownTimeout</Reference>             | `time.Duration`               | Specifies the maximum duration to wait for the server to gracefully shutdown. When the timeout is reached, the graceful shutdown process is interrupted and forcibly terminated, and the `context.DeadlineExceeded` error is passed to the `OnPostShutdown` callback. Set to 0 to disable the timeout and wait indefinitely. | `10 * time.Second` |
 | <Reference id="listeneraddrfunc">ListenerAddrFunc</Reference>           | `func(addr net.Addr)`         | Allows accessing and customizing `net.Listener`.                                                                                                                                                                                                                                                                             | `nil`              |
 | <Reference id="listenernetwork">ListenerNetwork</Reference>             | `string`                      | Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only), "unix" (Unix Domain Sockets). WARNING: When prefork is set to true, only "tcp4" and "tcp6" can be chosen.                                                                                                                                                  | `tcp4`             |
+| <Reference id="preforkrecoverinterval">PreforkRecoverInterval</Reference> | `time.Duration`             | Delays the respawn of a crashed child process by this duration. Only applies when prefork is enabled.                                                                                                                                                                                                                        | `0` (respawn immediately) |
 | <Reference id="preforkrecoverthreshold">PreforkRecoverThreshold</Reference> | `int`                      | Defines the maximum number of child process restarts after crashes before the prefork master exits with an error. Only applies when prefork is enabled.                                                                                                                                                                        | `max(1, runtime.GOMAXPROCS(0) / 2)` |
+| <Reference id="preforkshutdowngraceperiod">PreforkShutdownGracePeriod</Reference> | `time.Duration`      | How long the prefork master waits for child processes to exit after SIGTERM before sending SIGKILL during shutdown. On Windows children are always killed immediately. Only applies when prefork is enabled.                                                                                                                 | `5 * time.Second`  |
 | <Reference id="preforklogger">PreforkLogger</Reference>                 | `PreforkLogger`      | Sets a custom logger for the prefork process manager. Only applies when prefork is enabled.                                                                                                                                                                                                                                  | Fiber logger       |
 | <Reference id="unixsocketfilemode">UnixSocketFileMode</Reference>       | `os.FileMode`                 | FileMode to set for Unix Domain Socket (ListenerNetwork must be "unix")                                                                                                                                                                                                                                                      | `0770`             |
 | <Reference id="tlsconfigfunc">TLSConfigFunc</Reference>                 | `func(tlsConfig *tls.Config)` | Allows customizing `tls.Config` as you want. Ignored when `TLSConfig` is set.                                                                                                                                                                                                                                                | `nil`              |

versioned_docs/version-v3.x/api/fiber.md

@@ -164,7 +164,7 @@ Similar to [Laravel](https://laravel.com/docs/11.x/redirects#redirecting-with-fl
 Retrieve all flash messages. See [With](#with) for details.
 
 ```go title="Signature"
-func (r *Redirect) Messages() map[string]string
+func (r *Redirect) Messages() []FlashMessage
 ```
 
 ```go title="Example"
@@ -179,13 +179,13 @@ app.Get("/", func(c fiber.Ctx) error {
 Get a flash message by key; see [With](#with).
 
 ```go title="Signature"
-func (r *Redirect) Message(key string) *Redirect
+func (r *Redirect) Message(key string) FlashMessage
 ```
 
 ```go title="Example"
 app.Get("/", func(c fiber.Ctx) error {
   message := c.Redirect().Message("status")
-  return c.SendString(message)
+  return c.SendString(message.Value)
 })
 ```
 
@@ -194,7 +194,7 @@ app.Get("/", func(c fiber.Ctx) error {
 Retrieve stored input data. See [WithInput](#withinput).
 
 ```go title="Signature"
-func (r *Redirect) OldInputs() map[string]string
+func (r *Redirect) OldInputs() []OldInputData
 ```
 
 ```go title="Example"
@@ -209,13 +209,13 @@ app.Get("/", func(c fiber.Ctx) error {
 Get stored input data by key; see [WithInput](#withinput).
 
 ```go title="Signature"
-func (r *Redirect) OldInput(key string) string
+func (r *Redirect) OldInput(key string) OldInputData
 ```
 
 ```go title="Example"
 app.Get("/name", func(c fiber.Ctx) error {
   oldInput := c.Redirect().OldInput("name")
-  return c.SendString(oldInput)
+  return c.SendString(oldInput.Value)
 })
 ```
 

versioned_docs/version-v3.x/api/redirect.md

@@ -18,28 +18,32 @@ This structure is designed to be both flexible and efficient, allowing you to ea
 
 ```go
 type Request struct {
-    url       string
-    method    string
-    userAgent string
-    boundary  string
-    referer   string
-    ctx       context.Context
-    header    *Header
-    params    *QueryParam
-    cookies   *Cookie
-    path      *PathParam
+    ctx context.Context
 
-    timeout      time.Duration
-    maxRedirects int
+    body    any
+    header  Header
+    params  QueryParam
+    cookies Cookie
+    path    PathParam
 
     client *Client
 
-    body     any
-    formData *FormData
-    files    []*File
-    bodyType bodyType
+    formData FormData
 
     RawRequest *fasthttp.Request
+    url        string
+    method     string
+    userAgent  string
+    boundary   string
+    referer    string
+    files      []*File
+
+    timeout      time.Duration
+    maxRedirects int
+
+    bodyType bodyType
+
+    isPathNormalizingDisabled bool
 }
 ```
 
@@ -101,6 +105,14 @@ func (r *Request) Head(url string) (*Response, error)
 func (r *Request) Options(url string) (*Response, error)
 ```
 
+### Query
+
+**Query** sends a QUERY request. It sets the URL and method to QUERY, then sends the request.
+
+```go title="Signature"
+func (r *Request) Query(url string) (*Response, error)
+```
+
 ### Custom
 
 **Custom** sends a request using a custom HTTP method. For example, you can use this to send a TRACE or CONNECT request.

versioned_docs/version-v3.x/client/request.md

@@ -49,33 +49,13 @@ See [examples](examples.md) for more detailed usage.
 
 ```go
 type Client struct {
-    mu sync.RWMutex
+    logger    log.CommonLogger
+    transport httpClientTransport
 
-    fasthttp *fasthttp.Client
-
-    baseURL   string
-    userAgent string
-    referer   string
-    header    *Header
-    params    *QueryParam
-    cookies   *Cookie
-    path      *PathParam
-
-    debug bool
-
-    timeout time.Duration
-
-    // user-defined request hooks
-    userRequestHooks []RequestHook
-
-    // client package-defined request hooks
-    builtinRequestHooks []RequestHook
-
-    // user-defined response hooks
-    userResponseHooks []ResponseHook
-
-    // client package-defined response hooks
-    builtinResponseHooks []ResponseHook
+    header  *Header
+    params  *QueryParam
+    cookies *Cookie
+    path    *PathParam
 
     jsonMarshal   utils.JSONMarshal
     jsonUnmarshal utils.JSONUnmarshal
@@ -84,16 +64,20 @@ type Client struct {
     cborMarshal   utils.CBORMarshal
     cborUnmarshal utils.CBORUnmarshal
 
-    cookieJar *CookieJar
-
-    // proxy
-    proxyURL string
-
-    // retry
-    retryConfig *RetryConfig
+    cookieJar            *CookieJar
+    retryConfig          *RetryConfig
+    baseURL              string
+    userAgent            string
+    referer              string
+    userRequestHooks     []RequestHook
+    builtinRequestHooks  []RequestHook
+    userResponseHooks    []ResponseHook
+    builtinResponseHooks []ResponseHook
 
-    // logger
-    logger log.CommonLogger
+    timeout                   time.Duration
+    mu                        sync.RWMutex
+    isDebug                   bool
+    isPathNormalizingDisabled bool
 }
 ```
 
@@ -149,6 +133,14 @@ Sends a PATCH request.
 func (c *Client) Patch(url string, cfg ...Config) (*Response, error)
 ```
 
+### Query
+
+Sends a QUERY request.
+
+```go title="Signature"
+func (c *Client) Query(url string, cfg ...Config) (*Response, error)
+```
+
 ### Delete
 
 Sends a DELETE request.
@@ -893,6 +885,14 @@ Patch is a convenience method that sends a PATCH request using the `defaultClien
 func Patch(url string, cfg ...Config) (*Response, error)
 ```
 
+### Query
+
+Query is a convenience method that sends a QUERY request using the `defaultClient`.
+
+```go title="Signature"
+func Query(url string, cfg ...Config) (*Response, error)
+```
+
 ### Delete
 
 Delete is a convenience method that sends a DELETE request using the `defaultClient`.
@@ -922,7 +922,7 @@ func Options(url string, cfg ...Config) (*Response, error)
 **Replace** replaces the default client with a new one. It returns a function that can restore the old client.
 
 :::caution
-Do not modify the default client concurrently.
+Replacing the default client is concurrency-safe, but mutating the same `Client` instance still requires external synchronization.
 :::
 
 ```go title="Signature"

versioned_docs/version-v3.x/client/rest.md

@@ -198,3 +198,24 @@ For details on how to:
 * Convert `fiber.Ctx` to `http.Request`
 
 See the dedicated documentation: [Adaptor Documentation](../middleware/adaptor.md).
+
+## Troubleshooting common errors
+
+Crashes that surface in unrelated packages, with stack traces that never mention Fiber, usually trace back to a context value kept past the handler. The cases below name the symptom so a search for the panic text lands here.
+
+### Panic `id (N) <= evictCount (M)` (hpack / HTTP/2 / gRPC) {#panic-id-evictcount-hpack-grpc}
+
+This is not a bug in Fiber, gRPC, or `golang.org/x/net/http2`. It means a Fiber zero-copy context value (a header from `c.Get`, or `c.Query`, `c.Params`, `c.Cookies`, `c.Body`) was kept past the handler. Fiber reuses the request buffer on the next request, so the retained bytes change underneath whatever stored them. See [Zero Allocation](../intro.md#zero-allocation) for the underlying behavior.
+
+A common trigger is forwarding a header into a long-lived gRPC / HTTP/2 client's `metadata`. The value is held in the connection's HPACK dynamic table and later mutates, crashing the process inside the HPACK encoder, in a stack trace that never mentions Fiber:
+
+```text
+panic: id (N) <= evictCount (M)
+    golang.org/x/net/http2/hpack.(*headerFieldTable).idToIndex
+    ...
+    google.golang.org/grpc/internal/transport.(*loopyWriter).writeHeader
+```
+
+The crash is decoupled from your handler in both time and call stack, so ordinary tests and even the `-race` detector usually miss it.
+
+The fix is to detach the value before you keep it: copy it with `utils.CopyString` (or `strings.Clone`), or enable [`Immutable`](../api/fiber.md#immutable). A full reproduction is in [gofiber/fiber#4464](https://github.com/gofiber/fiber/issues/4464).

versioned_docs/version-v3.x/extra/faq.md

@@ -401,7 +401,8 @@ Fiber provides a comprehensive hook system that allows you to run custom functio
 - OnName: Invoked when a route is assigned a name.
 - OnGroup: Triggered when a group is created.
 - OnListen: Runs when the server starts listening.
-- OnShutdown: Called during graceful shutdown.
+- OnPreShutdown: Runs before the application shuts down.
+- OnPostShutdown: Runs after shutdown and receives the shutdown result.
 - OnFork: Invoked when a child process is forked.
 - OnMount: Used when a sub‑application is mounted.
 
@@ -412,15 +413,17 @@ flowchart TD
     ON[OnName]
     OG[OnGroup]
     OL[OnListen]
-    OS[OnShutdown]
+    OPRS[OnPreShutdown]
+    OPOS[OnPostShutdown]
     OF[OnFork]
     OM[OnMount]
 
     H --> OR
     H --> ON
     H --> OG
     H --> OL
-    H --> OS
+    H --> OPRS
+    H --> OPOS
     H --> OF
     H --> OM
 ```