Answer 504, not 408, when a request outlasts its time limit (closes #70)

The hand-written time limit middleware answered 408 and wrote that
answer from its own goroutine while the handler could still be writing.
It is replaced by chi's middleware.Timeout, placed after
JSONResponseMiddleware so its 504 is not lost behind a 200.
JSONValidationMiddleware answers 504 with the JSON error body when the
time limit has passed and the handler wrote nothing. status.json and
/api/v1/stats answer 504 themselves when their 4-second database read
runs out, instead of 408 or an empty answer that became 500.

Model: opus-5-5

internal/server/middleware.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
@@ -109,142 +110,17 @@ func JSONResponseMiddleware(next http.Handler) http.Handler {
 	})
 }
 
-// timeoutWriter wraps ResponseWriter to prevent concurrent writes after timeout
-type timeoutWriter struct {
-	http.ResponseWriter
-	mu      sync.Mutex
-	written bool
-	header  http.Header // cached header to prevent concurrent access
-}
-
-func (tw *timeoutWriter) Write(b []byte) (int, error) {
-	tw.mu.Lock()
-	defer tw.mu.Unlock()
-
-	if tw.written {
-		return 0, nil // Discard writes after timeout
-	}
-
-	return tw.ResponseWriter.Write(b)
-}
-
-func (tw *timeoutWriter) WriteHeader(statusCode int) {
-	tw.mu.Lock()
-	defer tw.mu.Unlock()
-
-	if tw.written {
-		return // Discard writes after timeout
-	}
-
-	tw.ResponseWriter.WriteHeader(statusCode)
-}
-
-func (tw *timeoutWriter) Header() http.Header {
-	tw.mu.Lock()
-	defer tw.mu.Unlock()
-
-	if tw.written {
-		// Return a copy to prevent modifications after timeout
-		if tw.header == nil {
-			tw.header = make(http.Header)
-		}
-
-		return tw.header
-	}
-
-	return tw.ResponseWriter.Header()
-}
-
-func (tw *timeoutWriter) markWritten() {
-	tw.mu.Lock()
-	defer tw.mu.Unlock()
-	tw.written = true
-}
-
-// TimeoutMiddleware creates an HTTP middleware that enforces a request timeout.
-// If the handler does not complete within the specified duration, the middleware
-// returns a JSON error response with HTTP status 408 (Request Timeout).
-//
-// The timeout parameter specifies the maximum duration allowed for request processing.
-// The returned middleware handles panics from the wrapped handler by re-panicking
-// after cleanup, and prevents concurrent writes to the response after timeout occurs.
-func TimeoutMiddleware(timeout time.Duration, logger *slog.Logger) func(http.Handler) http.Handler {
-	return func(next http.Handler) http.Handler {
-		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			startTime := time.Now()
-
-			ctx, cancel := context.WithTimeout(r.Context(), timeout)
-			defer cancel()
-
-			tw := &timeoutWriter{
-				ResponseWriter: w,
-				header:         make(http.Header),
-			}
-
-			done := make(chan struct{})
-			panicChan := make(chan interface{}, 1)
-
-			go func() {
-				defer func() {
-					if p := recover(); p != nil {
-						panicChan <- p
-					}
-				}()
-
-				next.ServeHTTP(tw, r.WithContext(ctx))
-				close(done)
-			}()
-
-			select {
-			case p := <-panicChan:
-				panic(p)
-			case <-done:
-				return
-			case <-ctx.Done():
-				tw.markWritten() // Prevent the handler from writing after timeout
-				execTime := time.Since(startTime)
-
-				// Log the timeout as a warning
-				logger.Warn("Request timeout",
-					"method", r.Method,
-					"path", r.URL.Path,
-					"duration_ms", execTime.Milliseconds(),
-					"remote_addr", r.RemoteAddr,
-				)
-
-				// Write directly to the underlying writer since we've marked tw as written
-				// This is safe because markWritten() prevents the handler from writing
-				tw.mu.Lock()
-				w.Header().Set("Content-Type", "application/json")
-				w.WriteHeader(http.StatusRequestTimeout)
-				tw.mu.Unlock()
-
-				response := map[string]interface{}{
-					"status": "error",
-					"error": map[string]interface{}{
-						"msg":  "Request timeout",
-						"code": http.StatusRequestTimeout,
-					},
-					"@meta": map[string]interface{}{
-						"time_zone":      "UTC",
-						"api_version":    1,
-						"execution_time": fmt.Sprintf("%d ms", execTime.Milliseconds()),
-					},
-				}
-
-				_ = json.NewEncoder(w).Encode(response)
-			}
-		})
-	}
-}
+// requestTimeoutMessage is the error message sent with 504 Gateway Timeout.
+const requestTimeoutMessage = "Request timeout"
 
 // JSONValidationMiddleware is an HTTP middleware that validates JSON API responses.
 // It ensures that responses with Content-Type "application/json" contain valid JSON.
 //
 // If a response is not valid JSON or is empty when JSON is expected, the middleware
-// returns a properly formatted JSON error response. For timeout errors (status 408),
-// the error message will be "Request timeout". For other errors, it returns
-// "Internal server error" with status 500 if the original status was 200.
+// returns a properly formatted JSON error response. If the request's time limit
+// has passed, it answers 504 with the error message "Request timeout". For other
+// errors, it returns "Internal server error" with status 500 if the original
+// status was 200.
 //
 // Non-JSON responses are passed through unchanged.
 func JSONValidationMiddleware(next http.Handler) http.Handler {
@@ -293,11 +169,14 @@ func JSONValidationMiddleware(next http.Handler) http.Handler {
 		if statusCode == http.StatusOK {
 			statusCode = http.StatusInternalServerError
 		}
+		if errors.Is(r.Context().Err(), context.DeadlineExceeded) {
+			statusCode = http.StatusGatewayTimeout
+		}
 		w.WriteHeader(statusCode)
 
 		errorMsg := "Internal server error"
-		if statusCode == http.StatusRequestTimeout {
-			errorMsg = "Request timeout"
+		if statusCode == http.StatusGatewayTimeout {
+			errorMsg = requestTimeoutMessage
 		}
 
 		response := map[string]interface{}{