🧹 [Maintenance]: Enhanced Timeout Middleware Configuration

[Andrei-hub11]

Maintenance Task Description

Summary

Add configurable timeout middleware with per-route timeouts, path exclusions, and custom timeout handlers while maintaining full backward compatibility.

Motivation

Current timeout middleware limitations:

• Global timeout for all routes
• Cannot skip specific paths (health checks, uploads)
• Fixed timeout response
• No per-route timeout configuration

Proposed Solution

Add NewWithConfig function following Fiber's established middleware patterns:

type Config struct {
    // Next defines a function to skip this middleware
    Next      func(c fiber.Ctx) bool
    
    // Timeout defines the default timeout duration
    Timeout   time.Duration
    
    // OnTimeout is called when a timeout occurs
    OnTimeout fiber.Handler
    
    // SkipPaths defines paths that should ignore timeout
    SkipPaths []string
    
    // PerRoute allows specific timeouts per route
    PerRoute  map[string]time.Duration
}

func NewWithConfig(config Config) fiber.Handler

Usage Examples

Basic Configuration

app.Use(timeout.NewWithConfig(timeout.Config{
    Timeout: 30 * time.Second,
}))

Per-Route Timeouts

app.Use(timeout.NewWithConfig(timeout.Config{
    Timeout: 5 * time.Second,
    PerRoute: map[string]time.Duration{
        "/api/reports": 30 * time.Second,
        "/api/uploads": 60 * time.Second,
    },
}))

Skip Specific Paths

app.Use(timeout.NewWithConfig(timeout.Config{
    Timeout: 5 * time.Second,
    SkipPaths: []string{"/health", "/metrics", "/webhook"},
}))

Custom Timeout Response

app.Use(timeout.NewWithConfig(timeout.Config{
    Timeout: 5 * time.Second,
    OnTimeout: func(c fiber.Ctx) error {
        return c.Status(408).JSON(fiber.Map{
            "error": "Request timeout",
            "path":  c.Path(),
        })
    },
}))

Benefits

• Flexible: Per-route timeout configuration
• Production-ready: Skip health checks and monitoring endpoints
• User-friendly: Custom timeout responses with context
• Backward compatible: Existing New() function unchanged

Implementation

• Uses goroutines for asynchronous request processing
• Context-based timeout management with context.WithTimeout
• Zero breaking changes to existing API

Backward Compatibility

✅ All existing timeout.New() calls work unchanged
✅ Can be adopted incrementally
✅ Follows same patterns as other Fiber middlewares (CORS, Logger)

---

Impact on the Project

This enhancement significantly increases the usefulness of the timeout middleware without introducing any breaking changes, bringing the following positive impacts:

• Greater flexibility in request timeout control, better suited to real-world production scenarios.
• Reduces the need for external workarounds or duplicated logic in handlers.
• Helps improve application stability and predictability, especially for public APIs with high-latency endpoints.
• Lays the groundwork for future improvements, such as dynamic timeouts based on headers or context.
• Keeps existing tests intact and adds coverage for new cases without interfering with the current API.

This change aligns with Fiber’s design philosophy and should be easy for the community to adopt.

Additional Context (optional)

Implementation is ready with full tests and documentation. Happy to submit a PR if this approach looks good! 🙏

Checklist:

• [x] I have confirmed that this maintenance task is currently not being addressed.
• [x] I understand that this task will be evaluated by the maintainers and prioritized accordingly.
• [x] I am available to provide further information if needed.

[welcome[bot]]

Thanks for opening your first issue here! 🎉 Be sure to follow the issue template! If you need help or want to chat with us, join us on Discord https://gofiber.io/discord

[gaby]

Because v3 is not release, we can do the breaking change. I will try to get this implemented using an AI Agent. Seems like a great feature to test it with.

[Andrei-hub11]

Hey, I understand that since v3 is not released yet, breaking changes can’t be made, but I’d really love to submit this PR — even if not right now — and collaborate on any improvements needed together with you. I use AI myself too — mostly for docs and TDD — but I’m genuinely excited to personally contribute this one if you agree.

[gaby]

@Andrei-hub11 I have a fully refactored middleware already implemented, including the features you requested. I can push it as a draft, and you can suggest improvements, etc ?

[Andrei-hub11]

@gaby Sure, I’m happy to help improve your version — as long as I can be added as a co-author. Let me know if that works for you.

[gaby]

@Andrei-hub11 See https://github.com/gofiber/fiber/pull/3518