Enhanced Timeout Middleware

[Andrei-hub11]

Summary

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

Motivation

Current timeout middleware limitations:

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

Proposed Solution

Add TimeoutWithConfig function following Chi's established middleware patterns:

type TimeoutConfig struct {
    // Timeout defines the default timeout duration
    Timeout time.Duration
    
    // OnTimeout is called when a timeout occurs (optional)
    OnTimeout func(w http.ResponseWriter, r *http.Request)
    
    // SkipPaths defines paths that should ignore timeout
    SkipPaths []string
    
    // PerRoute allows specific timeouts per route pattern
    PerRoute map[string]time.Duration
    
    // Skip defines a function to conditionally skip timeout
    Skip func(r *http.Request) bool
}

func TimeoutWithConfig(config TimeoutConfig) func(next http.Handler) http.Handler

Usage Examples

Basic Configuration (same as current)

r.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
    Timeout: 30 * time.Second,
}))

Per-Route Timeouts

r.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
    Timeout: 5 * time.Second,
    PerRoute: map[string]time.Duration{
        "/api/reports/*": 30 * time.Second,
        "/api/upload/*":  60 * time.Second,
    },
}))

Skip Specific Paths

r.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
    Timeout: 5 * time.Second,
    SkipPaths: []string{"/health", "/metrics", "/ping"},
}))

Custom Timeout Response

r.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
    Timeout: 5 * time.Second,
    OnTimeout: func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusRequestTimeout)
        json.NewEncoder(w).Encode(map[string]interface{}{
            "error":   "Request timeout",
            "path":    r.URL.Path,
            "timeout": "5s",
        })
    },
}))

Backward Compatibility

The existing Timeout(timeout time.Duration) function remains unchanged and fully compatible. New functionality is purely additive.

Benefits

• Zero breaking changes
• Flexible per-route configuration
• Custom timeout responses
• Skip health checks and uploads
• Follows Chi's middleware patterns

[Andrei-hub11]

@VojtechVitek I've been working on a prototype for this and would be really happy to contribute the implementation.
If you think this proposal makes sense for the project, would you mind if I go ahead and open a pull request?
I’d be glad to collaborate and adjust anything that’s needed.

[VojtechVitek]

Hi @Andrei-hub11,

Thanks for reaching out!

It's unlikely we'd accept / merge any advanced timeout middleware options into chi core. We want to keep chi minimal.

However, this still sounds like a useful and interesting project. Please feel free to share the Github repository with us on this issue for future reference :)

Best,
Vojtech

[Andrei-hub11]

@VojtechVitek, thank you very much for getting back to me. I'm a bit frustrated, but I think I understand the decision. In any case, yes, I'll probably publish it as a separate repository and share it here once it's done, so you can have a look.

[FarmerChillax]

Hi @Andrei-hub11,

Thanks for reaching out!

It's unlikely we'd accept / merge any advanced timeout middleware options into chi core. We want to keep chi minimal.

However, this still sounds like a useful and interesting project. Please feel free to share the Github repository with us on this issue for future reference :)

Best, Vojtech

Hi @VojtechVitek @pkieltyka , would you consider creating a middleware repository or menue? like gin: https://github.com/gin-gonic/contrib

[VojtechVitek]

@FarmerChillax We're hosting lots of middleware repositories under https://github.com/go-chi organization. In fact, we've pretty much locked chi's middleware package in favor of separate repositories. We'd like to avoid monorepo like "contrib".

If you want to donate a project under chi, please submit an issue. We're open to simple/minimal/well-crafted MIT-license packages with (almost-) zero dependencies.

[FarmerChillax]

@VojtechVitek My confusion is that there is no unified place for me to check all the middleware information under the go-chi organization. Maybe it would be more appropriate to maintain a menu?

[VojtechVitek]

Very good point. We can add README to the https://github.com/go-chi organization page or update chi's main README with more links etc. I'll think about it.

[FarmerChillax]

Great, I'll create a new issue for this and I'd hope to contribute to it

[olekukonko]

@VojtechVitek I have a similar need, and I believe this can be implemented as external middleware. I'm already using something like this internally (see below).

