Cancelación y plazos en Go con context.Context

Objetivo

Hacer que cada unidad de trabajo asociada a una solicitud en un servicio Go pueda detenerse desde fuera, con un ciclo de vida acotado, usando el paquete context de la biblioteca estándar en lugar de canales de parada hechos a medida.

Requisitos previos

Las reglas de la documentación del paquete: un Context es el primer parámetro, y se llama ctx; no se almacena en un struct; nunca se pasa nil (context.TODO() cuando hay dudas); los valores transportan únicamente datos de ámbito de solicitud que cruzan límites de API, no parámetros opcionales. Conocer qué bibliotecas aceptan un context (las solicitudes de net/http, database/sql, la mayoría de los clientes).

Pasos

1. Empezar por la raíz: un handler HTTP obtiene r.Context(), que según la documentación de net/http se cancela cuando se cierra la conexión del cliente, cuando la solicitud se cancela (HTTP/2) o cuando ServeHTTP retorna; un main o un worker crea uno con signal.NotifyContext para que SIGTERM lo cancele.
2. Derivar un hijo para cada operación acotada: ctx, cancel := context.WithTimeout(ctx, 2*time.Second) seguido inmediatamente de defer cancel(). La documentación indica que no llamar a la función cancel deja escapar el hijo hasta que se cancele el padre, y que go vet comprueba esto.
3. Pasar ctx a cada llamada que pueda bloquear: http.NewRequestWithContext, db.QueryContext, y las operaciones sobre canales envueltas en un select con un case <-ctx.Done().
4. En bucles y cálculos largos, comprobar ctx.Err() en los límites de cada iteración y devolverlo; el valor es context.Canceled o context.DeadlineExceeded.
5. Al cancelar de forma deliberada, usar context.WithCancelCause y registrar el motivo; quien llama lo lee con context.Cause(ctx) (Go 1.20 en adelante).
6. Para trabajo que debe sobrevivir a la solicitud (una escritura de auditoría, el llenado de una caché), derivar de context.WithoutCancel(ctx) (Go 1.21) para que los valores se conserven pero la cancelación no se propague, y asignarle su propio timeout.
7. Probar la ruta de cancelación: cancelar un context a mitad de una llamada y comprobar que la función retorna con prontitud con un error que envuelve ctx.Err().

Resultado esperado

Una solicitud cancelada o un plazo agotado deshace todo el árbol de llamadas; ninguna goroutine sigue consultando una base de datos para un cliente que ya se ha ido. Los timeouts se fijan una sola vez, cerca del límite, y se reducen de forma natural a lo largo de la cadena, porque un plazo del hijo posterior al de su padre se ignora.

Límites y base de verificación

La cancelación es cooperativa: el código que ignora ctx sigue ejecutándose hasta que retorna por sí mismo, y un bucle limitado por CPU que nunca comprueba ctx.Err() no se interrumpe. Los pasos siguen la documentación del paquete citada y la introducción del blog de Go; no se afirma ninguna medición de tiempos.

El apagado no es cancelación

El context procedente de signal.NotifyContext debería disparar la parada, no ser el padre de cada solicitud. Conectarlo a http.Server.BaseContext cancela todas las solicitudes en curso en el instante en que llega SIGTERM, que es precisamente la ráfaga de fallos que una parada ordenada existe para evitar. En su lugar, conviene esperar al context de la señal y luego llamar a srv.Shutdown(shutdownCtx) con un context.WithTimeout(context.Background(), 20*time.Second) nuevo: el servidor deja de aceptar solicitudes, y las solicitudes activas conservan sus propios contexts hasta que retornan o vence el plazo. Usar el context de la señal directamente solo para trabajo que deba detenerse de inmediato: consumidores de colas, bucles de sondeo, planificadores en segundo plano. Shutdown no espera a las conexiones tomadas (hijacked), como los WebSockets; estas deben cerrarse desde un callback RegisterOnShutdown.