Zum Hauptinhalt springen

Konsistenzmodell für Methoden

Diese Seite legt fest, was eine Methode über Transaktionen, Fehler, Reihenfolge und wiederholte Aufrufe annehmen darf und worauf sich der Aufrufer verlassen kann. Sie ist der Vertrag zwischen der Plattform, dem Autor eines Methoden-Handlers und dem Aufrufer einer Methode. Die praktische Anleitung steht in Methoden-Handler implementieren.

Stand

Das Wire-Format (Request, Response-Envelope, Fehlercodes) steht fest. Handler-SDK und Dispatcher sind freigegeben; Idempotenzschlüssel sind Teil der Plattform (siehe R8); asynchrone Methoden mit Operation-Handles sind freigegeben (siehe OD-5). Aussagen mit dem Vermerk Geplant beschreiben das vorgesehene Verhalten eines Teils, der noch nicht freigegeben ist. Punkte, die nicht entschieden sind, sind als Offene Entscheidung gekennzeichnet und am Ende dieser Seite gesammelt, zusammen mit den bisher getroffenen Entscheidungen.

Die eine Entscheidung hinter allem​

Eine Methode läuft außerhalb der Mongo-Transaktion des Requests, der sie aufgerufen hat.

Ein GraphQL-Request, der Daten ändert (zum Beispiel createDevice), läuft in einer MongoDB-Transaktion: Alle generischen Mutationen werden übernommen oder keine. Ein Methodenaufruf tritt dieser Transaktion nicht bei. Er wird über den Event Hub an einen Handler zugestellt, meist in einem anderen Dienst, und der Handler schließt seine Arbeit selbst ab (oder scheitert selbst). Auch ein Handler im Gateway-Prozess (In-Process-Handler) macht keine Ausnahme: Er bekommt ebenfalls eine eigene Arbeitseinheit.

Das ist Absicht. Eine Transaktion kann nicht über Dienste hinweg reichen, und ein Handler darf einen Request nicht für die Dauer einer langen Operation offen halten. Der Preis: Die Plattform macht einen Methodenaufruf und die Schreibvorgänge drumherum nicht atomar. Diese Seite beschreibt, was stattdessen gilt.

Die Regeln​

#RegelFolge
R1Keine gemeinsame Transaktion. Ein Handler tritt der Transaktion des Requests nie bei. Der Methodenkontext enthält keine Session und keine Transaktion.Ein Handler sieht keine nicht übernommenen Schreibvorgänge des aufrufenden Requests. Der Request kann ihn nicht zurückrollen.
R2Jeder Aufruf ist eine eigene Arbeitseinheit.Eine fehlschlagende Methode rollt frühere Schreibvorgänge des Requests nicht zurück. Ein fehlschlagender früherer Schreibvorgang verhindert keinen unabhängigen Methodenaufruf. Es gibt keine Atomarität über Aufrufe hinweg.
R3Der Handler verantwortet die Atomarität seiner eigenen Schreibvorgänge und antwortet erst mit Erfolg, wenn die Datenbank seine Schreibvorgänge bestätigt hat.Ein Aufruf ist so weit alles-oder-nichts, wie der Handler es umsetzt (Update eines Dokuments oder eigene Session für mehrere).
R4Kein automatischer Retry. Duplikate werden erkannt, wo es möglich ist, sonst METHOD_OUTCOME_UNKNOWN. Die Plattform sendet einen Aufruf nie erneut und führt keine Zustellung aus, die sie als mögliches Duplikat erkennt; Wiederholungen entscheidet der Aufrufer.Dieselbe fachliche Operation läuft nur dann zweimal, wenn der Aufrufer sie zweimal sendet (neue Invocation) – es sei denn, ein Idempotenzschlüssel wird verwendet (R8). Was die Plattform nicht erkennt, steht unter Grenzen.
R5Genau ein Envelope je Aufruf, mit zwei unsicheren Ausgängen. Der Aufrufer erhält ein CkMethodResponse. Das Ergebnis ist sicher, außer bei METHOD_TIMEOUT und METHOD_OUTCOME_UNKNOWN.Nach diesen beiden Codes muss der Aufrufer den Zustand lesen, bevor er erneut handelt.
R6Nach einem Erfolgs-Envelope sehen Lesevorgänge den übernommenen Zustand des Handlers.Ein Aufrufer, der auf das Envelope wartet und dann liest, sieht die Wirkung.
R7Keine Reihenfolge zwischen Aufrufen. Aufrufe derselben Methode können gleichzeitig, auf verschiedenen Handler-Instanzen und in beliebiger Reihenfolge laufen.Der Handler muss nebenläufigkeitssicher sein (optimistische Nebenläufigkeit oder atomare Updates).
R8Idempotenzschlüssel. Ein wiederholter Schlüssel innerhalb seiner Lebensdauer (standardmäßig 24 Stunden) liefert das erste Ergebnis, ohne erneut auszuführen. Jeder Ausgang, bei dem die Methode gelaufen sein kann, verbraucht den Schlüssel. Eine Methode mit execution.idempotent ignoriert den Schlüssel.Sichere Wiederholung für Methoden, die nicht doppelt laufen dürfen. Siehe R8.
R9Die Autorisierung wird zweimal geprüft – deklarativ im Gateway und erneut im Handler anhand des weitergereichten Tokens.Der Handler darf sich nicht darauf verlassen, dass das Gateway geprüft hat, und darf den informativen Aufruferdaten nicht vertrauen. Wie das Token geprüft wird: OD-10; welche Datenberechtigungen gelten: OD-12.

R1 – Was „außerhalb der Transaktion“ für den Handler bedeutet​

  • Der Methodenkontext enthält Mandant, Aufrufer, die Id der Ziel-Entität, das Abbruch-Token und die Frist. Er hat keine Datenbank-Session. Ein Unit-Test des SDK sichert das ab.
  • Ein Handler lädt das Ziel selbst. Zwischen der Prüfung im Gateway und dem Lesen im Handler kann die Entität geändert oder gelöscht worden sein. Der Handler autorisiert und validiert gegen das, was er liest, und antwortet mit METHOD_TARGET_NOT_FOUND, wenn die Entität weg ist.
  • Ein Handler läuft in einem eigenen Dependency-Injection-Scope. Er darf keine Dienste verwenden, die an den aufrufenden Request gebunden sind (HTTP-Kontext, Datenbank-Session oder Mandanten-Repository des Requests). Bei einem entfernten Handler ist das automatisch so; bei einem In-Process-Handler ist es eine Regel, die der Handler-Autor einhalten muss. Siehe Methoden-Handler implementieren.
  • Folge für Aufrufer innerhalb eines GraphQL-Requests: Eine Methode, die auf eine Entität zielt, die im selben Request angelegt oder geändert wurde, sieht diese nicht, weil der Request noch nicht übernommen ist. „Anlegen“ und „Methode auf der neuen Entität aufrufen“ nicht in einem Request kombinieren; das Gateway lehnt einen solchen Request ab, bevor etwas ausgeführt wird (Entscheidung OD-1 und OD-2).

R2 – Keine Atomarität über Aufrufe​

Alles, was die Plattform garantiert, gilt je Aufruf. Für einen Request mit mehreren Mutationen:

SituationErgebnis
Eine generische Mutation scheitert, nachdem eine Methode erfolgreich warDie Request-Transaktion rollt ihre generischen Schreibvorgänge zurück; die Wirkung der Methode bleibt.
Eine Methode scheitert, nachdem generische Mutationen angewendet wurdenDas Scheitern der Methode wird als Daten im Ergebnis gemeldet; die generischen Schreibvorgänge werden dadurch nicht zurückgerollt.
Zwei Methoden in einem Request, die zweite scheitertDie Wirkung der ersten Methode bleibt.

Methodenfehler werden immer als Daten gemeldet (ein Fehlercode im Ergebnis), nie als GraphQL-Fehler. Ein GraphQL-Fehler würde die Request-Transaktion abbrechen und benachbarte generische Mutationen verwerfen, was bei einem reinen Methodenfehler nicht gewollt ist. Ein Request enthält entweder generische Mutationen oder genau einen Methodenaufruf: Das Gateway lehnt eine Mischung und einen zweiten Methodenaufruf ab, bevor es etwas ausführt (Entscheidung OD-1 und OD-2). Die Zeilen oben beschreiben daher, was ein Aufrufer beobachten kann, wenn Requests nacheinander gesendet werden, und sie sind der Grund für die Regel.

Wenn eine fachliche Operation mehrere Schritte braucht, die gemeinsam gelingen oder scheitern sollen, ist sie eine Methode mit einem Handler, der die Schritte in seiner eigenen Transaktion ausführt – nicht mehrere Methodenaufrufe. Liegen die Schritte in verschiedenen Diensten, wird kompensiert.

R3 – Die eigene Atomarität des Handlers​

  • Ein Dokument: Ein einzelnes Update ist atomar.
  • Mehrere Dokumente: Der Handler öffnet eine eigene Session und Transaktion und übernimmt sie, bevor er antwortet.
  • Nie success antworten und danach schreiben. Das Erfolgs-Envelope bedeutet „übernommen“.
  • Kann der Handler nicht wissen, ob sein Schreibvorgang angewendet wurde (zum Beispiel Verbindungsabbruch während des Commits), antwortet er mit METHOD_OUTCOME_UNKNOWN, nicht mit METHOD_HANDLER_FAILED, damit der Aufrufer den Zustand prüft, statt anzunehmen, es sei nichts passiert.
  • Für die Datenbank erledigt das der Handler-Host selbst: Wird ein Schreibvorgang nicht rechtzeitig bestätigt, beantwortet er die Exception mit METHOD_OUTCOME_UNKNOWN und einer correlationId, auch wenn das Repository sie verpackt. Das gilt für einen Write-Concern-Fehler (die Repositories schreiben mit w:majority und einem wtimeout von 30 Sekunden; bestätigt die Mehrheit nicht rechtzeitig, kann der Schreibvorgang trotzdem auf dem Primary liegen) und für einen Commit, dessen Ergebnis der Datenbanktreiber als unbekannt meldet. Das Audit-Ereignis und die Metrik ck.method.calls tragen dasselbe Ergebnis. Ein Schreibvorgang, den die Datenbank abgelehnt hat (zum Beispiel ein doppelter Schlüssel), bleibt METHOD_HANDLER_FAILED. Fangen Sie diese Exceptions im Handler nicht ab. Ein Pipeline-Handler folgt derselben Regel: Der Adapter klassifiziert den fehlgeschlagenen Schreibvorgang mit demselben Klassifizierer, und der Controller antwortet METHOD_OUTCOME_UNKNOWN.
  • Die Frist ist eine Bitte aufzuhören: Der Handler prüft das Abbruch-Token, bevor er einen Schreibvorgang beginnt, und beginnt nach der Frist keinen mehr. Ein bereits begonnener Schreibvorgang kann trotzdem abgeschlossen werden.

R4 und R5 – Zustellung, Wiederholung und Ergebnis​

Zustellung. Ein Methodenaufruf ist eine Nachricht an eine Queue, die alle Handler-Instanzen dieser Methode teilen (Competing Consumers): Jede Nachricht erreicht genau eine Instanz. Die Nachricht ist mandatory: Ist keine Queue gebunden, gibt der Broker sie zurück, und der Aufrufer erhält sofort METHOD_HANDLER_NOT_AVAILABLE. Die Nachricht hat eine Lebensdauer in Höhe des Aufruf-Timeouts und wird vom Broker nicht persistiert, ein Aufruf, den niemand abgeholt hat, läuft also nicht später.

Kein Retry. Der Event Hub wiederholt fehlgeschlagene Nachrichtenverarbeitung für viele andere Endpunkte. Methoden-Endpunkte schalten das ab, weil eine wiederholte nicht idempotente Methode erneut laufen würde. Ein Handler wirft nie zum Bus: Jede Ausnahme wird zu einem Envelope (METHOD_HANDLER_FAILED mit Korrelations-Id).

Was das garantiert. Die Plattform sendet einen Aufruf einmal und nie von sich aus erneut (weder auf Aufruferseite noch auf Handlerseite ein Retry). Eine Zustellung, die der Broker als mögliches Duplikat kennzeichnet, und eine Invocation-Id, die die Handler-Instanz schon gesehen hat, werden nicht ausgeführt; der Aufrufer erhält METHOD_OUTCOME_UNKNOWN. Das ist keine Zusicherung „höchstens einmal“: Ein Duplikat mit neuer Invocation-Id oder eines, das ohne Kennzeichnung des Brokers auf einer anderen Handler-Instanz landet, wird nicht erkannt (siehe Grenzen). Mindestens-einmal-Verhalten baut der Aufrufer (Wiederholung) zusammen mit einem Idempotenzschlüssel (R8); beides zusammen ergibt effektiv einmal innerhalb der Lebensdauer des Schlüssels.

