Timeout

​

Overview

​

Installation

import "github.com/go-mizu/mizu/middlewares/timeout"

​

Quick Start

app := mizu.New()

// 30 second timeout
app.Use(timeout.New(30 * time.Second))

​

Configuration

​

Examples

​

Basic Timeout

app.Use(timeout.New(30 * time.Second))

​

Custom Error Handler

app.Use(timeout.WithOptions(timeout.Options{
    Timeout: 10 * time.Second,
    ErrorHandler: func(c *mizu.Ctx) error {
        return c.JSON(504, map[string]string{
            "error": "Request timed out",
        })
    },
}))

​

Different Timeouts Per Route

// Global: 30s
app.Use(timeout.New(30 * time.Second))

// Slow endpoint: 5 minutes
app.Post("/export", exportHandler, timeout.New(5*time.Minute))

// Fast endpoint: 5 seconds
app.Get("/health", healthHandler, timeout.New(5*time.Second))

​

Check Context in Handler

app.Get("/data", func(c *mizu.Ctx) error {
    for i := 0; i < 100; i++ {
        select {
        case <-c.Context().Done():
            return c.Context().Err() // Timeout reached
        default:
            processItem(i)
        }
    }
    return c.JSON(200, results)
})

​

API Reference

func New(timeout time.Duration) mizu.Middleware
func WithOptions(opts Options) mizu.Middleware

​

How It Works

1. Creates a context with deadline
2. Runs handler in goroutine
3. Returns whichever completes first:
   • Handler completion
   • Timeout expiration (returns 503)

​

Technical Details

​

Implementation

1. Context Creation: Creates a context with deadline using context.WithTimeout(c.Context(), opts.Timeout)
2. Request Update: Replaces the request’s context with the timeout context
3. Goroutine Execution: Runs the next handler in a separate goroutine to enable timeout detection
4. Channel Communication: Uses a buffered channel to receive the handler’s result
5. Select Statement: Races between handler completion and context cancellation
   • If handler completes first, returns the result
   • If timeout occurs first, calls error handler or returns 503 Service Unavailable

​

Default Values

• Timeout Duration: 30 seconds (when Timeout <= 0)
• Error Message: “Service Unavailable”
• HTTP Status: 503 Service Unavailable (when no custom error handler is provided)

​

Concurrency Safety

• Using a buffered channel (size 1) to prevent goroutine leaks
• Properly deferring the context cancel function to release resources
• Isolating each request’s timeout context

​

Best Practices

• Set reasonable timeouts based on expected duration
• Use longer timeouts for file uploads/downloads
• Check context in long-running operations
• Return 503 (Service Unavailable) on timeout

​

Testing

​

Test Cases

​

Related Middlewares

• recover - Panic recovery
• circuitbreaker - Failure handling