Skip to content
← Tous les articles
· Delta1 Labs ReliabilityKeyright

Clés d'idempotence pour des opérations de licence résistantes aux relances

Une écriture de licence qui expire vous laisse aveugle : le siège a-t-il été consommé, ou non ? Si vous relancez, vous risquez de débiter deux fois un pool de crédits ou de brûler deux fois un siège ; si vous abandonnez, vous avez peut-être vendu une licence que vous n'avez jamais livrée. C'est le problème de la réponse perdue que rencontre tout client de licence en réseau, et la solution est une clé d'idempotence qui transforme un transport au-moins-une-fois en effets exactement-une-fois. Voici comment l'activation, le comptage, l'émission et la désactivation restent correctes face aux relances contre votre instance Keyright auto-hébergée.

La plupart des clients de licence sont écrits comme si le réseau fonctionnait ou échouait de façon visible. Il ne fait ni l’un ni l’autre. L’échec qui vous coûte réellement de l’argent est celui que vous ne pouvez pas voir : une requête qui a atteint le service d’émission, a fait son travail — consommé un siège, débité un pool de crédits, frappé une licence — puis a perdu sa réponse sur le chemin du retour. Une connexion TLS coupée, un délai de lecture dépassé du proxy inverse, un processus client qui a redémarré en pleine requête : tous laissent l’appelant avec un délai dépassé et aucun moyen de savoir si l’opération a eu lieu.

Si vous relancez, vous pourriez consommer le siège deux fois, ou débiter de nouveau les minutes de la même tâche de rendu, ou émettre une seconde licence pour une seule commande. Si vous abandonnez, vous avez peut-être facturé un client pour une licence que vous n’avez jamais livrée. C’est le problème de la réponse perdue, et il est intrinsèque à toute opération qui change d’état sur un transport peu fiable. La solution n’est pas un meilleur réseau. C’est une clé d’idempotence : un identifiant choisi par le client qui permet au serveur de reconnaître une relance comme la même opération logique et de rejouer le résultat original au lieu de l’exécuter une seconde fois.

L’ambiguïté, illustrée

Prenons un comptage contre votre instance Keyright auto-hébergée. Le client envoie le comptage, le service débite le pool et valide, puis la réponse n’arrive jamais.

Client Service d'émission POST /v1/meter · Idempotency-Key: job-8842 débite 12 · stocke résultat@clé 200 OK (perdu) ✕ délai dépassé — relance POST /v1/meter · Idempotency-Key: job-8842 clé vue · rejoue, pas de 2e débit 200 OK · même MeterResult Livraison au-moins-une-fois, effet exactement-une-fois.

La seconde requête est octet pour octet la première, y compris son Idempotency-Key. Comme le serveur a enregistré le résultat sous cette clé lorsqu’il a validé le débit la première fois, il ne débite pas de nouveau : il renvoie le MeterResult stocké. Le transport a livré la requête deux fois ; le pool a bougé une seule fois. C’est tout le contrat : livraison au-moins-une-fois, effet exactement-une-fois.

L’activation est déjà idempotente — par ses propres entrées

Avant de recourir à des clés partout, sachez ce que vous obtenez gratuitement. L’activation Keyright est idempotente par (clé de licence, empreinte machine). Réactiver la même clé sur la même machine renvoie l’activation existante et son lease ; elle ne consomme pas un second siège. Les entrées sont l’identité de déduplication, de sorte que le SDK peut relancer de lui-même un ActivateAsync qui a expiré sans aucun en-tête supplémentaire.

var client = KeyrightClient.Initialize(new KeyrightOptions
{
    Product         = "acme-app",
    PublicKeyBase64 = config["Keyright:PublicKey"],   // vérification seule, pas un secret
    ServiceUrl      = config["Keyright:ServiceUrl"],   // votre instance auto-hébergée
});

// Sans risque à relancer : la paire (key, fingerprint) est l'identité naturelle d'idempotence.
LicenseInfo info = await Retry.OnTransient(() => client.ActivateAsync(userKey));

