🔥 feat: Add response time middleware (#3891)

* Fix responsetime lint warnings

* Enforce response time header usage

Author: gaby

.github/README.md

@@ -754,6 +754,7 @@ Here is a list of middleware that are included within the Fiber framework.
 | [recover](https://github.com/gofiber/fiber/tree/main/middleware/recover)             | Recovers from panics anywhere in the stack chain and handles the control to the centralized ErrorHandler.                                                               |
 | [redirect](https://github.com/gofiber/fiber/tree/main/middleware/redirect)           | Redirect middleware.                                                                                                                                                    |
 | [requestid](https://github.com/gofiber/fiber/tree/main/middleware/requestid)         | Adds a request ID to every request.                                                                                                                                     |
+| [responsetime](https://github.com/gofiber/fiber/tree/main/middleware/responsetime)   | Measures request handling duration and writes it to a configurable response header.                          |
 | [rewrite](https://github.com/gofiber/fiber/tree/main/middleware/rewrite)             | Rewrites the URL path based on provided rules. It can be helpful for backward compatibility or just creating cleaner and more descriptive links.                        |
 | [session](https://github.com/gofiber/fiber/tree/main/middleware/session)             | Session middleware. NOTE: This middleware uses our Storage package.                                                                                                     |
 | [skip](https://github.com/gofiber/fiber/tree/main/middleware/skip)                   | Skip middleware that skips a wrapped handler if a predicate is true.                                                                                                    |

constants.go

@@ -280,6 +280,7 @@ const (
 	HeaderXPingback                          = "X-Pingback"
 	HeaderXRequestID                         = "X-Request-ID"
 	HeaderXRequestedWith                     = "X-Requested-With"
+	HeaderXResponseTime                      = "X-Response-Time"
 	HeaderXRobotsTag                         = "X-Robots-Tag"
 	HeaderXUACompatible                      = "X-UA-Compatible"
 	HeaderAccessControlAllowPrivateNetwork   = "Access-Control-Allow-Private-Network"

docs/middleware/responsetime.md

@@ -0,0 +1,55 @@
+---
+id: responsetime
+---
+
+# ResponseTime
+
+Response time middleware for [Fiber](https://github.com/gofiber/fiber) that measures the time spent handling a request and exposes it via a response header.
+
+## Signatures
+
+```go
+func New(config ...Config) fiber.Handler
+```
+
+## Examples
+
+Import the package:
+
+```go
+import (
+    "github.com/gofiber/fiber/v3"
+    "github.com/gofiber/fiber/v3/middleware/responsetime"
+)
+```
+
+### Default config
+
+```go
+app.Use(responsetime.New())
+```
+
+### Custom header
+
+```go
+app.Use(responsetime.New(responsetime.Config{
+    Header: "X-Elapsed",
+}))
+```
+
+### Skip logic
+
+```go
+app.Use(responsetime.New(responsetime.Config{
+    Next: func(c fiber.Ctx) bool {
+        return c.Path() == "/healthz"
+    },
+}))
+```
+
+## Config
+
+| Property | Type | Description | Default |
+| :------- | :--- | :---------- | :------ |
+| Next | `func(c fiber.Ctx) bool` | Defines a function to skip this middleware when it returns `true`. | `nil` |
+| Header | `string` | Header key used to store the measured response time. If left empty, the default header is used. | `"X-Response-Time"` |

docs/whats_new.md

@@ -1244,6 +1244,12 @@ Cache keys are now redacted in logs and error messages by default, and a `Disabl
 The deprecated `Store` and `Key` options have been removed in v3. Use `Storage` and `KeyGenerator` instead.
 :::
 
+### ResponseTime
+
+A new response time middleware measures how long each request takes to process and adds the duration to the response headers.
+By default it writes the elapsed time to `X-Response-Time`, and you can change the header name. A `Next` hook lets you skip
+endpoints such as health checks.
+
 ### CORS
 
 We've made some changes to the CORS middleware to improve its functionality and flexibility. Here's what's new:

middleware/responsetime/config.go

@@ -0,0 +1,42 @@
+package responsetime
+
+import (
+	"github.com/gofiber/fiber/v3"
+)
+
+// 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 used to set the response time.
+	//
+	// Optional. Default: "X-Response-Time"
+	Header string
+}
+
+// ConfigDefault is the default config.
+var ConfigDefault = Config{
+	Next:   nil,
+	Header: fiber.HeaderXResponseTime,
+}
+
+// Helper function to set default values.
+func configDefault(config ...Config) Config {
+	// Return default config if nothing provided
+	if len(config) < 1 {
+		return ConfigDefault
+	}
+
+	// Override default config
+	cfg := config[0]
+
+	// Set default values
+	if cfg.Header == "" {
+		cfg.Header = ConfigDefault.Header
+	}
+
+	return cfg
+}

middleware/responsetime/responsetime.go

@@ -0,0 +1,29 @@
+package responsetime
+
+import (
+	"time"
+
+	"github.com/gofiber/fiber/v3"
+)
+
+// New creates a new middleware handler.
+func New(config ...Config) fiber.Handler {
+	// Set default config
+	cfg := configDefault(config...)
+
+	// Return new handler
+	return func(c fiber.Ctx) error {
+		// Don't execute middleware if Next returns true
+		if cfg.Next != nil && cfg.Next(c) {
+			return c.Next()
+		}
+
+		start := time.Now()
+
+		err := c.Next()
+
+		c.Set(cfg.Header, time.Since(start).String())
+
+		return err
+	}
+}

middleware/responsetime/responsetime_test.go

@@ -0,0 +1,99 @@
+package responsetime
+
+import (
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v3"
+	"github.com/stretchr/testify/require"
+)
+
+func TestResponseTimeMiddleware(t *testing.T) {
+	t.Parallel()
+
+	boom := errors.New("boom")
+
+	tests := []struct {
+		name                  string
+		expectedStatus        int
+		useCustomErrorHandler bool
+		returnError           bool
+		expectHeader          bool
+		skipWithNext          bool
+	}{
+		{
+			name:           "sets duration header",
+			expectedStatus: fiber.StatusOK,
+			expectHeader:   true,
+		},
+		{
+			name:           "skips when Next returns true",
+			expectedStatus: fiber.StatusOK,
+			expectHeader:   false,
+			skipWithNext:   true,
+		},
+		{
+			name:                  "propagates errors",
+			expectedStatus:        fiber.StatusTeapot,
+			useCustomErrorHandler: true,
+			returnError:           true,
+			expectHeader:          true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			configs := []Config(nil)
+			if tt.skipWithNext {
+				configs = []Config{{
+					Next: func(fiber.Ctx) bool {
+						return true
+					},
+				}}
+			}
+
+			appConfig := fiber.Config{}
+			if tt.useCustomErrorHandler {
+				appConfig.ErrorHandler = func(c fiber.Ctx, err error) error {
+					t.Helper()
+					require.ErrorIs(t, err, boom)
+
+					return c.Status(fiber.StatusTeapot).SendString(err.Error())
+				}
+			}
+
+			app := fiber.New(appConfig)
+			app.Use(New(configs...))
+
+			app.Get("/", func(c fiber.Ctx) error {
+				if tt.returnError {
+					return boom
+				}
+
+				return c.SendStatus(fiber.StatusOK)
+			})
+
+			resp, err := app.Test(httptest.NewRequest(fiber.MethodGet, "/", http.NoBody))
+
+			require.NoError(t, err)
+			require.Equal(t, tt.expectedStatus, resp.StatusCode)
+
+			header := resp.Header.Get(fiber.HeaderXResponseTime)
+			if tt.expectHeader {
+				require.NotEmpty(t, header)
+
+				_, parseErr := time.ParseDuration(header)
+				require.NoError(t, parseErr)
+
+				return
+			}
+
+			require.Empty(t, header)
+		})
+	}
+}