Fenêtres de grâce pour une panne transitoire du serveur de licences
Une vérification de licence en ligne qui échoue sèchement dès que votre service émetteur Keyright est brièvement injoignable transforme un hoquet DNS ou un déploiement de routine en panne visible par vos clients. Cet article montre comment encaisser les pannes passagères avec une fenêtre de grâce configurable au-dessus d'un résultat de validation signé et mis en cache : en distinguant « service injoignable » (passager, on continue) de « licence révoquée » (définitif, on échoue fermé tout de suite), en bornant la grâce par les horodatages signés par le service lui-même pour que personne ne la prolonge en débranchant le réseau, en journalisant chaque exécution sur cache et en échouant fermé proprement une fois la fenêtre épuisée.
Une vérification de licence en ligne vous apporte des choses qu”une vérification hors ligne ne peut pas : des décomptes de sièges en temps réel, une révocation instantanée, une mesure d”usage. Mais elle s”accompagne d”un mode de défaillance facile à introduire par accident. Si votre code traite chaque échec à joindre le service émetteur comme une validation ratée, alors la première fois que votre instance Keyright auto-hébergée est brièvement injoignable — un hoquet DNS, un déploiement progressif, un proxy qui coupe une connexion — tous les clients payants sont verrouillés d”un coup. Un événement d”infrastructure de trente secondes devient une panne de trente secondes côté client, et les tickets de support se moquent que la licence ait été valide tout du long.
La solution n”est pas d”arrêter de vérifier en ligne. C”est d”arrêter de confondre « le service a dit non » avec « je n”ai pas pu joindre le service », et d”encaisser le second cas sur un résultat signé et en cache pendant une fenêtre de grâce bornée.
À retenir : Mettez en cache la dernière validation réussie localement, signée pour qu”elle ne puisse pas être falsifiée. Quand le service est injoignable, continuez d”honorer le résultat en cache pendant une fenêtre de grâce configurable bornée par les propres horodatages signés du service (pour que personne ne la prolonge en débranchant). Quand le service est joignable et dit que la licence est révoquée ou expirée, échouez fermé immédiatement. Journalisez chaque exécution sur cache, et échouez fermé proprement une fois la fenêtre épuisée.
Les deux défaillances qui ne doivent pas se ressembler
Chaque revalidation en ligne se termine à l”un de trois endroits, et tout le design tient à les garder séparés.
- Confirmé. Le service a répondu et la licence est bonne. Renouvelez le lease en cache et continuez.
- Non définitif. Le service a répondu et la réponse est révoquée, expirée ou siège retiré. C”est définitif. Vous devez échouer fermé maintenant — la grâce ne s”applique pas, car la licence n”est réellement plus valide.
- Injoignable. Le service n”a pas répondu du tout : un délai de connexion dépassé, un échec DNS, un
502d”un proxy inverse en plein déploiement. Vous n”avez rien appris sur la licence. La dernière chose que le service vous a dite tient toujours, alors vous continuez de l”honorer — pour un temps.
L”erreur est de fusionner le deuxième et le troisième cas dans une seule branche « validation échouée ». Une révocation et une connexion TCP coupée sont des faits opposés. L”un signifie que le client doit s”arrêter ; l”autre signifie que votre réseau a eu un hoquet et que le client ne devrait rien remarquer.
Configurer la fenêtre de grâce
La grâce se configure une seule fois, là où vous initialisez le client. GracePeriod est la durée pendant laquelle une licence valide en cache continue de fonctionner après la dernière confirmation réussie tant que le service est injoignable. MaxOfflineDuration est le plafond absolu de la durée pendant laquelle un lease en cache est jamais honoré, quel que soit le nombre de fois où la grâce se réinitialiserait — c”est votre filet de sécurité face à une machine qui se déconnecte et ne revient pas.
static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = "MIIBIjANBgkq...", // ships in your binary; not a secret
ServiceUrl = "https://keyright.example.com", // your self-hosted instance
GracePeriod = TimeSpan.FromHours(72), // ride out outages this long after last contact
MaxOfflineDuration = TimeSpan.FromDays(14), // absolute ceiling on cached operation
});
Choisissez GracePeriod pour dépasser largement votre pire événement passager réaliste — un long déploiement, une rotation de certificats, un hoquet réseau régional — mais pas au point qu”un client réellement résilié tourne pendant des semaines. Soixante-douze heures couvrent un incident du vendredi soir que personne ne regarde avant le lundi. MaxOfflineDuration est la limite plus longue et plus grossière ; réglez-la sur votre cadence de facturation pour qu”une machine qui ne rappelle jamais finisse par devoir le faire.
Rafraîchir : là où vit la séparation passager-vs-définitif
Validate() reste exactement ce qu”elle a toujours été : une vérification pure et hors ligne du lease en cache contre votre clé publique embarquée, qui ne lève jamais d”exception et ne touche jamais le réseau. Le travail en ligne se passe dans RefreshAsync, et son résultat est là où vous distinguez les deux défaillances.
RefreshResult refresh = await License.RefreshAsync(ct);
switch (refresh.Status)
{
case RefreshStatus.Confirmed:
// Service reachable, license good. SDK has already renewed the signed
// cached lease (new ConfirmedAtUtc), so the grace window resets.
break;
case RefreshStatus.Revoked:
case RefreshStatus.Expired:
case RefreshStatus.SeatWithdrawn:
// Service reachable and said no. Definitive — DO NOT enter grace.
GateApplication(refresh.Reason);
break;
case RefreshStatus.ServiceUnreachable:
// We learned nothing. The cached lease still stands within its grace window.
_log.LogWarning("Keyright unreachable ({Detail}); running on cached validation.",
refresh.Detail);
break;
}
Si vous préférez les exceptions sur un chemin de plus bas niveau, l”échec de connectivité remonte sous forme d”exception typée que vous pouvez attraper, tandis qu”un rejet définitif, lui, ne le fait pas — il revient sous forme de résultat que vous devez inspecter :
try
{
await License.RefreshAsync(ct); // throwOnUnreachable: true overload
}
catch (KeyrightServiceUnreachableException ex)
{
// Transient only: DNS, connect timeout, 5xx from a proxy. Keep the cached lease.
_log.LogWarning(ex, "Transient Keyright outage; grace window active.");
}
La règle à retenir : une KeyrightServiceUnreachableException (ou RefreshStatus.ServiceUnreachable) est la seule chose qui mène vers la grâce. Un résultat révoqué ou expiré n”est jamais un problème de connectivité, il ne reçoit donc jamais le bénéfice du doute.
Vous n”appelez pas RefreshAsync sur le chemin chaud. Exécutez-la sur une minuterie — toutes les quelques minutes, ou à la reprise de l”appli — et laissez Validate() servir chaque décision de blocage réelle depuis le lease en cache entre-temps.
Lire la validation en cache et son horodatage signé
Quand Validate() répond depuis le cache plutôt que depuis une confirmation fraîche, LicenseInfo vous le dit, et porte l”horodatage signé qui borne la fenêtre de grâce. Chaque champ ici est couvert par la signature du service sur le lease, aucun ne peut donc être modifié sur disque sans casser la vérification.
LicenseInfo info = License.Validate();
if (info.ValidationSource == ValidationSource.Cache)
{
DateTimeOffset confirmedAt = info.Lease.ConfirmedAtUtc; // signed by the service
TimeSpan remaining = info.GraceRemaining; // how long cached operation is still allowed
_log.LogInformation(
"Running on cached license: last confirmed {ConfirmedAt:u}, grace remaining {Remaining}.",
confirmedAt, remaining);
if (remaining < TimeSpan.FromHours(6))
ShowBanner($"License server unreachable. Reconnect within {remaining:hh\\:mm} to stay licensed.");
}
if (info.Edition == LicenseEdition.Community)
{
// Grace exhausted (or never licensed): the SDK has already fallen back to
// Community Edition. Gate the paid entitlements, cleanly.
DisablePaidFeatures();
}
Notez la cible du repli : quand la grâce est épuisée, un déploiement auto-hébergé redescend vers Community Edition, il ne plante pas. Les droits payants se lisent comme désactivés via les mêmes appels IsEnabled / GetLimit que vous utilisez déjà, donc échouer fermé n”est que votre blocage habituel qui fait son travail — sans aucun chemin de code spécial « on vous a verrouillé ».
Considérations d”horloge : pourquoi vous ne pouvez pas tricher la grâce en débranchant
L”attaque évidente contre toute fenêtre de grâce hors ligne est de débrancher le réseau et de reculer l”horloge pour que la grâce ne s”écoule jamais. Keyright ferme cela sur deux fronts.
La grâce se mesure depuis un instant signé, pas un instant local. Le décompte part de Lease.ConfirmedAtUtc, que le service a signé lors de sa dernière réponse. Un utilisateur peut changer l”horloge de sa machine, mais il ne peut pas déplacer un horodatage qui est à l”intérieur d”un payload signé sans invalider la signature — et une signature invalide échoue fermé immédiatement.
Une horloge reculée est traitée comme une altération. À côté de l”horodatage signé, le SDK persiste un marqueur monotone et la dernière heure serveur signée qu”il a vue. Si l”horloge système indique ensuite une heure antérieure à ce plus-haut atteint — la signature d”un recul délibéré — le SDK cesse de faire confiance à l”horloge locale et échoue fermé plutôt que d”accorder une grâce illimitée :
if (info.ClockStatus == ClockStatus.WentBackwards)
{
// Wall clock is earlier than the last signed server time we recorded.
// Treat as tamper: do not extend grace.
GateApplication("System clock rolled back; reconnect to re-validate.");
}
MaxOfflineDuration est le filet de sécurité final. Même si toutes les vérifications d”horloge passaient, aucun lease en cache n”est honoré au-delà de ConfirmedAtUtc + MaxOfflineDuration. Débrancher le câble achète exactement GracePeriod, et au fil de pannes courtes répétées cela achète au plus MaxOfflineDuration au total — jamais pour toujours.
Télémétrie pendant le fonctionnement sur validation en cache
Fonctionner sur cache est un état dégradé, et vous voulez savoir que cela se produit avant qu”un client ne vous le dise. Deux choses méritent d”être émises. D”abord, une ligne de journal structurée chaque fois qu”une décision de blocage est servie depuis le cache plutôt que depuis une confirmation fraîche — exactement la branche ValidationSource == Cache ci-dessus — portant confirmedAt et remaining pour que vous puissiez voir à quelle profondeur dans la fenêtre une flotte a dérivé. Ensuite, une métrique ou un signal de santé sur lequel vous pouvez alerter : si une part significative d”instances est sur validation en cache en même temps, c”est votre service émetteur qui passe une mauvaise journée, pas une poignée de clients isolés qui passent hors ligne. Gardez la clé elle-même hors de ces journaux (caviardez-la en un préfixe) comme vous le feriez partout ailleurs.
Échouer fermé, proprement
Quand la grâce finit par s”écouler — MaxOfflineDuration atteint, recul d”horloge détecté, ou une révocation définitive revenue dès que le service fut joignable — l”état final est le même et il devrait être sans drame. Validate() renvoie LicenseEdition.Community, les droits payants se lisent désactivés et votre blocage existant réduit l”appli à sa surface gratuite. Le client voit un message clair et actionnable (« reconnectez-vous pour revalider ») plutôt qu”une trace de pile, et dès que le service redevient joignable un unique RefreshAsync confirme la licence et restaure la fonction complète sans réinstallation et sans ressaisie de clé.
Voilà toute la forme de la chose : une panne que vous avez causée ne devrait rien coûter à votre client, une résiliation devrait lui coûter ses fonctions payantes rapidement, et la différence entre les deux est un horodatage signé et une fenêtre bornée — jamais une connexion coupée prise pour un verdict.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.