Merge branch 'main' into fix-x-real-ip-header-handling-in-balancerforward

Author: gaby

app_integration_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"errors"
 	"io"
+	"mime/multipart"
 	"net"
 	"net/http"
 	"net/http/httptest"
@@ -578,6 +579,45 @@ func Test_Integration_App_ServerErrorHandler_PreservesHelmetHeadersOnBodyLimit(t
 	require.Equal(t, "require-corp", string(resp.Header.Peek("Cross-Origin-Embedder-Policy")))
 }
 
+func Test_Integration_App_ServerErrorHandler_CustomMultipartBodyLimit(t *testing.T) {
+	t.Parallel()
+
+	app := fiber.New(fiber.Config{
+		BodyLimit: 128,
+		ErrorHandler: func(c fiber.Ctx, err error) error {
+			code := fiber.StatusInternalServerError
+			var fiberErr *fiber.Error
+			if errors.As(err, &fiberErr) {
+				code = fiberErr.Code
+			}
+			return c.Status(code).JSON(fiber.Map{
+				"code":    code,
+				"message": err.Error(),
+			})
+		},
+	})
+	app.Post("/", func(c fiber.Ctx) error {
+		return c.SendString("ok")
+	})
+
+	body := &bytes.Buffer{}
+	writer := multipart.NewWriter(body)
+	fileWriter, err := writer.CreateFormFile("file", "large.txt")
+	require.NoError(t, err)
+	_, err = fileWriter.Write(bytes.Repeat([]byte{'a'}, 256))
+	require.NoError(t, err)
+	require.NoError(t, writer.Close())
+
+	resp := performOversizedRequest(t, app, func(req *fasthttp.Request) {
+		req.Header.Set(fiber.HeaderContentType, writer.FormDataContentType())
+		req.SetBody(body.Bytes())
+	})
+
+	require.Equal(t, fiber.StatusRequestEntityTooLarge, resp.StatusCode())
+	require.Contains(t, string(resp.Header.ContentType()), fiber.MIMEApplicationJSON)
+	require.JSONEq(t, `{"code":413,"message":"Request Entity Too Large"}`, string(resp.Body()))
+}
+
 func Test_Integration_App_ServerErrorHandler_PreservesRequestID(t *testing.T) {
 	const expectedRequestID = "integration-request-id"
 

docs/api/log.md

@@ -48,7 +48,9 @@ type ConfigurableLogger[T any] interface {
 type AllLogger[T any] interface {
     CommonLogger
     ConfigurableLogger[T]
-    WithLogger
+
+    // WithContext returns a new logger with the given context.
+    WithContext(ctx any) CommonLogger
 }
 ```
 
@@ -153,11 +155,16 @@ Setting the log level allows you to control the verbosity of the logs, filtering
 
 ### Writing Logs to Stderr
 
+`log.SetOutput(os.Stderr)` redirects the default logger to standard error.
+
 ```go
-var logger fiberlog.AllLogger[*log.Logger] = &defaultLogger{
-    stdlog: log.New(os.Stderr, "", log.LstdFlags|log.Lshortfile|log.Lmicroseconds),
-    depth:  4,
-}
+import (
+    "os"
+
+    fiberlog "github.com/gofiber/fiber/v3/log"
+)
+
+fiberlog.SetOutput(os.Stderr)
 ```
 
 This lets you route logs to a file, service, or any destination.
@@ -198,7 +205,125 @@ commonLogger := log.WithContext(ctx)
 commonLogger.Info("info")
 ```
 
-Context binding adds request-specific data for easier tracing.
+Context binding can render request-specific data for easier tracing. The default context format is `log.DefaultFormat` (the empty string), so `log.WithContext(ctx)` adds no fields until you configure a format with `log.SetContextTemplate` (or its `MustSetContextTemplate` panic-on-error variant).
+
+`SetContextTemplate` configures Fiber's built-in default logger. Custom loggers registered with `SetLogger` keep full control over their own `WithContext` behavior and should implement equivalent enrichment themselves when needed.
+
+```go
+import (
+    "github.com/gofiber/fiber/v3"
+    "github.com/gofiber/fiber/v3/log"
+    "github.com/gofiber/fiber/v3/middleware/requestid"
+)
+
+app.Use(requestid.New())
+
+log.MustSetContextTemplate(log.ContextConfig{Format: log.RequestIDFormat})
+
+app.Get("/", func(c fiber.Ctx) error {
+    log.WithContext(c).Info("start")
+    return c.SendString("Hello, World!")
+})
+```
+
+Middleware that stores request values registers its log context tags automatically. For example, importing `requestid` makes `${requestid}` and `${request-id}` available; the actual value is filled in once `requestid.New()` runs in your handler stack. Until then the tag renders as an empty string, so a format that references `${requestid}` still compiles without `requestid.New()` in the chain.
+
+Use `log.WithContext(c)` inside handlers when you want tags to read values stored by Fiber middleware. Passing `c.Context()` only exposes values propagated into the standard request context.
+
+:::tip
+Cross-reference: the access-log integration uses the same tag names — see [middleware/logger](../middleware/logger.md#config) for the request-time format.
+:::
+
+### Glossary
+
+- **Format** — the string with `${...}` placeholders, e.g. `"[${requestid}] "`.
+- **Template** — the compiled, reusable form of a format produced by `SetContextTemplate`.
+- **Tag** — a single `${name}` (bare) or `${name:param}` (parametric) placeholder inside a format.
+
+### Signatures
+
+```go
+// Configure the active context template (or pass log.ContextConfig{} to disable).
+func SetContextTemplate(config ContextConfig) error
+func MustSetContextTemplate(config ContextConfig)
+
+// Register a tag globally; the new renderer becomes available to subsequent
+// SetContextTemplate calls. The reserved TagContextValue ("value:") name
+// cannot be registered.
+func RegisterContextTag(tag string, fn ContextTagFunc) error
+func MustRegisterContextTag(tag string, fn ContextTagFunc)
+
+// Bind a context to the default logger. ctx accepts fiber.Ctx,
+// *fasthttp.RequestCtx, context.Context, or any value exposing
+// Value(key any)/UserValue(key any).
+func WithContext(ctx any) CommonLogger
+
+// Public types referenced by the API above.
+type ContextConfig struct {
+    CustomTags map[string]ContextTagFunc
+    Format     string
+}
+type ContextData struct{}
+type ContextTagFunc = logtemplate.Func[any, ContextData]
+type Buffer        = logtemplate.Buffer
+
+// Format constants.
+const (
+    DefaultFormat   = ""
+    RequestIDFormat = "[${requestid}] "
+    KeyValueFormat  = "request-id=${request-id} username=${username} api-key=${api-key} csrf-token=${csrf-token} session-id=${session-id} "
+    TagContextValue = "value:"
+)
+```
+
+### Context Formats
+
+| Format Constant | Format String | Description |
+| :-- | :-- | :-- |
+| `DefaultFormat` | `""` | Disables contextual fields. |
+| `RequestIDFormat` | `"[${requestid}] "` | Prepends the request ID when the requestid middleware is used. |
+| `KeyValueFormat` | `"request-id=${request-id} username=${username} api-key=${api-key} csrf-token=${csrf-token} session-id=${session-id} "` | Prepends common middleware context values as key/value fields. Sensitive values are redacted by the registering middleware. |
+
+### Context Tags
+
+| Tag | Source |
+| :-- | :-- |
+| `${requestid}` / `${request-id}` | `requestid` middleware |
+| `${username}` | `basicauth` middleware — written **in clear text** for audit-log use cases. Avoid this tag if your usernames are PII. |
+| `${api-key}` | `keyauth` middleware, redacted to a 4-byte prefix |
+| `${csrf-token}` | `csrf` middleware, redacted to a 4-byte prefix |
+| `${session-id}` | `session` middleware, redacted to a 4-byte prefix |
+| `${value:key}` | Any bound value with `Value(key)` or `UserValue(key)` lookup methods |
+
+:::caution
+`${value:KEY}` looks up arbitrary context values. CR, LF, NUL, and other ASCII control bytes (except tab) are replaced with spaces before they reach the log line, so attacker-controlled values cannot forge log lines via header smuggling. The lookup still writes the value verbatim apart from that scrub — strip or hash sensitive fields before storing them on the context if you do not want them in operator logs.
+:::
+
+### Custom Context Tags
+
+Register custom tags with `log.RegisterContextTag`, then reference them from a format passed to `SetContextTemplate`. The built-in `${value:key}` tag is reserved for context-value lookups and cannot be overridden.
+
+```go
+type tenantContextKey struct{}
+
+var tenantKey tenantContextKey
+
+log.MustRegisterContextTag("tenant", func(output log.Buffer, ctx any, _ *log.ContextData, _ string) (int, error) {
+    tenant, _ := fiber.ValueFromContext[string](ctx, tenantKey)
+    return output.WriteString(tenant)
+})
+
+log.MustSetContextTemplate(log.ContextConfig{Format: "[${tenant}] "})
+
+app.Use(func(c fiber.Ctx) error {
+    fiber.StoreInContext(c, tenantKey, "acme")
+    return c.Next()
+})
+```
+
+:::note
+Register tags **before** referencing them in `SetContextTemplate`. Compiling a format that references an unregistered name returns `*logtemplate.UnknownTagError` (or panics from `MustSetContextTemplate`).
+:::
 
 ## Logger
 

docs/middleware/logger.md

@@ -10,6 +10,8 @@ Logger middleware for [Fiber](https://github.com/gofiber/fiber) that logs HTTP r
 
 ```go
 func New(config ...Config) fiber.Handler
+func RegisterTag(tag string, fn LogFunc) error
+func MustRegisterTag(tag string, fn LogFunc)
 ```
 
 ## Examples
@@ -20,6 +22,7 @@ Import the package:
 import (
     "github.com/gofiber/fiber/v3"
     "github.com/gofiber/fiber/v3/middleware/logger"
+    "github.com/gofiber/fiber/v3/middleware/requestid"
 )
 ```
 
@@ -42,13 +45,7 @@ app.Use(logger.New(logger.Config{
 // Logging Request ID
 app.Use(requestid.New()) // Ensure requestid middleware is used before the logger
 app.Use(logger.New(logger.Config{
-    CustomTags: map[string]logger.LogFunc{
-        "requestid": func(output logger.Buffer, c fiber.Ctx, data *logger.Data, extraParam string) (int, error) {
-            return output.WriteString(requestid.FromContext(c))
-        },
-    },
-    // For more options, see the Config section
-    // Use the custom tag ${requestid} as defined above.
+    // requestid.New() registers ${requestid} automatically.
     Format: "${pid} ${requestid} ${status} - ${method} ${path}\n",
 }))
 
@@ -117,6 +114,94 @@ app.Use(logger.New(logger.Config{
 }))
 ```
 
+### Auto-Registered Tags
+
+Some Fiber middleware registers logger middleware tags automatically. Register the producing middleware before `logger.New()` and then use the tag in `Format`.
+
+```go
+app.Use(requestid.New())
+app.Use(logger.New(logger.Config{
+    Format: "${requestid} ${status} ${method} ${path}\n",
+}))
+```
+
+The logger middleware resolves tags in this order:
+
+1. Built-in logger tags, such as `${method}`, `${path}`, and `${status}`.
+2. Globally registered tags from Fiber middleware or `logger.RegisterTag`.
+3. `Config.CustomTags`, which override tags with the same name for that logger instance.
+
+The following tags are registered by Fiber middleware when the middleware is initialized:
+
+| Tag | Registered by | Value |
+| :-- | :------------ | :---- |
+| `${requestid}` / `${request-id}` | `requestid.New()` | Request ID stored by the requestid middleware. |
+| `${username}` | `basicauth.New()` | Authenticated username stored by the basicauth middleware. |
+| `${api-key}` | `keyauth.New()` | Redacted API key stored by the keyauth middleware. |
+| `${csrf-token}` | `csrf.New()` | Redacted marker when the csrf middleware stores a token. |
+| `${session-id}` | `session.New()` or `session.NewWithStore()` | Redacted session ID stored by the session middleware. |
+
+:::note
+Auto-registered tags are access-log tags for `middleware/logger`. The same names are also registered for application logs in the `log` package via `logger.RegisterContextTag` — see [api/log#context-tags](../api/log.md#context-tags) for details on `log.WithContext` enrichment.
+:::
+
+### Register Tags from Custom Middleware
+
+Third-party middleware can expose logger tags with `logger.RegisterTag` or `logger.MustRegisterTag`. Use `sync.Once` so the tag is registered once even when the middleware is initialized multiple times.
+
+```go
+package tenantmw
+
+import (
+    "sync"
+
+    "github.com/gofiber/fiber/v3"
+    "github.com/gofiber/fiber/v3/middleware/logger"
+)
+
+type tenantContextKey struct{}
+
+var tenantKey tenantContextKey
+
+var registerLoggerTagsOnce sync.Once
+
+func New() fiber.Handler {
+    registerLoggerTagsOnce.Do(func() {
+        logger.MustRegisterTag("tenant", func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+            tenant, _ := fiber.ValueFromContext[string](c, tenantKey)
+            return output.WriteString(tenant)
+        })
+    })
+
+    return func(c fiber.Ctx) error {
+        fiber.StoreInContext(c, tenantKey, "acme")
+        return c.Next()
+    }
+}
+```
+
+Use the registered tag in the logger format after installing the middleware:
+
+```go
+app.Use(tenantmw.New())
+app.Use(logger.New(logger.Config{
+    Format: "${tenant} ${status} ${method} ${path}\n",
+}))
+```
+
+Use `Config.CustomTags` when one logger instance needs a local override without changing the global tag registration:
+
+```go
+app.Use(logger.New(logger.Config{
+    Format: "${tenant} ${status} ${method} ${path}\n",
+    CustomTags: map[string]logger.LogFunc{
+        "tenant": func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+            return output.WriteString("override")
+        },
+    },
+}))
+```
+
 ### Use Logger Middleware with Other Loggers
 
 To combine the logger middleware with loggers like Zerolog, Zap, or Logrus, use the `LoggerToWriter` helper to adapt them to an `io.Writer`.
@@ -166,7 +251,7 @@ Writing to `os.File` is goroutine-safe, but custom streams may require locking t
 | Next          | `func(fiber.Ctx) bool`                            | Next defines a function to skip this middleware when it returns true.                                                                           | `nil`                                                                 |
 | Skip          | `func(fiber.Ctx) bool`                            | Skip is a function to determine if logging is skipped or written to Stream.                                                                   | `nil`                                                                 |
 | Done          | `func(fiber.Ctx, []byte)`                         | Done is a function that is called after the log string for a request is written to Stream, and pass the log string as parameter.              | `nil`                                                                 |
-| CustomTags    | `map[string]LogFunc`                              | tagFunctions defines the custom tag action.                                                                                                   | `map[string]LogFunc`                                                  |
+| CustomTags    | `map[string]LogFunc`                              | Defines custom tag actions for this logger instance. These tags override built-in and globally registered tags with the same name.             | `nil`                                                                 |
 | `Format`   | `string`  | Defines the logging tags. See more in [Predefined Formats](#predefined-formats), or create your own using [Tags](#constants). | `[${time}] ${ip} ${status} - ${latency} ${method} ${path} ${error}\n` (same as `DefaultFormat`) |
 | 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"`                                                             |
@@ -203,7 +288,7 @@ Logger provides predefined formats that you can use by name or directly by speci
 | `DefaultFormat` | `"[${time}] ${ip} ${status} - ${latency} ${method} ${path} ${error}\n"` | Fiber's default logger format. |
 | `CommonFormat` | `"${ip} - - [${time}] "${method} ${url} ${protocol}" ${status} ${bytesSent}\n"` | Common Log Format (CLF) used in web server logs. |
 | `CombinedFormat` | `"${ip} - - [${time}] "${method} ${url} ${protocol}" ${status} ${bytesSent} "${referer}" "${ua}"\n"` | CLF format plus the `referer` and `user agent` fields. |
-| `JSONFormat` | `"{time: ${time}, ip: ${ip}, method: ${method}, url: ${url}, status: ${status}, bytesSent: ${bytesSent}}\n"` | JSON format for structured logging. |
+| `JSONFormat` | `"{\"time\":\"${time}\",\"ip\":\"${ip}\",\"method\":\"${method}\",\"url\":\"${url}\",\"status\":${status},\"bytesSent\":${bytesSent}}\n"` | JSON format for structured logging. |
 | `ECSFormat` | `"{\"@timestamp\":\"${time}\",\"ecs\":{\"version\":\"1.6.0\"},\"client\":{\"ip\":\"${ip}\"},\"http\":{\"request\":{\"method\":\"${method}\",\"url\":\"${url}\",\"protocol\":\"${protocol}\"},\"response\":{\"status_code\":${status},\"body\":{\"bytes\":${bytesSent}}}},\"log\":{\"level\":\"INFO\",\"logger\":\"fiber\"},\"message\":\"${method} ${url} responded with ${status}\"}\n"` | Elastic Common Schema (ECS) format for structured logging. |
 
 :::tip