Rafraîchissement conditionnel de licence avec ETag
Un client Keyright rafraîchit son lease en cache sur une minuterie, et l'immense majorité de ces rafraîchissements répondent à la même question par la même réponse : rien n'a changé. Retélécharger le lease signé complet à chaque fois gaspille de la bande passante et refait une vérification de signature sans raison. HTTP possède déjà le bon outil pour « cette ressource a-t-elle changé depuis la dernière fois que je l'ai vue ? » : l'ETag et le GET conditionnel. Cet article montre comment le service émetteur marque chaque réponse de licence d'un validateur fort, comment le SDK envoie If-None-Match pour transformer un rafraîchissement en un économique 304 Not Modified, et les règles de correction qui empêchent un 304 de masquer une révocation.
Un client Keyright n’appelle pas le serveur à chaque vérification de licence. Il s’active une fois, met en cache le lease signé, et à partir de là chaque Validate() est une opération locale et hors ligne contre la clé publique embarquée. Ce qui parle au service émetteur, c’est le rafraîchissement en arrière-plan : sur une minuterie — généralement toutes les quelques minutes à quelques heures — le SDK récupère à nouveau le lease afin qu’un renouvellement, un changement d’entitlement ou une révocation soient pris en compte sans attendre un redémarrage.
Voici l’essentiel de cette boucle de rafraîchissement : presque toutes ses itérations ne font rien. Une licence est une ressource qui évolue lentement. Elle change quand quelqu’un renouvelle, met à niveau, transfère un siège ou se fait révoquer — des événements espacés de jours ou de semaines. Entre ces événements, un client qui rafraîchit toutes les cinq minutes demande au service « quel est l’état actuel de cette licence ? » des centaines de fois et reçoit en retour, octet pour octet, le même lease signé à chaque fois. Chacune de ces réponses est un corps complet que le service a sérialisé et signé, poussé sur le réseau, que le client a ensuite décodé en base64 et sur lequel il a exécuté une vérification RSA — le tout pour confirmer ce qu’il savait déjà.
HTTP possède la bonne primitive pour cela depuis 1999. C’est le GET conditionnel, construit sur l’en-tête de réponse ETag et l’en-tête de requête If-None-Match, et le câbler dans le chemin de rafraîchissement transforme le cas courant — rien n’a changé — en un aller-retour uniquement d’en-têtes qui renvoie 304 Not Modified avec un corps vide.
À retenir : Faites en sorte que votre service émetteur tamponne chaque réponse de licence d’un ETag fort dérivé de la version et de la signature de la licence. Faites en sorte que le SDK mémorise cette étiquette et la renvoie comme If-None-Match au rafraîchissement suivant. Quand rien n’a changé, le service répond 304 Not Modified sans corps, le client conserve son lease en cache intact, et vous avez remplacé un téléchargement complet de charge utile signée plus une vérification de signature par quelques centaines d’octets d’en-têtes — sans jamais laisser un cache périmé masquer une révocation.
À quoi ressemble aujourd’hui la récupération d’une licence
Retirez le SDK et un rafraîchissement est un GET HTTP ordinaire. Le client demande le lease actuel pour une clé ; le service renvoie le document signé.
GET /v1/licenses/current HTTP/1.1
Host: keyright.example.com
X-Keyright-Product: acme-suite
Authorization: Bearer AK-9f3c… ← le jeton d'activation du handshake initial
HTTP/1.1 200 OK
Content-Type: application/vnd.keyright.lease+json
Content-Length: 1184
{ "lease": "eyJhbGciOi…", "signature": "MEUCIQ…", "edition": "pro", "expiresAt": "2027-01-01T00:00:00Z" }
Ce blob lease est la charge utile canonique et signée que le client vérifie hors ligne. À plus d’un kilo-octet par coup, multiplié par une flotte de clients, par un rafraîchissement toutes les quelques minutes, par le fait que le contenu est identique entre les événements de licence, c’est du pur gaspillage. Le service a fait un vrai travail pour produire un corps dont personne n’avait besoin.
L’ETag : une empreinte que le client peut citer en retour
Un ETag (« entity tag ») est un validateur opaque que le serveur attache à une réponse. Son seul contrat est celui-ci : si deux réponses pour la même URL portent le même ETag, leurs représentations sont identiques ; si la ressource change, l’ETag doit changer. Le client le traite comme une boîte noire — il ne le parse jamais — et le cite simplement en retour à la requête suivante pour demander « as-tu toujours exactement ceci ? ».
Pour une licence, vous ne voulez pas hacher le corps complet de la réponse pour produire l’étiquette (cela fonctionne, mais cela coûte un hachage sur la charge utile à chaque requête). Vous avez déjà deux champs qui changent si et seulement si la licence change : une version monotone que le service émetteur incrémente à chaque mutation, et la signature elle-même. Combinez-les en un validateur fort :
ETag: "v47-3b9a1f" ← version 47 de la licence, premiers octets de la signature, étiquette forte
C’est un ETag fort (sans préfixe W/), ce qui est le bon choix ici : une requête conditionnelle ne devrait correspondre que lorsque les octets sont véritablement identiques, car le client va sauter la vérification d’une nouvelle signature en cas de correspondance. Une étiquette faible (W/"…"), qui ne promet qu’une équivalence sémantique, est inappropriée ici : « sémantiquement équivalent » n’est pas suffisant quand la différence pourrait être une révocation.
Le service calcule l’étiquette à partir de champs qu’il a déjà en main, donc étiqueter une réponse est essentiellement gratuit, et surtout l’étiquette change à l’instant où quoi que ce soit de la licence change : un renouvellement incrémente la version, une révocation incrémente la version, une modification d’entitlement incrémente la version.
Le GET conditionnel : If-None-Match transforme un rafraîchissement en 304
Une fois que le client a vu un ETag, le rafraîchissement suivant l’envoie dans un en-tête If-None-Match. La sémantique est précise : « renvoie la ressource complète seulement si son ETag actuel ne correspond à aucun de ceux-ci ; sinon, dis-moi qu’elle est inchangée ».
GET /v1/licenses/current HTTP/1.1
Host: keyright.example.com
X-Keyright-Product: acme-suite
Authorization: Bearer AK-9f3c…
If-None-Match: "v47-3b9a1f" ← j'ai déjà exactement ceci ; et toi ?
HTTP/1.1 304 Not Modified
ETag: "v47-3b9a1f"
Cache-Control: max-age=300
Pas de corps. Le client lit le 304, comprend « mon lease en cache est toujours à jour », réinitialise sa minuterie de rafraîchissement et ne fait rien d’autre — pas de décodage, pas de vérification de signature, pas de changement d’état. Quand la licence a changé, la correspondance échoue et le service répond exactement comme avant, avec un 200, le nouveau corps et un nouvel ETag que le client stocke pour la prochaine fois.
Implémenter le rafraîchissement conditionnel dans le client du SDK
Si vous consommez le client Keyright via l’enregistrement de typed-client, les requêtes conditionnelles sont quelque chose que vous ajoutez dans le chemin de rafraîchissement : le SDK stocke le dernier ETag à côté du lease en cache et l’envoie au sondage suivant. Voici la forme de ce handler, écrit contre HttpClient pour que la mécanique soit explicite.
public sealed class ConditionalLeaseFetcher(HttpClient http)
{
// Le validateur que le service nous a donné en dernier, conservé à côté du lease en cache.
private string? _etag;
private SignedLease? _cached;
public async Task<RefreshResult> RefreshAsync(CancellationToken ct)
{
using var req = new HttpRequestMessage(HttpMethod.Get, "/v1/licenses/current");
// Cite l'étiquette stockée en retour. EntityTagHeaderValue parse la forme entre guillemets.
if (_etag is not null)
req.Headers.IfNoneMatch.Add(EntityTagHeaderValue.Parse(_etag));
using var res = await http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, ct);
if (res.StatusCode == HttpStatusCode.NotModified)
{
// Le cas courant : le corps est vide par spécification. Conserve ce que nous avons, intact.
return RefreshResult.Unchanged(_cached!);
}
res.EnsureSuccessStatusCode();
// 200 : une représentation véritablement nouvelle. Ce n'est que maintenant qu'on paie décodage + vérif.
var body = await res.Content.ReadFromJsonAsync<LeaseResponse>(ct)
?? throw new KeyrightException("empty lease body");
var lease = SignedLease.VerifyAndParse(body, _publicKey); // la vérification RSA se fait ici
_cached = lease;
_etag = res.Headers.ETag?.ToString(); // stocke le nouveau validateur pour la prochaine fois
return RefreshResult.Updated(lease);
}
}
Les deux branches sont tout l’enjeu. Un 304 renvoie RefreshResult.Unchanged et ne touche jamais au chemin de signature — la chose la plus coûteuse qu’un rafraîchissement puisse faire est justement la seule que le chemin rapide saute. Un 200 est traité exactement comme le serait une récupération sans cache : vérifier, échanger le cache, stocker l’ETag frais. Il n’y a pas de troisième état à rater.
Remarquez HttpCompletionOption.ResponseHeadersRead : sur un 304 il n’y a pas de corps à mettre en mémoire tampon, donc vous voulez inspecter le statut à partir des en-têtes avant de décider de lire ou non du contenu.
Ne laissez pas max-age remplacer l’évaluation locale
Le Cache-Control: max-age=300 de la réponse indique au client qu’il peut servir le lease en cache sans redemander pendant jusqu’à cinq minutes — c’est ce qui fixe le plancher de votre intervalle de rafraîchissement. Ce qu’il ne doit pas faire, c’est supprimer la partie locale, dépendante du temps, d’une vérification de licence. Un lease peut porter un expiresAt qui tombe à l’intérieur de la fenêtre de max-age ; à l’instant où l’horloge murale le dépasse, l’entitlement a disparu même si les octets en cache sont toujours « frais » selon la définition de HTTP. C’est la même séparation couverte dans le travail de cache du chemin chaud : mettez en cache la vérification de signature (l’ETag protège cela), ne mettez jamais en cache l’évaluation à l’instant présent. Validate() réévalue toujours l’expiration contre l’horloge validée, quelle que soit la fraîcheur que le cache HTTP croit avoir de la représentation.
La règle de correction qui rend cela sûr
Une requête conditionnelle n’est aussi sûre que la garantie que l’ETag change chaque fois que la licence change. Ratez cela et un 304 devient un mensonge — le client conserve un lease que le service a déjà révoqué et continue de répondre 304 parce que l’étiquette n’a jamais bougé. Donc la règle du côté serveur est absolue :
Toute mutation qui change ce que la licence accorde doit changer l’ETag. Comme l’étiquette est dérivée de la version monotone, et que chaque mutation incrémente la version, cela va de soi : une révocation incrémente la version comme n’importe quelle autre modification, le If-None-Match suivant échoue à correspondre, et le client reçoit un 200 portant l’état désormais révoqué (qui, à la vérification, se résout au fallback de la Community Edition). Il n’y a aucun chemin où un changement de licence en direct soit masqué par une étiquette périmée, pourvu que la version soit l’unique source de vérité et que l’étiquette soit forte, pas faible.
L’échec inverse — l’étiquette change alors que la licence n’a pas changé — est inoffensif. Cela signifie simplement un 200 inutile de temps en temps, le même coût que vous payiez à chaque requête auparavant. Les requêtes conditionnelles dégradent vers « télécharge la chose complète », jamais vers « sers quelque chose de périmé ».
Le tester avec curl
Vous pouvez observer tout l’échange depuis la ligne de commande, ce qui est le moyen le plus rapide de confirmer que votre service étiquette correctement avant de toucher au SDK. La première récupération capture l’étiquette ; la seconde la renvoie.
$ curl -s -D - -H "Authorization: Bearer AK-9f3c…" \
https://keyright.example.com/v1/licenses/current -o /dev/null | grep -i etag
ETag: "v47-3b9a1f"
$ curl -s -D - -H "Authorization: Bearer AK-9f3c…" \
-H 'If-None-Match: "v47-3b9a1f"' \
https://keyright.example.com/v1/licenses/current -o /dev/null | head -1
HTTP/1.1 304 Not Modified
Un 304 au second appel prouve que l’aller-retour fonctionne. Maintenant forcez un changement — renouvelez la licence, ou incrémentez sa version dans votre harnais de test — et répétez l’appel conditionnel : vous devriez obtenir un 200, un nouveau corps et un ETag différent. Si vous obtenez un 200 avec le même ETag, votre étiquette n’est pas dérivée d’un champ qui a réellement changé ; si vous obtenez un 304 après une révocation, votre chemin de révocation n’incrémente pas la version, ce qui est un bug de correction, pas de cache.
Un piège : proxies et suppression d’en-têtes
Si vos clients atteignent le service émetteur à travers un proxy inverse ou un CDN, confirmez qu’il transmet If-None-Match en amont et qu’il ne répond pas lui-même à la requête conditionnelle depuis un cache qui ignore la révocation. Une réponse de licence devrait être marquée Cache-Control: private précisément pour que les caches partagés ne la stockent pas ; la validation conditionnelle appartient entre le client et le service émetteur, pas à un intermédiaire qui n’a aucune idée qu’une licence a été retirée. Gardez le validateur de bout en bout et le 304 signifiera exactement ce que vous pensez qu’il signifie.
Voilà tout le mécanisme. La boucle de rafraîchissement continue de tourner sur sa minuterie, continue de prendre en compte chaque renouvellement et chaque révocation à temps, et continue de vérifier chaque lease véritablement nouveau — mais le cas extrêmement courant, « rien n’a changé depuis la dernière fois que j’ai demandé », coûte désormais quelques centaines d’octets d’en-têtes et une lecture de ligne de statut au lieu d’un téléchargement de charge utile signée et d’une vérification à clé publique. La licence n’a pas changé, donc le client ne fait pas le travail de faire semblant qu’elle aurait pu.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.