Merge branch 'main' into 2025-08-11-00-12-44

Author: gaby

.github/testdata/fs/css/test/style2.css

@@ -0,0 +1,3 @@
+h1 {
+  color: black;
+}

ctx_test.go

@@ -29,12 +29,13 @@ import (
 	"time"
 
 	"github.com/fxamacker/cbor/v2"
-	"github.com/gofiber/fiber/v3/internal/storage/memory"
 	"github.com/gofiber/utils/v2"
 	"github.com/shamaton/msgpack/v2"
 	"github.com/stretchr/testify/require"
 	"github.com/valyala/bytebufferpool"
 	"github.com/valyala/fasthttp"
+
+	"github.com/gofiber/fiber/v3/internal/storage/memory"
 )
 
 const epsilon = 0.001
@@ -5413,23 +5414,24 @@ func Test_Ctx_SendStreamWriter_Interrupted(t *testing.T) {
 	t.Parallel()
 	app := New()
 	var flushed atomic.Int32
+	var flushErrLine atomic.Int32
 	app.Get("/", func(c Ctx) error {
 		return c.SendStreamWriter(func(w *bufio.Writer) {
 			for lineNum := 1; lineNum <= 5; lineNum++ {
 				fmt.Fprintf(w, "Line %d\n", lineNum)
 
 				if err := w.Flush(); err != nil {
-					if lineNum <= 3 {
-						t.Errorf("unexpected error: %s", err)
-					}
+					flushErrLine.Store(int32(lineNum)) //nolint:gosec // this is a test
 					return
 				}
 
 				if lineNum <= 3 {
 					flushed.Add(1)
 				}
 
-				time.Sleep(500 * time.Millisecond)
+				if lineNum == 3 {
+					time.Sleep(500 * time.Millisecond)
+				}
 			}
 		})
 	})
@@ -5439,7 +5441,7 @@ func Test_Ctx_SendStreamWriter_Interrupted(t *testing.T) {
 		// allow enough time for three lines to flush before
 		// the test connection is closed but stop before the
 		// fourth line is sent
-		Timeout:       1400 * time.Millisecond,
+		Timeout:       200 * time.Millisecond,
 		FailOnTimeout: false,
 	}
 	resp, err := app.Test(req, testConfig)
@@ -5453,6 +5455,10 @@ func Test_Ctx_SendStreamWriter_Interrupted(t *testing.T) {
 
 	// ensure the first three lines were successfully flushed
 	require.Equal(t, int32(3), flushed.Load())
+
+	// verify no flush errors occurred before the fourth line
+	v := flushErrLine.Load()
+	require.True(t, v == 0 || v >= 4, "unexpected flush error on line %d", v)
 }
 
 // go test -run Test_Ctx_Set

docs/middleware/timeout.md

@@ -4,15 +4,16 @@ id: timeout
 
 # Timeout
 
-There exist two distinct implementations of timeout middleware [Fiber](https://github.com/gofiber/fiber).
+The timeout middleware limits how long a handler can take to complete. When the
+deadline is exceeded, Fiber responds with `408 Request Timeout`. The middleware
+uses `context.WithTimeout` and makes the context available through
+`c.Context()` so that your code can listen for cancellation.
 
-## New
-
-As a `fiber.Handler` wrapper, it creates a context with `context.WithTimeout` which is then used with `c.Context()`.
-
-If the context passed executions (eg. DB ops, Http calls) takes longer than the given duration to return, the timeout error is set and forwarded to the centralized `ErrorHandler`.
-
-It does not cancel long running executions. Underlying executions must handle timeout by using `context.Context` parameter.
+:::caution
+`timeout.New` wraps your final handler and can't be added with `app.Use` or
+used in a middleware chain. Register it per route and avoid calling
+`c.Next()` inside the wrapped handler—doing so will panic.
+:::
 
 ## Signatures
 
@@ -22,45 +23,58 @@ func New(handler fiber.Handler, config ...timeout.Config) fiber.Handler
 
 ## Examples
 
-Import the middleware package that is part of the Fiber web framework
+### Basic example
+
+The following program times out any request that takes longer than two seconds.
+The handler simulates work with `sleepWithContext`, which stops when the
+request's context is canceled:
 
 ```go
+package main
+
 import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
     "github.com/gofiber/fiber/v3"
     "github.com/gofiber/fiber/v3/middleware/timeout"
 )
-```
 
-After you initiate your Fiber app, you can use the following possibilities:
+func sleepWithContext(ctx context.Context, d time.Duration) error {
+    select {
+    case <-time.After(d):
+        return nil
+    case <-ctx.Done():
+        return ctx.Err()
+    }
+}
 
-```go
 func main() {
     app := fiber.New()
-    h := func(c fiber.Ctx) error {
-        sleepTime, _ := time.ParseDuration(c.Params("sleepTime") + "ms")
-        if err := sleepWithContext(c.Context(), sleepTime); err != nil {
+
+    handler := func(c fiber.Ctx) error {
+        delay, _ := time.ParseDuration(c.Params("delay") + "ms")
+        if err := sleepWithContext(c.Context(), delay); err != nil {
             return fmt.Errorf("%w: execution error", err)
         }
-        return nil
+        return c.SendString("finished")
     }
 
-    app.Get("/foo/:sleepTime", timeout.New(h, timeout.Config{Timeout: 2 * time.Second}))
+    app.Get("/sleep/:delay", timeout.New(handler, timeout.Config{
+        Timeout: 2 * time.Second,
+    }))
+
     log.Fatal(app.Listen(":3000"))
 }
+```
 
-func sleepWithContext(ctx context.Context, d time.Duration) error {
-    timer := time.NewTimer(d)
+Test it with curl:
 
-    select {
-    case <-ctx.Done():
-        if !timer.Stop() {
-            <-timer.C
-        }
-        return context.DeadlineExceeded
-    case <-timer.C:
-    }
-    return nil
-}
+```bash
+curl -i http://localhost:3000/sleep/1000   # finishes within the timeout
+curl -i http://localhost:3000/sleep/3000   # returns 408 Request Timeout
 ```
 
 ## Config
@@ -72,19 +86,7 @@ func sleepWithContext(ctx context.Context, d time.Duration) error {
 | OnTimeout | `fiber.Handler`    | Handler executed when a timeout occurs. Defaults to returning `fiber.ErrRequestTimeout`. | `nil`  |
 | Errors    | `[]error`          | Custom errors treated as timeout errors.                            | `nil`  |
 
-Test http 200 with curl:
-
-```bash
-curl --location -I --request GET 'http://localhost:3000/foo/1000' 
-```
-
-Test http 408 with curl:
-
-```bash
-curl --location -I --request GET 'http://localhost:3000/foo/3000' 
-```
-
-Use with custom error:
+### Use with custom error
 
 ```go
 var ErrFooTimeOut = errors.New("foo context canceled")
@@ -117,7 +119,7 @@ func sleepWithContextWithCustomError(ctx context.Context, d time.Duration) error
 }
 ```
 
-Sample usage with a DB call:
+### Sample usage with a database call
 
 ```go
 func main() {

docs/whats_new.md

@@ -110,8 +110,6 @@ app.Get("/login/:id<ulid>", func(c fiber.Ctx) error {
 - **ListenTLSWithCertificate**: Use `app.Listen()` with `tls.Config`.
 - **ListenMutualTLS**: Use `app.Listen()` with `tls.Config`.
 - **ListenMutualTLSWithCertificate**: Use `app.Listen()` with `tls.Config`.
-- **Context()**: Removed. `Ctx` now directly implements `context.Context`, so you can pass `c` anywhere a `context.Context` is required.
-- **SetContext()**: Removed. Attach additional context information using `Locals` or middleware if needed.
 
 ### Method Changes
 
@@ -453,7 +451,7 @@ testConfig := fiber.TestConfig{
 
 - Cookie now allows Partitioned cookies for [CHIPS](https://developers.google.com/privacy-sandbox/3pcd/chips) support. CHIPS (Cookies Having Independent Partitioned State) is a feature that improves privacy by allowing cookies to be partitioned by top-level site, mitigating cross-site tracking.
 - Cookie automatic security enforcement: When setting a cookie with `SameSite=None`, Fiber automatically sets `Secure=true` as required by RFC 6265bis and modern browsers (Chrome, Firefox, Safari). This ensures compliance with the "None" SameSite policy. See [Mozilla docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#none) and [Chrome docs](https://developers.google.com/search/blog/2020/01/get-ready-for-new-samesitenone-secure) for details.
-- Context now implements [context.Context](https://pkg.go.dev/context#Context).
+- `Ctx` now implements the [context.Context](https://pkg.go.dev/context#Context) interface, replacing the former `UserContext` helpers.
 
 ### New Methods
 
@@ -490,6 +488,8 @@ testConfig := fiber.TestConfig{
 - **RedirectToRoute**: Use `c.Redirect().Route()` instead.
 - **RedirectBack**: Use `c.Redirect().Back()` instead.
 - **ReqHeaderParser**: Use `c.Bind().Header()` instead.
+- **UserContext**: Removed. `Ctx` itself now satisfies `context.Context`; pass `c` directly where a `context.Context` is required.
+- **SetUserContext**: Removed. Use `context.WithValue` on `c` or `c.Locals` to store additional request-scoped values.
 
 ### Changed Methods
 
@@ -500,9 +500,7 @@ testConfig := fiber.TestConfig{
 - **Attachment and Download**: Non-ASCII filenames now use `filename*` as
   specified by [RFC 6266](https://www.rfc-editor.org/rfc/rfc6266) and
   [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187).
-- **Context**: Renamed to `RequestCtx` to correspond with the FastHTTP Request Context.
-- **UserContext**: Renamed to `Context`, which returns a `context.Context` object.
-- **SetUserContext**: Renamed to `SetContext`.
+- **Context()**: Renamed to `RequestCtx()` to access the underlying `fasthttp.RequestCtx`.
 
 ### SendStreamWriter
 
@@ -940,10 +938,10 @@ func main() {
 ```sh
 $ go run . -v
 
-    _______ __             
+    _______ __
    / ____(_) /_  ___  _____
   / /_  / / __ \/ _ \/ ___/
- / __/ / / /_/ /  __/ /    
+ / __/ / / /_/ /  __/ /
 /_/   /_/_.___/\___/_/          v3.0.0
 --------------------------------------------------
 INFO Server started on:         http://127.0.0.1:3000 (bound on host 0.0.0.0 and port 3000)

middleware/static/static.go

@@ -23,6 +23,9 @@ import (
 // It returns an error if the path attempts to traverse directories.
 func sanitizePath(p []byte, filesystem fs.FS) ([]byte, error) {
 	var s string
+
+	hasTrailingSlash := len(p) > 0 && p[len(p)-1] == '/'
+
 	if bytes.IndexByte(p, '\\') >= 0 {
 		b := make([]byte, len(p))
 		copy(b, p)
@@ -66,6 +69,10 @@ func sanitizePath(p []byte, filesystem fs.FS) ([]byte, error) {
 		s = "/" + s
 	}
 
+	if hasTrailingSlash && len(s) > 1 && s[len(s)-1] != '/' {
+		s += "/"
+	}
+
 	return utils.UnsafeBytes(s), nil
 }
 

middleware/static/static_test.go

@@ -651,6 +651,20 @@ func Test_Static_FS_Browse(t *testing.T) {
 	require.NoError(t, err, "app.Test(req)")
 	require.Contains(t, string(body), "color")
 
+	resp, err = app.Test(httptest.NewRequest(fiber.MethodGet, "/dirfs/test", nil))
+	require.NoError(t, err, "app.Test(req)")
+	require.Equal(t, 200, resp.StatusCode, "Status code")
+	require.Equal(t, fiber.MIMETextHTMLCharsetUTF8, resp.Header.Get(fiber.HeaderContentType))
+
+	resp, err = app.Test(httptest.NewRequest(fiber.MethodGet, "/dirfs/test/style2.css", nil))
+	require.NoError(t, err, "app.Test(req)")
+	require.Equal(t, 200, resp.StatusCode, "Status code")
+	require.Equal(t, fiber.MIMETextCSSCharsetUTF8, resp.Header.Get(fiber.HeaderContentType))
+
+	body, err = io.ReadAll(resp.Body)
+	require.NoError(t, err, "app.Test(req)")
+	require.Contains(t, string(body), "color")
+
 	resp, err = app.Test(httptest.NewRequest(fiber.MethodGet, "/embed", nil))
 	require.NoError(t, err, "app.Test(req)")
 	require.Equal(t, 200, resp.StatusCode, "Status code")