Intégrer le SDK Keyright dans ASP.NET Core avec résilience
Les équipes qui instancient le client Keyright à la main tombent sur l'un des deux échecs classiques de HttpClient : épuisement des sockets dû à un client par appel, ou DNS périmé dû à un unique client statique conservé pour toujours. Cet article enregistre le client Keyright via IHttpClientFactory comme client typé pour que les message handlers soient mutualisés et renouvelés correctement, choisit les bons lifetimes de DI et ajoute un pipeline de résilience — timeout, nouvelle tentative avec jitter et un circuit breaker réglé pour un appel de licence — afin qu'un bref hoquet du service émetteur se dégrade avec élégance plutôt que d'échouer brutalement.
La plupart des intégrations Keyright commencent de la même façon : quelqu’un doit valider une licence contre le service émetteur auto-hébergé, alors il écrit new HttpClient(), le pointe vers le ServiceUrl et l’expédie. Ça marche en développement et sur la démo. Puis ça part en production et l’une des deux choses se produit.
Soit le client est créé par appel — un HttpClient neuf dans la méthode qui vérifie la licence — et sous le trafic réel le processus se retrouve à court de sockets. Chaque client supprimé laisse des connexions en TIME_WAIT, la plage de ports éphémères se remplit, et vous commencez à voir SocketException: Only one usage of each socket address is normally permitted. Soit quelqu’un lit le conseil « réutilisez un seul HttpClient », crée une unique instance static et la garde pour toute la vie du processus — ce qui règle les sockets mais fige le DNS. Le jour où vous déplacez ou mettez à l’échelle votre service émetteur, ce client statique continue d’appeler l’adresse qu’il a résolue au démarrage, bien après sa disparition.
Les deux échecs viennent de la gestion manuelle du HttpMessageHandler. La bonne réponse en ASP.NET Core est de cesser de le faire et d’enregistrer le client Keyright comme un client typé via IHttpClientFactory, qui mutualise et renouvelle le handler pour vous, puis d’ajouter un pipeline de résilience afin qu’un bref hoquet du service émetteur se dégrade avec élégance au lieu de faire tomber brutalement un client payant.
À retenir : Enregistrez le client Keyright avec AddHttpClient<IKeyrightClient, KeyrightClient>() pour que la fabrique mutualise et renouvelle le handler sous-jacent — pas d’épuisement de sockets, pas de DNS périmé. Injectez IKeyrightClient comme n’importe quel service (le wrapper est sûr en singleton ; le HttpClient n’est pas conservé pour toujours). Accrochez AddStandardResilienceHandler() avec un timeout, une nouvelle tentative avec jitter et un circuit breaker réglé pour un appel de licence — retentez l’idempotent ValidateAsync/RefreshAsync, prudence avec l’activation — et repliez-vous sur la validation en cache quand le service est brièvement injoignable.
Les deux anti-patterns, concrètement
Voici la version de l’épuisement des sockets. Elle paraît inoffensive parce que chaque client est supprimé.
// ANTI-PATTERN 1: a new HttpClient per license check.
public async Task<bool> IsLicensedAsync(string key, CancellationToken ct)
{
using var http = new HttpClient { BaseAddress = new Uri("https://keyright.example.com") };
var client = new KeyrightClient(http, _options); // new handler every call
var info = await client.ValidateAsync(key, ct);
return info.IsValid;
}
using supprime le client, mais la connexion TCP qu’il a ouverte persiste en TIME_WAIT pendant quelques minutes. Quelques centaines de vérifications par seconde et vous êtes à court de ports. Le second anti-pattern inverse le problème :
// ANTI-PATTERN 2: one static HttpClient for the life of the process.
static readonly HttpClient Http = new() { BaseAddress = new Uri("https://keyright.example.com") };
static readonly KeyrightClient Client = new(Http, Options);
// Reuses connections — but the handler never rotates, so DNS is cached forever.
Celui-ci survit à la charge, puis échoue silencieusement au prochain changement d’infrastructure. Aucun ne se trompe sur le fait que HttpClient est coûteux à créer et bon marché à réutiliser — chacun a raison à moitié, et la moitié qui leur manque est le renouvellement du handler.
Enregistrer Keyright comme client typé
Le correctif est un unique enregistrement au démarrage. AddHttpClient<IKeyrightClient, KeyrightClient>() indique à la fabrique de construire KeyrightClient avec un HttpClient dont le handler provient du pool. Vous configurez le client — adresse de base, timeout, en-têtes par défaut — dans le callback, et les options au niveau du SDK (produit, clé publique) via les habituelles KeyrightOptions.
var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<KeyrightOptions>(o =>
{
o.Product = "acme-suite";
o.PublicKeyBase64 = builder.Configuration["Keyright:PublicKey"]!; // ships in your binary; not a secret
o.ServiceUrl = builder.Configuration["Keyright:ServiceUrl"]!; // your self-hosted instance
});
builder.Services
.AddHttpClient<IKeyrightClient, KeyrightClient>((sp, http) =>
{
var opts = sp.GetRequiredService<IOptions<KeyrightOptions>>().Value;
http.BaseAddress = new Uri(opts.ServiceUrl);
http.Timeout = Timeout.InfiniteTimeSpan; // let the resilience pipeline own timeouts
http.DefaultRequestHeaders.Add("X-Keyright-Product", opts.Product);
})
.AddStandardResilienceHandler(); // Microsoft.Extensions.Http.Resilience
Deux détails comptent ici. D’abord, KeyrightClient reçoit un HttpClient dans son constructeur — la surcharge du client typé résout le reste de ses dépendances depuis la DI, donc la clé publique et le produit arrivent via KeyrightOptions. Ensuite, le HttpClient.Timeout propre au client est réglé à l’infini à dessein : quand un pipeline de résilience est accroché, vous voulez que lui gère le timeout par tentative, pas le timeout grossier de requête complète intégré à HttpClient, qui ne sait pas distinguer une première tentative lente d’une nouvelle tentative.
Si vous préférez un unique point d’appel, enveloppez l’enregistrement dans une méthode d’extension pour que les applications disent simplement AddKeyright(...) :
public static IServiceCollection AddKeyright(
this IServiceCollection services, Action<KeyrightOptions> configure)
{
services.Configure(configure);
services.AddHttpClient<IKeyrightClient, KeyrightClient>((sp, http) =>
{
var o = sp.GetRequiredService<IOptions<KeyrightOptions>>().Value;
http.BaseAddress = new Uri(o.ServiceUrl);
http.Timeout = Timeout.InfiniteTimeSpan;
})
.AddStandardResilienceHandler();
return services;
}
Désormais tout tient dans builder.Services.AddKeyright(o => { o.Product = "acme-suite"; /* … */ });, et les consommateurs injectent IKeyrightClient sans jamais voir de HttpClient.
Lifetimes : pourquoi le wrapper est sûr en singleton mais pas le handler
AddHttpClient<TClient>() enregistre le client typé comme transient par défaut, et c’est délibéré. L’objet client lui-même est bon marché — c’est un wrapper fin — et chaque instance qu’il vous remet est liée à un HttpClient produit par la fabrique. La chose coûteuse et à longue durée de vie est le HttpMessageHandler en dessous, et la fabrique en garde un pool, renouvelant chacun au terme de sa durée de vie (deux minutes par défaut) afin que les connexions soient réutilisées mais que le DNS ne vieillisse pas.
La règle pratique : résolvez IKeyrightClient là où vous en avez besoin et utilisez-le ; ne capturez pas le HttpClient qu’il enveloppe dans un champ d’un singleton à vous. L’état du wrapper Keyright — la clé publique embarquée, le lease en cache, la dernière édition de licence connue — est à l’échelle du processus et peut être traité en toute sécurité comme un singleton, c’est pourquoi KeyrightClient.Initialize(...) renvoie un objet à longue durée de vie dans les applications sans DI. En ASP.NET Core vous obtenez la même ergonomie via la fabrique sans figer de handler, parce que le lease en cache vit dans le SDK, pas dans le HttpClient.
public sealed class LicensedFeature(IKeyrightClient license)
{
public async Task<IResult> RunAsync(CancellationToken ct)
{
// Pure, offline check against the embedded public key — no network, never throws.
var info = license.Validate();
if (!info.IsEnabled("acme.export"))
return Results.StatusCode(StatusCodes.Status402PaymentRequired);
return Results.Ok(await DoExportAsync(ct));
}
}
Validate() sert la décision de la porte depuis le lease en cache, elle est donc appropriée sur le chemin critique. L’appel réseau ne vit que dans RefreshAsync, que vous exécutez sur une minuterie — pas à chaque requête.
Le pipeline de résilience, réglé pour un appel de licence
AddStandardResilienceHandler() vous donne une pile par défaut raisonnable : un timeout de requête total, une stratégie de nouvelles tentatives, un circuit breaker et un timeout par tentative, dans cet ordre. Les valeurs par défaut sont réglées pour une API aval générique ; pour un appel de licence vous voudrez ajuster quelques boutons.
builder.Services
.AddHttpClient<IKeyrightClient, KeyrightClient>(ConfigureClient)
.AddStandardResilienceHandler(o =>
{
// Per-attempt timeout: the issuing service answers a validate in well under a second.
o.AttemptTimeout.Timeout = TimeSpan.FromSeconds(3);
// Retry: idempotent validate/refresh is safe to repeat. Exponential + jitter so a
// fleet recovering from a blip does not stampede the service in lockstep.
o.Retry.MaxRetryAttempts = 3;
o.Retry.BackoffType = DelayBackoffType.Exponential;
o.Retry.UseJitter = true;
o.Retry.Delay = TimeSpan.FromMilliseconds(200);
// Circuit breaker: once the service is clearly down, stop hammering it and fail fast,
// letting the SDK's cached-lease path take over instead of queueing doomed requests.
o.CircuitBreaker.FailureRatio = 0.5;
o.CircuitBreaker.MinimumThroughput = 10;
o.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(30);
o.CircuitBreaker.BreakDuration = TimeSpan.FromSeconds(15);
// Total timeout must exceed AttemptTimeout × attempts, or retries get cut off.
o.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(15);
});
Le handler standard ne retente que sur des conditions transitoires — échecs de connexion, HttpRequestException, timeouts, 5xx et 408 — et jamais sur un 4xx. Ce comportement par défaut est exactement le bon pour la licence : un 403 ou un 409 du service émetteur est une réponse définitive (révoquée, siège retiré, produit qui ne correspond pas) et ne doit pas être retentée, tandis qu’un 503 pendant un déploiement progressif est transitoire et devrait l’être.
Si vous préférez construire le pipeline à la main — par exemple pour varier la stratégie selon l’opération — le ResiliencePipelineBuilder de Polly s’insère de la même façon :
var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
.AddRetry(new HttpRetryStrategyOptions
{
MaxRetryAttempts = 3,
BackoffType = DelayBackoffType.Exponential,
UseJitter = true,
ShouldHandle = static args => ValueTask.FromResult(
args.Outcome.Result is { StatusCode: >= HttpStatusCode.InternalServerError }
|| args.Outcome.Exception is HttpRequestException or TimeoutException),
})
.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions())
.AddTimeout(TimeSpan.FromSeconds(3))
.Build();
Validate est sûr à retenter ; l’activation ne l’est pas
C’est le seul endroit où une politique unique pour chaque appel vous met en difficulté. ValidateAsync et RefreshAsync sont des lectures idempotentes — elles demandent l’état actuel et ne changent rien — donc retenter l’une d’elles qui a expiré est toujours sûr. L’activation est différente. Elle peut consommer un siège ou lier une machine, donc une nouvelle tentative aveugle risque un double comptage : si la première tentative a bel et bien atteint le service et réussi mais que la réponse a été perdue au retour, une nouvelle tentative active une seconde fois.
Enregistrez l’activation sur son propre client nommé avec une politique plus conservatrice, et appuyez-vous sur une idempotency key que le service déduplique :
// A separate, named client for the non-idempotent activation call.
builder.Services.AddHttpClient("keyright-activate", ConfigureClient)
.AddResilienceHandler("activate", b => b
.AddRetry(new HttpRetryStrategyOptions { MaxRetryAttempts = 1, UseJitter = true })
.AddTimeout(TimeSpan.FromSeconds(10)));
// …and pass an idempotency key so a retried activation is coalesced server-side.
var result = await license.ActivateAsync(
key, new ActivationRequest { IdempotencyKey = deviceInstallId }, ct);
Avec l’idempotency key, même l’unique nouvelle tentative autorisée ne peut pas consommer un siège en double : le service reconnaît la clé répétée et renvoie le résultat d’origine au lieu d’activer à nouveau.
Se dégrader avec élégance plutôt qu’échouer brutalement
La raison pour laquelle tout cela compte est que l’appel réseau au service émetteur ne devrait jamais être ce qui fait tomber votre client. Un validate qui expire une fois, retente et réussit est invisible. Un service véritablement hors service pendant une minute déclenche le circuit breaker, et au lieu que chaque requête fasse la queue derrière une connexion condamnée, le breaker échoue vite et vos décisions de porte se replient sur le lease en cache du SDK — le même chemin de validation en cache qui empêche une brève panne de bloquer qui que ce soit. Quand le service revient, le breaker s’entrouvre, une sonde réussit, et le trafic reprend sans redémarrage ni intervention.
Tester le câblage
Vous pouvez tester l’enregistrement et le comportement de résilience sans service émetteur en direct en remplaçant le handler primaire par un stub. ConfigurePrimaryHttpMessageHandler remplace le handler le plus interne en laissant les handlers de résilience en place, vous exercez donc le pipeline réel.
var services = new ServiceCollection();
services.AddKeyright(o => { o.Product = "acme-suite"; o.ServiceUrl = "https://keyright.test"; });
// Fail twice, then succeed — proves the retry strategy is wired and bounded.
var attempts = 0;
services.ConfigureHttpClientDefaults(b => b.ConfigurePrimaryHttpMessageHandler(() =>
new StubHandler(_ =>
++attempts < 3
? new HttpResponseMessage(HttpStatusCode.ServiceUnavailable)
: new HttpResponseMessage(HttpStatusCode.OK) { Content = ValidLeaseJson() })));
var client = services.BuildServiceProvider().GetRequiredService<IKeyrightClient>();
var info = await client.RefreshAsync(CancellationToken.None);
Assert.Equal(3, attempts); // two transient failures were retried
Assert.Equal(RefreshStatus.Confirmed, info.Status);
Un second test pointe le stub vers un 403 et vérifie que l’appel n’est pas retenté et remonte comme un rejet définitif — c’est votre garde-fou contre quelqu’un qui relâcherait le prédicat ShouldHandle jusqu’à ce que les révocations se mettent à être retentées.
Voilà toute la forme d’une intégration Keyright correcte en ASP.NET Core : un unique enregistrement de client typé pour que les handlers soient mutualisés et renouvelés, un pipeline de résilience qui retente les appels idempotents et respecte les définitifs, et un lease en cache en dessous pour qu’un hoquet de votre service émetteur coûte une nouvelle tentative — jamais un client.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.