Skip to content
← Alle Beiträge
· Delta1 Labs LicensingKeyright

Das Keyright-SDK mit Resilienz in ASP.NET Core einbinden

Teams, die den Keyright-Client ad hoc instanziieren, laufen in einen der beiden klassischen HttpClient-Fehler: Socket-Erschöpfung durch einen Client pro Aufruf oder veraltetes DNS durch einen einzigen, dauerhaft gehaltenen statischen Client. Dieser Beitrag registriert den Keyright-Client über IHttpClientFactory als typisierten Client, damit Message-Handler korrekt gepoolt und rotiert werden, wählt die richtigen DI-Lebensdauern und legt eine Resilienz-Pipeline darüber — Timeout, Retry mit Jitter und einen auf einen Lizenzaufruf abgestimmten Circuit Breaker — sodass ein kurzer Aussetzer des Issuing-Service elegant degradiert statt hart zu scheitern.

Die meisten Keyright-Integrationen beginnen gleich: Jemand muss eine Lizenz gegen den selbstgehosteten Issuing-Service validieren, also schreibt er new HttpClient(), richtet ihn auf die ServiceUrl und liefert aus. In der Entwicklung und in der Demo funktioniert es. Dann geht es in Produktion und eines von zwei Dingen passiert.

Entweder wird der Client pro Aufruf erzeugt — ein frischer HttpClient innerhalb der Methode, die die Lizenz prüft — und unter echtem Verkehr gehen dem Prozess die Sockets aus. Jeder verworfene Client lässt Verbindungen für ein paar Minuten in TIME_WAIT zurück, der Bereich der ephemeren Ports füllt sich, und du beginnst SocketException: Only one usage of each socket address is normally permitted zu sehen. Oder jemand liest den Rat „verwende einen einzigen HttpClient wieder”, erstellt eine einzelne static-Instanz und hält sie für die Lebensdauer des Prozesses — was die Sockets behebt, aber das DNS einfriert. An dem Tag, an dem du deinen Issuing-Service verschiebst oder skalierst, wählt dieser statische Client weiterhin die beim Start aufgelöste Adresse an, lange nachdem sie verschwunden ist.

Beide Fehler stammen daher, den HttpMessageHandler von Hand zu verwalten. Die richtige Antwort in ASP.NET Core ist, damit aufzuhören und den Keyright-Client als typisierten Client über IHttpClientFactory zu registrieren, die den Handler für dich poolt und rotiert, und anschließend eine Resilienz-Pipeline darüberzulegen, damit ein kurzer Aussetzer des Issuing-Service elegant degradiert, statt einen zahlenden Kunden hart ausfallen zu lassen.

Kernaussage: Registriere den Keyright-Client mit AddHttpClient<IKeyrightClient, KeyrightClient>(), damit die Factory den zugrunde liegenden Handler poolt und rotiert — keine Socket-Erschöpfung, kein veraltetes DNS. Injiziere IKeyrightClient wie jeden anderen Service (der Wrapper ist Singleton-sicher; der HttpClient wird nicht für immer gehalten). Hänge AddStandardResilienceHandler() mit einem Timeout, Retry mit Jitter und einem auf einen Lizenzaufruf abgestimmten Circuit Breaker an — wiederhole das idempotente ValidateAsync/RefreshAsync, sei bei der Aktivierung vorsichtig — und falle auf die gecachte Validierung zurück, wenn der Service kurzzeitig nicht erreichbar ist.

Die beiden Antipattern, konkret

Hier ist die Socket-Erschöpfungs-Variante. Sie wirkt harmlos, weil jeder Client verworfen wird.

// 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 verwirft den Client, aber die TCP-Verbindung, die er geöffnet hat, bleibt ein paar Minuten in TIME_WAIT. Ein paar hundert Prüfungen pro Sekunde, und dir gehen die Ports aus. Das zweite Antipattern kehrt das Problem um:

// 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.

