Annulation et délais en Go avec context.Context

Objectif

Rendre chaque travail à portée de requête d'un service Go interruptible de l'extérieur, avec une durée de vie bornée, en utilisant le paquet context de la bibliothèque standard plutôt que des canaux d'arrêt maison.

Prérequis

Les règles de la documentation du paquet : un Context est le premier paramètre, nommé ctx ; il n'est pas stocké dans une struct ; nil n'est jamais transmis (context.TODO() en cas de doute) ; les valeurs ne transportent que des données à portée de requête franchissant des frontières d'API, pas des paramètres optionnels. Connaître les bibliothèques qui acceptent un contexte (requêtes net/http, database/sql, la plupart des clients).

Étapes

1. Partir de la racine : un gestionnaire HTTP obtient r.Context(), que la documentation de net/http dit être annulé quand la connexion du client se ferme, quand la requête est annulée (HTTP/2) ou quand ServeHTTP retourne ; un main ou un worker en crée un avec signal.NotifyContext afin que SIGTERM l'annule.
2. Dériver un enfant pour chaque opération bornée : ctx, cancel := context.WithTimeout(ctx, 2*time.Second) suivi immédiatement de defer cancel(). La documentation indique que ne pas appeler la fonction d'annulation fait fuir l'enfant jusqu'à ce que le parent soit annulé, et que go vet le détecte.
3. Transmettre ctx à chaque appel susceptible de bloquer : http.NewRequestWithContext, db.QueryContext, et les opérations sur canal enveloppées dans un select avec un case <-ctx.Done().
4. Dans les boucles et les calculs longs, vérifier ctx.Err() aux limites d'itération et le retourner ; la valeur est context.Canceled ou context.DeadlineExceeded.
5. Lors d'une annulation délibérée, utiliser context.WithCancelCause et consigner la raison ; les appelants la lisent avec context.Cause(ctx) (Go 1.20 et ultérieur).
6. Pour un travail qui doit survivre à la requête (une écriture d'audit, un remplissage de cache), dériver depuis context.WithoutCancel(ctx) (Go 1.21) afin que les valeurs survivent mais que l'annulation ne se propage pas, et lui donner son propre délai.
7. Tester le chemin d'annulation : annuler un contexte en plein milieu d'un appel et vérifier que la fonction retourne rapidement avec une erreur qui enveloppe ctx.Err().

Résultat attendu

Une requête annulée ou un délai expiré déroule tout l'arbre d'appels ; aucune goroutine ne continue d'interroger une base de données pour un client qui a disparu. Les délais sont fixés une fois, près de la frontière, et se réduisent naturellement le long de la chaîne, car un délai enfant postérieur à celui de son parent est ignoré.

Limites et base de vérification

L'annulation est coopérative : un code qui ignore ctx continue de s'exécuter jusqu'à ce qu'il retourne de lui-même, et une boucle liée au CPU qui ne vérifie jamais ctx.Err() n'est pas interrompue. Les étapes suivent la documentation du paquet citée et l'introduction du blog Go ; aucune revendication de temps n'est faite.

L'arrêt n'est pas une annulation

Le contexte issu de signal.NotifyContext devrait déclencher l'arrêt, pas être le parent de chaque requête. Le câbler dans http.Server.BaseContext annule toutes les requêtes en cours dès que SIGTERM arrive, ce qui est exactement la rafale d'échecs qu'un arrêt gracieux existe pour éviter. À la place, attendre le contexte de signal, puis appeler srv.Shutdown(shutdownCtx) avec un context.WithTimeout(context.Background(), 20*time.Second) fraîchement créé : le serveur cesse d'accepter, et les requêtes actives conservent leurs propres contextes jusqu'à ce qu'elles retournent ou que le délai s'écoule. N'utiliser le contexte de signal directement que pour un travail qui doit s'arrêter immédiatement : consommateurs de file d'attente, boucles de sondage, planificateurs en arrière-plan. Shutdown n'attend pas les connexions détournées (hijacked) comme les WebSockets ; les fermer depuis un callback RegisterOnShutdown.