🧹 [Maintenance]: Enhanced Timeout Middleware Configuration #3514
Description
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.HandlerUsage 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:
- I have confirmed that this maintenance task is currently not being addressed.
- I understand that this task will be evaluated by the maintainers and prioritized accordingly.
- I am available to provide further information if needed.
Metadata
Metadata
Assignees
Type
Projects
Status