GarantieOhne IdempotenzschlüsselMit Idempotenzschlüssel
Eine Invocation wird ausgeführteinmal, oder gar nicht, wenn das Duplikat erkannt wird (siehe Grenzen)gleich
Eine fachliche Operation wird ausgeführthöchstens einmal je Aufruf des Aufrufers; eine Wiederholung führt sie erneut aushöchstens einmal innerhalb der Lebensdauer des Schlüssels
Der Aufrufer erfährt das Ergebnisgenau ein Envelope, oder METHOD_TIMEOUT / METHOD_OUTCOME_UNKNOWNgleich; eine Wiederholung liefert das gespeicherte erste Ergebnis, oder METHOD_OUTCOME_UNKNOWN, wenn der erste Ausgang unbekannt war

Ein Broker kann in seltenen Fällen eine Nachricht doppelt zustellen (zum Beispiel wenn eine Handler-Instanz nach dem Lesen und vor der Bestätigung stirbt). Dafür gibt es den Envelope-Code METHOD_OUTCOME_UNKNOWN („mögliche doppelte Zustellung, nicht erneut ausgeführt“). Welche Duplikate die Plattform erkennt und welche nicht, ist in OD-3 entschieden und unter Grenzen aufgelistet.

Was die Plattform mit einer Zustellung tut. Der Handler-Host prüft in dieser Reihenfolge und führt nur eine Zustellung aus, die beide Prüfungen besteht:

  1. Der Broker kennzeichnet die Zustellung als erneut zugestellt, oder der Bus wiederholt sie: nicht ausgeführt, METHOD_OUTCOME_UNKNOWN. Die Logzeile nennt Invocation-Id, Methode, Mandant und die Zustellinformation (Redelivered-Kennzeichen, Wiederholungsversuch, Zähler, Nachrichten-Id), nie die Parameter. Typischer Fall ist eine Handler-Instanz, die ihre Broker-Verbindung vor der Bestätigung verliert: Der Broker gibt die Nachricht an eine andere Instanz, und diese lehnt sie ab. Die erste Ausführung kann abgeschlossen sein.
  2. Die Instanz hat diese Invocation-Id schon gesehen: nicht ausgeführt, METHOD_OUTCOME_UNKNOWN. Die Instanz merkt sich eine Id bis zur Frist des Aufrufs plus 5 Minuten, höchstens 1 Stunde ab der Zustellung.

Ein Handler, der nach einem Seiteneffekt eine Ausnahme wirft, lief trotzdem genau einmal: Der Aufrufer erhält METHOD_HANDLER_FAILED, und der Bus führt die Methode nicht erneut aus.

Der Dispatcher sendet einen Aufruf einmal. Es gibt weder auf Senderseite einen Retry noch ein erneutes Senden: Ein Transportfehler endet als METHOD_TIMEOUT (keine Antwort) oder METHOD_HANDLER_NOT_AVAILABLE (der Broker gab die Nachricht zurück), nie als zweite Zustellung. Verliert die einzige Handler-Instanz während der Arbeit ihre Verbindung, geht die Nachricht mit der Queue verloren, und der Aufrufer erhält METHOD_TIMEOUT.

Grenzen: was nicht erkannt wird​

Die Plattform gibt keine Zusicherung „höchstens einmal“. Die Tabelle nennt jede Art von Duplikat mit der Antwort auf „erkennt die Plattform es?“ und der Entscheidung, die dafür zuständig ist (OD-3 für Zustellungen einer Invocation-Id, OD-4 für eine erneut gesendete Operation). Nur ein erkanntes Duplikat wird nicht ausgeführt; die anderen erreichen den Handler und laufen.

DuplikatErkanntWie oder warum nichtZuständig
Der Broker stellt eine Nachricht nach einer verlorenen Bestätigung erneut zu (Handler-Instanz gestorben, Verbindung abgebrochen, Bestätigung später als der Consumer-Timeout des Brokers), an dieselbe oder eine andere Instanz, auch nach einem Neustart.JaDie Zustellung trägt das Redelivery-Kennzeichen des Brokers; der Handler-Host lehnt sie ab.OD-3
Dieselbe Nachricht erreicht dieselbe Handler-Instanz zweimal ohne Kennzeichen.JaDie Instanz merkt sich die Invocation-Id (bis zur Frist des Aufrufs plus 5 Minuten, höchstens 1 Stunde).OD-3
Dieselbe Invocation-Id erreicht eine andere Handler-Instanz ohne Kennzeichen.NeinDas Gedächtnis gesehener Ids gilt je Instanz, und es gibt keinen gemeinsamen Speicher. Kein Weg der Plattform erzeugt diesen Fall: Der Dispatcher sendet einen Aufruf nie erneut, und ein Requeue des Brokers trägt das Kennzeichen. Möglich ist er nur durch etwas außerhalb der Plattform, etwa eine Komponente, die Nachrichten verdoppelt, oder einen fremden Publisher am Bus.OD-3
Eine Handler-Instanz wurde neu gestartet, nachdem sie einen Aufruf ausgeführt hat, und erhält dieselbe Invocation-Id ohne Kennzeichen erneut.NeinDas Gedächtnis gesehener Ids übersteht keinen Neustart. Gleiche Anmerkung wie oben.OD-3
Der Aufrufer sendet dieselbe fachliche Operation erneut (Wiederholung nach Timeout, Doppelklick).NeinDas Gateway erzeugt für jeden Aufruf eine neue Invocation-Id, und keine API lässt einen Client sie wählen. Ein erneut gesendeter Aufruf ist daher eine neue Invocation, keine doppelte Zustellung. Nur ein Idempotenzschlüssel deckt ihn ab.OD-4

Späte Bestätigung (Consumer-Timeout des Brokers). Hält ein Handler eine Zustellung länger als den Consumer-Timeout des Brokers (RabbitMQ consumer_timeout, standardmäßig 30 Minuten), verliert er seinen Kanal: Der Broker schließt ihn und stellt die unbestätigte Nachricht als erneut zugestellt gekennzeichnet wieder in die Queue. Das ist die erste Zeile der Tabelle: Die Instanz, die die Nachricht erneut erhält, lehnt sie ab, und der Aufrufer erhält METHOD_OUTCOME_UNKNOWN, während die erste Ausführung noch läuft und ihre Wirkung übernimmt (dem Aufrufer wird „unbekannt“ gemeldet, obwohl der Aufruf einmal lief). Endet die erste Ausführung, findet ihre späte Antwort den Aufruf schon beantwortet vor und ändert nichts; nichts läuft doppelt. Die Instanz, die ihren Kanal verlor, nahm im Test keine weiteren Aufrufe an (CkMethodDispatcherBusTests); die übrigen Instanzen bedienen sie, ein solches Replikat ist daher neu zu starten. Den Consumer-Timeout des Brokers über der längsten Methoden-Frist halten (300 Sekunden): Ein Handler wird an seiner Frist beantwortet, der Fall braucht also einen niedrigeren Broker-Timeout oder einen Handler, der den Abbruch ignoriert.

Eine Methode, die nie doppelt laufen darf. Verlassen Sie sich nicht auf die Erkennung oben: Sie ist bewusst unvollständig und gibt kein „höchstens einmal“. Eine solche Methode wird mit einem Idempotenzschlüssel aufgerufen (R8) und schreibt idempotent (eine eindeutige Id oder ein bedingtes Update statt eines blinden Inserts oder Inkrements), sodass ein Duplikat, das durchrutscht, nichts verändert. Der Schlüssel schützt vor dem realistischen Duplikat, der erneut gesendeten Operation. Die Entscheidung fügt keinen Handler-seitigen Claim für Aufrufe mit Schlüssel hinzu; wann das nötig wird, steht unter OD-3. Wie viele abgelehnte Duplikate auftreten und warum, zeigt der Zähler ck.method.duplicate_refused (Methoden-Metriken).

Nach METHOD_TIMEOUT, METHOD_OUTCOME_UNKNOWN und METHOD_HANDLER_FAILED liest der Aufrufer den Zustand, bevor er erneut aufruft (R5).

Wie der Aufrufer das Ergebnis erfährt.

EnvelopeBedeutungAktion des Aufrufers
success: true, resultJsonDie Methode lief und wurde übernommen.Ergebnis verwenden.
success: true, operationEine asynchrone Methode wurde angenommen. Über den Abschluss ist nichts gesagt.Operation-Handle abfragen (retryAfterSeconds nennt den Zeitpunkt). Die Regeln dieser Seite gelten für die Arbeit hinter dem Handle.
success: false, deklarierter FehlercodeDie Methode lief und hat aus fachlichem Grund abgelehnt. Es wurde nichts geändert, sofern die Methode nichts anderes dokumentiert.Eingabe korrigieren oder den Benutzer informieren.
success: false, Plattform-Code, der sagt „Methode lief nicht“ (METHOD_HANDLER_NOT_AVAILABLE, METHOD_FORBIDDEN, METHOD_VALIDATION_FAILED, METHOD_TARGET_NOT_FOUND, METHOD_CONTRACT_VERSION_UNSUPPORTED, METHOD_REQUEST_IN_PROGRESS)Es wurde nichts geändert.Später wiederholen (nicht verfügbar, Version, Request läuft noch) oder die Ursache beheben.
METHOD_HANDLER_FAILEDDer Handler ist unerwartet gescheitert. Ob Teilwirkungen bleiben, hängt vom Handler ab: Ein Handler, der R3 einhält, hinterlässt keine.Korrelations-Id melden. Zustand prüfen, bevor eine nicht idempotente Methode wiederholt wird.
METHOD_TIMEOUTKeine Antwort rechtzeitig. Der Handler kann noch laufen oder schon fertig sein.Zustand lesen. Eine nicht idempotente Methode nicht blind wiederholen.
METHOD_OUTCOME_UNKNOWNMögliche doppelte Zustellung oder unbekannter Commit-Zustand.Zustand lesen.

Die vollständige Codetabelle mit Parametern steht im Wire-Vertrag; alle Codes sind sprachneutral: Auf der Leitung stehen ein stabiler Code und Parameter, nie ein Meldungstext.

Fristen und Timeouts​

  • Woher der Timeout kommt. execution.timeoutSeconds der Methodendefinition (1–300 Sekunden, Standard 15, wenn der Schlüssel fehlt; der Compiler weist andere Werte ab). Die Frist des Aufrufers ist jetzt plus dieser Timeout. Ein Gateway liest den Timeout aus der Construction-Kit-Definition und setzt die absolute Frist im Request; der Request trägt außerdem den Timeout in Sekunden, der im Parameter timeoutSeconds von METHOD_TIMEOUT zurückgemeldet wird.
  • Zur Frist. Das Abbruch-Token des Handlers wird zur Frist abgebrochen, und der Handler-Host antwortet METHOD_TIMEOUT. Der Dispatcher wartet eine kurze Karenzzeit länger als die Frist (Standard 2 Sekunden), damit die Antwort des Handlers zuerst eintrifft; kommt sie nicht (die Handler-Instanz ist weg oder die Nachricht ging verloren), antwortet der Dispatcher selbst METHOD_TIMEOUT. Ein Aufrufer hat seine Antwort also innerhalb von Frist + Karenzzeit.
  • Ein Handler, der sein Token ignoriert. Auf einen In-Process-Handler, der nicht auf das Token reagiert, wird nicht gewartet: Der Aufrufer erhält METHOD_TIMEOUT zur Frist, der Handler kann noch fertig werden, sein spätes Ergebnis wird verworfen. Bei einem entfernten Handler, der nicht auf das Token reagiert, antwortet der Dispatcher nach der Karenzzeit.
  • Ein Request, der nach seiner Frist ankommt, wird nicht ausgeführt; der Handler-Host antwortet METHOD_TIMEOUT.
  • Absurde Werte brechen keinen Aufruf. Eine Frist, die weiter weg liegt als der maximale Timeout des Dispatchers (Standard 10 Minuten), wird darauf gekürzt, bevor ein Filter oder ein Transport den Request sieht; der Handler sieht also ebenfalls die gekürzte Frist. Ein Timeout beliebiger Größe wird begrenzt, eine Frist in ferner Vergangenheit ist schlicht abgelaufen, und ein Handler-Host wirft nie wegen einer Frist, die ein anderer Sender schickt.
  • In-Process- und entfernte Handler verhalten sich gleich: gleiches Envelope, gleiche Begrenzung, gleiche Timeout-Antwort.

