Merge pull request #4009 from gofiber/fix/timeout-immediate-return-and-context-propagation

ReneWerner87 · web-flow · commit bb7d6d8cbc94 · 2026-01-21T08:29:53.000+01:00
diff --git a/ctx.go b/ctx.go
@@ -13,6 +13,7 @@ import (
 	"mime/multipart"
 	"strconv"
 	"strings"
+	"sync/atomic"
 	"time"
 
 	"github.com/gofiber/utils/v2"
@@ -59,8 +60,8 @@ type DefaultCtx struct {
 	fasthttp         *fasthttp.RequestCtx // Reference to *fasthttp.RequestCtx
 	bind             *Bind                // Default bind reference
 	redirect         *Redirect            // Default redirect reference
-	values           [maxParams]string    // Route parameter values
 	viewBindMap      Map                  // Default view map to bind template engine
+	values           [maxParams]string    // Route parameter values
 	baseURI          string               // HTTP base uri
 	pathOriginal     string               // Original HTTP path
 	flashMessages    redirectionMsgs      // Flash messages
@@ -70,6 +71,7 @@ type DefaultCtx struct {
 	indexRoute       int                  // Index of the current route
 	indexHandler     int                  // Index of the current handler
 	methodInt        int                  // HTTP method INT equivalent
+	abandoned        atomic.Bool          // If true, ctx won't be pooled until ForceRelease is called
 	matched          bool                 // Non use route matched
 	skipNonUseRoutes bool                 // Skip non-use routes while iterating middleware
 }
@@ -661,7 +663,7 @@ func (c *DefaultCtx) Reset(fctx *fasthttp.RequestCtx) {
 	c.fasthttp.SetUserValue(userContextKey, nil)
 }
 
-// Release is a method to reset context fields when to use ReleaseCtx()
+// release is a method to reset context fields when to use ReleaseCtx()
 func (c *DefaultCtx) release() {
 	c.route = nil
 	c.fasthttp = nil
@@ -677,11 +679,41 @@ func (c *DefaultCtx) release() {
 		c.redirect = nil
 	}
 	c.skipNonUseRoutes = false
+	// performance: no need for using c.abandoned.Store(false) here, as it is always set to false when it was true in ForceRelease
 	c.handlerCtx = nil
 	c.DefaultReq.release()
 	c.DefaultRes.release()
 }
 
+// Abandon marks this context as abandoned. An abandoned context will not be
+// returned to the pool when ReleaseCtx is called.
+//
+// This is used by the timeout middleware to return immediately while the
+// handler goroutine continues using the context safely.
+//
+// Only call ForceRelease after Abandon if you can guarantee no other goroutine
+// (including Fiber's requestHandler and ErrorHandler) will touch the context.
+// The timeout middleware intentionally does NOT call ForceRelease to avoid
+// races, which means timed-out requests leak their contexts until a safe
+// reclamation strategy exists.
+func (c *DefaultCtx) Abandon() {
+	c.abandoned.Store(true)
+}
+
+// IsAbandoned returns true if Abandon() was called on this context.
+func (c *DefaultCtx) IsAbandoned() bool {
+	return c.abandoned.Load()
+}
+
+// ForceRelease releases an abandoned context back to the pool.
+// This MUST only be called after all goroutines (including requestHandler and
+// ErrorHandler) have completely finished using this context. Calling it while
+// any goroutine is still running causes races.
+func (c *DefaultCtx) ForceRelease() {
+	c.abandoned.Store(false)
+	c.app.ReleaseCtx(c)
+}
+
 func (c *DefaultCtx) renderExtensions(bind any) {
 	if bindMap, ok := bind.(Map); ok {
 		// Bind view map
diff --git a/ctx_interface.go b/ctx_interface.go
@@ -16,6 +16,22 @@ type CustomCtx interface {
 	// Reset is a method to reset context fields by given request when to use server handlers.
 	Reset(fctx *fasthttp.RequestCtx)
 
+	// release is called before returning the context to the pool.
+	release()
+
+	// Abandon marks the context as abandoned. An abandoned context will not be
+	// returned to the pool when ReleaseCtx is called. This is used by the timeout
+	// middleware to return immediately while the handler goroutine continues.
+	// The cleanup goroutine must call ForceRelease when the handler finishes.
+	Abandon()
+
+	// IsAbandoned returns true if the context has been abandoned.
+	IsAbandoned() bool
+
+	// ForceRelease releases an abandoned context back to the pool.
+	// Must only be called after the handler goroutine has completely finished.
+	ForceRelease()
+
 	// Methods to use with next stack.
 	getMethodInt() int
 	getIndexRoute() int
@@ -66,7 +82,14 @@ func (app *App) AcquireCtx(fctx *fasthttp.RequestCtx) CustomCtx {
 }
 
 // ReleaseCtx releases the ctx back into the pool.
+// If the context was abandoned (e.g., by timeout middleware), this is a no-op.
+// Call ForceRelease only when you can guarantee no goroutines (including the
+// requestHandler and ErrorHandler) still touch the context; the timeout
+// middleware intentionally leaves abandoned contexts unreleased to avoid races.
 func (app *App) ReleaseCtx(c CustomCtx) {
+	if c.IsAbandoned() {
+		return
+	}
 	c.release()
 	app.pool.Put(c)
 }
diff --git a/ctx_interface_gen.go b/ctx_interface_gen.go
diff --git a/ctx_test.go b/ctx_test.go
@@ -7956,6 +7956,44 @@ func Test_Ctx_OverrideParam(t *testing.T) {
 	})
 }
 
+func Test_Ctx_AbandonSkipsReleaseCtx(t *testing.T) {
+	t.Parallel()
+
+	app := New()
+	ctx := app.AcquireCtx(&fasthttp.RequestCtx{}).(*DefaultCtx) //nolint:errcheck,forcetypeassert // controlled test setup
+	ctx.route = &Route{}
+
+	t.Cleanup(func() {
+		ctx.ForceRelease()
+	})
+
+	require.False(t, ctx.IsAbandoned())
+
+	ctx.Abandon()
+	require.True(t, ctx.IsAbandoned())
+
+	app.ReleaseCtx(ctx)
+
+	require.True(t, ctx.IsAbandoned(), "ReleaseCtx must not pool abandoned contexts")
+	require.NotNil(t, ctx.fasthttp, "ReleaseCtx should not reset fasthttp on abandoned ctx")
+	require.NotNil(t, ctx.route, "ReleaseCtx should not reset route on abandoned ctx")
+}
+
+func Test_Ctx_ForceReleaseClearsAbandon(t *testing.T) {
+	t.Parallel()
+
+	app := New()
+	ctx := app.AcquireCtx(&fasthttp.RequestCtx{}).(*DefaultCtx) //nolint:errcheck,forcetypeassert // controlled test setup
+	ctx.route = &Route{}
+
+	ctx.Abandon()
+	ctx.ForceRelease()
+
+	require.False(t, ctx.IsAbandoned(), "ForceRelease should clear abandon flag")
+	require.Nil(t, ctx.fasthttp, "ForceRelease should release fasthttp reference")
+	require.Nil(t, ctx.route, "ForceRelease should reset route before pooling")
+}
+
 // go test -v -run=^$ -bench=Benchmark_Ctx_IsProxyTrusted -benchmem -count=4
 func Benchmark_Ctx_IsProxyTrusted(b *testing.B) {
 	// Scenario without trusted proxy check
diff --git a/docs/api/ctx.md b/docs/api/ctx.md
@@ -8,6 +8,26 @@ description: >-
 sidebar_position: 3
 ---
 
+### Abandon
+
+Marks the context as abandoned. An abandoned context will not be returned to the pool when `ReleaseCtx` is called. This is used internally by the [timeout middleware](../middleware/timeout.md) to return immediately while the handler goroutine continues safely.
+
+```go title="Signature"
+func (c fiber.Ctx) Abandon()
+func (c fiber.Ctx) IsAbandoned() bool
+func (c fiber.Ctx) ForceRelease()
+```
+
+| Method         | Description                                                                 |
+|:---------------|:----------------------------------------------------------------------------|
+| `Abandon()`    | Marks the context as abandoned. ReleaseCtx becomes a no-op for this context. |
+| `IsAbandoned()`| Returns `true` if `Abandon()` was called on this context.                   |
+| `ForceRelease()`| Releases an abandoned context back to the pool. Must only be called after the handler has completely finished. |
+
+:::caution
+These methods are primarily for internal use and advanced middleware development. Most applications should not need to call them directly.
+:::
+
 ### App
 
 Returns the [\*App](app.md) reference so you can easily access all application settings.
diff --git a/docs/middleware/timeout.md b/docs/middleware/timeout.md
@@ -4,10 +4,34 @@ id: timeout
 
 # Timeout
 
-The timeout middleware aborts handlers that run too long. It wraps them with
+The timeout middleware enforces a deadline on handler execution. It wraps handlers with
 `context.WithTimeout`, exposes the derived context through `c.Context()`, and
 returns `408 Request Timeout` when the deadline is exceeded.
 
+## How It Works
+
+When a timeout occurs, the middleware **returns immediately** without waiting for the
+handler to finish. This is achieved through Fiber's **Abandon mechanism**:
+
+1. The handler runs in a goroutine with a timeout context
+2. On timeout, the middleware marks the context as "abandoned" and returns `408` immediately
+3. The handler goroutine can continue safely (e.g., for cleanup) without blocking the response
+4. A background cleanup goroutine waits for the handler to finish and performs context cleanup
+
+Handlers can detect the timeout by listening on `c.Context().Done()` and return early.
+This is the recommended pattern for cooperative cancellation.
+
+If a handler panics, the middleware catches it and returns `500 Internal Server Error`.
+
+## Known limitations
+
+- Timed-out requests abandon their `fiber.Ctx` to avoid data races with the core
+  request handler (including the `ErrorHandler`). These contexts are **not**
+  returned to the pool, so each timed-out request leaks a context. Calling
+  `ForceRelease` is only safe if you can guarantee that no goroutine (including
+  Fiber internals) will touch the context anymore; the timeout middleware
+  intentionally does not call it.
+
 :::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
@@ -78,12 +102,12 @@ curl -i http://localhost:3000/sleep/3000   # returns 408 Request Timeout
 
 ## Config
 
-| Property  | Type               | Description                                                          | Default |
-|:----------|:-------------------|:---------------------------------------------------------------------|:-------|
-| Next      | `func(fiber.Ctx) bool` | Function to skip this middleware when it returns `true`.            | `nil`  |
-| Timeout   | `time.Duration`    | Timeout duration for requests. `0` or a negative value disables the timeout. | `0`    |
-| OnTimeout | `fiber.Handler`    | Handler executed when a timeout occurs. Defaults to returning `fiber.ErrRequestTimeout`. | `nil`  |
-| Errors    | `[]error`          | Custom errors treated as timeout errors.                            | `nil`  |
+| Property    | Type               | Description                                                          | Default |
+|:------------|:-------------------|:---------------------------------------------------------------------|:-------|
+| Next        | `func(fiber.Ctx) bool` | Function to skip this middleware when it returns `true`.            | `nil`  |
+| Timeout     | `time.Duration`    | Timeout duration for requests. `0` or a negative value disables the timeout. | `0`    |
+| OnTimeout   | `fiber.Handler`    | Handler executed when a timeout occurs. Defaults to returning `fiber.ErrRequestTimeout`. | `nil`  |
+| Errors      | `[]error`          | Custom errors treated as timeout errors.                            | `nil`  |
 
 ### Use with a custom error
 
@@ -127,11 +151,11 @@ func main() {
 
     handler := func(ctx fiber.Ctx) error {
         tran := db.WithContext(ctx.Context()).Begin()
-        
+
         if tran = tran.Exec("SELECT pg_sleep(50)"); tran.Error != nil {
             return tran.Error
         }
-        
+
         if tran = tran.Commit(); tran.Error != nil {
             return tran.Error
         }
diff --git a/docs/whats_new.md b/docs/whats_new.md
@@ -1595,6 +1595,19 @@ For more details on these changes and migration instructions, check the [Session
 
 The timeout middleware is now configurable. A new `Config` struct allows customizing the timeout duration, defining a handler that runs when a timeout occurs, and specifying errors to treat as timeouts. The `New` function now accepts a `Config` value instead of a duration.
 
+**Behavioral changes:**
+
+- **Immediate return on timeout**: The middleware now returns immediately when a timeout occurs, without waiting for the handler to finish. This is achieved through the new **Abandon mechanism** which marks the context as abandoned so it won't be returned to the pool while the handler is still running.
+- **Context propagation**: The timeout context is properly propagated to the handler. Handlers can detect timeouts by listening on `c.Context().Done()` and return early.
+- **Panic handling**: Panics in the handler are caught and converted to `500 Internal Server Error` responses.
+- **Race-free design**: The implementation uses fasthttp's `TimeoutErrorWithCode` combined with Fiber's Abandon mechanism to ensure complete race-freedom between the middleware, handler goroutine, and context pooling.
+
+**New Ctx methods for the Abandon mechanism:**
+
+- `Abandon()`: Marks the context as abandoned
+- `IsAbandoned()`: Returns true if the context was abandoned
+- `ForceRelease()`: Releases an abandoned context back to the pool (for advanced use)
+
 **Migration:** Replace calls like `timeout.New(handler, 2*time.Second)` with `timeout.New(handler, timeout.Config{Timeout: 2 * time.Second})`.
 
 ## 🔌 Addons
@@ -2863,6 +2876,12 @@ app.Use(timeout.New(handler, 2*time.Second))
 app.Use(timeout.New(handler, timeout.Config{Timeout: 2 * time.Second}))
 ```
 
+**Important behavioral changes:**
+
+- The middleware now returns immediately on timeout without waiting for the handler (using the new Abandon mechanism).
+- Handlers can detect timeouts by listening on `c.Context().Done()` and return early.
+- Panics in the handler are caught and converted to `500 Internal Server Error`.
+
 #### Filesystem
 
 You need to move filesystem middleware to static middleware due to it has been removed from the core.
diff --git a/middleware/timeout/timeout.go b/middleware/timeout/timeout.go
diff --git a/middleware/timeout/timeout_test.go b/middleware/timeout/timeout_test.go
