Cancelamento e prazos em Go com context.Context

Objetivo

Tornar todo trabalho associado a uma requisição em um serviço Go interrompível a partir de fora e com tempo de vida limitado, usando o pacote context da biblioteca padrão em vez de canais de parada feitos à mão.

Pré-requisitos

As regras da documentação do pacote: o Context é o primeiro parâmetro e se chama ctx; ele não é guardado em uma struct; nunca se passa nil (use context.TODO() em caso de dúvida); os valores carregam apenas dados do escopo da requisição que atravessam fronteiras de API, não parâmetros opcionais. Também é preciso saber quais bibliotecas aceitam um contexto (requisições do net/http, database/sql, a maioria dos clientes).

Passos

1. Comece pela raiz: um handler HTTP recebe r.Context(), que, segundo a documentação do net/http, é cancelado quando a conexão do cliente é fechada, quando a requisição é cancelada (HTTP/2) ou quando ServeHTTP retorna; um main ou worker cria o seu com signal.NotifyContext, de modo que o SIGTERM o cancele.
2. Derive um filho para cada operação limitada: ctx, cancel := context.WithTimeout(ctx, 2*time.Second), seguido imediatamente de defer cancel(). A documentação afirma que, se a função cancel não for chamada, o filho vaza até que o pai seja cancelado, e que o go vet verifica isso.
3. Passe ctx para toda chamada que pode bloquear: http.NewRequestWithContext, db.QueryContext e operações em canais envolvidas em um select com um case <-ctx.Done().
4. Em laços e cálculos longos, verifique ctx.Err() nos limites de cada iteração e retorne esse erro; o valor é context.Canceled ou context.DeadlineExceeded.
5. Ao cancelar de propósito, use context.WithCancelCause e registre o motivo; quem chama lê o motivo com context.Cause(ctx) (Go 1.20 e posterior).
6. Para trabalho que precisa sobreviver à requisição (uma gravação de auditoria, o preenchimento de um cache), derive de context.WithoutCancel(ctx) (Go 1.21): os valores são preservados, mas o cancelamento não se propaga; dê a esse trabalho o seu próprio timeout.
7. Teste o caminho de cancelamento: cancele um contexto no meio de uma chamada e verifique que a função retorna rapidamente com um erro que encapsula ctx.Err().

Resultado esperado

Uma requisição cancelada ou um prazo expirado desfaz toda a árvore de chamadas; nenhuma goroutine continua consultando o banco de dados para um cliente que já foi embora. Os timeouts são definidos uma única vez, perto da fronteira, e encurtam-se naturalmente ao longo da cadeia, porque o prazo de um filho posterior ao do pai é ignorado.

Limites e base de verificação

O cancelamento é cooperativo: o código que ignora ctx continua executando até terminar por conta própria, e um laço limitado por CPU que nunca verifica ctx.Err() não é interrompido. Os passos seguem a documentação do pacote citada e a introdução do blog do Go; não se faz nenhuma afirmação sobre tempos de execução.

Encerramento não é cancelamento

O contexto de signal.NotifyContext deve disparar a parada, não ser o pai de todas as requisições. Ligá-lo a http.Server.BaseContext cancela todas as requisições em andamento no instante em que o SIGTERM chega, justamente a rajada de falhas que um encerramento gracioso existe para evitar. Em vez disso, espere o contexto do sinal e chame srv.Shutdown(shutdownCtx) com um novo context.WithTimeout(context.Background(), 20*time.Second): o servidor deixa de aceitar conexões, e as requisições ativas mantêm seus próprios contextos até retornarem ou até o prazo expirar. Use o contexto do sinal diretamente apenas para trabalho que deve parar imediatamente: consumidores de fila, laços de polling, agendadores em segundo plano. O Shutdown não espera conexões sequestradas (hijacked), como WebSockets; feche-as em um callback de RegisterOnShutdown.