R6 und R7 – Sichtbarkeit und Nebenläufigkeit​

  • Read-your-method. Ein Aufrufer, der success erhalten hat und danach über die Plattform liest, sieht die übernommene Wirkung. Ein Aufrufer, der keine Antwort erhalten hat (Timeout), sieht sie möglicherweise noch nicht.
  • Keine Reihenfolge. Zwei Aufrufe, die ein Client nacheinander sendet, ohne die Antwort des ersten abzuwarten, können in beliebiger Reihenfolge, auf verschiedenen Instanzen, auch gleichzeitig laufen. Ein Client, der eine Reihenfolge braucht, wartet auf die Antwort des ersten Aufrufs.
  • Gleichzeitige Aufrufe auf einem Ziel (zwei Administratoren setzen dasselbe Passwort zurück, zwei Importe starten) sind Sache des Handlers: ein atomares Update mit Bedingung, eine Versionsprüfung oder ein Sperrdokument mit Lebensdauer. Der Verlierer erhält einen deklarierten Fehler (zum Beispiel OPERATION_ALREADY_RUNNING).
  • Mehrere Replikate eines Dienstes teilen sich den Verkehr einer Methode. Der Handler darf keinen Zustand früherer Aufrufe in Instanzfeldern halten; der nächste Aufruf kann auf einer anderen Instanz landen.

R8 – Idempotenzschlüssel​

Ein Request kann einen optionalen idempotencyKey tragen (in GraphQL das Argument idempotencyKey der Methoden-Mutation, siehe Idempotenzschlüssel). Ein Aufruf mit Schlüssel läuft innerhalb der Lebensdauer des Schlüssels höchstens einmal je Mandant, Methode, Aufrufer und Schlüssel; eine Wiederholung liefert das erste Ergebnis, ohne die Methode erneut auszuführen. Ein Aufruf ohne Schlüssel ist nicht betroffen: Es wird nichts gespeichert, und der Idempotenz-Schritt kostet nichts. Die folgenden Regeln sind die Entscheidung OD-4.

Wann ein Schlüssel gesendet wird. Bei jedem Aufruf einer Methode, die nicht doppelt laufen darf (ein zweiter Lauf würde die Mail erneut senden, erneut buchen, einen zweiten Datensatz anlegen). Eine Methode mit execution.idempotent: true kann ohne Schlüssel gefahrlos wiederholt werden, und die Plattform behandelt sie so: Ein an sie gesendeter Schlüssel wird angenommen und ignoriert. Der Aufruf berührt den Idempotenzspeicher nicht und läuft jedes Mal wie ein Aufruf ohne Schlüssel. Das heißt: keine Format- oder Längenprüfung des Schlüssels, keine Ablehnung wegen sensiblem Ergebnis oder fehlendem Fingerabdruck-Schlüssel, kein parameters-changed bei gleichem Schlüssel mit anderen Parametern, kein METHOD_REQUEST_IN_PROGRESS bei zwei gleichzeitigen Aufrufen und keine Wiedergabe (zwei Aufrufe mit demselben Schlüssel laufen beide). Audit und Metriken sehen den Aufruf wie jeden anderen: genau ein Audit-Ereignis und ein Zähler in ck.method.calls, nie als Wiederholung markiert. Eine Methode ohne dieses Kennzeichen (oder eine unbekannte Methode) behält das volle Verhalten, das unten beschrieben ist.

So verwendet ein Aufrufer ihn:

  • Einen Schlüssel je fachlicher Operation erzeugen (zum Beispiel beim Klick auf den Button), nicht je Versuch. Bei jeder Wiederholung derselben Operation denselben Schlüssel verwenden. Ein Schlüssel hat 1 bis 128 Zeichen.
  • Ein Schlüssel ist nur nach einem Aufruf wiederverwendbar, der nicht lief. Nach METHOD_HANDLER_NOT_AVAILABLE (und METHOD_CONTRACT_VERSION_UNSUPPORTED) lief die Methode nicht, und derselbe Schlüssel führt sie aus. Nach METHOD_REQUEST_IN_PROGRESS warten und denselben Schlüssel erneut senden. Nach einem Transportfehler ohne Antwort denselben Schlüssel erneut senden: Der Aufruf läuft entweder einmal, oder das erste Ergebnis wird geliefert.
  • Nach METHOD_TIMEOUT und METHOD_OUTCOME_UNKNOWN ist der Schlüssel verbraucht: Die Methode kann gelaufen sein, deshalb führt die Plattform sie unter diesem Schlüssel nie wieder aus. Zustand des Ziels lesen, dann für einen neuen Versuch einen neuen Schlüssel verwenden. Dasselbe gilt nach METHOD_HANDLER_FAILED.
  • Einen fachlichen Fehler nie unverändert wiederholen, mit oder ohne Schlüssel.

Was ein wiederholter Schlüssel bekommt, je nach Ausgang des ersten Aufrufs:

Erster AufrufDerselbe Schlüssel erneut
läuft noch (bis zur Frist des Requests plus Antwort-Karenz des Dispatchers, Standard 2 s)METHOD_REQUEST_IN_PROGRESS; die Methode läuft nicht. Denselben Schlüssel später senden.
war erfolgreich, wurde angenommen (Operation-Handle) oder endete mit einem Fehler, den die Methode deklariertdas gespeicherte erste Ergebnis, mit der Invocation-Id der Wiederholung; das Audit-Ereignis der Wiederholung nennt den ersten Aufruf als replayOf.
METHOD_HANDLER_FAILEDder gespeicherte Fehler; die Methode läuft nicht erneut. Der Schlüssel ist verbraucht: Zustand lesen und einen neuen Schlüssel verwenden.
METHOD_TIMEOUT, METHOD_OUTCOME_UNKNOWN, vom Aufrufer abgebrochen, oder der Anspruch wurde nie abgeschlossen (zum Beispiel weil das Gateway stehen blieb)METHOD_OUTCOME_UNKNOWN; der Schlüssel ist verbraucht.
nicht ausgeführt (METHOD_HANDLER_NOT_AVAILABLE, METHOD_CONTRACT_VERSION_UNSUPPORTED)der Schlüssel wird freigegeben: Die Wiederholung führt die Methode aus.

Ein Aufruf, den das Gateway ablehnt, bevor er den Dispatcher erreicht (METHOD_FORBIDDEN, METHOD_TARGET_NOT_FOUND, METHOD_PARAMETERS_TOO_LARGE, ein ungültiger Parameter), belegt nie einen Schlüssel und kann nach Behebung der Ursache mit demselben Schlüssel erneut gesendet werden.

Geltungsbereich. Ein Schlüssel ist die Kombination aus Mandant, Methode, Aufrufer und Schlüssel. Ein Benutzer wird über das sub des geprüften Tokens bestimmt, ein Service-Token (Client Credentials, ohne sub: eine Pipeline, ein Bot, das CLI mit Client Credentials) über client:<client_id>. Ein Benutzer und ein Client teilen sich daher nie einen Schlüssel, auch wenn das sub des Benutzers und die Client-Id dieselbe Zeichenkette sind; ein Token, dessen sub selbst mit client: beginnt, hat keinen Geltungsbereich und wird mit caller-unknown abgewiesen. Der Aufrufer stammt nie aus den informativen caller-Daten eines Requests. Zwei Aufrufer können denselben Schlüssel unabhängig voneinander verwenden. Das Audit nennt einen Service-Aufrufer mit seiner Client-Id ohne Präfix. Die Ziel-Entität gehört nicht zum Geltungsbereich, aber zum Parameter-Fingerabdruck: Derselbe Schlüssel auf einer anderen Entität gilt als andere Parameter. Autorisierung und Datenberechtigungsprüfung laufen, bevor der Schlüssel betrachtet wird; ein Schlüssel erweitert also keine Berechtigung, und ein nicht berechtigter Aufrufer erfährt nichts über gespeicherte Schlüssel. Der rohe Schlüssel wird nicht gespeichert, nur ein SHA-256-Hash der vier Teile.

Parameter-Fingerabdruck. Die Plattform vergleicht einen Fingerabdruck aus Typ, Ziel und kanonischen Parametern der Methode, berechnet aus den echten Werten, bevor sensible Parameter geschwärzt werden; zwei verschiedene neue Passwörter unter einem Schlüssel werden so unterschieden. Es ist ein Hash mit Schlüssel (HMAC-SHA-256); die Schlüssel-Id wird mitgespeichert. Wer die Datenbank oder ein Backup liest, kann daraus ohne das Geheimnis keinen Wert mit geringer Entropie wie ein Passwort ableiten. Eine Methode ohne sensible Parameter verwendet einen einfachen SHA-256, wenn kein Fingerabdruck-Schlüssel konfiguriert ist. Der Fingerabdruck wird nie protokolliert, auditiert oder zurückgegeben.

Ablehnungen. Alle sind METHOD_VALIDATION_FAILED mit field = idempotencyKey; die Methode läuft nicht, und nichts wird gespeichert.

reasonUrsacheWas zu tun ist
parameters-changedDer Schlüssel wurde schon mit anderen Parametern, einem anderen Ziel oder einem anderen Typ verwendet, oder sein gespeicherter Fingerabdruck lässt sich nicht prüfen (seine Schlüssel-Id ist nicht mehr konfiguriert).Für den neuen Request einen neuen Schlüssel verwenden.
result-sensitiveDas Ergebnis der Methode ist als sensitive markiert (oder die Plattform kennt die Methode nicht). Eine solche Methode lehnt einen Schlüssel ab: Das erste Ergebnis wiederzugeben hieße, ein Geheimnis in der Mandantendatenbank zu speichern.Ohne Schlüssel aufrufen; den Zustand lesen, um zu erfahren, ob der erste Aufruf lief.
caller-unknownDas geprüfte Token hat weder ein sub noch eine client_id, der Schlüssel hat also keinen Geltungsbereich.Den Aufruf authentifizieren.
key-too-longDer Schlüssel hat mehr als 128 Zeichen.Schlüssel kürzen.
fingerprint-key-missingEin Schlüssel wurde an eine Methode mit sensiblen Parametern gesendet, aber der Dienst hat keinen Fingerabdruck-Schlüssel (Aufgabe des Betriebs, siehe Idempotenzschlüssel betreiben).Den Betrieb fragen; bis dahin ohne Schlüssel aufrufen.
fingerprint-unavailableDer Dienst hat keine Fingerabdruck-Funktion für Aufrufe mit Schlüssel (die Idempotenz-Optionen sind im Host nicht registriert).Den Betrieb fragen.

Kann der Idempotenzspeicher nicht entscheiden (Datenbank nicht erreichbar, keine Zugangsdaten, unbekannter Mandant), wird der Aufruf nicht ausgeführt: METHOD_HANDLER_NOT_AVAILABLE mit reason = idempotency-store-unavailable. Die Methode lief nicht; später mit demselben Schlüssel wiederholen. Ein Aufruf ohne Schlüssel berührt den Speicher nie.

Idempotenzschlüssel betreiben​

Für den Betrieb des Dienstes, der das Methoden-Gateway hostet (das Asset Repository). Konfigurationsabschnitt Methods:Idempotency (appsettings oder Umgebungsvariablen mit dem Präfix OCTO_ und __ als Trenner, zum Beispiel OCTO_Methods__Idempotency__Ttl):

