🐛 bug: timeout middleware leaks fiber.Ctx on timeout (unbounded memory leak)

[pageton]

Problem

The timeout middleware (middleware/timeout/timeout.go:44-82, 136-152) permanently leaks fiber.Ctx objects when a request times out. When the timeout fires:

1. The handler goroutine continues using the fiber.Ctx.
2. The middleware calls c.Abandon() which prevents ReleaseCtx from returning the context to the pool.
3. The cleanup goroutine (line ~136) blocks indefinitely waiting for the handler to finish.

The code comment at line ~145 explicitly acknowledges: "timed-out requests leak their contexts until a safe reclamation strategy exists."

Impact

• Each timed-out request permanently leaks one DefaultCtx + all embedded fasthttp allocations (byte buffers, etc.).
• Under sustained upstream degradation (the exact scenario that triggers timeouts), this becomes an unbounded memory leak.
• At 1K timed-out requests/sec, ~1K DefaultCtx objects accumulate every second, leading to OOM kills.

Note: The related redesign issue #3394 was closed but this specific memory leak was not addressed.

Proposed fix

1. Implement a finalizer goroutine pool or sync.WaitGroup-based cleanup that eventually calls ForceRelease after the handler goroutine completes.
2. Add a secondary timeout for the cleanup goroutine itself (e.g., 2x the original timeout).
3. Consider a bounded pool of "reclaimer" goroutines rather than spawning one per timeout.

Reproduction

app.Use(timeout.New(func(c fiber.Ctx) error {
    time.Sleep(10 * time.Second) // simulate slow upstream
    return nil
}, 100*time.Millisecond))

// Fire 10K requests → 10K leaked DefaultCtx objects

Priority

P0 — Unbounded memory leak under the exact failure mode the middleware is designed to handle.

---

Identified during a full performance architecture review of the Fiber codebase.

[ReneWerner87]

Folding #4347 into this issue, since both describe the same timeout-middleware leak.

In addition to the fiber.Ctx not being returned to the pool (the TODO at middleware/timeout/timeout.go:145), #4347 raised a second, related vector: the cleanup goroutine at middleware/timeout/timeout.go:136-152 waits on done/panicChan and only exits once the handler returns. If a handler blocks forever (deadlocked DB, unreachable service), both the handler goroutine and the cleanup goroutine leak permanently, and repeated timeouts grow the goroutine/memory count monotonically.

Reproduction (from #4347): timeout middleware with a short timeout plus a handler that does select{}, then send requests until timeouts fire; the goroutine count climbs and never drops.

Note this part is partly inherent to the goroutine-per-request timeout pattern (Go cannot force-kill a goroutine that never returns), but the eventual reclaim / "garbage collector" design mentioned in the TODO here should account for both the abandoned ctx and the parked cleanup goroutine.

[ReneWerner87]

Update: Status with PR #4400

PR #4400 lands the reclamation machinery for the dominant case. Closing context for what is now solved and what still needs work.

Solved by #4400:

• Timed-out request where the handler eventually returns: the fiber.Ctx is now returned to the pool via ScheduleReclaim (race-free latch: handler-done + request-released, both required, no time.After shortcut).
• Panic-after-timeout: same reclaim path, covered by TestTimeout_PanicAfterTimeoutReclaimed.
• Repro from the issue body (10s handler, 100ms timeout, 10K requests): no longer leaks, contexts reclaimed once handlers complete.

Still open (intentionally out of scope for #4400):

• Hung-handler reclamation. If the handler never returns (select{}, deadlocked driver, unreachable upstream), the reclaim goroutine waits on <-handlerDone forever and the ctx + goroutine stay leaked. This is the 🐛 [Bug]: Timeout middleware goroutine leak — cleanup goroutine waits indefinitely #4347 vector folded into this issue. The PR documents this as a known limitation. Force-reclaiming after 2x timeout would race with the handler that still owns the ctx, so a real fix needs either a side-channel "is it safe yet" probe or accepting the race with a guard (e.g. snapshot fields the handler is still allowed to touch). Non-trivial design work.
• Bounded reclaimer pool. Still one goroutine per timed-out request. In normal operation this is bounded by handler latency (goroutine exits when handler exits), so steady-state is fine. Becomes relevant only in combination with the hung-handler case above. Lower priority.

Leaving this issue open to track the two remaining items above. PR #4400 closes the P0 unbounded leak; the residual concerns are P1/P2 design questions.

[gaby]

@ReneWerner87 is this done?

[ReneWerner87]

i will check, sec

[ReneWerner87]

Fixed. The leak is gone.

On timeout the middleware now calls ScheduleReclaim on the abandoned DefaultCtx instead of dropping it. The context goes back to the pool once two things are true: the handler goroutine has actually returned, and Fiber's request handler has released the context. Both conditions are required, so there is no race with a goroutine still touching the ctx.

If a handler never returns, its ctx is intentionally not reclaimed, since the handler still owns it. A forced reclaim with a second timeout would just bring back the race we are trying to avoid, so we did not add one.

Only *fiber.DefaultCtx is reclaimed automatically. Custom Ctx implementations keep the old behavior (abandoned, stays out of the pool), because they lack the release signal wiring.

Good to close.