timeout

Documentation

Overview

Package timeout provides request timeout middleware for celeris.

The middleware wraps each request's context with a deadline. If the downstream handler does not complete before the deadline, the context is cancelled and a configurable error response is returned.

Basic usage with the default 5-second timeout:

server.Use(timeout.New())

Custom timeout and error handler:

server.Use(timeout.New(timeout.Config{
    Timeout: 10 * time.Second,
    ErrorHandler: func(c *celeris.Context) error {
        return c.JSON(503, map[string]string{"error": "timed out"})
    },
}))

Preemptive Mode

Set Config.Preemptive to true to run the handler in a separate goroutine with response buffering. In preemptive mode, the middleware returns the timeout error immediately when the deadline expires, even if the handler is blocked on a non-context-aware operation. Panics in the preemptive goroutine are recovered automatically.

server.Use(timeout.New(timeout.Config{
    Timeout:    5 * time.Second,
    Preemptive: true,
}))

Handlers MUST check c.Context().Done() to react promptly to cancellation, especially in non-preemptive mode.

ErrServiceUnavailable is the exported sentinel error (503) returned on timeout, usable with errors.Is for error handling in upstream middleware.

Index

• Variables
• func New(config ...Config) celeris.HandlerFunc
• type Config

Examples

• New
• New (Preemptive)

Variables

var DefaultConfig = Config{
	Timeout: 5 * time.Second,
}

DefaultConfig is the default timeout configuration.

var ErrServiceUnavailable = celeris.NewHTTPError(503, "Service Unavailable")

ErrServiceUnavailable is returned when the request timeout is exceeded.

Functions

func New

func New(config ...Config) celeris.HandlerFunc

New creates a timeout middleware with the given config.

Example

package main

import (
	"github.com/goceleris/middlewares/timeout"
)

func main() {
	// Zero-config: 5-second cooperative timeout.
	_ = timeout.New()
}

Example (Preemptive)

package main

import (
	"time"

	"github.com/goceleris/middlewares/timeout"
)

func main() {
	// Preemptive timeout: returns 503 even if handler is blocked.
	// Handlers MUST check c.Context().Done() for prompt cancellation.
	_ = timeout.New(timeout.Config{
		Timeout:    3 * time.Second,
		Preemptive: true,
	})
}

Types

type Config

type Config struct {
	// Skip defines a function to skip this middleware for certain requests.
	Skip func(c *celeris.Context) bool

	// Timeout is the request timeout duration. Default: 5s.
	Timeout time.Duration

	// ErrorHandler handles timeout errors. Default: 503 Service Unavailable.
	ErrorHandler func(c *celeris.Context) error

	// SkipPaths lists paths to skip (exact match).
	SkipPaths []string

	// Preemptive enables preemptive timeout mode. When true, the handler
	// runs in a goroutine and the response is buffered. If the handler
	// does not complete within the timeout, the middleware waits for the
	// goroutine to finish, discards the buffered response, and returns
	// the error handler result. Handlers MUST respect context cancellation
	// (select on c.Context().Done()) to avoid blocking the response.
	Preemptive bool
}

Config defines the timeout middleware configuration.