One key focus for me was performance, especially since timing requires a custom writer. To optimize this, I merged the timing and size tracking logic into a single middleware, avoiding multiple passes through the route. That said, the logic can definitely be separated and improved.

I'm also working on adding a target option this would allow the same resource configuration to apply across multiple routes (e.g., /api/*, admin/*, team/*, etc.). The goal is to enable flexible configuration without breaking existing code, while keeping performance and allocations minimal.

If this is something you're interested in, I’d be happy to make it public so we can collaborate. What do you think?

func main() {
	r := chi.NewRouter()

	// 1. Basic configuration with defaults
	basicCfg := chix.Config{
		DefaultTimeout:   30 * time.Second,
		DefaultSizeLimit: 10 << 20, // 10MB
		ContentTypes:     []string{"application/json"},
	}

	// 2. Advanced configuration with per-route settings
	cfg := chix.Config{
		DefaultTimeout:   30 * time.Second,
		DefaultSizeLimit: 10 << 20, // 10MB
		ContentTypes:     []string{"application/json", "multipart/form-data"},
		OnTimeout: func(w http.ResponseWriter, r *http.Request) {
			w.WriteHeader(http.StatusGatewayTimeout)
			w.Write([]byte(`{"error": "request_timeout"}`))
		},
		OnSizeLimitExceeded: func(w http.ResponseWriter, r *http.Request) {
			w.WriteHeader(http.StatusRequestEntityTooLarge)
			w.Write([]byte(`{"error": "request_too_large"}`))
		},
		Resources: map[string]chix.Route{
			"/api/uploads": {
				Timeout:     5 * time.Minute,
				SizeLimit:   50 << 20, // 50MB
				ContentTypes: []string{"multipart/form-data"},
			},
			"/api/reports": {
				Timeout: 2 * time.Minute,
			},
			"/health": {
				Skip: true, // No constraints for health checks
			},
			"/api/*": { // Wildcard match for all /api routes
				Timeout: 15 * time.Second,
			},
		},
		Skip: func(r *http.Request) bool {
			// Skip for certain user agents
			return strings.Contains(r.UserAgent(), "MonitoringBot")
		},
	}

	// Apply middleware
	r.Use(chix.Resource(cfg))

	// Routes
	r.Get("/health", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("OK"))
	})

	r.Post("/api/uploads", func(w http.ResponseWriter, r *http.Request) {
		// Handle file upload (has 5 minute timeout and 50MB limit)
		w.Write([]byte("Upload successful"))
	})

	r.Get("/api/reports", func(w http.ResponseWriter, r *http.Request) {
		// Generate report (has 2 minute timeout)
		w.Write([]byte("Report data"))
	})

	r.Post("/api/data", func(w http.ResponseWriter, r *http.Request) {
		// Falls under /api/* wildcard (15 second timeout)
		w.Write([]byte("Data processed"))
	})

	r.Post("/other", func(w http.ResponseWriter, r *http.Request) {
		// Uses default config (30 second timeout, 10MB limit)
		w.Write([]byte("Other endpoint"))
	})

	http.ListenAndServe(":8080", r)
}

Key Usage Examples:

1. Basic Setup:

   basicCfg := chix.Config{
       DefaultTimeout:   30 * time.Second,
       DefaultSizeLimit: 10 << 20, // 10MB
   }
   r.Use(chix.Resource(basicCfg))

2. Custom Handlers:

   cfg := chix.Config{
       OnTimeout: func(w http.ResponseWriter, r *http.Request) {
           w.WriteHeader(http.StatusGatewayTimeout)
           w.Write([]byte(`{"error": "timeout"}`))
       },
   }

3. Per-Route Settings:

   Resources: map[string]chix.Route{
       "/api/uploads": {
           Timeout:   5 * time.Minute,
           SizeLimit: 50 << 20,
       },
   }

4. Wildcard Routes:

   Resources: map[string]chix.Route{
       "/api/*": {
           Timeout: 15 * time.Second,
       },
   }

5. Skipping Routes:

   Resources: map[string]chix.Route{
       "/health": {
           Skip: true,
       },
   },
   Skip: func(r *http.Request) bool {
       return strings.Contains(r.UserAgent(), "MonitoringBot")
   }