README
¶
Timeout Middleware
What it does
Applies a request deadline and returns a controlled timeout response when handlers exceed the configured duration.
How to implement
package main
import (
"time"
"github.com/oarkflow/fh"
"github.com/oarkflow/fh/mw/timeout"
)
func main() {
app := fh.New()
app.Use(timeout.New(5 * time.Second))
app.Get("/", func(c fh.Ctx) error {
return c.Status(fh.StatusOK).SendString("ok")
})
}
Impact
Protects workers from hanging requests and downstream stalls. Long-running handlers may be canceled.
Ordering guidance
Run before handlers and dependency calls. Pair with context-aware downstream clients.
Production considerations
Choose route-specific timeouts. Ensure handlers honor context cancellation and release resources.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrTimeout = errors.New("request timeout") ErrInvalidTimeout = errors.New("invalid timeout duration") )
Functions ¶
func New ¶
func New(timeout time.Duration) fh.HandlerFunc
New returns timeout middleware using the given duration.
func NewWithConfig ¶
func NewWithConfig(cfg Config) fh.HandlerFunc
NewWithConfig returns production-safe timeout middleware.
Types ¶
type Config ¶
type Config struct {
// Timeout is the maximum time allowed for downstream middleware/handler work.
// If <= 0, DefaultTimeout is used unless RejectInvalidTimeout is true.
Timeout time.Duration
// StatusCode is used by the default timeout response.
// Defaults to 503.
StatusCode int
// Message is used by the default timeout response.
Message string
// HeaderName is set on timeout responses.
// Defaults to "X-Timeout".
HeaderName string
// HeaderValue is set on timeout responses.
// Defaults to the timeout duration string.
HeaderValue string
// Skipper skips timeout handling for selected requests.
Skipper Skipper
// OnTimeout customizes timeout response behavior.
OnTimeout TimeoutHandler
// OnError customizes non-timeout error handling.
OnError ErrorHandler
// RejectInvalidTimeout makes NewWithConfig return middleware that rejects
// every request with 500 if Timeout <= 0. Usually keep this false.
RejectInvalidTimeout bool
// PreserveContext controls whether the previous context is restored after
// the request returns. This should normally stay true.
PreserveContext bool
}
Config configures timeout middleware.
This middleware is intentionally cooperative and production-safe. It sets c.Context() to a deadline context and expects long-running handlers, database calls, queues, HTTP clients, and business logic to observe c.Context().Done().
It does not forcibly kill the handler goroutine because fh.Ctx is usually pooled and response writing after timeout can cause races or corrupted output.
type ErrorHandler ¶
ErrorHandler handles non-timeout errors returned by downstream handlers.
Source Files