if (!info.IsValid)
    return Gate.Deny(info.Reason);   // échoue en fermé sur un refus réel, pas sur un timeout

La discipline importante ici est de distinguer une activation refusée (sièges épuisés, clé révoquée — un LicenseInfo réel que vous devez respecter et ne pas relancer) d’un échec de transport (timeout, 503 — relancez). Nous rendrons cette séparation précise plus bas.

Les opérations qui nécessitent une clé explicite

Toute écriture ne s’identifie pas d’elle-même. Trois opérations courantes ne sont pas idempotentes par leurs entrées, délibérément, parce que deux requêtes d’apparence identique sont généralement censées être deux effets distincts :

  • Comptages — deux appels MeterAsync("render-minutes", 12) débitent normalement 24. Il faut indiquer à la relance d’un seul comptage qu’il s’agit d’une relance.
  • Émission depuis l’automatisation de fulfillment — votre gestionnaire de webhooks frappe une licence lorsqu’une commande est payée. Un webhook relivré ne doit pas en frapper une seconde.
  • Désactivation — libérer un siège que vous avez déjà libéré devrait être un no-op, pas une erreur.

Pour celles-ci, vous attachez un en-tête Idempotency-Key (le SDK l’expose comme paramètre là où c’est pertinent). La clé est un identifiant stable de l’opération métier, choisi une fois et réutilisé à chaque relance de cette opération :

// L'id de la tâche de rendu EST la clé naturelle — un comptage par tâche, à jamais.
MeterResult draw = await Retry.OnTransient(
    () => client.MeterAsync(pool: "render-minutes", amount: job.Minutes, idempotencyKey: job.Id));

if (!draw.Allowed)
    return Gate.Deny("Minutes de rendu épuisées. Rechargez pour continuer.");

Pour l’émission pilotée par votre propre automatisation, l’opération est un POST HTTP vers l’API d’administration et vous posez vous-même l’en-tête. Utilisez l’id de commande pour qu’un événement de paiement relivré soit inoffensif :

POST /admin/licenses HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_token}
Idempotency-Key: order-2026-5591
Content-Type: application/json

{
  "product": "acme-app",
  "edition": "pro",
  "seats": 5,
  "customer": "cust_8e21",
  "entitlements": ["export", "api"]
}

Un second POST portant Idempotency-Key: order-2026-5591 renvoie la même licence que le premier appel a créée — même id, même matériel de clé — sans frapper de seconde licence. Votre gestionnaire de fulfillment devient sûr à appeler autant de fois que le système de commerce relivre l’événement.

Choisir la clé correctement

La clé a exactement deux rôles, et il est facile de se tromper sur les deux :

  1. La même à travers les relances d’une opération. Si vous générez un nouveau Guid.NewGuid() à chaque tentative, chaque relance ressemble à une nouvelle opération et le mécanisme ne fait rien. Dérivez la clé de l’entité métier (job.Id, order.Id), ou générez un GUID une fois, persistez-le à côté de l’opération et réutilisez-le à chaque relance — y compris après un redémarrage du processus.
  2. Différente entre opérations véritablement distinctes. Si un client exécute légitimement deux tâches de rendu, chacune a besoin de sa propre clé, sinon vous fusionnerez deux débits réels en un seul. L’id métier vous le donne naturellement ; une constante partagée non.

Une règle utile : la clé doit être aussi durable que l’intention de l’opération. Si l’intention survit à une panne — vous devez toujours cette licence au client — la clé doit survivre à la panne aussi. Cela signifie qu’elle appartient à votre propre magasin (la ligne de commande, l’enregistrement de la tâche), écrite avant la première tentative.

Ce que le serveur impose, et pourquoi cela devrait vous importer

Une implémentation correcte de l’idempotence fait plus que mettre en cache une réponse. Deux comportements vous importent en tant qu’appelant :

L’empreinte de la requête doit correspondre. Le serveur enregistre un hash du corps de la requête à côté de la clé. Si une seconde requête arrive avec le même Idempotency-Key mais un corps différent — disons, seats: 5 la première fois et seats: 50 la seconde — c’est un bug de votre côté, pas une relance, et le service la rejette avec 409 Conflict plutôt que d’honorer silencieusement l’une ou l’autre. Traitez un 409 ici comme « vous avez réutilisé une clé pour une opération différente » et corrigez le point d’appel ; ne le masquez jamais en faisant tourner la clé.