SchlüsselStandardBedeutung
Methods:Idempotency:Ttl24 StundenLebensdauer eines Schlüssels, gezählt ab seinem ersten Aufruf. Eine .NET-Zeitspanne (24:00:00). Höchstens 7 Tage (7.00:00:00): Ein größerer Wert wird darauf gekürzt und eine Warnung protokolliert. Null oder negativ lässt den Start des Dienstes scheitern. Ein geänderter Wert gilt nur für neue Schlüssel.
Methods:Idempotency:Fingerprint:Current:IdkeinerÖffentlicher Name des aktuellen Fingerabdruck-Schlüssels: 1 bis 64 Zeichen aus A-Z a-z 0-9 . _ -. Wird mit jedem Fingerabdruck gespeichert.
Methods:Idempotency:Fingerprint:Current:SecretkeinerDas Schlüsselmaterial: Base64 von mindestens 32 Zufallsbytes (zum Beispiel aus openssl rand -base64 32).
Methods:Idempotency:Fingerprint:Previous:Id / :SecretkeinerDer Schlüssel der Rotation davor; wird nur verwendet, um bereits gespeicherte Fingerabdrücke zu prüfen.
  • Das Geheimnis ist ein Geheimnis der Umgebung. Platform Ops stellt es je Umgebung bereit (Vault und ein geheimer Helm-Wert); es gehört nie in eine eingecheckte Datei, ein Ticket oder ein Log. Jedes Replikat des Dienstes muss dieselben Schlüssel halten, sonst wirkt eine Wiederholung, die auf einem anderen Replikat landet, wie geänderte Parameter. Die Schlüssel werden beim Start des Dienstes gelesen; eine Rotation braucht einen Rollout.
  • Ohne konfigurierten Current-Schlüssel werden Aufrufe mit Schlüssel an Methoden mit sensiblen Parametern abgelehnt (fingerprint-key-missing); Aufrufe mit Schlüssel an andere Methoden funktionieren mit einem einfachen SHA-256. Den Schlüssel konfigurieren, bevor Aufrufe mit Schlüssel auf einer gemeinsam genutzten Umgebung freigeschaltet werden.
  • Rotation. (1) Die Werte von Current nach Previous verschieben. (2) Ein neues Current mit neuer Id und neuem Geheimnis setzen. (3) Auf alle Replikate ausrollen. (4) Previous entfernen, nachdem mindestens die konfigurierte Ttl vergangen ist; ein Schlüssel, der noch in seiner Lebensdauer ist und unter einem entfernten Schlüssel fingerabgedruckt wurde, wird mit parameters-changed beantwortet. Die Ids müssen sich unterscheiden, und Previous ohne Current wird abgelehnt. Fehlerhafte oder halb konfigurierte Schlüssel lassen den Start des Dienstes scheitern; die Meldung nennt die Einstellung, nie den Wert.
  • Der Speicher ist die Mandantendatenbank. Die Collection MethodIdempotency jedes Mandanten hält ein Dokument je Schlüssel (Schlüssel-Hash, Zustand, Methoden-Id, erste Invocation-Id, Fingerabdruck mit Schlüssel-Id, die Zeiten und die erste Antwort). Sie ist Teil des Mandanten-Backups und der Wiederherstellung und wird mit dem Mandanten entfernt. Alle Replikate teilen sie. Abgelaufene Dokumente entfernt ein MongoDB-TTL-Index; Leser prüfen den Ablauf selbst, die Entfernung darf daher etwa eine Minute nachlaufen, ohne Wirkung.
  • Ein Mandant, der unter einer anderen Mandanten-Id kopiert wurde, trägt Zeilen, die kein Aufruf mehr erreicht, weil die Mandanten-Id Teil des Schlüssel-Hashs ist. Sie laufen von selbst ab; es muss nichts aufgeräumt werden.
  • Fail closed. Solange die Mandantendatenbank nicht verfügbar ist, werden Aufrufe mit Schlüssel mit METHOD_HANDLER_NOT_AVAILABLE (idempotency-store-unavailable) beantwortet; Aufrufe ohne Schlüssel sind nicht betroffen.
  • Gemischter Rollout. Ein Gateway-Replikat ohne das Argument idempotencyKey weist eine Abfrage, die es trägt, bei der Schemavalidierung ab; der Schlüssel wird nie stillschweigend ignoriert.

Audit: ein Ereignis pro Aufruf​

Ein Prüfer kann aus dem Ereignisprotokoll beantworten, wer welche Methode auf welcher Entität mit welchem Ergebnis aufgerufen hat. Die Plattform schreibt genau ein Audit-Ereignis pro Aufruf-ID, für jeden Transport (Bus und In-Process) und jedes Ergebnis:

  • Erfolg, einen deklarierten Geschäftsfehler, METHOD_HANDLER_FAILED, METHOD_TIMEOUT, METHOD_HANDLER_NOT_AVAILABLE und METHOD_OUTCOME_UNKNOWN;
  • einen von der Autorisierung abgelehnten Aufruf (METHOD_FORBIDDEN), obwohl der Handler nie lief, und einen Aufruf, den das Gateway ablehnt, bevor er den Dispatcher erreicht (verboten, unbekanntes oder nicht sichtbares Ziel, zu große oder ungültige Parameter);
  • einen Replay: Ein Aufruf, der aus dem Idempotenzspeicher beantwortet wird, ist ein eigener Aufruf mit eigener Aufruf-ID und eigenem Ereignis; das Ereignis nennt die erste Aufruf-ID als replayOf, nie den Idempotenzschlüssel. METHOD_REQUEST_IN_PROGRESS und die Ablehnung für einen Schlüssel, der mit anderen Parametern wiederverwendet wurde, werden mit ihrem eigenen Code erfasst und sind keine Replays;
  • eine Ausnahme in einem Pipeline-Filter: ein Ereignis mit METHOD_HANDLER_FAILED, der Aufruf wird wie bisher beantwortet;
  • ein Fehler des Gateways selbst, bevor der Aufruf die Pipeline erreicht (eine Ausnahme bei der Prüfung des Ziels, bei der Parametervalidierung oder in einem Dispatcher, der eine Ausnahme wirft): ein Ereignis mit dem Transport gateway und METHOD_HANDLER_FAILED; der Aufrufer erhält denselben Fehler wie ohne Audit;
  • einen Fehler des Dispatchers, bevor der Aufruf die Pipeline erreicht (zum Beispiel lässt sich die Methode nicht auflösen): Der Aufrufer erhält die übliche Antwort METHOD_HANDLER_FAILED und ein Ereignis mit demselben Ergebnis;
  • einen Abbruch durch den Aufrufer: ein Ereignis mit dem Ergebnis CALLER_CANCELLED, auch wenn der Aufrufer aufgibt, bevor der Aufruf die Pipeline erreicht hat. Die Methode ist möglicherweise gelaufen; prüfen Sie den Zustand des Ziels, bevor Sie erneut aufrufen.

Das Ereignis hat die Kategorie Method.Invocation und enthält Aufruf-ID, Mandant, Methoden-ID, Ziel, den Aufrufer (Subjekt und Name), den Transport (in-process, bus oder gateway für eine Ablehnung vor dem Dispatcher), die Handler-Instanz, das Ergebnis (SUCCESS, ACCEPTED für eine lang laufende Operation oder den Fehlercode), die Dauer und replayOf.

Ablehnungen durch das Gateway. Das Gateway beantwortet einige Aufrufe, bevor sie die Aufruf-Pipeline erreichen; der Audit-Filter sieht sie daher nie. Das Gateway erfasst jede dieser Ablehnungen über denselben Recorder, mit dem Transport gateway, der Aufruf-ID, die der Aufrufer erhalten hat, ohne Handler-Instanz und mit dem Fehlercode als Ergebnis:

AblehnungErgebnis
Der Aufrufer darf die Methode nicht aufrufen (Rollen, Scopes, allowSelf, unbekannte Methode, nicht authentifiziert)METHOD_FORBIDDEN
Die Parameter überschreiten Methods:MaxParametersBytesMETHOD_PARAMETERS_TOO_LARGE
Das Ziel existiert nicht oder der Aufrufer darf es nicht sehenMETHOD_TARGET_NOT_FOUND
Der Aufrufer sieht das Ziel, aber die Datenberechtigung verbietet den AufrufMETHOD_FORBIDDEN
Die Parameter passen nicht zur DeklarationMETHOD_VALIDATION_FAILED

Fehler des Gateways. Ein Fehler ist keine Ablehnung: eine Ausnahme in den eigenen Schritten des Gateways (zum Beispiel ist der Speicher nicht erreichbar, während das Gateway das Ziel lädt) oder in einem Dispatcher, der eine Ausnahme wirft. Das Gateway erfasst sie einmal, mit dem Transport gateway, der von ihm erzeugten Aufruf-ID, ohne Handler-Instanz und mit dem Ergebnis METHOD_HANDLER_FAILED, und wirft die Ausnahme dann weiter: Der Aufrufer erhält genau den Fehler, den er bisher erhielt. Die Plattform verwendet dafür kein eigenes Ergebnis: METHOD_HANDLER_FAILED ist der Code, den der Audit-Filter bereits für eine Ausnahme in der Pipeline schreibt; so findet eine Abfrage jeden unerwarteten Plattformfehler, und Metriken sowie die Audit-Stufe (Error) kennen genau diesen Code, während ein erfundener Code als invalid_code gezählt würde. Gelesen wird die Kombination: Transport gateway und keine Handler-Instanz bedeuten, dass der Fehler vor dem Erreichen eines Handlers auftrat; die Einzelheiten stehen im Dienstprotokoll unter der Aufruf-ID. Ob die Methode lief, lässt sich bei einem Dispatcher-Fehler allein aus dem Ereignis nicht sagen; den Zustand des Ziels prüfen, bevor erneut aufgerufen wird. Ein Aufruf, der die Pipeline erreicht hat, wird nie vom Gateway erfasst: Der Audit-Filter erfasst seinen Fehler, es gibt also kein zweites Ereignis.

Abbruch und Dispatcher-Fehler vor der Pipeline. Wer das Ende eines Aufrufs beobachtet, erfasst es, und nur dieser eine; so gibt es pro Aufruf-ID ein Ereignis und eine Zählung in ck.method.calls. Gibt der Aufrufer auf, während das Gateway noch das Ziel prüft, hat weder ein Filter noch der Dispatcher den Aufruf gesehen: Das Gateway erfasst ein Ereignis mit dem Transport gateway und CALLER_CANCELLED, und der Abbruch erreicht den Aufrufer wie bisher. Ist der Aufruf an den Dispatcher übergeben, erfasst ihn der Audit-Filter (bei einem Abbruch vor der Pipeline der Dispatcher) und das Gateway nicht. Scheitert der Dispatcher selbst, bevor die Pipeline läuft, antwortet er mit METHOD_HANDLER_FAILED als normale Antwort und erfasst ein Ereignis mit dem Transport des Aufrufs (bus, oder in-process, sobald der In-Process-Transport gewählt war) und ohne Handler-Instanz; das Gateway sieht eine Antwort, keine Ausnahme, und erfasst nichts weiter. Ein fehlgeschlagener Audit-Schreibvorgang ändert die Antwort des Aufrufs nie.

Ein Aufruf, der das Gateway passiert, wird nur vom Audit-Filter erfasst; es bleibt also bei genau einem Ereignis pro Aufruf-ID. Ablehnungen rund um den Idempotenzschlüssel (zu lang, mit anderen Parametern wiederverwendet, noch in Arbeit) entstehen innerhalb der Pipeline und werden vom Filter mit dem Transport des Aufrufs erfasst. Wie jedes Audit-Ereignis enthält ein Gateway-Ereignis keine Parameter, kein Token und keinen Idempotenzschlüssel. Kann das Audit-Ereignis eines abgelehnten Aufrufs nicht geschrieben werden, erhält der Aufrufer trotzdem die Ablehnung; der Fehler wird protokolliert und gezählt (ck.method.audit.failures).

Was nie erfasst wird: keine Parameter (auch keine geschwärzten), kein Ergebnis, keine Fehlerparameter, kein Zugriffstoken und keine anderen Zugangsdaten, kein Idempotenzschlüssel, kein Parameter-Fingerabdruck, kein Ausnahmetext. Das gilt unabhängig davon, ob Parameter als sensitive markiert sind.

Wenn das Audit nicht geschrieben werden kann. Standardmäßig lässt ein fehlgeschlagener Audit-Schreibvorgang den Methodenaufruf nie scheitern: Die Plattform protokolliert den Fehler und zählt ihn (ck.method.audit.failures). Jeder Schreibvorgang ist durch ein Timeout begrenzt (Methods:Audit:WriteTimeout, Standard 5 Sekunden), sodass ein hängender Ereignisspeicher keinen Aufruf aufhalten kann; ein Schreibvorgang, der in das Timeout läuft, gilt als fehlgeschlagen. Für regulierte Mandanten kann ein Betreiber das umkehren (Methods:Audit:FailCallOnAuditFailure für alle Mandanten, Methods:Audit:FailCallOnAuditFailureTenants für benannte Mandanten): Der Aufruf scheitert dann, wenn sein Audit-Ereignis nicht geschrieben werden konnte. Weil das Ereignis nach dem Aufruf geschrieben wird, ist die Methode möglicherweise schon gelaufen; die Antwort lautet daher METHOD_OUTCOME_UNKNOWN (Zustand des Ziels prüfen, bevor Sie erneut aufrufen). Ein Aufruf, der nicht ausgeführt wurde, etwa eine Ablehnung, behält seinen eigenen Ablehnungscode.

