handleTimeout() — fiber Function Reference

Source Code

middleware/timeout/timeout.go lines 95–155

func handleTimeout(
	parent context.Context,
	ctx fiber.Ctx,
	cancel context.CancelFunc,
	done <-chan error,
	panicChan <-chan any,
	cfg Config,
) error {
	// Mark fiber context as abandoned - ReleaseCtx will skip pooling.
	// The context will NOT be returned to the pool. This is an intentional
	// trade-off: we accept the small memory cost of not recycling timed-out
	// contexts in exchange for complete race-freedom.
	//
	// This is the same approach fasthttp uses - timed-out RequestCtx objects
	// are never returned to the pool (see fasthttp's releaseCtx which panics
	// if timeoutResponse is set).
	ctx.Abandon()

	// Prepare the timeout response before marking the RequestCtx as timed out so
	// custom OnTimeout handlers can shape the response body.
	timeoutErr := invokeOnTimeout(ctx, cfg)

	// If no OnTimeout handler is configured or the response is still the default
	// 200/empty, ensure a sensible timeout response is captured for fasthttp to send.
	if cfg.OnTimeout == nil || (ctx.Response().StatusCode() == fiber.StatusOK && len(ctx.Response().Body()) == 0) {
		ctx.Response().SetStatusCode(fiber.StatusRequestTimeout)
		if len(ctx.Response().Body()) == 0 {
			ctx.Response().SetBodyString(fiber.ErrRequestTimeout.Message)
		}
	}

	// Tell fasthttp to not recycle the RequestCtx - it will acquire a new one
	// for the response and send the captured payload (either default or from
	// OnTimeout). All ctx mutations after this call are ignored by fasthttp.
	ctx.RequestCtx().TimeoutErrorWithResponse(&ctx.RequestCtx().Response)

	// Spawn cleanup goroutine that waits for handler to finish.
	// This only does context cleanup (cancel + restore parent), NOT ctx release.
	// The fiber.Ctx is intentionally NOT released to avoid races with requestHandler
	// which may still access ctx (e.g., ErrorHandler) after this function returns.
	// ForceRelease cannot be called safely here for the same reason.
	go func() {
		select {
		case <-done:
		case <-panicChan:
		}
		// Handler finished - cancel timeout context and restore parent
		cancel()
		ctx.SetContext(parent)

		// TODO: Currently the ctx is not returned to the pool (memory leak for timed-out requests).
		// Future improvement: Implement a concurrent "garbage collector" list where abandoned
		// contexts are queued after both the handler AND requestHandler are done. A background
		// goroutine would periodically process this list and call ForceRelease() to recycle
		// the contexts safely. This would require tracking when requestHandler finishes
		// (e.g., via a channel signaled in ReleaseCtx) without adding per-request overhead
		// for non-timeout cases.
	}()

	return timeoutErr
}