Integrar el SDK de Keyright en ASP.NET Core con resiliencia
Los equipos que instancian el cliente de Keyright a mano caen en uno de los dos fallos clásicos de HttpClient: agotamiento de sockets por crear un cliente por llamada, o DNS obsoleto por mantener un único cliente estático para siempre. Este artículo registra el cliente de Keyright a través de IHttpClientFactory como un cliente tipado para que los message handlers se agrupen y se roten correctamente, elige los lifetimes de DI adecuados y añade un pipeline de resiliencia — timeout, reintento con jitter y un circuit breaker ajustado para una llamada de licencia — de modo que un breve hipo del servicio emisor degrade con elegancia en lugar de fallar en seco.
La mayoría de las integraciones de Keyright empiezan igual: alguien necesita validar una licencia contra el servicio emisor autoalojado, así que escribe new HttpClient(), lo apunta al ServiceUrl y lo despacha. Funciona en desarrollo y en la demo. Luego llega a producción y pasa una de dos cosas.
O bien el cliente se crea por llamada — un HttpClient nuevo dentro del método que comprueba la licencia — y bajo tráfico real el proceso se queda sin sockets. Cada cliente desechado deja conexiones en TIME_WAIT, el rango de puertos efímeros se llena y empiezas a ver SocketException: Only one usage of each socket address is normally permitted. O bien alguien lee el consejo de «reutiliza un único HttpClient», crea una sola instancia static y la mantiene durante toda la vida del proceso — lo que arregla los sockets pero congela el DNS. El día que muevas o escales tu servicio emisor, ese cliente estático seguirá marcando la dirección que resolvió al arrancar, mucho después de que haya desaparecido.
Ambos fallos vienen de gestionar el HttpMessageHandler a mano. La respuesta correcta en ASP.NET Core es dejar de hacerlo y registrar el cliente de Keyright como un cliente tipado a través de IHttpClientFactory, que agrupa y rota el handler por ti, y después añadir un pipeline de resiliencia para que un breve hipo del servicio emisor degrade con elegancia en lugar de tumbar en seco a un cliente que paga.
Idea clave: Registra el cliente de Keyright con AddHttpClient<IKeyrightClient, KeyrightClient>() para que la factoría agrupe y rote el handler subyacente — sin agotamiento de sockets, sin DNS obsoleto. Inyecta IKeyrightClient como cualquier otro servicio (el wrapper es seguro como singleton; el HttpClient no se mantiene para siempre). Engancha AddStandardResilienceHandler() con un timeout, reintento con jitter y un circuit breaker ajustado para una llamada de licencia — reintenta el idempotente ValidateAsync/RefreshAsync, ten cuidado con la activación — y recurre a la validación en caché cuando el servicio esté brevemente inalcanzable.
Los dos antipatrones, en concreto
Esta es la versión del agotamiento de sockets. Parece inofensiva porque cada cliente se desecha.
// 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 desecha el cliente, pero la conexión TCP que abrió permanece en TIME_WAIT un par de minutos. Unos cientos de comprobaciones por segundo y te quedas sin puertos. El segundo antipatrón invierte el problema:
// 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.
Este sobrevive a la carga y luego falla en silencio en el siguiente cambio de infraestructura. Ninguno se equivoca en que HttpClient es caro de crear y barato de reutilizar — cada uno acierta a medias, y la mitad que les falta es la rotación del handler.
Registrar Keyright como cliente tipado
El arreglo es un único registro al arrancar. AddHttpClient<IKeyrightClient, KeyrightClient>() indica a la factoría que construya KeyrightClient con un HttpClient cuyo handler sale del pool. Configuras el cliente — dirección base, timeout, cabeceras por defecto — en el callback, y las opciones a nivel de SDK (producto, clave pública) a través de las habituales 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
Aquí importan dos detalles. Primero, KeyrightClient recibe un HttpClient en su constructor — la sobrecarga del cliente tipado resuelve el resto de sus dependencias desde la DI, así que la clave pública y el producto entran a través de KeyrightOptions. Segundo, el HttpClient.Timeout propio del cliente se fija a infinito a propósito: cuando hay un pipeline de resiliencia enganchado, quieres que él gestione el timeout por intento, no el tosco timeout de petición completa que trae HttpClient, que no sabe distinguir un primer intento lento de un reintento.
Si prefieres un único punto de llamada, envuelve el registro en un método de extensión para que las aplicaciones solo digan 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;
}
Ahora todo queda en builder.Services.AddKeyright(o => { o.Product = "acme-suite"; /* … */ });, y los consumidores inyectan IKeyrightClient sin ver jamás un HttpClient.
Lifetimes: por qué el wrapper es seguro como singleton pero el handler no
AddHttpClient<TClient>() registra el cliente tipado como transient por defecto, y es deliberado. El objeto cliente en sí es barato — es un wrapper fino — y cada instancia que te entrega está ligada a un HttpClient que produjo la factoría. Lo caro y de larga vida es el HttpMessageHandler de debajo, y la factoría mantiene un pool de ellos, rotando cada uno al cumplirse su tiempo de vida (dos minutos por defecto) para que las conexiones se reutilicen pero el DNS no envejezca.
La regla práctica: resuelve IKeyrightClient donde lo necesites y úsalo; no captures el HttpClient que envuelve en un campo de un singleton propio. El estado del wrapper de Keyright — la clave pública embebida, el lease en caché, la última edición de licencia conocida — es a escala de proceso y es seguro tratarlo como un singleton, que es por lo que KeyrightClient.Initialize(...) devuelve un objeto de larga vida en aplicaciones sin DI. En ASP.NET Core obtienes la misma ergonomía a través de la factoría sin congelar un handler, porque el lease en caché vive en el SDK, no en el 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() sirve la decisión de la puerta desde el lease en caché, así que es correcto en la ruta caliente. La llamada de red vive solo en RefreshAsync, que ejecutas con un temporizador — no en cada petición.
El pipeline de resiliencia, ajustado para una llamada de licencia
AddStandardResilienceHandler() te da una pila por defecto sensata: un timeout de petición total, una estrategia de reintentos, un circuit breaker y un timeout por intento, en ese orden. Los valores por defecto están ajustados para una API posterior genérica; para una llamada de licencia conviene retocar algunos mandos.
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);
});
El handler estándar solo reintenta ante condiciones transitorias — fallos de conexión, HttpRequestException, timeouts, 5xx y 408 — y nunca ante un 4xx. Ese valor por defecto es justo el adecuado para la licencia: un 403 o un 409 del servicio emisor es una respuesta definitiva (revocada, asiento retirado, producto que no coincide) y no debe reintentarse, mientras que un 503 durante un despliegue progresivo es transitorio y sí debería.
Si prefieres construir el pipeline a mano — por ejemplo para variar la estrategia por operación — el ResiliencePipelineBuilder de Polly encaja igual:
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 es seguro de reintentar; la activación no
Este es el único punto donde una sola política para todas las llamadas te mete en problemas. ValidateAsync y RefreshAsync son lecturas idempotentes — piden el estado actual y no cambian nada — así que reintentar una que agotó el tiempo es siempre seguro. La activación es distinta. Puede consumir un asiento o vincular una máquina, así que un reintento ciego arriesga un doble conteo: si el primer intento en realidad llegó al servicio y tuvo éxito pero la respuesta se perdió de vuelta, un reintento activa una segunda vez.
Registra la activación en su propio cliente con nombre y con una política más conservadora, y apóyate en una idempotency key que el servicio deduplique:
// 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);
Con la idempotency key, ni siquiera el único reintento permitido puede consumir un asiento por duplicado: el servicio reconoce la clave repetida y devuelve el resultado original en lugar de activar de nuevo.
Degradar con elegancia en lugar de fallar en seco
La razón por la que todo esto importa es que la llamada de red al servicio emisor nunca debería ser lo que tumbe a tu cliente. Un validate que agota el tiempo una vez, reintenta y tiene éxito es invisible. Un servicio que está genuinamente caído durante un minuto dispara el circuit breaker, y en lugar de que cada petición haga cola detrás de una conexión condenada, el breaker falla rápido y tus decisiones de puerta recurren al lease en caché del SDK — la misma ruta de validación en caché que evita que una breve caída bloquee a nadie. Cuando el servicio vuelve, el breaker se entreabre, una sonda tiene éxito y el tráfico se reanuda sin reinicio y sin intervención.
Probar el cableado
Puedes probar el registro y el comportamiento de resiliencia sin un servicio emisor en vivo intercambiando el handler primario por un stub. ConfigurePrimaryHttpMessageHandler sustituye el handler más interno dejando los handlers de resiliencia en su sitio, así que ejercitas el pipeline real.
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 segundo test apunta el stub a un 403 y comprueba que la llamada no se reintenta y aflora como un rechazo definitivo — esa es tu salvaguarda contra alguien que relaje el predicado ShouldHandle hasta que empiecen a reintentarse las revocaciones.
Esa es toda la forma de una integración correcta de Keyright en ASP.NET Core: un único registro de cliente tipado para que los handlers se agrupen y roten, un pipeline de resiliencia que reintenta las llamadas idempotentes y respeta las definitivas, y un lease en caché por debajo para que un hipo en tu servicio emisor cueste un reintento — nunca un cliente.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.