Seiteneffekte​

Ein Handler schreibt oft in die Datenbank und tut etwas anderes: eine Nachricht veröffentlichen, eine Mail senden, einen anderen Dienst aufrufen. Weil es keine gemeinsame Transaktion und keinen Retry der Plattform gibt, muss ein Handler die Reihenfolge ausdrücklich durchdenken.

Zuerst schreiben, nach dem Commit ankündigen. Nie ein Ereignis veröffentlichen oder eine Mail senden, bevor der Datenbank-Commit gelungen ist: Ein Rollback würde eine Nachricht über etwas hinterlassen, das nicht passiert ist.

Die Lücke nach dem Commit. Stirbt der Prozess zwischen Commit und Veröffentlichung, geht die Ankündigung verloren. Veröffentlicht der Handler zuerst und stirbt vor dem Commit, ist die Ankündigung falsch. Wählen Sie nach den Kosten des jeweiligen Fehlers und schließen Sie die Lücke dort, wo es zählt, mit einer Outbox:

MusterEinsatzUmsetzung
Commit, dann Veröffentlichung nach bestem BemühenDer Verlust der Nachricht ist vertretbar (Cache-Hinweis, neu berechenbare Benachrichtigung).Commit; veröffentlichen; bei Fehlschlag eine Warnung loggen.
OutboxDie Nachricht muss gesendet werden, wenn (und nur wenn) der Schreibvorgang übernommen wurde.Baut der Dienst selbst; die Plattform hat keine Outbox-Komponente (OD-6). In derselben Transaktion wie der fachliche Schreibvorgang ein Outbox-Dokument { id: invocationId, kind, payload, state: pending } einfügen. Ein separates Relay (ein Hintergrunddienst desselben Dienstes) liest offene Dokumente, veröffentlicht sie mit der Outbox-Id als Nachrichten-Id und markiert sie als gesendet. Das Relay darf doppelt senden, der Empfänger dedupliziert daher über die Id (er ist idempotent).
KompensationSchritte reichen über mehrere Dienste und können keine Transaktion teilen.Jeder Schritt hält seinen Zustand vor und nach der Ausführung fest. Scheitert Schritt n, führt der Handler die Umkehrung der Schritte n−1…1 aus (jede Umkehrung muss selbst wiederholbar sein) und meldet den Fehler mit einem deklarierten Fehlercode und Parametern, die den gescheiterten Schritt benennen. Scheitert eine Kompensation, wird sie für einen Operator festgehalten und mit METHOD_HANDLER_FAILED und Korrelations-Id geantwortet.
Idempotenter EmpfängerWas auch immer der Sender tut, der Empfänger muss ein Duplikat verkraften.Jeder Nachricht und jedem externen Aufruf eine stabile, aus der Invocation-Id abgeleitete Id geben und darüber deduplizieren.

Die Plattform liefert keine Outbox-Komponente (OD-6, entschieden: nur Anleitung). Bevor Sie eine bauen, prüfen Sie, ob Reihenfolge oder Kompensation die Lücke schließt; für jeden Fall, den die Plattform heute hat, tut es eines von beiden.

Reihenfolge: Ein Absturz muss einen sicheren Zustand hinterlassen. Setzen Sie einen idempotenten schützenden Schreibvorgang vor den riskanten und wiederholen Sie ihn danach. Beispiel: Das Ändern oder Zurücksetzen eines Passworts speichert den neuen Passwort-Hash, erneuert den Security-Stamp des Benutzers und widerruft seine Refresh-Tokens und Autorisierungen, drei getrennte Schreibvorgänge. Stirbt der Handler nach dem Schreiben des Passworts und vor dem Widerruf, ist das neue Passwort aktiv, während alte Refresh-Tokens bis zu ihrem Ablauf weiter eingelöst werden können. Die Regel: Die Tokens vor dem Schreiben des Passworts widerrufen und danach noch einmal. Ein Absturz an beliebiger Stelle hinterlässt dann höchstens die Tokens, die im Moment zwischen den beiden Widerrufen ausgestellt wurden, und eine Wiederholung schadet nicht, weil der Widerruf idempotent ist. (Liegen die Schreibvorgänge in derselben Datenbank, schließt eine Transaktion über alle die Lücke vollständig, siehe R3.)

Kompensation: Ein Abgleich-Job repariert, was ein Schritt nach bestem Bemühen verloren hat. Beispiel: Das Hinzufügen oder Entfernen eines Secrets eines Clients, der in Kind-Mandanten gespiegelt wird, übernimmt die Änderung zuerst am Client und aktualisiert danach die Spiegel als Schritt nach bestem Bemühen. Scheitert dieser Schritt, nachdem ein Secret entfernt wurde, bleibt das entfernte Secret in den Kind-Mandanten gültig. Der Handler wiederholt nicht; ein regelmäßiger Abgleich-Job (standardmäßig alle 5 Minuten) und der Endpunkt für die erneute Bereitstellung leiten jeden Spiegel neu aus seinem Quell-Client ab, sodass eine verlorene Aktualisierung von selbst heilt. Der Job muss idempotent sein und laufen können, während Handler schreiben: Jeder Schreiber der abgeleiteten Daten schreibt mit der Version, die er gelesen hat (ein Schreibvorgang ohne erwartete Version erhöht sie nicht), sonst kann ein langsamer Job einen älteren Stand zurückschreiben.

Commit, dann nach bestem Bemühen, wenn der Verlust von selbst heilt. Beispiel: die Nachricht, mit der andere Dienste nach einer Client-Änderung ihre zwischengespeicherten CORS-Einstellungen neu laden; eine verlorene Nachricht wird repariert, wenn der Cache abläuft.

Verhalten, das die Plattform bereits festlegt, braucht kein zusätzliches Muster: das Audit-Ereignis und der Abschluss eines Idempotenzschlüssels nach dem Handler.

Die Dauerhaftigkeit des Schreibvorgangs selbst ist kein Seiteneffekt, um den Sie sich kümmern müssen: Das Mandanten-Repository schreibt mit Write-Concern Majority (OD-7), ein übernommener Schreibvorgang hat also eine Mehrheit der Datenbank-Mitglieder erreicht, bevor der Handler antwortet.

Geheimnisse bleiben aus Seiteneffekten heraus: Sensible Methodenparameter (sensitive: true im Modell) dürfen nicht in Logs, Audit-Ereignisse, Traces, Outbox-Nutzdaten oder Fehlerparameter gelangen. Was die Plattform für Sie schwärzt und was nicht, steht unter Sensible Parameter und Filter.

Fehlerbeispiele​

Alle Beispiele verwenden die Methode User.ChangePassword (der Aufrufer ändert ein Passwort; siehe das durchgängige Beispiel). Der Handler schreibt den neuen Passwort-Hash und antwortet danach.

#Was passiertAufrufer siehtZustandRichtige Reaktion
1Handler stürzt nach dem Schreiben, vor der Antwort ab.METHOD_TIMEOUTDas Passwort ist geändert.Zustand lesen: Anmeldung mit dem neuen Passwort versuchen. Mit Idempotenzschlüssel ist der erste Aufruf verbraucht (unbekannter Ausgang): Eine Wiederholung mit demselben Schlüssel antwortet METHOD_OUTCOME_UNKNOWN; nach dem Lesen des Zustands einen neuen Schlüssel verwenden.
2Handler stürzt vor dem Schreiben ab.METHOD_TIMEOUTUnverändert.Wie 1 – der Aufrufer kann 1 und 2 am Envelope allein nicht unterscheiden. Zustand lesen.
3Handler wirft eine unerwartete Ausnahme.METHOD_HANDLER_FAILED mit correlationIdUnverändert, wenn der Handler R3 einhält; die Ausnahme steht im Handler-Log unter der Korrelations-Id.Id melden; später wiederholen.
4Die Frist läuft ab, während der Handler langsam ist. Das Token des Handlers wird zur Frist abgebrochen, und der Handler antwortet; der Dispatcher wartet eine kurze Karenzzeit (Standard 2 s) länger und antwortet dann selbst.METHOD_TIMEOUTDer Handler beginnt nach seiner Frist keinen Schreibvorgang; ein bereits laufender kann abschließen.Zustand lesen.
5Request kommt nach Ablauf der Frist an (Queue war gestaut).METHOD_TIMEOUTNicht ausgeführt.Mit neuer Frist wiederholen.
6Kein Handler läuft (Dienst down, noch nicht angekündigt).METHOD_HANDLER_NOT_AVAILABLE in unter einer SekundeNicht ausgeführt.Später wiederholen. Sicher, auch bei nicht idempotenten Methoden.
7Der Benutzer klickt doppelt. Zwei Invocations.Zwei Antworten; die zweite kann mit CURRENT_PASSWORD_INVALID scheitern, weil die erste das Passwort schon geändert hat.Einmal geändert, durch Zufall. Bei einer Methode ohne so einen natürlichen Schutz würde sie zweimal laufen.Button sperren, solange ein Aufruf offen ist; Idempotenzschlüssel verwenden (R8): Der zweite Klick liefert das erste Ergebnis.
8Der Broker stellt die Nachricht doppelt zu.Eine Antwort; das Duplikat antwortet METHOD_OUTCOME_UNKNOWN.Nicht erneut ausgeführt, solange das Duplikat erkannt wird (siehe Grenzen).Zustand lesen.
9Rolling Update: Ein neueres Gateway sendet eine neuere Wire-Vertragsversion an einen alten Handler.METHOD_CONTRACT_VERSION_UNSUPPORTEDNicht ausgeführt.Nach dem Update wiederholen.
10Der Aufrufer bricht den GraphQL-Request ab (Browser geschlossen), während der Aufruf läuft.Nichts (kein Client)Der Handler läuft zu Ende, solange seine Frist nicht abläuft.Keine – die Methode ist nicht an die Lebensdauer des Requests gebunden.
11Gemischter Request: createDevice zusammen mit einem Methodenaufruf in einem GraphQL-Request (oder zwei Methodenaufrufe).Das Gateway lehnt den gesamten Request ab, bevor es etwas ausführt.Nichts geändert: weder eine generische Mutation noch eine Methode lief.Die generischen Mutationen in einem Request senden und den Methodenaufruf in einem eigenen Request, nachdem der erste erfolgreich war. Siehe Entscheidung OD-1 und OD-2.
12Der Handler schrieb zwei Dokumente ohne Transaktion und stürzte dazwischen ab.METHOD_TIMEOUT oder METHOD_HANDLER_FAILEDHalb fertig.Fehler im Handler: verletzt R3. Transaktion oder Kompensation verwenden.

Entscheidungstabelle​

Zur Entscheidung, wie gebaut und wie aufgerufen wird.

FrageAntwort
Sieht mein Handler nicht übernommene Daten des Aufrufers?Nein (R1). Vor dem Aufruf übernehmen.
Darf ein Handler die Datenbank-Session des Requests verwenden?Nein (R1). Der Kontext hat keine; nicht zum Repository des Requests greifen.
Kann ich zwei Methodenaufrufe gemeinsam gelingen oder scheitern lassen?Nein (R2). Eine Methode daraus machen oder kompensieren.
Was, wenn der Handler mehrere Dokumente schreibt?Eigene Session und Transaktion, übernehmen, dann antworten (R3).
Was, wenn der Handler nicht weiß, ob er übernommen hat?METHOD_OUTCOME_UNKNOWN.
Wiederholt die Plattform einen fehlgeschlagenen Aufruf?Nie (R4). Eine Zustellung, die sie als mögliches Duplikat erkennt, wird nicht ausgeführt (METHOD_OUTCOME_UNKNOWN).
Darf ein Aufrufer wiederholen?Ja nach METHOD_HANDLER_NOT_AVAILABLE, METHOD_CONTRACT_VERSION_UNSUPPORTED (nichts lief). Nach METHOD_TIMEOUT, METHOD_OUTCOME_UNKNOWN, METHOD_HANDLER_FAILED nur nach Lesen des Zustands, oder wenn die Methode als idempotent deklariert ist. Mit Idempotenzschlüssel darf derselbe Schlüssel nach METHOD_HANDLER_NOT_AVAILABLE, METHOD_CONTRACT_VERSION_UNSUPPORTED und METHOD_REQUEST_IN_PROGRESS erneut gesendet werden; nach METHOD_TIMEOUT, METHOD_OUTCOME_UNKNOWN und METHOD_HANDLER_FAILED ist der Schlüssel verbraucht (nach dem Lesen des Zustands einen neuen verwenden).
Läuft ein doppelter Aufruf zweimal?Ja, außer es wird ein Idempotenzschlüssel verwendet (R8).
In welcher Reihenfolge laufen gleichzeitige Aufrufe?Undefiniert (R7). Auf die Antwort warten, wenn die Reihenfolge zählt.
Wann sehe ich die Wirkung eines Aufrufs?Nach dem Erfolgs-Envelope (R6).
Wann veröffentliche ich ein Ereignis oder sende eine Mail?Nach dem Commit. Darf es nicht verloren gehen: die Schreibvorgänge so ordnen, dass ein Absturz einen sicheren Zustand hinterlässt, oder einen Abgleich-Job reparieren lassen (Seiteneffekte); eine Outbox der Plattform gibt es nicht (OD-6).
Wohin gehört eine Wiederholungsschleife?In den Aufrufer, nicht in den Handler (der Bus wiederholt nicht).
Lang laufende Arbeit?Eine asynchrone Methode liefert nach der Annahme ein Handle; dieselben Regeln gelten für die Arbeit dahinter.