Les doublons concurrents sont sérialisés. Si deux copies de la même requête sont en vol en même temps (un client a relancé avant que la réponse de la première tentative ne soit perdue, et les deux atterrissent), le service laisse la première se terminer et répond à la seconde depuis le résultat stocké — ou, si la première est encore en cours, renvoie un signal relançable pour que le doublon recule au lieu de s’exécuter en parallèle. Vous n’avez pas à coordonner cela entre vos propres processus ; la clé le fait.

Une politique de relance qui ne relance que ce qui est sûr

Les clés d’idempotence rendent les relances sûres ; elles ne décident pas quand relancer. Associez-les à une politique qui relance les échecs de transport et laisse les refus métier tranquilles. Avec Polly :

var transient = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        MaxRetryAttempts = 4,
        BackoffType      = DelayBackoffType.Exponential,
        UseJitter        = true,                       // étale les relances, évite une ruée
        ShouldHandle     = new PredicateBuilder()
            .Handle<HttpRequestException>()            // connexion coupée
            .Handle<TaskCanceledException>()           // timeout
            .HandleResult<HttpResponseMessage>(r =>
                   r.StatusCode == HttpStatusCode.ServiceUnavailable   // 503
                || r.StatusCode == HttpStatusCode.GatewayTimeout       // 504
                || (int)r.StatusCode == 429),                          // limité : recule
    })
    .Build();

La ligne à tenir est celle-ci : relancez 429, 503, 504 et les échecs de connexion bruts ; ne relancez pas 400, 401, 403, 404, 409 ni un LicenseInfo valide-mais-refusé. Le premier groupe, c’est « l’opération a pu avoir lieu ou non » — exactement là où la clé d’idempotence vous protège. Le second groupe, ce sont des réponses définitives ; les relancer ne fait que marteler le service avec une requête qui continuera d’être refusée. Un 409 d’un endpoint d’idempotence est spécial, comme noté : il signifie clé réutilisée avec un corps différent, ce qui est un défaut de code, pas quelque chose à relancer.

Enfin, gardez la porte en échec fermé sur les refus et opérationnelle en cas d’échec sur les erreurs de transport pour lesquelles vous avez épuisé les relances. Un comptage qui ne peut atteindre le service après quatre tentatives devrait se rabattre sur le lease en cache et sa fenêtre de grâce — pas refuser un client payant à cause d’un accroc — tandis qu’un comptage que le service a activement refusé (pool vide) reste refusé. La clé d’idempotence est ce qui rend inoffensives les relances entre les deux.

Liste de contrôle

  • Activation et revalidation : appuyez-vous sur l’idempotence (key, fingerprint) ; relancez directement les timeouts.
  • Comptage, émission, désactivation : attachez un Idempotency-Key dérivé de l’id métier (job.Id, order.Id).
  • Choisissez la clé une fois, persistez-la avec l’opération, réutilisez-la à chaque relance — y compris après un redémarrage.
  • Ne générez jamais une nouvelle clé par tentative ; ne réutilisez jamais une clé réglée pour une opération différente.
  • Ne relancez que 429/503/504/erreurs de connexion ; honorez les 4xx et le LicenseInfo refusé comme définitifs.
  • Traitez un 409 Conflict d’un endpoint d’idempotence comme un bug de même-clé/corps-différent au point d’appel.
  • Gardez les relances bien à l’intérieur de la fenêtre de rétention des clés du serveur.

Rien de tout cela n’apparaît sur le chemin heureux, ce qui est précisément pourquoi il faut le concevoir plutôt que le découvrir. Le transport livrera certaines de vos écritures de licence plus d’une fois ; avec une clé d’idempotence sur chaque appel qui change d’état, vos sièges, vos pools de crédits et vos licences émises bougent exactement une fois quoi qu’il arrive.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.