Propagación de Cancelación en Manejadores HTTP

Cada manejador HTTP debe tratar r.Context() como la raíz de su árbol de trabajo y pasarlo sin cambios a las operaciones de I/O descendentes.

Cuando el cliente se desconecta o el servidor aplica un tiempo de espera, ese contexto se cancela y los llamadores cooperativos deben detenerse.

Resumen

net/http adjunta un context.Context por solicitud a cada *http.Request.

Los manejadores pasan r.Context() a las consultas de bases de datos, llamadas HTTP salientes y stubs gRPC para que las solicitudes abandonadas no sigan consumiendo recursos.

Los envoltorios de frameworks en chi, gin y echo aún exponen el mismo contexto de solicitud subyacente.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

func usersHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    users, err := store.ListUsers(ctx)
    if err != nil {
        if errors.Is(err, context.Canceled) {
            return // cliente desconectado; no escribir 500
        }
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(users)
}

Cuándo usar esto:

• Cualquier manejador que llame a APIs bloqueantes debe pasar r.Context() como primer argumento hacia abajo.
• Retorna silenciosamente en context.Canceled cuando la respuesta no puede llegar al cliente.
• Envuelve con WithTimeout más corto solo en límites internos intencionales, no en la raíz del manejador.

Ejemplo de Trabajo

package main
 
import (
    "context"
    "database/sql"
    "encoding/json"
    "errors"
    "log"
    "net/http"
    "time"
 
    _ "github.com/mattn/go-sqlite3"
)
 
type Store struct{ db *sql.DB }
 
func (s *Store) SlowQuery(ctx context.Context) (string, error) {
    var out string
    err := s.db.QueryRowContext(ctx, `SELECT 'ok'`).Scan(&out)
    return out, err
}
 
func handler(store *Store) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
        defer cancel()
 
        val, err := store.SlowQuery(ctx)
        if err != nil {
            if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
                return
            }
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        _ = json.NewEncoder(w).Encode(map[string]string{"status": val})
    }
}
 
func main() {
    db, _ := sql.Open("sqlite3", ":memory:")
    defer db.Close()
    mux := http.NewServeMux()
    mux.Handle("/api", handler(&Store{db: db}))
    srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}
    log.Fatal(srv.ListenAndServe())
}

Lo que esto demuestra:

• El manejador deriva un hijo limitado de r.Context(), no de context.Background().
• QueryRowContext respeta la cancelación cuando el cliente aborta.
• context.Canceled y context.DeadlineExceeded se cortocircuitan sin un 500 engañoso.
• ReadHeaderTimeout a nivel de servidor complementa los presupuestos por manejador.

Análisis Profundo

Cómo Funciona

• http.Server crea un contexto de solicitud cuando acepta una conexión.
• El contexto se cancela cuando el cliente cierra el socket, el manejador retorna, o los tiempos de espera a nivel de servidor se disparan.
• Las escrituras de ResponseWriter después de la cancelación pueden fallar silenciosamente; protege con verificaciones de contexto antes de trabajos costosos.
• El middleware debe aceptar (w, r) y pasar r.Context() a next.ServeHTTP sin reemplazarlo a menos que agregue valores o plazos.

Notas sobre Frameworks

Lista de Verificación de Propagación

Notas sobre Go

// Middleware que agrega un valor de ID de solicitud - aún preserva la cancelación del padre
func requestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := uuid.NewString()
        ctx := context.WithValue(r.Context(), requestIDKey, id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Trampas

• Reemplazar con Background en manejadores - Pierde las señales de desconexión del cliente. Solución: siempre enraizar en r.Context().
• Escribir 500 en context.Canceled - El cliente se ha ido; las respuestas de error desperdician trabajo. Solución: retornar temprano sin escribir o registrar en nivel de depuración.
• Crear goroutines sin ctx - El trabajo en segundo plano sobrevive al final de la solicitud. Solución: pasar r.Context() o separar explícitamente con context.WithoutCancel solo para limpieza asíncrona intencional.
• Timeout de middleware más corto que el descendente - Las llamadas internas fallan mientras la externa aún se ejecuta. Solución: documentar el orden de los tiempos de espera; los presupuestos internos deben caber dentro del middleware.
• Ignorar ctx en manejadores de streaming - Los bucles de flusher se bloquean después de la desconexión. Solución: seleccionar en ctx.Done() entre fragmentos.
• No cerrar el cuerpo de la solicitud - Las cancelaciones pueden retrasar la reutilización de la conexión. Solución: defer r.Body.Close() en manejadores que leen cuerpos.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Contexto - Primitivas WithCancel y WithTimeout
• Plazos y Tiempos de Espera a Través de Límites de Servicio - presupuestos de múltiples saltos
• Contexto en database/sql y gRPC - cancelación de drivers y RPC
• Pruebas de Código que Acepta context.Context - patrones de httptest
• Mejores Prácticas del Paquete Context - convenciones de manejadores

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC Green Tea, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación) y golangci-lint (última versión - verificar conjunto de linters en la compilación).