Dieses übersteht die Last und scheitert dann beim nächsten Infrastrukturwechsel lautlos. Keines irrt darin, dass HttpClient teuer zu erstellen und billig wiederzuverwenden ist — jedes hat halb recht, und die Hälfte, die ihnen fehlt, ist die Handler-Rotation.

App codecontroller / svcIKeyrightClienttyped clientresilience pipelinetimeout (per-attempt)retry + jitter (idempotent)circuit breakerpooled handlerrotates ~2 minissuingservicecached leaselocal Validate()network only on refresh — not the hot path

Keyright als typisierten Client registrieren

Die Korrektur ist eine einzige Registrierung beim Start. AddHttpClient<IKeyrightClient, KeyrightClient>() weist die Factory an, KeyrightClient mit einem HttpClient zu konstruieren, dessen Handler aus dem Pool stammt. Du konfigurierst den Client — Basisadresse, Timeout, Standard-Header — im Callback und die SDK-Optionen (Produkt, öffentlicher Schlüssel) über die üblichen 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

Zwei Details sind hier wichtig. Erstens nimmt KeyrightClient einen HttpClient in seinem Konstruktor — die Überladung des typisierten Clients löst den Rest seiner Abhängigkeiten aus der DI auf, sodass der öffentliche Schlüssel und das Produkt über KeyrightOptions einfließen. Zweitens wird das eigene HttpClient.Timeout des Clients absichtlich auf unendlich gesetzt: Wenn eine Resilienz-Pipeline angehängt ist, soll sie das Timeout pro Versuch besitzen, nicht das grobe Gesamt-Anfrage-Timeout, das in HttpClient eingebacken ist und einen langsamen ersten Versuch nicht von einem Retry unterscheiden kann.

Wenn du eine einzige Aufrufstelle bevorzugst, kapsle die Registrierung in einer Erweiterungsmethode, damit Anwendungen einfach AddKeyright(...) sagen:

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;
}

Jetzt passt das Ganze in builder.Services.AddKeyright(o => { o.Product = "acme-suite"; /* … */ });, und Konsumenten injizieren IKeyrightClient, ohne je einen HttpClient zu sehen.

Lebensdauern: warum der Wrapper Singleton-sicher ist, der Handler aber nicht

AddHttpClient<TClient>() registriert den typisierten Client standardmäßig als transient, und das ist Absicht. Das Client-Objekt selbst ist billig — es ist ein dünner Wrapper — und jede Instanz, die es dir übergibt, ist an einen HttpClient gebunden, den die Factory erzeugt hat. Das teure, langlebige Ding ist der HttpMessageHandler darunter, und die Factory hält einen Pool davon, rotiert jeden nach Ablauf seiner Handler-Lebensdauer (standardmäßig zwei Minuten), damit Verbindungen wiederverwendet werden, das DNS aber nicht veraltet.

Die praktische Regel: Löse IKeyrightClient dort auf, wo du ihn brauchst, und nutze ihn; erfasse nicht den HttpClient, den er umschließt, in einem Feld deines eigenen Singletons. Der Zustand des Keyright-Wrappers — der eingebettete öffentliche Schlüssel, das gecachte Lease, die zuletzt bekannte Lizenzedition — ist prozessweit und kann sicher als Singleton behandelt werden, weshalb KeyrightClient.Initialize(...) in Apps ohne DI ein langlebiges Objekt zurückgibt. In ASP.NET Core bekommst du dieselbe Ergonomie über die Factory, ohne einen Handler einzufrieren, weil das gecachte Lease im SDK lebt, nicht im 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() bedient die Gate-Entscheidung aus dem gecachten Lease, es ist also auf dem Hot Path in Ordnung. Der Netzwerkaufruf lebt nur in RefreshAsync, das du per Timer ausführst — nicht bei jeder Anfrage.

Die Resilienz-Pipeline, abgestimmt auf einen Lizenzaufruf

AddStandardResilienceHandler() gibt dir einen sinnvollen Standard-Stack: ein Gesamt-Anfrage-Timeout, eine Retry-Strategie, einen Circuit Breaker und ein Timeout pro Versuch, in dieser Reihenfolge. Die Standardwerte sind auf eine generische nachgelagerte API abgestimmt; für einen Lizenzaufruf willst du ein paar Stellschrauben anpassen.

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);
    });

