Idempotenzschlüssel für wiederholungssichere Lizenzoperationen
Ein Lizenz-Schreibvorgang, der in einen Timeout läuft, lässt Sie im Dunkeln: Wurde der Sitzplatz verbraucht oder nicht? Wiederholen Sie, riskieren Sie, einen Kreditpool doppelt zu belasten oder einen Sitzplatz zweimal zu verbrennen; geben Sie auf, haben Sie vielleicht eine Lizenz verkauft, die Sie nie geliefert haben. Das ist das Problem der verlorenen Antwort, auf das jeder vernetzte Lizenz-Client trifft, und die Lösung ist ein Idempotenzschlüssel, der einen At-least-once-Transport in Exactly-once-Effekte verwandelt. So bleiben Aktivierung, Verbrauchszählung, Ausstellung und Deaktivierung auch bei Wiederholungen gegen Ihre selbstgehostete Keyright-Instanz korrekt.
Die meisten Lizenz-Clients sind so geschrieben, als würde das Netzwerk entweder funktionieren oder sichtbar versagen. Es tut weder das eine noch das andere. Der Fehler, der Sie wirklich Geld kostet, ist der, den Sie nicht sehen können: eine Anfrage, die den Issuing-Service erreicht, ihre Arbeit getan hat — einen Sitzplatz verbraucht, einen Kreditpool belastet, eine Lizenz geprägt — und dann ihre Antwort auf dem Rückweg verloren hat. Eine abgebrochene TLS-Verbindung, ein Lese-Timeout des Reverse-Proxys, ein Client-Prozess, der mitten im Aufruf neu gestartet wurde: alle lassen den Aufrufer mit einem Timeout zurück, ohne jede Möglichkeit zu wissen, ob die Operation stattgefunden hat.
Wiederholen Sie, könnten Sie den Sitzplatz zweimal verbrauchen, oder die Minuten desselben Render-Jobs erneut belasten, oder eine zweite Lizenz für eine einzige Bestellung ausstellen. Geben Sie auf, haben Sie vielleicht einem Kunden eine Lizenz berechnet, die Sie nie geliefert haben. Das ist das Problem der verlorenen Antwort, und es ist jeder Operation eigen, die ihren Zustand über einen unzuverlässigen Transport ändert. Die Lösung ist kein besseres Netzwerk. Sie ist ein Idempotenzschlüssel: ein vom Client gewählter Bezeichner, der es dem Server erlaubt, eine Wiederholung als dieselbe logische Operation zu erkennen und das ursprüngliche Ergebnis erneut auszuspielen, statt es ein zweites Mal auszuführen.
Die Mehrdeutigkeit, veranschaulicht
Betrachten wir eine Verbrauchszählung gegen Ihre selbstgehostete Keyright-Instanz. Der Client sendet die Zählung, der Service belastet den Pool und committet, und dann kommt die Antwort nie an.
Die zweite Anfrage ist Byte für Byte die erste, einschließlich ihres Idempotency-Key. Weil der Server das Ergebnis unter diesem Schlüssel festgehalten hat, als er die Belastung das erste Mal committete, belastet er nicht erneut — er gibt das gespeicherte MeterResult zurück. Der Transport hat die Anfrage zweimal zugestellt; der Pool hat sich einmal bewegt. Das ist der ganze Vertrag: At-least-once-Zustellung, Exactly-once-Effekt.
Die Aktivierung ist bereits idempotent — durch ihre eigenen Eingaben
Bevor Sie überall zu Schlüsseln greifen, sollten Sie wissen, was Sie gratis bekommen. Die Keyright-Aktivierung ist idempotent pro (Lizenzschlüssel, Maschinen-Fingerprint). Dieselbe Schlüssel auf derselben Maschine erneut zu aktivieren gibt die bestehende Aktivierung und ihr Lease zurück; sie verbraucht keinen zweiten Sitzplatz. Die Eingaben sind die Dedup-Identität, sodass das SDK ein abgelaufenes ActivateAsync von sich aus ohne jeden zusätzlichen Header wiederholen kann.
var client = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-app",
PublicKeyBase64 = config["Keyright:PublicKey"], // nur Verifikation, kein Geheimnis
ServiceUrl = config["Keyright:ServiceUrl"], // Ihre selbstgehostete Instanz
});
// Gefahrlos wiederholbar: das Paar (key, fingerprint) ist die natürliche Idempotenz-Identität.
LicenseInfo info = await Retry.OnTransient(() => client.ActivateAsync(userKey));
if (!info.IsValid)
return Gate.Deny(info.Reason); // fail closed bei echter Ablehnung, nicht bei einem Timeout
Die wichtige Disziplin hier ist, eine abgelehnte Aktivierung (Sitzplätze erschöpft, Schlüssel widerrufen — ein echtes LicenseInfo, das Sie respektieren und nicht wiederholen dürfen) von einem Transport-Fehler (Timeout, 503 — wiederholen) zu unterscheiden. Diese Trennung machen wir weiter unten präzise.
Die Operationen, die einen expliziten Schlüssel brauchen
Nicht jeder Schreibvorgang identifiziert sich selbst. Drei verbreitete Operationen sind absichtlich nicht durch ihre Eingaben idempotent, weil zwei identisch aussehende Anfragen üblicherweise zwei getrennte Effekte sein sollen:
- Verbrauchszählungen — zwei Aufrufe von
MeterAsync("render-minutes", 12)belasten normalerweise 24. Der Wiederholung einer einzelnen Zählung muss man sagen, dass es eine Wiederholung ist. - Ausstellung aus der Fulfillment-Automatisierung — Ihr Webhook-Handler prägt eine Lizenz, wenn eine Bestellung bezahlt wird. Ein erneut zugestellter Webhook darf keine zweite prägen.
- Deaktivierung — einen bereits freigegebenen Sitzplatz freizugeben sollte ein No-op sein, kein Fehler.
Für diese hängen Sie einen Idempotency-Key-Header an (das SDK stellt ihn dort als Parameter bereit, wo es relevant ist). Der Schlüssel ist ein stabiler Bezeichner der Geschäftsoperation, einmal gewählt und bei jeder Wiederholung dieser Operation wiederverwendet:
// Die ID des Render-Jobs IST der natürliche Schlüssel — eine Zählung pro Job, für immer.
MeterResult draw = await Retry.OnTransient(
() => client.MeterAsync(pool: "render-minutes", amount: job.Minutes, idempotencyKey: job.Id));
if (!draw.Allowed)
return Gate.Deny("Render-Minuten erschöpft. Laden Sie auf, um fortzufahren.");
Für eine durch Ihre eigene Automatisierung gesteuerte Ausstellung ist die Operation ein HTTP-POST an die Admin-API, und Sie setzen den Header selbst. Verwenden Sie die Bestell-ID, damit ein erneut zugestelltes Zahlungsereignis harmlos ist:
POST /admin/licenses HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_token}
Idempotency-Key: order-2026-5591
Content-Type: application/json
{
"product": "acme-app",
"edition": "pro",
"seats": 5,
"customer": "cust_8e21",
"entitlements": ["export", "api"]
}
Ein zweites POST mit Idempotency-Key: order-2026-5591 gibt die dieselbe Lizenz zurück, die der erste Aufruf erzeugt hat — dieselbe ID, dasselbe Schlüsselmaterial — ohne eine zweite Lizenz zu prägen. Ihr Fulfillment-Handler wird gefahrlos so oft aufrufbar, wie das vorgelagerte Commerce-System das Ereignis erneut zustellt.
Den Schlüssel richtig wählen
Der Schlüssel hat genau zwei Aufgaben, und bei beiden irrt man sich leicht:
- Gleich über die Wiederholungen einer Operation. Wenn Sie bei jedem Versuch eine frische
Guid.NewGuid()erzeugen, sieht jede Wiederholung wie eine neue Operation aus, und der Mechanismus tut nichts. Leiten Sie den Schlüssel aus der Geschäftsentität ab (job.Id,order.Id), oder erzeugen Sie einmal eine GUID, persistieren Sie sie neben der Operation und verwenden Sie sie bei jeder Wiederholung wieder — auch bei Wiederholungen nach einem Prozess-Neustart. - Unterschiedlich über wirklich verschiedene Operationen. Wenn ein Kunde legitim zwei Render-Jobs ausführt, braucht jeder seinen eigenen Schlüssel, sonst verschmelzen Sie zwei echte Belastungen zu einer. Die Geschäfts-ID gibt Ihnen das natürlich; eine gemeinsame Konstante nicht.
Eine nützliche Regel: Der Schlüssel sollte so dauerhaft sein wie die Absicht der Operation. Wenn die Absicht einen Absturz überlebt — Sie schulden diesem Kunden immer noch eine Lizenz — muss der Schlüssel den Absturz ebenfalls überleben. Das heißt, er gehört in Ihren eigenen Speicher (die Bestellzeile, den Job-Datensatz), geschrieben vor dem ersten Versuch.
Was der Server erzwingt, und warum es Sie kümmern sollte
Eine korrekte Idempotenz-Implementierung tut mehr, als eine Antwort zwischenzuspeichern. Zwei Verhaltensweisen sind für Sie als Aufrufer wichtig:
Der Request-Fingerprint muss übereinstimmen. Der Server hält einen Hash des Anfragerumpfs neben dem Schlüssel fest. Wenn eine zweite Anfrage mit demselben Idempotency-Key, aber einem anderen Rumpf eintrifft — etwa seats: 5 beim ersten und seats: 50 beim zweiten Mal — ist das ein Bug auf Ihrer Seite, keine Wiederholung, und der Service lehnt sie mit 409 Conflict ab, statt stillschweigend eine der beiden zu honorieren. Behandeln Sie ein 409 hier als „Sie haben einen Schlüssel für eine andere Operation wiederverwendet” und korrigieren Sie die Aufrufstelle; übertünchen Sie es niemals, indem Sie den Schlüssel rotieren.
Gleichzeitige Duplikate werden serialisiert. Wenn zwei Kopien derselben Anfrage zugleich unterwegs sind (ein Client hat wiederholt, bevor die Antwort des ersten Versuchs verloren ging, und beide treffen ein), lässt der Service die erste abschließen und beantwortet die zweite aus dem gespeicherten Ergebnis — oder, falls die erste noch läuft, gibt er ein wiederholbares Signal zurück, damit das Duplikat zurückweicht, statt parallel auszuführen. Sie müssen das nicht über Ihre eigenen Prozesse hinweg koordinieren; der Schlüssel tut es.
Eine Wiederholungsstrategie, die nur das Sichere wiederholt
Idempotenzschlüssel machen Wiederholungen sicher; sie entscheiden nicht, wann zu wiederholen ist. Kombinieren Sie sie mit einer Strategie, die Transportfehler wiederholt und geschäftliche Ablehnungen in Ruhe lässt. Mit Polly:
var transient = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions
{
MaxRetryAttempts = 4,
BackoffType = DelayBackoffType.Exponential,
UseJitter = true, // Wiederholungen streuen, Ansturm vermeiden
ShouldHandle = new PredicateBuilder()
.Handle<HttpRequestException>() // Verbindung abgebrochen
.Handle<TaskCanceledException>() // Timeout
.HandleResult<HttpResponseMessage>(r =>
r.StatusCode == HttpStatusCode.ServiceUnavailable // 503
|| r.StatusCode == HttpStatusCode.GatewayTimeout // 504
|| (int)r.StatusCode == 429), // gedrosselt: zurückweichen
})
.Build();
Die Linie, an der man festhält, ist diese: Wiederholen Sie 429, 503, 504 und rohe Verbindungsfehler; wiederholen Sie nicht 400, 401, 403, 404, 409 oder ein gültig-aber-abgelehntes LicenseInfo. Die erste Gruppe bedeutet „die Operation hat vielleicht stattgefunden oder nicht” — genau dort schützt Sie der Idempotenzschlüssel. Die zweite Gruppe sind endgültige Antworten; sie zu wiederholen hämmert nur den Service mit einer Anfrage, die weiterhin abgelehnt wird. Ein 409 von einem Idempotenz-Endpunkt ist besonders, wie erwähnt: es bedeutet Schlüssel mit einem anderen Rumpf wiederverwendet, was ein Code-Defekt ist, nichts zum Wiederholen.
Halten Sie schließlich das Gate bei Ablehnungen fail-closed und bei Transportfehlern, deren Wiederholungen Sie erschöpft haben, betriebsfähig. Eine Verbrauchszählung, die den Service nach vier Versuchen nicht erreichen kann, sollte auf das zwischengespeicherte Lease und sein Kulanzfenster zurückfallen — und nicht einen zahlenden Kunden wegen eines Aussetzers abweisen — während eine Zählung, die der Service aktiv abgelehnt hat (Pool leer), abgelehnt bleibt. Der Idempotenzschlüssel ist das, was die Wiederholungen dazwischen harmlos macht.
Checkliste
- Aktivierung und Revalidierung: stützen Sie sich auf die
(key, fingerprint)-Idempotenz; wiederholen Sie Timeouts direkt. - Verbrauchszählung, Ausstellung, Deaktivierung: hängen Sie einen aus der Geschäfts-ID abgeleiteten
Idempotency-Keyan (job.Id,order.Id). - Wählen Sie den Schlüssel einmal, persistieren Sie ihn mit der Operation, verwenden Sie ihn bei jeder Wiederholung wieder — auch nach einem Neustart.
- Erzeugen Sie niemals einen frischen Schlüssel pro Versuch; verwenden Sie niemals einen abgeschlossenen Schlüssel für eine andere Operation wieder.
- Wiederholen Sie nur
429/503/504/Verbindungsfehler; honorieren Sie4xxund ein abgelehntesLicenseInfoals endgültig. - Behandeln Sie ein
409 Conflictvon einem Idempotenz-Endpunkt als gleicher-Schlüssel/anderer-Rumpf-Bug an der Aufrufstelle. - Halten Sie Wiederholungen deutlich innerhalb des Schlüssel-Aufbewahrungsfensters des Servers.
Nichts davon zeigt sich auf dem glücklichen Pfad, und genau deshalb muss es eingeplant und nicht entdeckt werden. Der Transport wird einige Ihrer Lizenz-Schreibvorgänge mehr als einmal zustellen; mit einem Idempotenzschlüssel auf jedem zustandsändernden Aufruf bewegen sich Ihre Sitzplätze, Ihre Kreditpools und Ihre ausgestellten Lizenzen dennoch genau einmal.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.