Propagação de Cancelamento em Handlers HTTP

Todo handler HTTP deve tratar r.Context() como a raiz da sua árvore de trabalho e passá-lo inalterado para I/O downstream.

Quando o cliente desconecta ou o servidor impõe um timeout, esse contexto é cancelado e os chamados cooperativos devem parar.

Resumo

net/http anexa um context.Context por requisição a cada *http.Request.

Handlers passam r.Context() para consultas a banco de dados, chamadas HTTP de saída e stubs gRPC para que requisições abandonadas não continuem consumindo recursos.

Wrappers de framework em chi, gin e echo ainda expõem o mesmo contexto de requisição subjacente.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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; não escreva 500
        }
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(users)
}

Quando usar isso:

• Qualquer handler que chame APIs bloqueantes deve passar r.Context() como o primeiro argumento downstream.
• Retorne silenciosamente em context.Canceled quando a resposta não puder alcançar o cliente.
• Envolva com WithTimeout mais curto apenas em limites internos intencionais, não na raiz do handler.

Exemplo de Trabalho

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())
}

O que isso demonstra:

• O handler deriva um filho limitado de r.Context(), não de context.Background().
• QueryRowContext respeita o cancelamento quando o cliente aborta.
• context.Canceled e context.DeadlineExceeded interrompem sem um 500 enganoso.
• ReadHeaderTimeout em nível de servidor complementa os orçamentos por handler.

Análise Profunda

Como Funciona

• http.Server cria um contexto de requisição quando aceita uma conexão.
• O contexto é cancelado quando o cliente fecha o socket, o handler retorna, ou os timeouts em nível de servidor são acionados.
• Escritas em ResponseWriter após o cancelamento podem falhar silenciosamente; proteja com verificações de contexto antes de trabalho caro.
• Middleware deve aceitar (w, r) e passar r.Context() para next.ServeHTTP sem substituí-lo, a menos que esteja adicionando valores ou prazos.

Notas de Framework

Checklist de Propagação

Notas Go

// Middleware que adiciona um valor de ID de requisição - ainda preserva o cancelamento pai
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))
    })
}

Armadilhas

• Substituir por Background em handlers - Perde sinais de desconexão do cliente. Correção: sempre inicie em r.Context().
• Escrever 500 em context.Canceled - O cliente se foi; respostas de erro desperdiçam trabalho. Correção: retorne cedo sem escrever ou registre em nível de debug.
• Criar goroutines sem ctx - Trabalho em background sobrevive ao fim da requisição. Correção: passe r.Context() ou desanexe explicitamente com context.WithoutCancel apenas para limpeza assíncrona intencional.
• Timeout de middleware menor que o downstream - Chamadas internas falham enquanto as externas ainda rodam. Correção: documente a ordem dos timeouts; orçamentos internos devem caber dentro do middleware.
• Ignorar ctx em handlers de streaming - Loops de Flusher bloqueiam após a desconexão. Correção: use select em ctx.Done() entre os blocos.
• Não fechar o corpo da requisição - Cancelamentos podem atrasar a reutilização da conexão. Correção: defer r.Body.Close() em handlers que leem corpos.

Alternativas

FAQs

Relacionados

• Noções Básicas de Contexto - Primitivas WithCancel e WithTimeout
• Prazos e Timeouts Entre Limites de Serviço - orçamentos de múltiplos saltos
• Contexto em database/sql & gRPC - cancelamento de driver e RPC
• Testando Código Que Aceita context.Context - padrões httptest
• Melhores Práticas do Pacote Context - convenções de handler

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).