Der Standard-Handler wiederholt nur bei transienten Bedingungen — Verbindungsfehler, HttpRequestException, Timeouts, 5xx und 408 — und nie bei einem 4xx. Dieser Standard ist für die Lizenzierung genau richtig: Ein 403 oder ein 409 vom Issuing-Service ist eine endgültige Antwort (widerrufen, Sitz entzogen, Produkt stimmt nicht überein) und darf nicht wiederholt werden, während ein 503 während eines rollierenden Deployments transient ist und wiederholt werden sollte.

Wenn du die Pipeline lieber von Hand baust — etwa um die Strategie pro Operation zu variieren — fügt sich Pollys ResiliencePipelineBuilder genauso ein:

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 darf wiederholt werden; die Aktivierung nicht

Das ist die eine Stelle, an der eine einzige Richtlinie für jeden Aufruf dich in Schwierigkeiten bringt. ValidateAsync und RefreshAsync sind idempotente Lesevorgänge — sie fragen den aktuellen Zustand ab und ändern nichts — daher ist der Retry eines abgelaufenen immer sicher. Die Aktivierung ist anders. Sie kann einen Sitz verbrauchen oder eine Maschine binden, daher riskiert ein blinder Retry eine Doppelzählung: Wenn der erste Versuch den Service tatsächlich erreicht hat und erfolgreich war, die Antwort aber auf dem Rückweg verloren ging, aktiviert ein Retry ein zweites Mal.

Registriere die Aktivierung auf einem eigenen benannten Client mit einer konservativeren Richtlinie und stütze dich auf einen Idempotency Key, den der Service dedupliziert:

// 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);

Mit dem Idempotency Key kann selbst der eine erlaubte Retry keinen Sitz doppelt verbrauchen: Der Service erkennt den wiederholten Key und gibt das ursprüngliche Ergebnis zurück, statt erneut zu aktivieren.

Elegant degradieren statt hart zu scheitern

Der Grund, warum all das wichtig ist: Der Netzwerkaufruf an den Issuing-Service sollte nie das sein, was deinen Kunden lahmlegt. Ein Validate, das einmal abläuft, wiederholt und dann gelingt, ist unsichtbar. Ein Service, der eine Minute lang wirklich ausgefallen ist, löst den Circuit Breaker aus, und statt dass jede Anfrage sich hinter einer zum Scheitern verurteilten Verbindung anstellt, scheitert der Breaker schnell und deine Gate-Entscheidungen fallen auf das gecachte Lease des SDK zurück — derselbe gecachte Validierungspfad, der verhindert, dass ein kurzer Ausfall irgendjemanden aussperrt. Wenn der Service zurückkehrt, öffnet sich der Breaker halb, eine Probe gelingt, und der Verkehr nimmt ohne Neustart und ohne Eingriff wieder auf.

Die Verdrahtung testen

Du kannst die Registrierung und das Resilienzverhalten ohne einen laufenden Issuing-Service testen, indem du den primären Handler gegen einen Stub tauschst. ConfigurePrimaryHttpMessageHandler ersetzt den innersten Handler und lässt die Resilienz-Handler an Ort und Stelle, du übst also die echte Pipeline.

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);

Ein zweiter Test richtet den Stub auf ein 403 und prüft, dass der Aufruf nicht wiederholt wird und als endgültige Ablehnung durchschlägt — das ist dein Schutz dagegen, dass jemand das ShouldHandle-Prädikat so weit lockert, bis Widerrufe wiederholt zu werden beginnen.

Das ist die ganze Form einer korrekten Keyright-Integration in ASP.NET Core: eine einzige Registrierung des typisierten Clients, damit Handler gepoolt und rotiert werden, eine Resilienz-Pipeline, die die idempotenten Aufrufe wiederholt und die endgültigen respektiert, und ein gecachtes Lease darunter, damit ein Aussetzer deines Issuing-Service einen Retry kostet — nie einen Kunden.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.