Offene Entscheidungen​

Punkte mit dem Vermerk Entschieden sind abgeschlossen; sie bleiben mit ihrer Begründung hier stehen. Die übrigen sind nicht entschieden: Der Text oben nennt ein Standardverhalten nur dort, wo sich die Plattform bereits definiert verhält, und jeder offene Punkt listet die Optionen; die Entscheidung trifft das zuständige Feature.

OD-1 – Sichtbarkeit nicht übernommener Request-Schreibvorgänge für eine Methode im selben Request​

Entschieden (OD-1 Option C, OD-2 Option A): eine Gateway-Regel für OD-1 und OD-2. Ein GraphQL-Request enthält entweder generische Mutationen oder genau einen Methodenaufruf. Ein Request, der generische Mutationen mit einem Methodenaufruf mischt oder eine zweite Methode aufruft, wird abgelehnt, bevor etwas ausgeführt wird: Weder eine generische Mutation noch eine Methode läuft. Das war die frühere Empfehlung („höchstens eine Methode je Request“); sie löst zwei Probleme:

  • Eine Methode, die auf eine im selben Request angelegte oder geänderte Entität zielt, würde diese nicht finden, weil die Request-Transaktion nicht übernommen ist und die Methode außerhalb davon läuft (R1).
  • Bei mehreren Aufrufen in einem Request müssten Reihenfolge, Umgang mit einem Fehler in der Mitte und die Meldung von Teilergebnissen definiert werden; mit einem Aufruf je Request ist das Envelope dieses Aufrufs die ganze Antwort.

Die Alternativen waren, alle Methoden nach dem Commit des Requests auszuführen (Methoden sähen die generischen Schreibvorgänge, würden aber bei einem Fehler übersprungen und in anderer Reihenfolge als geschrieben laufen) und Methoden an ihrer geschriebenen Position außerhalb der Transaktion auszuführen (einfach, aber Seiteneffekte bleiben, wenn eine spätere Mutation scheitert). Beide lassen die Frage des Teilfehlers offen und wurden nicht gewählt.

Folgen für Aufrufer: die Entität in einem Request anlegen, die Methode im nächsten aufrufen. Mehrere Methodenaufrufe sind mehrere Requests; für sie gilt R7 (keine Reihenfolge, solange der Client nicht auf die Antwort wartet).

Entschieden (Option A): Asynchrone Methoden sind nicht ausgenommen. Eine Methode, die nur ein Operation-Handle zurückgibt, zählt wie jede andere Methode: ein Methodenaufruf je Request; mehrere Handle liefernde Aufrufe in einem Request werden abgelehnt.

Die Regel wird in der Validierungsphase des GraphQL-Requests durchgesetzt, bevor ein Resolver läuft; die Ablehnung ist ein Fehler mit dem Code ONE_METHOD_CALL_PER_REQUEST (Details). Der Code gehört zur GraphQL-Schicht, nicht zum Antwort-Envelope des Methoden-Wire-Contracts. Die Prüfung, ob eine Methode zählt, ist eine einzige Funktion; eine spätere Änderung der Regel beträfe nur diese Funktion.

OD-2 – Mehrere Methoden-Mutationen in einem Request​

Entschieden zusammen mit OD-1: Es gibt keine mehreren Methoden-Mutationen in einem Request. Ein zweiter Methodenaufruf wird vor der Ausführung abgelehnt (Fehler ONE_METHOD_CALL_PER_REQUEST), sodass Reihenfolge, Stoppen oder Weitermachen nach einem Fehler und eine Zusammenfassung des Teilfehlers nicht entstehen. Asynchrone Methoden sind nicht ausgenommen, siehe OD-1.

OD-3 – Doppelte Zustellung erkennen​

Entschieden (30.10.2026, Entscheidungsnotiz des Spikes, Odin). Option A, wie ausgeliefert. Der Handler-Host führt eine Zustellung nicht aus, die der Broker als mögliches Duplikat kennzeichnet, und ebenso keine Invocation-Id, die die Instanz schon gesehen hat (ein Speicher je Instanz); der Aufrufer erhält METHOD_OUTCOME_UNKNOWN. Es gibt keinen gemeinsamen Speicher für Invocation-Ids. Welche Duplikate das erkennt und welche nicht: Grenzen.

Gründe:

  • Das Gateway erzeugt die Invocation-Id für jeden Aufruf, und keine API lässt einen Client sie wählen. Ein erneut gesendeter Aufruf ist daher eine neue Invocation und Sache des Idempotenzschlüssels (OD-4). Ein Duplikat derselben Invocation-Id stammt nur vom Broker (Redelivery, gekennzeichnet) oder von einem fremden Publisher am Bus; auch den würde ein Claim-Speicher nicht aufhalten: Er nimmt einfach eine neue Id.
  • Ein gemeinsamer Claim für jeden Aufruf würde einem Dispatch-Pfad von etwa 1 ms eine Datenbank-Roundtrip hinzufügen, und jeder Handler-Host hinge von diesem Speicher ab.
  • Der Speicher des Idempotenzschlüssels wird am Gateway vor dem Senden der Nachricht befragt; er sieht deshalb keine zweite Zustellung derselben Invocation-Id.

