Document ContextTimeout middleware with comprehensive examples

[vishr]

Summary

Addresses issue #2745 by providing comprehensive documentation for the ContextTimeout middleware, which was completely undocumented despite being the recommended approach for handling request timeouts in Echo.

Problem Solved

Users were confused because:

• ContextTimeout middleware exists but has zero documentation
• Website only documents the deprecated Timeout middleware (with warnings against it)
• No examples showing how to properly implement handlers that work with ContextTimeout
• No explanation of why ContextTimeout is preferred over Timeout

Changes

📚 Comprehensive Configuration Documentation

Overview & Key Differences:

• Clear explanation of ContextTimeout vs deprecated Timeout middleware
• Safety benefits: no response writer interference, no data races
• Cooperative cancellation model explanation

Configuration Examples (3 scenarios):

• Basic usage: middleware.ContextTimeout(30 * time.Second)
• Custom error handling with JSON responses
• Route-specific timeout skipping for health checks

🛠️ Practical Handler Examples

3 Detailed Real-World Scenarios:

1. Database Operations: Context-aware SQL queries with proper error handling
2. Long-Running Processing: Goroutine-based operations with select statements
3. HTTP Proxy/Client: Outbound requests with context propagation

📖 Best Practices & Patterns

Common Integration Patterns:

• Database: db.QueryContext(ctx, query, args...)
• HTTP Client: http.NewRequestWithContext(ctx, method, url, body)
• Redis: redisClient.Get(ctx, key)
• CPU-intensive loops with ctx.Done() checking

Practical Guidelines:

• Recommended timeout values for different use cases
• How to handle context cancellation gracefully
• When and where to place the middleware

🔧 Enhanced Field Documentation

• Skipper: Examples for excluding health check endpoints
• ErrorHandler: Custom timeout response patterns with JSON
• Timeout: Recommended durations for APIs, uploads, background tasks

🚀 Function Documentation

• ContextTimeout(): Basic usage with handler requirements
• ContextTimeoutWithConfig(): Advanced configuration examples
• ToMiddleware(): Validation and error handling scenarios

Impact

This documentation addresses the exact concerns raised in issue #2745:

1. ✅ "Cannot find any mention of ContextTimeout middleware" → Now has 280+ lines of comprehensive docs
2. ✅ "Documentation only lists the recommended-against Timeout middleware" → Clear explanation of why ContextTimeout is preferred
3. ✅ "Usage example showing what the handler should look like" → 3 detailed handler examples + common patterns

Before/After

Before: Zero documentation, users confused about which timeout middleware to use
After: Enterprise-grade documentation with practical examples and best practices

Testing

• ✅ All existing ContextTimeout tests pass
• ✅ Code compiles without issues
• ✅ Documentation follows Go conventions
• ✅ Examples are syntactically correct and functional

Fixes #2745

---

This PR complements PR #2818 (Logger middleware documentation) as part of ongoing efforts to improve Echo's middleware documentation quality.