Auslöser für eine Neubewertung (Option B'). B' ist ein Claim, den der Handler-Host nur für Aufrufe mit Idempotenzschlüssel nimmt und der das Dokument des Schlüssels wiederverwendet. Er ist definiert, aber nicht eingeplant. Er wird eingeplant, wenn eines davon eintritt:

  1. Eine doppelte Zustellung ohne Broker-Kennzeichen wird gemessen: Der Zähler ck.method.duplicate_refused (Methoden-Metriken) zeigt Ablehnungen mit dem Grund seen_id, während broker_flag flach bleibt, oder ein Test mit erzwungenen Fehlern zeigt es.
  2. Es wird eine Methode deklariert, die doppelte Ausführung nicht verträgt und keinen natürlichen eigenen Schutz hat.

Bis dahin verwendet eine Methode, die nie doppelt laufen darf, einen Idempotenzschlüssel und schreibt idempotent (siehe Grenzen).

Zuständig: Features für Methoden-Zustellung und Idempotenz.

OD-4 – Details des Idempotenzschlüssels​

Entschieden (30.10.2026, Entscheidungsnotiz des Spikes, Odin und Gerald). Die Regeln von R8, in sechs Zeilen plus zwei Sicherheitsentscheidungen:

#FrageEntscheidung
1Geltungsbereich eines SchlüsselsMandant, qualifizierte Methoden-Id, Aufrufer (vom Principal-Provider des geprüften Tokens, nie aus den informativen caller-Daten: das sub eines Benutzers, client:<client_id> eines Service-Tokens) und der Schlüssel. Als SHA-256-Hash gespeichert; der rohe Schlüssel liegt nicht ab. Das Ziel gehört nicht zum Geltungsbereich, sondern zum Fingerabdruck.
2Gleicher Schlüssel, andere ParameterAbgelehnt mit METHOD_VALIDATION_FAILED (field = idempotencyKey, reason = parameters-changed). Der Fingerabdruck deckt Typ, Ziel und kanonische Parameter ab und wird vor der Schwärzung berechnet.
3Gleicher Schlüssel, während der erste Aufruf läuftNeuer additiver Plattformcode METHOD_REQUEST_IN_PROGRESS (der Aufruf wird nicht ausgeführt; denselben Schlüssel später erneut senden). Kein Warten.
4Welche Ausgänge gespeichert werdenErfolg, Angenommen und von der Methode deklarierte Fehler werden gespeichert und wiedergegeben. Ein unbekannter Ausgang (Timeout, Ausgang unbekannt, ein im Lauf abgelaufener Anspruch) verbraucht den Schlüssel (METHOD_OUTCOME_UNKNOWN). Auch METHOD_HANDLER_FAILED verbraucht den Schlüssel, als gespeicherter Fehler: Der Aufrufer wiederholt mit einem neuen Schlüssel, die Methode läuft also nie versehentlich zweimal. Nur nicht ausgeführte Plattformcodes geben den Schlüssel frei.
5LebensdauerMethods:Idempotency:Ttl, Standard 24 Stunden, höchstens 7 Tage, Ablauf je Dokument mit einem TTL-Index als Aufräumhilfe.
6SpeicherDie Mandantendatenbank, Collection MethodIdempotency; Teil des Mandanten-Backups (nicht ausgenommen); fail closed.
G1Fingerabdruck sensibler Parameter (Option A)Ein HMAC mit Schlüssel, vor der Schwärzung berechnet, mit einem Konfigurationsgeheimnis, das alle Replikate teilen, und einem Slot für den vorherigen Schlüssel zur Rotation (Methods:Idempotency:Fingerprint:Current und Previous). Ohne konfigurierten Schlüssel wird ein Aufruf mit Schlüssel an eine Methode mit sensiblen Parametern abgelehnt (fingerprint-key-missing). Platform Ops stellt das Geheimnis je Umgebung bereit, bevor Aufrufe mit Schlüssel auf gemeinsam genutzten Umgebungen freigeschaltet werden.
G2Methoden mit sensiblem Ergebnis (Option A)Eine solche Methode lehnt einen Schlüssel ab (reason = result-sensitive); nichts wird gespeichert. Zu überprüfen, wenn die erste solche Methode Idempotenz braucht (dann wahrscheinlich verschlüsselter Speicher).

Folgen, Verhalten und Betrieb: R8 und Idempotenzschlüssel betreiben.

OD-5 – Asynchrone Methoden​

Entschieden (18.10.2026): asynchron wird in der Methodendefinition deklariert (execution.mode: async, Standard sync). Es gibt kein Kennzeichen pro Aufruf; eine Methode ist für alle Aufrufer synchron oder asynchron. Der Modus gehört zum Aufrufvertrag (er ändert die Form der Antwort): Eine Änderung ist eine Major-Änderung, und ein Typ, der eine Interface-Methode mit einem anderen Modus erneut deklariert, wird abgelehnt. Bei einer asynchronen Methode begrenzt timeoutSeconds den Annahmeschritt (die Zeit bis zur Rückgabe des Handles), nicht die Operation.

Entschieden (07.11.2026, Entscheidungsnotiz des Spikes, Kommentar 6651539; Entscheidung in Kommentar 6651544, Odin): höchstens einmal nach der Annahme, ein dauerhafter Operationsdatensatz in der Systemdatenbank, 7 Tage Aufbewahrung, kein Abbrechen. Das Verhalten unten ist umgesetzt: der Operationsdatensatz, das Handler-SDK und der Sweep in der Methoden-Laufzeit der Plattform, das Handle und runtime.operations in der GraphQL-API (Asynchrone Methoden und Operationen); wie ein Handler einen Aufruf annimmt, beschreibt Asynchrone Handler.

#FrageEntscheidung
1Was garantiert „angenommen“?Höchstens einmal nach der Annahme. Der Operationsdatensatz wird dauerhaft geschrieben, bevor das Envelope „angenommen“ (das Handle) zurückgegeben wird. Die Arbeit startet einmal; die Plattform startet sie nie ein zweites Mal.
2Was passiert, wenn der Handler nach der Annahme verloren geht?Die Operation endet Failed mit METHOD_OUTCOME_UNKNOWN (Grund handler-lost). Sie wird nie erneut ausgeführt, auch nicht nach einem Neustart. Ob sie noch einmal laufen soll, entscheidet der Aufrufer, mit einem neuen Idempotenzschlüssel.
3Übersteht ein Handle einen Neustart, und wie lange wird es aufbewahrt?Das Handle übersteht Neustarts und Rolling Updates der Dienste. Es ist lesbar, solange die Operation läuft, und 7 Tage nach dem Abschluss (einstellbar von 1 Stunde bis 30 Tage). Danach, und für unbekannte oder fremde Ids, lautet die Antwort OPERATION_NOT_FOUND.
4Wo wird der Zustand der Operation gespeichert?In der Systemdatenbank, mit der Mandanten-Id als Pflichtteil jedes Schlüssels und jeder Abfrage. Nicht in der Mandantendatenbank: Ein Restore ersetzt die Mandantendatenbank und würde den Datensatz der Restore-Operation selbst löschen (oder wiederbeleben). Datensätze eines gelöschten Mandanten werden mit ihm gelöscht.
5Wer darf ein Handle lesen?Nur innerhalb des Mandanten der Route: der Aufrufer, der die Operation gestartet hat, und Mandanten-Administratoren. Aufrufer können ihre eigenen Operationen auflisten, damit eine Operation wiedergefunden wird, wenn die Antwort auf die Annahme verloren ging. Alle anderen erhalten dasselbe OPERATION_NOT_FOUND wie für eine unbekannte Id (kein Existenz-Orakel).
6Kann eine Operation abgebrochen werden?Nein, nicht in diesem Feature (außerhalb des Umfangs; bei Bedarf ein späteres Feature). Das bestehende Abbrechen der Job-Endpunkte bleibt bis dahin für die migrierten Job-Typen erhalten.
7Was liefert ein wiederholter Idempotenzschlüssel?Dieselbe Operations-Id wie der erste Aufruf, solange der Schlüssel lebt (R8); es wird keine zweite Operation gestartet. Die Aufbewahrung von 7 Tagen ist mindestens die maximale Lebensdauer eines Schlüssels, ein wiederholter Schlüssel liefert also nie ein abgelaufenes Handle.
8Welche Abfragemechanismen ersetzt das Handle?Das Job-Polling der Bot-Services, ein Job-Typ nach dem anderen: zuerst Dump, dann Restore und Archiv-Export/-Import. system/v1/jobs antwortet für die migrierten Job-Typen weiter und wird als veraltet markiert ([OctoRestDeprecated]) mit einem Sunset-Termin, der noch bekannt gegeben wird (entschieden, sobald die Umstellung umgesetzt ist, Gerald 2026-11-11; siehe Veraltete REST-Endpunkte); in diesem Feature wird es nicht entfernt.

Lieferstand der Punkte oben: 1–3, 5 und 7 sind wie entschieden umgesetzt; Punkt 7 gilt, solange Methods:Operations:Retention mindestens Methods:Idempotency:Ttl beträgt (die Standardwerte, 7 Tage und 24 Stunden, erfüllen das), und nicht für eine Methode mit execution.idempotent: true, die den Schlüssel ignoriert. Punkt 4: Der Datensatz liegt in der Systemdatenbank, und jeder Lesezugriff nennt den Tenant; Datensätze werden noch nicht gelöscht, wenn ihr Tenant gelöscht wird — sie laufen nach Abschluss mit der Aufbewahrungsdauer ab. Punkt 6: Es gibt kein Abbrechen. Punkt 8: Der Repository-Dump läuft als asynchrone Methode TenantRepository.Dump; Restore und Archiv-Export/-Import folgen, und mit ihnen die Abkündigung von system/v1/jobs.

Gründe: Nur diese Kombination ist mit der Regel „kein Retry“ (R4), dem gespeicherten Ergebnis „angenommen“ der Idempotenzschlüssel (R8) und OD-10 Option C vereinbar (der validierte Principal bleibt im Prozess und es wird kein Token gespeichert, eine neu gestartete Instanz kann die Arbeit also nicht im Namen des Aufrufers fortsetzen). Die Alternativen wurden verworfen: mindestens einmal nach der Annahme (eine dauerhafte Queue, die nach einem Neustart fortsetzt oder neu ausführt) braucht einen gespeicherten Principal oder ein Token und Handler, die eine erneute Ausführung vertragen, was Dump und Restore nicht tun; best effort (ein Handle im Speicher) verliert das Handle bei einem Neustart oder auf einer anderen Replica und verfehlt die Anforderung, dass Handles einen Neustart überstehen; der Job-Speicher der Bot-Services als Operationsspeicher würde das öffentliche Handle an ein Implementierungsdetail der Bot-Services und an deren Retry-Standardwerte koppeln.

Folgen für Aufrufer: Ein angenommener Aufruf bedeutet „dauerhaft erfasst und höchstens einmal gestartet“, nicht „wird irgendwann abgeschlossen“. Nach Failed mit handler-lost lesen Sie den Zustand des Ziels, bevor Sie die Operation erneut starten. Die Form des Handles im Envelope steht fest (Operations-Id, Annahmezeitpunkt, retryAfterSeconds, Ablauf).

Zuständig: Feature für asynchrone Methoden.

OD-6 – Outbox als Plattformkomponente​

Optionen: nur Anleitung (diese Seite), ein wiederverwendbarer Outbox-Helper im Handler-SDK oder ein plattformweiter Outbox-Dienst.

Entschieden (01.11.2026, Entscheidungsnotiz des Spikes, Kommentar 6629556; Entscheidung in Kommentar 6629611, Odin und Gerald): Option A, nur Anleitung. Die Plattform liefert keine Outbox-Komponente. Handler ordnen und kompensieren ihre Seiteneffekte wie unter Seiteneffekte beschrieben.

Gründe:

  • Keiner der sieben absehbaren Fälle braucht eine Outbox. Die Passwortänderung braucht Reihenfolge (Tokens vor und nach dem Schreiben des Passworts widerrufen), die gespiegelten Client-Secrets brauchen einen Abgleich-Job, und der Rest (CORS-Cache-Nachricht, Audit-Ereignis, Abschluss des Idempotenzschlüssels, Rollen- und Berechtigungsmethoden mit einem einzigen Schreibvorgang) ist Reihenfolge oder bereits festgelegtes Verhalten.
  • Ein Helper im Handler-SDK (etwa drei Tage) bringt ein Relay mit Leases, eine Outbox-Collection je Mandant und einen At-least-once-Vertrag, den jeder Empfänger einhalten muss; ein plattformweiter Dienst würde Wochen dauern und fügt eine Komponente hinzu, von der jeder Handler abhängt. Beides lohnt sich ohne einen Fall, der es braucht, nicht.

Auslöser für eine Neubewertung. Die erste Methode, die eine Mail senden oder ein externes System aufrufen muss, wenn und nur wenn ihr Schreibvorgang übernommen wurde (heute sendet keine Methode eine Mail). Dann wird der Helper (Option B) zuerst neben dieser Methode gebaut und danach verallgemeinert. Ein plattformweiter Outbox-Dienst (Option C) ist nicht geplant.

Zuständig: Handler-SDK.

OD-7 – Dauerhaftigkeit vor dem Erfolgs-Envelope​

Ob die Plattform einen bestimmten Datenbank-Write-Concern (zum Beispiel Majority) verlangt, bevor ein Handler Erfolg melden darf, oder die Standardwerte des Mandanten-Repositorys belässt.

Entschieden (01.11.2026, Entscheidungsnotiz des Spikes, Kommentar 6629557; Entscheidung in Kommentar 6629612, Odin und Gerald): Option A, die Standardwerte behalten und dokumentieren, dazu ein Schutztest.

  • Jeder Repository-Client für Mandanten und System setzt im Code den Write-Concern Majority mit einem wtimeout von 30 Sekunden und den Read-Concern Majority. Die Werte kommen nicht aus der Konfiguration, und eine Verbindungsoption kann sie nicht abschwächen. Das Journaling folgt dem Replica-Set (writeConcernMajorityJournalDefault, MongoDB-Standard true), eine Bestätigung durch die Mehrheit heißt also, dass der Schreibvorgang im Journal einer Mehrheit der Mitglieder steht. Die eigene Transaktion eines Handlers (R3) erbt diesen Write-Concern.
  • Alle gemeinsamen Umgebungen laufen mit Replica-Sets aus drei Mitgliedern ohne Arbiter, Majority-Schreibvorgänge funktionieren also auch mit einem ausgefallenen Mitglied weiter. Ein lokaler Entwicklungs-Stack läuft mit einem Mitglied; Majority bedeutet dort dieses Mitglied.
  • Ein Unit-Test der MongoDB-Persistenzschicht hält alle drei Werte an den Einstellungen der echten Datenbank-Clients fest; er schlägt fehl, wenn sich einer davon ändert. Eine Änderung braucht eine neue Entscheidung an dieser Stelle.
  • Kosten: Lokal gemessen kostet Majority etwa 0,3 ms je Schreibvorgang mehr als w: 1 (das Warten auf das Journal); in einem Cluster mit drei Mitgliedern kommt ein Replikations-Roundtrip hinzu.

Gründe: Die Garantie ist für jeden Client bereits im Code gesetzt, das ist stärker als ein Konfigurations-Standardwert. Das Replica-Set beim Dienststart zu prüfen (Option B), braucht einen privilegierten Datenbankbefehl für einen Fall, den unterstützte Installationen nicht haben; Majority in jedem Handler je Schreibvorgang zu erzwingen (Option C), fügt Disziplin hinzu, aber keine Garantie.

Wird die Mehrheit nicht innerhalb der 30 Sekunden erreicht, meldet die Datenbank einen Write-Concern-Fehler, der Schreibvorgang wird auf dem Primary aber nicht rückgängig gemacht. Der Handler kann daher nicht wissen, ob der Schreibvorgang dauerhaft ist; das ist ein unbekanntes Ergebnis (R3), kein Fehlschlag.

Zuständig: Handler-SDK.

OD-8 – Isolation von In-Process-Handlern vom Request​

Der SDK-Test beweist, dass der Methodenkontext kein Session-Mitglied hat. Er kann nicht beweisen, dass ein In-Process-Handler kein Request-Repository auflöst, das die Session hält.

Entschieden: Ein In-Process-Handler läuft losgelöst vom Umgebungs-Ausführungskontext des aufrufenden Requests, in einem frischen Dependency-Injection-Scope, der keine Request-Session registriert, und das SDK ergänzt eine Laufzeitprüfung, die den Aufruf fehlschlagen lässt, wenn im Umgebungskontext noch eine Session aktiv ist (HasSession). Die Regel in Methoden-Handler implementieren bleibt Pflicht des Autors; Scope und Prüfung sorgen dafür, dass ein Verstoß laut fehlschlägt, statt stillschweigend der Request-Transaktion beizutreten. Die losgelöste Ausführung, die ausdrückliche Übernahme von Trace, Kultur und Logging-Scope sowie der Probe-Haken (AddCkInProcessAmbientStateProbe<TProbe>()) sind Teil des Handler-SDK (Meshmakers.Octo.Services.Methods); das Gateway registriert die Probe für seine Request-Session. Details: Methoden-Handler implementieren.

Zuständig: Handler-SDK, Gateway-Features.

OD-9 – Sensible Parameter in Pipeline-Handlern​

Entschieden: verbieten. Ein Pipeline-Handler erhält die Methodenparameter als Pipeline-Eingabe, und eine Pipeline-Ausführung speichert ihre Ein- und Ausgabe. Eine Methode mit mindestens einem sensitive-Parameter kann deshalb nicht execution.handler: pipeline deklarieren: Der Compiler lehnt die Kombination mit Meldung 132 ab (siehe Meldungscodes), sodass kein Mandant ein solches Modell ausführen kann. Methoden, die ein Geheimnis entgegennehmen, etwa das Setzen eines Passworts, sind Service-Handler. Der Pipeline-Handler lehnt eine solche Methode zur Laufzeit ebenfalls ab, als zweites Tor.

Die Alternative, die Kombination zu erlauben und die Werte in jeder Komponente zu schwärzen, die Pipeline-Daten berührt, wurde verworfen: Sie braucht für jeden Knoten einen lückenlosen Nachweis und müsste so erhalten bleiben. Sie bleibt als spätere Erweiterung möglich, falls ein konkreter Bedarf entsteht.

Dieselbe Regel gilt für ein sensibles Ergebnis: Das Modell markiert es mit sensitive: true am result (Sensible Ergebnisse), und der Compiler lehnt handler: pipeline für eine solche Methode mit Meldung 134 ab, weil der Ausführungsspeicher die Ausgabe behält. Die Schwärzung sensibler Ergebnisse in Audit-Ereignissen, Logs und Traces folgt mit der Methoden-Laufzeit; bis dahin nicht darauf verlassen.

Zuständig: Methodensicherheit, Pipeline-Handler.

OD-10 – Vertrauen in das Aufrufer-Token in Remote-Handlern​

Entschieden am 19.10.2026 (Option A mit vier Anpassungen). Der Bus ist pro Nachricht nicht authentifiziert, die caller-Daten eines Requests beweisen also nichts. Die Frage war, wie ein Remote-Handler erfährt, wer aufruft.

Optionen:

  • A. Weitergereichtes Token. Der Handler validiert das Access-Token, das der Request weiterreicht, mit denselben Einstellungen wie die HTTP-API seines Dienstes (Aussteller, Signaturschlüssel des Identity-Dienstes, Ablauf, Mandant, Scope).
  • B. Ein Token pro Aufruf. B1: Identity stellt ein kurzlebiges Token (rund 60 Sekunden) aus, gebunden an Aufruf, Methode und Ziel. B2: Der Dispatcher signiert es mit einem eigenen Schlüssel.
  • C. Ein gespeicherter Principal. Die Plattform behält den validierten Principal statt eines Tokens, für asynchrone Methoden.

Entscheidung: A für synchrone Methoden, mit vier Anpassungen:

  1. Eine optionale Audience-Einstellung Methods:Token:ValidAudiences. Die Plattform validiert die Audience an ihren HTTP-APIs nicht, daher gilt als Vorgabe leer = nicht validiert; ist sie gesetzt, muss eine der aufgeführten Audiences vorliegen.
  2. Service-Tokens (Client Credentials, ohne sub) werden über client_id akzeptiert, fail-closed.
  3. Keine Regel für übergeordnete Mandanten: Der Claim tenant_id muss dem Mandanten des Requests entsprechen. (Später eingeschränkt: Ein Benutzer-Token eines übergeordneten Tenants darf die Methoden für Backup, Wiederherstellung und Archivdaten eines Unter-Tenants aufrufen, siehe Administration durch den übergeordneten Tenant über CK-Methoden.)
  4. Ein abgelaufenes Token hat einen eigenen Grund, token-expired; der Code bleibt METHOD_FORBIDDEN, damit ein Client mit einem frischen Token wiederholen kann.

Teilentscheidungen:

  • Der Pipeline-Handler validiert das weitergereichte Token ebenfalls, statt den nicht authentifizierten Caller-Daten zu vertrauen. Der Aufrufer der Pipeline wird ausschließlich aus dem validierten Token gebildet, mit Vertrauensstufe stark; ein abgelehntes Token startet keine Pipeline.
  • Asynchrone Methoden verwenden in Phase 3 Option C: Der Principal bleibt im Prozess, es wird kein Token gespeichert, und asynchrone Methoden sind auf Bot-Job-Typen beschränkt (siehe OD-5).
  • B1 nur, wenn das Security-Review des Credential-Leak-Epics das Replay-Fenster des weitergereichten Tokens ablehnt. Wer das Token auf dem Bus empfangen darf, steht in OD-11.

Unberührt: der In-Process-Transport (der Prozess, der den Aufruf gestartet hat, hat den Aufrufer bereits authentifiziert), die Authentifizierung am Gateway auf dem GraphQL-Pfad und die Schwärzung von Tokens und sensiblen Parametern.

Was Option A in Kauf nimmt: Ohne Audience-Einstellung ist jedes octo_api-Token des Mandanten für einen Aufruf gültig, und ein Handler (oder wer die Methoden-Queue lesen kann) kann das weitergereichte Token bis zum Ablauf gegen die APIs des Mandanten wiederverwenden. Die Schritte und Einstellungen stehen unter Validierung des Aufrufer-Tokens.

Verantwortlich: Methodensicherheit.

OD-11 – Wer eine Methode auf dem Bus bedienen darf​

Entschieden am 23.10.2026: zuerst B0, dann B1 zusammen mit der Einschränkung des öffentlichen Broker-Ports; bis B0 live ist, gilt Option C.

Der Bus ist pro Nachricht nicht authentifiziert. Die Handler-Ankündigung speist nur das Registry des Dispatchers, das beratend ist; die Aufrufe selbst gehen an die Methoden-Queue. Wer diese Queue am Broker konsumieren kann, erhält daher die Parameter und das weitergereichte Aufrufer-Token jedes Aufrufs, der dorthin geroutet wird, ob er sich angekündigt hat oder nicht. Entscheidend für die Gefährdung ist also, wer Broker-Zugangsdaten mit Leserecht auf die Methoden-Queues hat, nicht, wer sich ankündigen darf.

Optionen:

  • A. Authentifizierte Ankündigung. Handler-Hosts kündigen sich mit einem Service-Token (Client Credentials) an, und das Registry akzeptiert nur Ankündigungen der für eine Methode erlaubten Clients. Das schützt das Registry (Verfügbarkeit), aber nicht die Queue.
  • B. Den Broker einschränken. B0: ein eigener Broker-Benutzer für Adapter und Edge-Standorte ohne Leserecht auf die Methoden-Queues. B1: TLS auf der Broker-Verbindung und kein öffentlicher unverschlüsselter Port. Ein eigener Virtual Host für die Methoden-Queues ist ein späterer Schritt.
  • C. Das Risiko für die aktuelle Phase akzeptieren und dokumentieren, mit einer erkennenden Kontrolle.

Entscheidung:

  1. Zuerst B0, dann B1 zusammen mit der Einschränkung des öffentlichen Broker-Ports. Option A ist spätere Härtung des Registry, nicht die Sicherheitskontrolle.
  2. Bis B0 live ist, gilt Option C: Das Risiko ist hier dokumentiert, und ein Alarm überwacht die Zahl der Consumer auf den Methoden-Queues.
  3. Keine Methode, die ein Passwort (oder ein anderes Geheimnis) trägt, darf auf einer gemeinsam genutzten Staging- oder Produktionsumgebung aktiviert werden, bevor B0 und die Port-Einschränkung ausgerollt sind. Entwicklung und Tests laufen auf lokalen und Testumgebungen mit Testkonten.
  4. Ein Token pro Aufruf (OD-10, Option B1) wird nur eingeführt, wenn das Security-Review das Replay-Fenster des weitergereichten Tokens nach B0 ablehnt. Das Fenster ist die Restlaufzeit des Tokens, standardmäßig 3600 Sekunden pro Client; das Urteil für die Produktion bleibt eine Annahme, bis die echten Laufzeiten pro Client gelesen sind.

Verantwortlich: Methodensicherheit, Plattformbetrieb.

OD-12 – Datenberechtigungen eines Methodenaufrufs​

Entschieden am 19.10.2026: Option A für Phase 3, Option B als Endzustand, Option C verworfen.

Ein Methodenaufruf auf einen Datensatz, den Datenberechtigungen schützen, darf kein Umweg um sie sein. Die Frage war, wo und wie die Regeln der Engine für Datenberechtigungen auf Methoden angewendet werden.

Optionen:

  • A. Prüfung am Gateway. Das Gateway des Asset Repository prüft die Datenberechtigung des Ziels mit dem einen Auswerter der Engine, vor dem Handler. Handler laufen weiter mit den Rechten des Dienstes.
  • B. A plus ein an den Aufrufer gebundener Handler. Das Handler-SDK gibt dem Handler zusätzlich einen Datenzugriff, der an den validierten Aufrufer gebunden ist, sodass jedes Lesen und Schreiben des Handlers wie das des Aufrufers gefiltert wird.
  • C. Keine Datenberechtigungen für Methoden in Phase 3. Verworfen: Eine Methode auf einem geschützten Datensatz (ein Benutzer, ein Client) würde umgehen, was die generische Mutation durchsetzt.

Entscheidung: A für Phase 3 (eine öffentliche Prüfung in der Engine, der Gateway-Schritt, die Deklaration dataAccess), B als Endzustand (nicht eingeplant), C verworfen. Teilentscheidungen:

  1. Die Standard-Datenaktion einer Methode ist Write. Die optionale Deklaration authorization.dataAccess: Read ist additiv und lässt eine abfrageartige Methode mit einem Leserecht passieren.
  2. allowSelf befreit nicht von der Prüfung der Datenberechtigung.
  3. Ein Ziel, das Datenberechtigungen vor dem Aufrufer verbergen, wird mit METHOD_TARGET_NOT_FOUND beantwortet, nicht mit METHOD_FORBIDDEN. Die deklarierte Autorisierung läuft vorher und bleibt für ein vorhandenes und ein fehlendes Ziel identisch.
  4. Reihenfolge: authentifizieren, deklarierte Autorisierung, Ziel laden, Prüfung der Datenberechtigung, zustellen.

Unberührt: die deklarierte Autorisierung (Rollen, Scopes, octo_api, Default-Deny), die generischen Mutations- und Lesepfade, die Guards für Stream Data und Dateien.

Folge für Modelle: Ein Benutzer, dessen Rolle keine Datenberechtigung auf die Benutzerdatensätze hat, kann sein eigenes Passwort nicht ändern. Das Modell muss sie erteilen (durchgängiges Beispiel).

Die Regeln, wie sie gebaut sind, mit den Fehlerantworten: Datenberechtigungen und das Gateway-Tor.

Verantwortlich: Methodensicherheit.

Fehlercodes​

Die maßgebliche Tabelle (Code, Parameter, ob die Methode lief, Aktion des Aufrufers) ist Teil des Wire-Vertrags der Plattform; diese Tabelle fasst sie für Handler-Autoren zusammen.

CodeMethode lief?Typische UrsacheAktion des Aufrufers
METHOD_HANDLER_NOT_AVAILABLEneinKein aktiver Handler, Handler abgelaufen, Pipeline nicht deployt; oder der Idempotenzspeicher kann nicht entscheiden (reason: idempotency-store-unavailable)Später wiederholen (derselbe Idempotenzschlüssel darf erneut verwendet werden)
METHOD_TIMEOUTunbekanntKeine Antwort vor der Frist, oder der Request kam danach an (Parameter methodId, timeoutSeconds: der Timeout der Methode, aus dem die Frist abgeleitet wurde)Zustand lesen; eine nicht idempotente Methode nicht blind wiederholen
METHOD_FORBIDDENneinDer Aufrufer darf die Methode nicht aufrufen, die Datenberechtigung auf dem Ziel erlaubt die Aktion nicht (reason: data-permission), oder ein Remote-Handler hat das weitergereichte Token abgewiesen (reason: token-missing, token-expired, token-invalid, tenant-not-allowed, audience-mismatch)Nicht wiederholen; nach token-expired mit einem frischen Token wiederholen
METHOD_VALIDATION_FAILEDneinEin Parameter fehlt oder ist ungültig (Parameter field). Beim Idempotenzschlüssel: field = idempotencyKey mit reason parameters-changed, result-sensitive, caller-unknown, key-too-long, fingerprint-key-missing oder fingerprint-unavailable (R8)Korrigieren und erneut aufrufen; bei parameters-changed einen neuen Schlüssel verwenden
METHOD_TARGET_NOT_FOUNDneinZiel existiert nicht, oder Datenberechtigungen verbergen es vor dem Aufrufer (die Antwort ist identisch)Id prüfen
METHOD_HANDLER_FAILEDja, gescheitertUnerwarteter Handler-Fehler; Details nur im Handler-Log unter correlationIdId melden; vor einer Wiederholung Zustand lesen
METHOD_OUTCOME_UNKNOWNunbekanntMögliche doppelte Zustellung oder unbekannter Commit-ZustandZustand lesen
METHOD_REQUEST_IN_PROGRESSneinEin Aufruf mit demselben Idempotenzschlüssel (gleicher Mandant, gleiche Methode, gleicher Aufrufer) läuft noch; dieser Aufruf wurde nicht ausgeführtDenselben Schlüssel später erneut senden; dann wird das erste Ergebnis geliefert
METHOD_NOT_SUPPORTED_BY_HANDLER_VERSIONneinReserviert: Der Handler unterstützt die Methodenversion nicht–
METHOD_CONTRACT_VERSION_UNSUPPORTEDneinNachricht nutzt eine neuere Wire-Vertragsversion, als der Empfänger verstehtAuf das Rolling Update warten

Das Präfix METHOD_ ist für die Plattform reserviert; ein Modell deklariert eigene Codes ohne dieses Präfix (siehe Methodendefinitionen).

Siehe auch​