Methoden-Handler implementieren
Eine Methode wird in einem Construction-Kit-Modell deklariert. Ein Handler ist der Code, der läuft, wenn die Methode aufgerufen wird. Diese Anleitung zeigt, wie man einen Handler für jede der drei Arten schreibt, eine Methode zu behandeln, und welche Regeln jeder Handler einhält. Die Konsistenzregeln (Transaktionen, Fehler, Wiederholungen) stehen im Konsistenzmodell für Methoden; bitte zuerst lesen.
Der Wire-Vertrag (Request, Response-Envelope, Fehlercodes) steht fest. Das Handler-SDK, das diese Anleitung beschreibt (Meshmakers.Octo.Services.Methods, typisierte Handler, AddCkMethodHandlers), der Dispatcher, der In-Process-Transport und der Pipeline-Handler sind freigegeben; Aufrufer erreichen sie über die typisierten GraphQL-Methoden-Mutationen. Asynchrone Methoden mit Operation-Handles sind ebenfalls freigegeben: Ein Service-Handler kann einen lang laufenden Aufruf annehmen und seinen Fortschritt melden (siehe Asynchrone Handler und OD-5).
Drei Arten, eine Methode zu behandeln
| Entfernter Handler (Bus) | In-Process-Handler | Pipeline-Handler | |
|---|---|---|---|
| Deklariert durch | execution.handler: service (Standard) | execution.handler: service | execution.handler: pipeline |
| Läuft in | dem Dienst, der das Modell besitzt (zum Beispiel der Identity-Dienst für System.Identity) | dem Gateway (Asset Repository) selbst, für Methoden, die das Gateway besitzt (geplant: Tenant.*, Archive.*; noch keine produktiv) | einer Pipeline auf einem Mesh Adapter |
| Wie er erreicht wird | Event Hub, eine Queue je Methode, geteilt von allen Instanzen des Dienstes | direkter Aufruf im selben Prozess; nichts wird auf dem Bus veröffentlicht | der Communication Controller startet die deployte Pipeline, deren Well-known-Name der qualifizierten Methoden-Id entspricht |
| Sie schreiben | eine Handler-Klasse | dieselbe Handler-Klasse, als In-Process registriert | eine Pipeline, die mit SetPipelineExecutionResult endet |
Unabhängig vom Transport sind Request und Response-Envelope, die sprachneutralen Fehlercodes, die Frist, der Timeout, die Konsistenzregeln, Autorisierung und Audit gleich. Der Aufrufer kann die Transporte nicht unterscheiden: Er erhält immer ein CkMethodResponse.
Der Dispatcher
Aufrufer sprechen nicht selbst mit einer Queue. Das Gateway, ein Job oder eine Pipeline ruft den Dispatcher (ICkMethodDispatcher) auf. Er bestimmt den Handler, führt den Aufruf durch die Invocation-Pipeline (Audit, Autorisierung, Idempotenz) und liefert eine CkMethodResponse. Er wirft bei einem fehlschlagenden Aufruf nie eine Ausnahme; nur ein Abbruch durch den Aufrufer wird weitergereicht.
- Die Queue des deklarierenden Elements. Eine Methode kann in einem abgeleiteten Typ nicht überschrieben werden, es gibt also genau einen Handler pro Methode: den des Elements, das sie deklariert. Ein Aufruf auf einen abgeleiteten Typ erreicht die Queue des Typs, der die geerbte Methode deklariert; ein Aufruf auf einen Typ, der ein Interface implementiert, erreicht die Queue des Elements, das die Interface-Methode deklariert. Sie registrieren einen Handler einmal für das deklarierende Element, und er bedient jeden Typ, der die Methode erbt oder implementiert.
- Zuerst In-Process. Hat der Dienst, in dem der Dispatcher läuft, einen In-Process-Handler für die Methode (siehe unten), erfolgt der Aufruf direkt im selben Prozess, und nichts wird auf den Bus veröffentlicht. Dasselbe gilt für eine Methode, die der Service selbst für den Bus hostet, wenn er sie über seine eigene REST-Fassade aufruft. Andernfalls sendet der Dispatcher den Aufruf an die Queue der Methode im Event-Hub. Für beide Transporte gilt dieselbe Invocation-Pipeline, ein Filter läuft also für beide.
- Das Senden ist mandatory und wird nie wiederholt. Ist keine Queue gebunden oder konsumiert niemand sie (Dienst down, noch nicht angekündigt, letztes Replikat gestoppt), gibt der Broker die Nachricht zurück, und der Aufrufer erhält sofort
METHOD_HANDLER_NOT_AVAILABLE(lokal binnen einer Sekunde), mit dem Namen der Methode und ohne Stacktrace. Der Dispatcher sendet nicht erneut und kennt keinen Retry auf Senderseite: Ein Transportfehler endet alsMETHOD_TIMEOUToderMETHOD_HANDLER_NOT_AVAILABLE, nie als zweite Zustellung. Ob wiederholt wird, entscheidet der Aufrufer (Wiederholungen); nachMETHOD_HANDLER_NOT_AVAILABLEist es immer sicher, weil nichts lief. - Ein Envelope. Erfolg, ein deklarierter Fehler und
METHOD_HANDLER_FAILEDkommen unverändert vom Handler an, egal welcher Transport den Aufruf bedient hat.
Gemeinsame Regeln
Diese gelten für jeden Handler, gleich welcher Transport.
- Den Aufrufer erneut prüfen. Der Bus ist intern und wird nicht je Nachricht authentifiziert. Der
callerim Request ist nur informativ. Autorisieren Sie anhand des weitergereichten Access-Tokens (Signatur, Aussteller, Ablauf, Mandant, Scope und, falls konfiguriert, Audience), nie anhand dercaller-Daten. Ein gefälschtercallerdarf keine Wirkung haben. Die Validierung übernimmt der Host, wenn der Dienst sich dafür entscheidet: siehe Validierung des Aufrufer-Tokens. - In dieser Reihenfolge prüfen: authentifizieren → autorisieren → nachschlagen → Parameter validieren → schreiben. Antworten Sie mit
METHOD_FORBIDDENmit demselben Text, egal ob das Ziel existiert, damit ein Aufrufer ohne Recht nicht nach Entitäten sondieren kann. - Den Datenzugriff selbst verantworten. Im Methodenkontext gibt es keine Session, und Sie dürfen keine suchen. Verwenden Sie keine Dienste, die an den aufrufenden Request gebunden sind: HTTP-Kontext, Mandanten-Repository des Requests, einen
UserManageroder Store, der seinen Mandanten aus dem HTTP-Request bestimmt. Außerhalb eines Requests fallen sie auf den System-Mandanten zurück und würden in die falsche Datenbank schreiben. Bestimmen Sie den Mandanten ausdrücklich aus dertenantIddes Requests, erzeugen Sie, was Sie brauchen, für genau diesen Mandanten und geben Sie es wieder frei. - Schreibvorgänge atomar machen und vor der Antwort übernehmen. Ein Dokument: ein atomares Update. Mehrere: eigene Session und Transaktion. Siehe R3.
- Die Frist beachten. Das Abbruch-Token wird zur Frist des Handlers abgebrochen. Prüfen Sie es, bevor Sie einen Schreibvorgang beginnen; beginnen Sie danach keinen mehr.
- Nie zum Bus werfen, nie wiederholen. Auch die Plattform wiederholt keinen Aufruf: Ein Handler, der nach einem Seiteneffekt eine Ausnahme wirft, lief genau einmal, und der Aufrufer erhält
METHOD_HANDLER_FAILED. Eine Zustellung, die der Broker als mögliches Duplikat kennzeichnet, und eine Invocation-Id, die die Instanz schon gesehen hat, erreichen Ihren Handler nie; der Aufrufer erhältMETHOD_OUTCOME_UNKNOWN. Was nicht erkannt wird, steht unter Grenzen; halten Sie einen nicht idempotenten Handler daher auch gegen dieselbe fachliche Operation sicher, die zweimal eintrifft. Geben Sie für jeden Ausgang ein Envelope zurück. Eine unerwartete Ausnahme wird zuMETHOD_HANDLER_FAILEDmit Korrelations-Id; der Stacktrace geht unter dieser Id ins Log, nie auf die Leitung. Das erledigt der Host für Sie; fangen Sie keine Ausnahmen ab, die die eigentliche Ursache verbergen würden. - Deklarierte Fehler sind Daten. Eine fachliche Ablehnung ist ein Code aus der
errors-Liste der Methode mit Parametern (Strings), nie freier Text für den Benutzer. Parameterwerte der Methode dürfen nicht in Fehlerparametern stehen. - Keine Geheimnisse in Logs. Als
sensitive: truemarkierte Parameter und das Access-Token werden nicht geloggt, nicht auditiert, nicht in Traces, Outbox-Nutzdaten oder Ausnahmemeldungen geschrieben. Loggen Sie Invocation-Id, Methoden-Id, Mandant und Ergebnis. Was die Plattform für Sie schwärzt, steht unter Sensible Parameter und Filter. - Kein Zustand in Instanzfeldern. Der nächste Aufruf kann von einer anderen Instanz bedient werden.
- Seiteneffekte nach dem Commit. Veröffentlichen oder senden Sie erst, wenn der Schreibvorgang übernommen wurde; verwenden Sie eine Outbox, wenn eine verlorene Nachricht nicht hinnehmbar ist (Seiteneffekte).
- Nebenläufigkeit vertragen. Zwei Aufrufe auf demselben Ziel können gleichzeitig laufen. Verwenden Sie ein atomares bedingtes Update oder eine Versionsprüfung.
Validierung des Aufrufer-Tokens (Remote-Handler)
Ein Request, der über den Bus ankommt, trägt neben den informativen caller-Daten das Access-Token des Aufrufers (CallerAccessToken). Der Bus ist pro Nachricht nicht authentifiziert, daher beweist nur das Token, wer aufruft. Ein Remote-Handler-Host validiert dieses Token, bevor die Parameter gelesen werden und bevor der Handler läuft, mit demselben Vertrauen wie die HTTP-API seines Dienstes. Die Entscheidung und ihre Alternativen sind als OD-10 festgehalten.
Der Dienst entscheidet sich einmal dafür:
builder.Services.AddCkMethodCallerTokenValidation(o => o.Authority = "<Authority der HTTP-API dieses Dienstes>");
Die Einstellungen stehen im Konfigurationsabschnitt Methods:Token. Ein gültiges Token erreicht den Handler als context.CallerPrincipal (Subjekt, Client-Id, Mandant, IsServiceToken). Ein Dienst, der sich nicht dafür entschieden hat, erhält CallerPrincipal == null, und es wird nichts validiert: Ein solcher Handler hat keinen verifizierten Aufrufer und muss Methoden abweisen, die einen brauchen. Der In-Process-Transport validiert kein Token; er läuft in dem Prozess, der den Aufrufer bereits authentifiziert hat, und gibt diesen Principal weiter. Die Mandantenregel (Zeile 6 unten) wendet er aber auf jeden In-Process-Aufruf mit Access-Token an, zentral und vor dem Handler, unabhängig vom Modus des HTTP-Mandanten-Gates: Ein Token eines anderen Mandanten wird mit tenant-not-allowed abgewiesen; nur ein Dienst-Token, dessen Client in TenantAuthorization:CrossTenantServiceClientIds steht, kommt durch, und ein Benutzer-Token eines anderen Mandanten nur für die Methoden für Backup, Wiederherstellung und Archivdaten eines direkten Unter-Tenants (beim System-Tenant jedes Tenants), siehe Administration durch den übergeordneten Tenant über CK-Methoden. Ein Principal, den ein Dienst für seinen eigenen Job selbst baut, trägt kein Access-Token und wird nicht geprüft; dieser Dienst steht für den Mandanten seiner Aufrufe ein. Ein In-Process-Handler, der über das Gateway aufgerufen wird, braucht keine eigene Mandantenprüfung.
Die Schritte
| # | Prüfung | Bei Fehler (METHOD_FORBIDDEN, Parameter reason) |
|---|---|---|
| 1 | Ein Token ist vorhanden. | token-missing |
| 2 | Signatur und Aussteller: Der Aussteller ist die Authority des Dienstes (mit abschließendem Schrägstrich), die Signaturschlüssel stammen aus dem Schlüsselsatz des Identity-Dienstes. Nur asymmetrische Algorithmen werden akzeptiert; none und HS* nie. | token-invalid |
| 3 | Ablauf, mit einer Uhrabweichung von 30 Sekunden. | token-expired (nur für ein sonst echtes Token; ein abgelaufenes und gefälschtes Token ist token-invalid, ein abgelaufenes Token eines anderen Mandanten tenant-not-allowed) |
| 4 | Audience, nur wenn ValidAudiences konfiguriert ist: Das Token trägt eine der aufgeführten Audiences. | audience-mismatch |
| 5 | Scope octo_api. | token-invalid |
| 6 | Mandant: Der Claim tenant_id entspricht dem Mandanten des Requests (ohne Beachtung der Groß-/Kleinschreibung). Der Claim allowed_tenants ist nur ein Hinweis zur Mandantenauswahl und wird nie herangezogen. Die einzige Ausnahme für übergeordnete Mandanten betrifft die Methoden für Backup, Wiederherstellung und Archivdaten, siehe Administration durch den übergeordneten Tenant über CK-Methoden. | tenant-not-allowed |
| 7 | Subjekt: Ein Benutzer-Token trägt sub. Ein Token ohne sub ist ein Service-Token (Client Credentials) und muss client_id tragen. | token-invalid |
Die Antwort nennt nie den Claim, der fehlgeschlagen ist, und gibt einem Fälscher damit nichts zum Abtasten. Der Handler wird nicht aufgerufen, und nichts wird geschrieben. Die Logzeile einer Ablehnung enthält den Mandanten, den Grund und eine interne Kategorie, nie das Token, einen Claim-Wert oder eine Schlüssel-Id. Kann der Host keinen Signaturschlüssel laden (Identity nicht erreichbar und nichts im Cache), wird der Aufruf mit METHOD_HANDLER_FAILED beantwortet: Der Aufrufer hat nichts falsch gemacht, und ein Token wird nie ohne verifizierte Signatur akzeptiert.
Service-Tokens
Jobs, Pipelines und andere Dienste rufen Methoden mit einem Client-Credentials-Token auf, das kein sub hat. Ein solches Token wird akzeptiert, wenn es client_id trägt und sein tenant_id dem Mandanten des Requests entspricht, oder wenn sein Client auf der Allow-List TenantAuthorization:CrossTenantServiceClientIds steht (dieselbe Liste wie für die HTTP-API). Die Validierung ist immer fail-closed: Die Modi LogOnly und Disabled der HTTP-Seite gelten nie. Das Subjekt des Principals ist die Client-Id.
Audience
Die Plattform validiert die Audience an ihren HTTP-APIs nicht, daher ist Methods:Token:ValidAudiences standardmäßig leer, und die Audience wird nicht geprüft. Bei leerer Einstellung wird jedes octo_api-Token des Mandanten für einen Methodenaufruf akzeptiert. Setzen Sie sie, sobald der Identity-Dienst Audience-bezogene Tokens ausstellt.
Abgelaufene Tokens
token-expired unterscheidet sich von den anderen Gründen, damit ein Client „frisches Token holen und erneut aufrufen“ von „nicht erlaubt“ unterscheiden kann. Der Code bleibt METHOD_FORBIDDEN. Ein Aufruf wartet in der Queue höchstens so lange wie sein Timeout (1 bis 300 Sekunden, Standard 15), ein beim Aufruf gültiges Token läuft also selten ab, während der Aufruf wartet.
Pipeline-Handler
Der Pipeline-Handler des Communication Controllers validiert das weitergereichte Token mit demselben Validator und bildet den Aufrufer der Pipeline ausschließlich aus dem validierten Principal, mit Vertrauensstufe stark; die caller-Daten des Requests werden nie verwendet. Ein Aufruf ohne gültiges Token wird mit METHOD_FORBIDDEN beantwortet (dieselben Gründe wie oben), und es wird keine Pipeline gestartet. Dafür ist kein Opt-in nötig: Der Controller übernimmt die Einstellungen seiner eigenen HTTP-API (Details). Ein Remote-Handler, der als Service-Handler geschrieben ist, erhält den validierten Principal vom Host, wie oben beschrieben.
Was das Token nicht schützt
Das weitergereichte Token ist für die APIs des Mandanten bis zum Ablauf gültig und wird an jeden zugestellt, der die Methoden-Queue konsumiert. Die Validierung schützt einen Handler vor einem gefälschten Aufrufer; sie schützt den Aufrufer nicht vor einem Empfänger am Broker. Wer die Queue konsumieren darf, wird am Broker entschieden und eingeschränkt, siehe OD-11, einschließlich der Regel, dass keine Methode, die ein Passwort trägt, auf einer gemeinsam genutzten Staging- oder Produktionsumgebung laufen darf, bevor der Broker eingeschränkt ist.
Durchgängiges Beispiel: User.ChangePassword
Die Methode ändert das Passwort eines Benutzers. Ein Benutzer ändert sein eigenes Passwort (und muss das aktuelle angeben); ein Benutzer mit der Rolle UserManagement setzt das Passwort eines anderen zurück (kein aktuelles Passwort nötig). Das Beispiel stammt aus dem Identity-Dienst; das Modell ist so gezeigt, wie es deklariert würde, und enthält keine echten Werte.
1. Die Methode im Modell
types:
- typeId: User
# ...
methods:
- methodId: ChangePassword-1
description: Changes (self service) or resets (administrator) the password of a user.
parameters:
- name: currentPassword
valueType: String
isOptional: true # required for self service, ignored for a reset
sensitive: true
- name: newPassword
valueType: String
sensitive: true
errors:
- code: PASSWORD_POLICY_VIOLATION
- code: CURRENT_PASSWORD_INVALID
- code: USER_LOCKED_OUT
authorization:
roles: [ UserManagement ]
allowSelf: true
execution:
timeoutSeconds: 15
idempotent: false # a second call with a new password is not the same as the first
Der Source-Generator erzeugt neben dem Modell die Id-Konstante SystemIdentityCkIds.UserChangePasswordMethodId (System.Identity/User.ChangePassword-1) und den Record UserChangePasswordParameters mit CurrentPassword und NewPassword. Beide Parameter sind sensitive: Das generierte ToString() gibt *** aus.
authorization wird im Gateway und vom Handler-Host geprüft: Die Deklaration sagt, wer aufrufen darf; bevor der Handler läuft, wertet der Host sie für den validierten Aufrufer erneut aus, mit demselben Evaluator wie das Gateway. Der Handler muss die deklarierte Prüfung nicht wiederholen.
Wo die Deklaration durchgesetzt wird. Die Plattform setzt authorization ohne Handler-Code an vier Stellen mit denselben Regeln durch: Das Gateway prüft, bevor es das Ziel lädt (GraphQL-Aufrufer); der Autorisierungsfilter der Aufruf-Pipeline (Band 200, AddCkMethodAuthorization() in Meshmakers.Octo.Services.Methods) prüft jeden Aufruf, der den Dispatcher erreicht – über den Bus und In-Process gleichermaßen – und ist die einzige Prüfung für Aufrufer, die nicht über das Gateway kommen (REST, Jobs, Pipelines); der Handler-Host wertet die Deklaration nach der Token-Validierung und vor dem Lesen der Parameter für den validierten Aufrufer aus, im Remote-Host und im In-Process-Host gleichermaßen: Ein gültiges Token des Mandanten, das direkt auf den Bus gelegt wird, erreicht keinen Handler, dessen Rollen, Scopes oder allowSelf es nicht erfüllt; eine Methode ohne Definition wird abgewiesen, und ein Remote-Host ohne aktivierte Token-Validierung hat keinen validierten Aufrufer und weist jeden Aufruf ab; der Handler validiert nur noch das, was allein er wissen kann (Regel 1). Der Filter übernimmt den Aufrufer von dem Prozess, der den Aufruf startet (ein validiertes Token oder die Identität des Jobs), nie aus den caller-Daten eines Requests, der über den Bus eintrifft. Er läuft innerhalb des Audit-Filters (Band 100), sodass eine Ablehnung protokolliert wird, und außerhalb des Idempotenz-Filters (Band 300) und des Transports, die ein abgelehnter Aufruf nie erreicht. Eine Ablehnung ist der sprachneutrale Fehler METHOD_FORBIDDEN mit den Parametern methodId und reason: not-authorized; er verrät nie, welche Regel fehlgeschlagen ist, und ist identisch, egal ob das Ziel existiert.
2. Der Handler
Ein Handler ist eine Klasse mit einer Methode. Der Host deserialisiert die Parameter in den generierten Record, serialisiert das Ergebnis und macht aus Ausnahmen Envelopes.
internal sealed class ChangePasswordHandler(ChangePasswordService service)
: ICkMethodHandler<UserChangePasswordParameters> // no result
{
public async Task<CkMethodResult> InvokeAsync(
CkMethodContext context, // tenant, caller token, target id, deadline
UserChangePasswordParameters parameters,
CancellationToken cancellationToken) // cancelled at the handler deadline
{
// Thin adapter: everything that matters lives in a transport-independent service,
// which is unit-testable without the messaging package.
var outcome = await service.ChangeAsync(
context.TenantId, context.TargetRtId, context.CallerAccessToken, parameters, cancellationToken);
return outcome.Success
? CkMethodResult.Ok()
: CkMethodResult.Fail(outcome.ErrorCode, outcome.ErrorParameters);
}
}
Der Service führt den Algorithmus in der Reihenfolge von Regel 2 aus:
| Schritt | Was | Bei Fehler |
|---|---|---|
| 1 | Den Aufrufer aus context.CallerPrincipal nehmen, den der Host gefüllt hat, nachdem er das Token validiert hat (Schritte: Signatur, Aussteller, Ablauf, tenant_id entspricht dem Mandanten des Requests, Scope octo_api, optionale Audience). Ein Dienst, der sich nicht dafür entschieden hat, hat keinen validierten Aufrufer; sein Host weist den Aufruf ab, bevor der Handler läuft. | METHOD_FORBIDDEN |
| 2 | Auf geparsten Ids autorisieren, nicht auf Strings: Selbst, wenn das Subjekt (sub) des Principals der Ziel-Id entspricht, Administrator, wenn das Token UserManagement trägt. OctoObjectIds vergleichen (der Parser akzeptiert Hex in Großbuchstaben, ein Stringvergleich nicht). | METHOD_FORBIDDEN – dieselbe Antwort, egal ob das Ziel existiert |
| 3 | Mandantenkontext aus der Mandanten-Id des Requests bestimmen; prüfen, dass der Mandant das Identity-Modell hat. | METHOD_HANDLER_FAILED |
| 4 | Den Ziel-Benutzer mit einem User-Manager laden, der für diesen Mandanten erzeugt wurde (siehe Regel 3) und nach dem Aufruf freigegeben wird. | METHOD_TARGET_NOT_FOUND |
| 5 | Parameter validieren: newPassword vorhanden; currentPassword bei Selbstbedienung vorhanden. | METHOD_VALIDATION_FAILED mit Parameter field |
| 6 | Einen gesperrten Benutzer ablehnen. | USER_LOCKED_OUT |
| 7 | Abbruch-Token prüfen, dann schreiben. Selbst: Änderung mit dem aktuellen Passwort; ein falsches aktuelles Passwort zählt wie eine fehlgeschlagene Anmeldung zur Sperre. Administrator: Zurücksetzen. Der Schreibvorgang aktualisiert Passwort-Hash und Security Stamp in einer Operation. | CURRENT_PASSWORD_INVALID, PASSWORD_POLICY_VIOLATION |
| 8 | Ergebnis auf das Envelope abbilden; eine Zeile loggen mit Invocation-Id, Mandant, Ziel-Id, Aufrufer-Id und Ergebnis – keine Parameter, kein Token. |
Konsistenzentscheidungen in diesem Beispiel:
- Die Passwortänderung ist ein einzelner logischer Schreibvorgang, den das Identity-Framework in einer Operation ausführt, sie ist daher atomar (R3). Der Handler braucht keine eigene Transaktion über mehrere Dokumente.
- Sie ist nicht idempotent: Eine Wiederholung mit anderem Passwort ist eine andere Anforderung. Ein wiederholter Aufruf mit denselben Parametern vom selben Benutzer scheitert beim zweiten Mal meist mit
CURRENT_PASSWORD_INVALID(ein natürlicher Schutz, keine Garantie). - Stürzt der Handler nach dem Schreiben und vor der Antwort ab, erhält der Aufrufer
METHOD_TIMEOUT, obwohl das Passwort geändert wurde (Fehlerbeispiel 1). Der Client liest den Zustand, indem er sich mit dem neuen Passwort anmeldet. - Eine Benachrichtigungsmail nach einem Zurücksetzen durch einen Administrator ist ein Seiteneffekt: nach dem Commit senden, über einen an den Mandanten gebundenen Mailweg (nicht über einen Dienst, der seinen Mandanten aus dem HTTP-Request bestimmt), und einen Mailfehler als Warnung behandeln, nicht als Fehler der Methode.
- Das Widerrufen von Sitzungen nach einer Passwortänderung (Refresh-Tokens) ist ein eigener Schreibvorgang in einem anderen Store. Er gehört nach dem Commit, mit Outbox oder Kompensation, wenn er nicht verloren gehen darf.
3. Registrierung
// Program.cs of the service that owns the model
builder.Services.AddCkMethodHandlers("IdentityService", methods =>
methods.Handle<ChangePasswordHandler>(SystemIdentityCkIds.UserChangePasswordMethodId));
Beim Start prüft der Host die Registrierung gegen den CK-Cache: Eine unbekannte Methoden-Id oder ein nicht zum Modell passender Parametertyp stoppt den Dienst mit einer Meldung, die die Methode nennt. Danach kündigt der Host den Handler im Event Hub an, sobald sein Endpunkt bereit ist, wiederholt die Ankündigung als Heartbeat und zieht sie vor dem Herunterfahren zurück. Sie berühren nie Queues, JSON oder Ankündigungen.
Bei zwei Replikaten des Identity-Dienstes kündigen sich beide an; die Queue der Methode wird geteilt, jeder Aufruf geht also an eines davon.
Das Gateway merkt sich seine Handler über einen Neustart. Das Gateway (und jeder andere Host, der Methoden dispatcht) hält seine Liste der angekündigten Handler als Snapshot in der Systemdatenbank, sodass ein neu gestartetes Gateway einen Aufruf beantwortet, ohne auf die nächste Heartbeat-Runde zu warten. Der Snapshot ist ein Zuletzt-gesehen-Eintrag, kein Versprechen, dass der Handler lebt: Eine Zeile gilt nur so lange als aktiv, wie das Heartbeat-Fenster, mit dem sie angekündigt wurde (standardmäßig 45 Sekunden), nicht abgelaufen ist. Ein Handler, der gestoppt wurde, dessen Fenster abgelaufen ist oder der sich zurückgezogen hat, wird nie verwendet; der Aufruf endet als METHOD_HANDLER_NOT_AVAILABLE. Der Snapshot enthält nur Dienstdaten (Methoden-Id, Dienstname, Instanz-Id, Versionen, Zeiten, bediente Mandanten), nie einen Parameterwert, ein Token oder Benutzerdaten. Ohne den Snapshot-Store lebt die Liste nur im Speicher, genau wie bisher.
Heartbeat und TTL. Ein Handler-Host wiederholt seine Ankündigung alle 15 Sekunden, und jede Ankündigung gilt 45 Sekunden. Diese beiden Werte sind die endgültigen Standardwerte; normalerweise ändern Sie sie nicht. Sie werden im Abschnitt Methods der Host-Konfiguration gesetzt:
| Schlüssel | Umgebungsvariable | Standard |
|---|---|---|
Methods:HeartbeatInterval | OCTO_Methods__HeartbeatInterval | 00:00:15 |
Methods:Ttl | OCTO_Methods__Ttl | 00:00:45 |
- Regeln.
HeartbeatIntervalmuss mindestens 1 Sekunde betragen,Ttlmindestens das Doppelte vonHeartbeatInterval(damit ein aktiver Handler einen verlorenen Heartbeat übersteht) und höchstens 24 Stunden. Ein Host, der eine Regel verletzt, startet nicht; die Fehlermeldung nennt Schlüssel und Regel, zum BeispielMethods:Ttl is 00:00:20 but must be at least 2 x Methods:HeartbeatInterval (00:00:30). - Unterschiedliche Werte je Host. Jede Ankündigung trägt ihre eigene TTL, und ein Dispatcher zählt sie ab dem Empfang der Ankündigung. Hosts verschiedener Dienste dürfen daher unterschiedliche Werte verwenden, ohne dass am Gateway etwas eingestellt werden muss.
- Warum diese Werte. Die Liste der Handler ist nur beratend. Ob ein Aufruf schnell mit
METHOD_HANDLER_NOT_AVAILABLEfehlschlägt, entscheidet der Broker, der eine Nachricht ohne möglichen Empfänger zurückweist, nicht die TTL. Die TTL bestimmt nur, was Diagnose und Snapshot als aktiv zeigen. 45 Sekunden tolerieren zwei verlorene Heartbeats; kürzere Werte erzeugen nur mehr Nachrichtenverkehr.
4. Tests
| Test | Beweist |
|---|---|
| Unit-Tests des Service mit gefälschter Token-Prüfung | jeden Schritt und Fehlercode der Tabelle oben, einschließlich: ein gefälschter Aufrufer wird abgelehnt, und derselbe METHOD_FORBIDDEN-Text für vorhandene und fehlende Ziele |
| Log-Capture-Test | kein Passwort und kein Token in irgendeiner Logzeile, auch auf Fehlerpfaden |
| Integrationstest gegen eine echte Datenbank | das Passwort ist geändert, der Security Stamp ändert sich, die Sperre zählt; ein abgebrochenes Token vor Schritt 7 schreibt nichts |
| Test der Handler-Registrierung | eine falsche Methoden-Id scheitert beim Start |
| Fehlertest | Handler wirft → METHOD_HANDLER_FAILED mit Korrelations-Id, kein Stacktrace im Envelope |
Derselbe Handler als In-Process-Handler
Das Asset Repository wird einige Methoden selbst besitzen (geplant: Tenant.*, Archive.*; noch ist keine produktive Methode registriert, der Transport ist freigegeben). Ihre Handler sind dieselben Klassen; sie werden als In-Process registriert, sodass der Dispatcher sie findet, bevor er nach einem entfernten Handler sucht. Es wird nichts auf dem Bus veröffentlicht, und der Handler wird nicht als entfernter Handler angekündigt. Envelope, Frist und Ausnahmeabbildung sind gleich, ebenso die Pipeline-Schritte für Autorisierung und Audit, die für jeden Transport laufen.
Was sich für Sie ändert:
- Zwischen Gateway und Handler liegt kein Netzwerk, und es ist verlockend, zu nehmen, was zur Hand ist: die Datenbank-Session des Requests, den HTTP-Kontext, das Repository des Requests. Tun Sie es nicht (Regel 3). Die Methode ist eine eigene Arbeitseinheit. Ein In-Process-Handler wird in einem eigenen Scope aufgelöst; ein Handler, der nach der Session des Requests greift, würde der Request-Transaktion stillschweigend beitreten und R1 brechen. Die Plattform macht dies zu einer Garantie (OD-8) und nicht nur zu einer Regel: Der In-Process-Transport führt jeden Handler losgelöst vom Umgebungs-Ausführungskontext des Aufrufers aus, in einem frischen Dependency-Injection-Scope pro Aufruf. Ein Wert, den der Aufrufer in einem
AsyncLocalhält (die Request-Session des Gateways, ein Principal-Scope, ein Logging-Scope), ist im Handler leer, auch nach dessen erstemawait, und nichts, was der Handler setzt, erreicht den Aufrufer. Ein neuer Scope allein genügt nicht, weil Umgebungswerte mit dem asynchronen Ablauf wandern und nicht mit dem Scope.
Bewusst übernommen werden: der Trace (der Span des Handlers ist ein Kind der Aktivität des Aufrufers, der Trace eines Requests setzt sich also durch den Aufruf fort), die Kultur des Aufrufers (CurrentCulture und CurrentUICulture), der Logging-Scope, der den Aufruf kennzeichnet (MethodId, InvocationId, CorrelationId, TenantId), und das Abbruch-Token mit der Frist. Sonst wird nichts übernommen; eine Bibliothek, die im Handler einen anderen Umgebungswert liest, sieht dessen Standardwert. Geben Sie dem Handler im Request mit, was er braucht.
Als Stolperdraht registriert ein Dienst für jede Art von Request-gebundenem Zustand, die er besitzt, eine Probe (AddCkInProcessAmbientStateProbe<TProbe>(); das Gateway registriert eine für die Request-Session, HasSession). Die Probe wird beim Start des Handlers im eigenen Ablauf des Handlers befragt. Meldet sie Zustand, schlägt der Aufruf mit METHOD_HANDLER_FAILED fehl und der Handler läuft nicht; das Log nennt die Probe, nie die Daten. Mit der Loslösung tritt das nie auf; es fängt eine Regression ab.
- Fristen und Timeouts gelten wie bei einem entfernten Aufruf.
- Ein Handler, der für beide Transporte registriert ist (zum Beispiel in einem Test), verhält sich gleich; das ist der Test eines transportunabhängigen Handlers.
Eine REST-Fassade über eine Methode, die der Service selbst hostet
Ein Service, der einen Methoden-Handler hostet, kann dieselbe Operation über einen eigenen REST-Endpunkt anbieten, eine Fassade
(zum Beispiel die Benutzer-Endpunkte des Identity Service über den User.*-Methoden). Die Fassade ruft die Methode wie jeder andere
Aufrufer über den Dispatcher auf, und der Handler läuft im selben Prozess durch dieselbe Invocation-Pipeline wie
ein Aufruf aus einem anderen Service: deklarierte Autorisierung, Parametervalidierung, Maskierung von sensitive-Parametern, Audit
und die ck.method.*-Metriken (Transport in-process). Es gibt keinen Weg über den Bus, also erreicht kein Parameter (etwa ein
Passwort) den Broker.
AddCkMethodHandlers registriert diesen lokalen Transport selbst; AddCkMethodDispatcher gibt der Fassade ihren
ICkMethodDispatcher.
Zwei Registrierungen, eine Regel.
| Registrierung | Angekündigt, Bus-Queue | Ein anderer Prozess ruft auf | Dieser Prozess ruft auf |
|---|---|---|---|
m.Handle<THandler>(methodId) in AddCkMethodHandlers | ja | über den Bus | in-process (nichts wird gesendet) |
m.HandleLocalOnly<THandler>(methodId) in AddCkMethodHandlers | nein | METHOD_HANDLER_NOT_AVAILABLE (keine Queue) | in-process |
m.Handle<THandler>(methodId) in AddCkInProcessMethodHandlers | nein | METHOD_HANDLER_NOT_AVAILABLE | in-process |
HandleLocalOnly<THandler>(methodId)ist für eine Methode, deren Bus-Angebot abgeschaltet ist, deren Fassade aber weiter funktionieren muss, zum Beispiel die Passwort-Methoden des Identity Service, solange der Broker nicht geschützt ist:EnablePasswordMethods ? m.Handle<H>(id) : m.HandleLocalOnly<H>(id).- Ein Ort pro Methode. Eine Methode wird entweder für den Bus oder nur lokal registriert; beides für dieselbe Id stoppt den Service beim Start.
- Dieselbe Hülle. Eine für den Bus registrierte Methode, die ihr eigener Host aufruft, antwortet mit der angekündigten Handler-Instanz-Id; die Antworthülle ist also Byte für Byte dieselbe, die ein entfernter Aufrufer von diesem Host bekommt.
- Methoden, die der Service nicht hostet, gehen weiterhin über den Bus. Darf eine Fassade den Prozess nie verlassen, prüfen Sie
beim Start
ICkInProcessMethodTransport.CanHandle(methodId).
Der Aufrufer. Der lokale Weg validiert kein Token. Der Principal ist der, den die Fassade mit CkMethodPrincipalScope aus dem
authentifizierten HTTP-Benutzer setzt. Ohne Scope gibt es keinen Principal, und die deklarierte Autorisierung lehnt den Aufruf mit
METHOD_FORBIDDEN ab; es gibt keinen Rückfall auf eine System-Identität. Wie jeder Methoden-Aufrufer braucht der Principal den Scope
octo_api.
Das Ergebnis. CkMethodFacadeResults.ToActionResult(response, options) (Namespace Meshmakers.Octo.Services.Methods.Facades)
macht aus der Antworthülle ein MVC-IActionResult:
| Ergebnis | Standard-Status |
|---|---|
| Erfolg mit Ergebnis / ohne Ergebnis | 200 mit dem Ergebnis-JSON / 204 |
| angenommen (asynchroner Aufruf, Operation-Handle gesetzt) | 202 mit dem Operation-Handle |
METHOD_VALIDATION_FAILED | 400 |
METHOD_FORBIDDEN | 403 |
METHOD_TARGET_NOT_FOUND | 404 |
METHOD_REQUEST_IN_PROGRESS | 409 |
METHOD_PARAMETERS_TOO_LARGE | 413 |
METHOD_HANDLER_FAILED, METHOD_OUTCOME_UNKNOWN, ein unbekannter METHOD_*-Code | 500 |
METHOD_HANDLER_NOT_AVAILABLE, METHOD_CONTRACT_VERSION_UNSUPPORTED, METHOD_NOT_SUPPORTED_BY_HANDLER_VERSION | 503 |
METHOD_TIMEOUT | 504 |
| ein Code, den die Methode deklariert | 400 |
Der Standard-Fehlerinhalt ist Problem Details (application/problem+json) mit dem Code als title und den Erweiterungen code,
parameters und details. Fehlerparameter enthalten nie Parameterwerte, der Inhalt kann also zurückgegeben werden. Ein Endpunkt,
der seine bisherigen Statuscodes und Inhalte behalten muss, konfiguriert CkMethodFacadeOptions: MapError(code, status),
MapError(code, error => result) (auch für Plattform-Codes) und MapSuccess(response => result). Bauen Sie die Optionen einmal
pro Endpunkt.
// Program.cs des Identity Service
services.AddCkMethodHandlers("IdentityService", m =>
{
m.Handle<UserSetRolesHandler>(SystemIdentityCkIds.UserSetRolesMethodId);
if (options.EnablePasswordMethods) m.Handle<UserResetPasswordHandler>(SystemIdentityCkIds.UserResetPasswordMethodId);
else m.HandleLocalOnly<UserResetPasswordHandler>(SystemIdentityCkIds.UserResetPasswordMethodId);
});
services.AddCkMethodDispatcher(); // Einstiegspunkt der Fassade; lokale Methoden berühren den Bus nie
// UsersController
private static readonly CkMethodFacadeOptions ResetPasswordFacade = new CkMethodFacadeOptions()
.MapError("PASSWORD_POLICY_VIOLATED", error => new BadRequestObjectResult(error.Details))
.MapSuccess(_ => new NoContentResult());
[HttpPost("{id}/reset-password")]
public async Task<IActionResult> ResetPassword(string tenantId, string id, ResetPasswordDto dto)
{
var request = new CkMethodRequest(tenantId)
{
InvocationId = Guid.NewGuid(),
MethodId = SystemIdentityCkIds.UserResetPasswordMethodId,
CkTypeId = "System.Identity/User",
TargetRtId = id,
ParametersJson = JsonSerializer.Serialize(new UserResetPasswordParameters { NewPassword = dto.Password }, CkMethodJson.Options),
DeadlineUtc = timeouts.GetDeadlineUtc(tenantId, "System.Identity/User", SystemIdentityCkIds.UserResetPasswordMethodId)
};
using (CkMethodPrincipalScope.Begin(CkMethodPrincipal.FromClaimsPrincipal(User)))
{
var response = await dispatcher.InvokeAsync(request, HttpContext.RequestAborted);
return response.ToActionResult(ResetPasswordFacade);
}
}
Eine Pipeline als Handler
Eine Methode mit execution.handler: pipeline wird von einer Pipeline statt von C#-Code implementiert. Das eignet sich für die Orchestrierung vorhandener Knoten (lesen, transformieren, aufrufen, schreiben) und für Modelle, die keinen eigenen Dienst besitzen.
methods:
- methodId: UpdateFirmware-1
parameters:
- name: version
valueType: String
execution:
timeoutSeconds: 120 # mandatory for a pipeline method
handler: pipeline
So wird der Aufruf behandelt:
- Der Communication Controller kündigt sich als Handler jeder Methode an, deren kompilierte Definition
handler: pipelinesagt. - Für einen Aufruf sucht er im Mandanten des Aufrufs die deployte Pipeline, deren Well-known-Name der qualifizierten Methoden-Id entspricht (zum Beispiel
Acme.Assets/Device.UpdateFirmware-1; eine weitere Bindung gibt es nicht). Gibt es keine solche Pipeline:METHOD_HANDLER_NOT_AVAILABLEmitreasonpipeline-not-deployed. Eine geänderte Pipeline wirkt, nachdem sie erneut deployt wurde. - Er startet die Pipeline mit den Methodenparametern als Eingabe und der Identität des Aufrufers, genau wie bei einer manuellen Ausführung; die Pipeline läuft also mit den Rechten des Aufrufers.
- Die Pipeline beginnt mit dem Execute-Command-Trigger und endet mit
SetPipelineExecutionResult, dessen Ausgabe zum Ergebnis-Record der Methode passen muss. - Das Ergebnis wird auf das Envelope abgebildet: Erfolg mit passendem Ergebnis → Erfolg; Pipeline-Fehler →
METHOD_HANDLER_FAILED; ein von der Pipeline gesetzter Fehlercode → dieser Code; ein Ergebnis, das nicht zum Ergebnis-Record passt →METHOD_HANDLER_FAILEDmit Validierungsparameter; die Frist läuft ab →METHOD_TIMEOUT.
Konsistenz eines Pipeline-Handlers:
- Ein Pipeline-Lauf ist wie jeder Handler eine eigene Arbeitseinheit; die Knoten der Pipeline übernehmen ihre Schreibvorgänge, während sie laufen. Es gibt kein Zurückrollen früherer Knoten, wenn ein späterer Knoten scheitert. Entwerfen Sie die Pipeline so, dass die schreibenden Knoten zuletzt kommen, oder bilden Sie Kompensation als Knoten ab.
- Bei
METHOD_TIMEOUTkann die Pipeline noch fertig werden. Das ist dokumentiert, nicht verhindert. Eine nicht idempotente Pipeline-Methode liegt in der Verantwortung des Autors. - Eine Methode mit einem
sensitive-Parameter kann keine Pipeline-Methode sein: Eine Pipeline-Ausführung speichert ihre Ein- und Ausgabe, deshalb lehnt der Compilerhandler: pipelinefür eine solche Methode mit Meldung 132 ab (Entscheidung OD-9). Setzen Sie sie als Service-Handler um. Der Pipeline-Handler lehnt eine solche Methode zur Laufzeit ebenfalls ab (reasonsensitive-parameters-not-supported). Dasselbe gilt für ein alssensitive: truemarkiertes Ergebnis, das der Compiler für eine Pipeline-Methode mit Meldung 134 ablehnt (Sensible Ergebnisse); der Pipeline-Handler lehnt es zur Laufzeit ebenfalls ab, mitreasonsensitive-result-not-supported.
Die vollständige, getestete Beispiel-Pipeline für eine Pipeline-Methode steht unter Pipeline-Methoden-Handler.
Asynchrone Handler
Eine Methode mit execution.mode: async (Ausführungsmodus) erledigt ihre Arbeit, nachdem der Aufruf zurückgekehrt ist. Der Handler nimmt den Aufruf an, die Plattform schreibt einen dauerhaften Operationsdatensatz und antwortet dem Aufrufer mit einem Operation-Handle; Zustand, Fortschritt und Ergebnis liest der Aufrufer später über das Handle (GraphQL runtime.operations, siehe Asynchrone Methoden und Operationen). Die Zusagen sind in OD-5 entschieden: höchstens einmal nach der Annahme, kein Abbrechen, ein verlorener Handler endet als METHOD_OUTCOME_UNKNOWN.
Nur ein Service-Handler kann asynchron sein, und nach Entscheidung OD-10 nur einer eines Bot-Job-Typs (die Bot-Services führen die Arbeit aus; der Repository-Dump ist der erste). Ein Pipeline-Handler antwortet synchron, und der Compiler lehnt mode: async zusammen mit handler: pipeline ab (Meldung 142). Bei einer asynchronen Methode begrenzt timeoutSeconds den Annahmeschritt, nicht die Operation.
Der Handler
Validieren Sie die Parameter synchron und antworten Sie sofort mit einem deklarierten Fehler, wenn sie falsch sind. Geben Sie Accepted nur zurück, wenn die Arbeit starten kann:
public sealed class BackupDumpHandler(IDumpService dumps)
: ICkMethodHandler<BackupDumpParameters, BackupDumpResult>
{
public Task<CkMethodOutcome<BackupDumpResult>> HandleAsync(
CkMethodContext<BackupDumpParameters> context, CancellationToken cancellationToken)
{
if (string.IsNullOrEmpty(context.Parameters.Target))
{
return Task.FromResult(CkMethodOutcome<BackupDumpResult>.ValidationFailed("target", "required"));
}
var tenantId = context.TenantId; // kopieren, was die Arbeit braucht; das Token des Aufrufers nie behalten
return Task.FromResult(CkMethodOutcome<BackupDumpResult>.Accepted(async (progress, ct) =>
{
await progress.ReportAsync(CkMethodOperationProgress.Create(10, "COPYING_COLLECTIONS"), ct);
var file = await dumps.DumpAsync(tenantId, ct);
return new BackupDumpResult { Value = file }; // oder ein deklarierter Fehler
}));
}
}
CkMethodOutcome.Accepted(work) gilt genauso für eine Methode ohne Ergebnis. Der Arbeits-Delegate erhält einen Fortschrittsmelder (ICkMethodOperationProgress, der auch die OperationId trägt) und ein Cancellation-Token. Der Repository-Dump der Bot-Services (System.Bot/TenantRepository.Dump) ist die erste Methode in Produktion, die so gebaut ist.
Regeln für die Arbeit:
- Sie läuft einmal, nachdem die Annahme-Antwort hinaus ist, losgelöst vom Aufrufer (kein Ambient-Zustand des Requests, wie bei einem In-Process-Handler), im Dependency-Injection-Scope des Handlers, der offen bleibt, bis die Arbeit endet. Kopieren Sie vor der Rückgabe, was die Arbeit aus dem Kontext braucht; das Token des Aufrufers wird nicht aufbewahrt (OD-10).
- Ihr Token wird abgebrochen, wenn der Host stoppt. Die Operation endet dann
FailedmitMETHOD_OUTCOME_UNKNOWN(reasonhandler-lost). Es gibt kein Fortsetzen und keine Wiederholung. - Sie endet mit einem Ergebnis oder einem deklarierten Fehler. Ein nicht deklarierter Code oder eine Exception wird zu
METHOD_HANDLER_FAILED(mit Korrelations-Id, mit maskierten Secrets geloggt), ein unbestätigter Schreibvorgang zuMETHOD_OUTCOME_UNKNOWN— dieselbe Abbildung wie bei einem synchronen Aufruf. Die Arbeit kann nicht erneut annehmen. progress.ReportAsync(...)nimmt einen optionalen Prozentwert (0–100), einen optionalen sprachneutralen Stufen-Code (UPPER_SNAKE_CASE) und bis zu 16 String-Parameter; nie Meldungstext. Jede Meldung ist zugleich ein Heartbeat. Ein Problem des Speichers beim Melden wird geloggt und lässt die Arbeit nie scheitern.Acceptedaus einer Methode, die nicht mitexecution.mode: asyncdeklariert ist, ist ein Handler-Fehler: Der Aufruf wird mitMETHOD_HANDLER_FAILEDbeantwortet, und nichts wird aufgezeichnet.
Registrierung
services.AddCkMethodHandlers("BotServices", m => m.Handle<BackupDumpHandler>("MyModel/Backup.Dump-1"));
services.AddCkMethodMongoOperationStore(); // Paket Meshmakers.Octo.Services.Methods.MongoDb, Systemdatenbank
services.AddCkMethodOperations(); // Runner, Heartbeat, Sweep
Ohne AddCkMethodOperations() wird ein Handler, der Accepted zurückgibt, mit METHOD_HANDLER_FAILED beantwortet. Ein Host, der Operationen nur liest (das Asset-Repository, das runtime.operations bedient), registriert den Speicher und AddCkMethodOperationSweep(). Tests und Hosts mit nur einem Replikat dürfen AddCkMethodInMemoryOperationStore() verwenden; dieser Speicher ist weder dauerhaft noch geteilt.
Was bei einem Aufruf passiert
- Der Handler gibt
Accepted(work)zurück. - Der Host schreibt den Operationsdatensatz, bevor er antwortet. Scheitert das Schreiben, erhält der Aufrufer
METHOD_HANDLER_NOT_AVAILABLE(reasonoperation-store-unavailable), und die Arbeit startet nie. Ein Host, der herunterfährt, zeichnet nichts auf und antwortetMETHOD_HANDLER_NOT_AVAILABLE(reasonhost-stopping), sodass der Aufrufer es erneut versuchen kann. - Der Aufrufer erhält
success: truemitoperation { operationId, acceptedAtUtc, retryAfterSeconds };expiresAtUtcbleibt leer, bis die Operation abgeschlossen ist. - Die Arbeit startet: Zustand
RUNNING, Fortschritt und ein Heartbeat alleHeartbeatInterval. - Die Arbeit endet:
SUCCEEDEDmit dem Ergebnis (keines bei einem Ergebnis, das das Modell alssensitivemarkiert) oderFAILEDmit dem Code und seinen Parametern;expiresAtUtcist der Abschlusszeitpunkt plus die Aufbewahrungsdauer. Ein abgeschlossener Datensatz ändert sich nie mehr. - Ein Handler, der stirbt (beendet, abgestürzt), sendet keinen Heartbeat. Nach
StaleAfterbeendet der Sweep eines beliebigen Replikats den Datensatz mitFAILED/METHOD_OUTCOME_UNKNOWN/handler-lost. Ein spätes Ergebnis dieser Arbeit wird verworfen, und nichts startet sie neu.
Der Datensatz enthält den Tenant, die Operations-Id, die Methoden-Id, die Aufruf- und die Korrelations-Id, den Besitzer (das sub eines Benutzers, sonst die client_id eines Service-Aufrufers, aus dem validierten Principal), den Zustand, den Fortschritt, das Ergebnis oder den Fehler und die Zeitstempel. Er enthält nie die Parameter, das Token des Aufrufers oder ein sensibles Ergebnis. Er liegt in der Collection MethodOperations der Systemdatenbank; jeder Lesezugriff nennt den Tenant, und abgelaufene Datensätze entfernt ein TTL-Index.
Einstellungen
Methods:Operations (Umgebung OCTO_Methods__Operations__*):
| Einstellung | Standard | Grenzen |
|---|---|---|
Retention | 7 Tage | 1 Stunde bis 30 Tage |
HeartbeatInterval | 15 s | mindestens 1 s |
StaleAfter | 2 min | mindestens 3 × HeartbeatInterval |
SweepInterval | 1 min | mindestens 1 s |
RetryAfterSeconds | 5 | 1 bis 3600 |
Ein ungültiger Wert stoppt den Service beim Start; die Meldung nennt die Einstellung und ihre Grenzen, nie den konfigurierten Wert.
Idempotenz und Metriken
Ein Aufruf einer asynchronen Methode mit Schlüssel verhält sich wie jeder Aufruf mit Schlüssel (R8): Eine Wiederholung mit demselben Schlüssel und denselben Parametern erhält die gespeicherte Annahme-Antwort mit derselben operationId, der Handler wird nicht erneut aufgerufen, und es gibt nur eine Operation — innerhalb der Schlüssel-Lebensdauer: Nach Ablauf des Schlüssels startet eine Wiederholung eine zweite Operation, auch während die erste noch läuft; ein Aufrufer, der spät wiederholt, listet deshalb zuerst seine eigenen Operationen (runtime.operations mit methodId und since). Passen mehrere Aufrufe der Methode, kann die Liste nicht zeigen, welcher Eintrag zum Aufruf mit verlorener Annahme-Antwort gehört; dann entscheidet der Zustand des Ziels, ob die Arbeit erneut gestartet wird. Eine passende Operation im Zustand ACCEPTED oder RUNNING kann das Ziel noch ändern: Warten Sie, bis sie beendet ist (SUCCEEDED oder FAILED), bevor Sie das Ziel lesen und über eine Wiederholung entscheiden. FAILED mit METHOD_OUTCOME_UNKNOWN / handler-lost beweist nicht, dass die Arbeit gestoppt ist: Der Sweep setzt den Zustand, wenn die Heartbeats ausbleiben, er bricht die Arbeit nicht ab, und ein spätes Ergebnis wird nur verworfen. Behandeln Sie das Ziel als möglicherweise noch in Änderung; wiederholen Sie nur, wenn sein Zustand zeigt, dass die Arbeit nicht gewirkt hat und nicht mehr läuft. Zwei weitere Grenzen: Eine Methode mit execution.idempotent: true ignoriert den Schlüssel, jeder Aufruf startet also eine neue Operation; und das wiederholte Handle ist nur lesbar, solange die Operation aufbewahrt wird — halten Sie Methods:Operations:Retention auf jedem Host mindestens so lang wie die Schlüssel-Lebensdauer Methods:Idempotency:Ttl (standardmäßig 24 Stunden, höchstens 7 Tage); bei kürzerer Aufbewahrung kann eine Wiederholung ein Handle liefern, dessen Abfrage OPERATION_NOT_FOUND ergibt.
Der Counter ck.method.operations (Meter Meshmakers.Octo.Methods, Labels method_id und state) zählt die Zustandswechsel accepted, running, succeeded und failed; siehe Methoden-Metriken.
Einen asynchronen Handler testen
- Validierungsfehler werden synchron beantwortet, bevor etwas angenommen wird.
- Die Arbeit meldet Fortschritt und endet mit dem Ergebnis oder jedem deklarierten Fehler; eine Exception endet als
METHOD_HANDLER_FAILED. - Die Arbeit kopiert, was sie braucht, und verwendet weder das Token des Aufrufers noch etwas, das an den Request gebunden ist.
- Die eigenen Tests des SDK (octo-common-services,
tests/Methods.Tests/Operations/,tests/Methods.IntegrationTests/Operations/) decken die Reihenfolge des Datensatzes, den verlorenen Handler und den Sweep ab; Ihr Handler wiederholt sie nicht.
Idempotenzschlüssel und Ihr Handler
Der Idempotenz-Filter (Band 300) läuft auf der Dispatcher-Seite, im Gateway. Ihr Handler implementiert dafür nichts und sieht weder den Schlüssel noch eine Wiederholung: Ein Aufruf, der aus dem Speicher beantwortet wird, erreicht den Handler nicht. Was ein Handler-Autor wissen muss:
- Ein Schlüssel sorgt dafür, dass die Plattform die Methode höchstens einmal ausführt; er macht Ihre Schreibvorgänge nicht sicher gegen zwei verschiedene Aufrufe (R7). Halten Sie gleichzeitige Aufrufe auf einem Ziel sicher.
- Ein Fehler Ihres Handlers (
METHOD_HANDLER_FAILED) verbraucht den Schlüssel für den Aufrufer, der nach dem Lesen des Zustands einen neuen Schlüssel verwenden muss. Halten Sie Ihre Schreibvorgänge atomar (R3), damit eine Wiederholung mit neuem Schlüssel sicher ist. - Eine Methode mit
sensitive-Ergebnis kann nicht mit Schlüssel aufgerufen werden. Taucht die erste Methode auf, die beides braucht, ist die Entscheidung OD-4 G2 zu überprüfen. execution.idempotent: truelässt die Plattform den Speicher überspringen: Ein Aufruf mit Schlüssel an eine solche Methode wird angenommen, der Schlüssel wird ignoriert und die Methode läuft jedes Mal, als wäre kein Schlüssel gesendet worden. Deklarieren Sie das nur, wenn eine Wiederholung wirklich sicher ist, denn keine Wiederholung wird je aus dem Speicher beantwortet. Details: R8.
Regeln für Aufrufer und die Einstellungen des Betriebs: R8.
Audit
Der Audit-Filter ist der äußerste Filter der Aufruf-Pipeline (Band 100). Er schreibt ein Audit-Ereignis pro Aufruf-ID mit dem endgültigen Ergebnis; ein von der Autorisierung (Band 200) abgelehnter Aufruf, ein vom Idempotenzfilter (Band 300) beantworteter Replay und ein Timeout werden daher wie ein Erfolg auditiert. Ein Gateway, das einen Aufruf ablehnt, bevor er den Dispatcher erreicht, schreibt sein Ereignis über denselben gemeinsamen Recorder (ICkMethodAuditRecorder, Registrierung mit AddCkMethodAudit()), sodass das Ereignisprotokoll pro Aufruf ein Ereignis enthält, egal wie der Aufruf endete. Was das Ereignis enthält, wie Replays, Ausnahmen und Abbrüche erfasst werden und welche Einstellungen für einen fehlgeschlagenen Audit-Schreibvorgang gelten (Methods:Audit:WriteTimeout, FailCallOnAuditFailure, FailCallOnAuditFailureTenants, Antwort METHOD_OUTCOME_UNKNOWN), steht unter Audit: ein Ereignis pro Aufruf.
Für Handler- und Filter-Autoren: Das Ereignis enthält nie Parameter (geschwärzt oder nicht), Ergebnisse, Token, Idempotenzschlüssel oder Fingerabdrücke; ein Handler oder Filter muss für das Audit nichts tun und darf solche Werte nicht selbst in ein Audit-Ereignis schreiben.
Die Zähler und Histogramme der Aufruf-Pipeline, einschließlich der abgelehnten doppelten Zustellungen, sind in Methoden-Metriken beschrieben.
Sensible Parameter und Filter
Im Modell mit sensitive: true markierte Parameter sind auf dem Weg zum Handler geschützt. Dieser Abschnitt richtet sich an Autoren von Filtern der Aufruf-Pipeline (Audit, Autorisierung, Idempotenz) und an Handler-Autoren, die wissen wollen, was geschwärzt wird.
- Filter sehen eine geschwärzte Sicht. Der Aufrufkontext gibt jedem Filter eine Sicht auf den Request: Die Werte sensibler Parameter (der ganze Wert, auch verschachtelte Objekte und Arrays; Namen werden ohne Beachtung der Groß-/Kleinschreibung verglichen) sind durch
"***"ersetzt, das Access-Token des Aufrufers istnull. Eine Nutzlast, die sich nicht parsen lässt oder kein JSON-Objekt ist, wird zu{}. Nur der Transport und damit der Handler erhält die Rohwerte. Ein Audit-Filter darf den Request, den er sieht, daher serialisieren, und ein Filter kann nichts preisgeben, was er nicht sieht. - Fail-closed. Eine Methode, die der Definitionsquelle unbekannt ist (oder für die es gar keine Definitionsquelle gibt), wird vollständig geschwärzt: Jeder Parameterwert ist maskiert. Ein Validierungsfehler nennt den Parameter (
field) und wiederholt nie seinen Wert. - Ein Filter, der die Parameter ändert, behält seine Änderung, pro Mitglied zusammengeführt. Gibt ein Filter den Request weiter, setzt die Pipeline die Rohwerte für den Transport wieder ein. Ändert er das Parameter-JSON (normalisiert, ergänzt), wird die Änderung verwendet, Mitglied für Mitglied zusammengeführt: Ein sensibles Mitglied, das noch
"***"ist, wird aus dem Roh-Request wiederhergestellt, sodass das Ändern eines nicht sensiblen Mitglieds nie den Platzhalter an den Handler schickt; ein sensibles Mitglied, dem der Filter einen anderen Wert gegeben hat, ist eine ausdrückliche Ersetzung und wird unverändert verwendet; ein entferntes Mitglied bleibt entfernt. Ein"***"für ein sensibles Mitglied, das der Request nicht enthält, lässt sich nicht wiederherstellen, und der Aufruf wird mitMETHOD_VALIDATION_FAILEDabgelehnt (fieldnennt das Mitglied), bevor der Handler aufgerufen wird. Ein Filter kann den Platzhalter nicht von einem echten Wert"***"unterscheiden; der Rohwert gewinnt. - Die Antwort wird genauso geschwärzt. Für eine Methode, deren Ergebnis als
sensitivemarkiert ist (und für eine Methode, die die Plattform nicht kennt), erhalten die Filter die Antwort mitResultJsonersetzt durch den JSON-String"***". Die echte Antwort geht an den Aufrufer zurück, solange die Filter die Sicht weiterreichen; ein Filter, der eine andere Antwort zurückgibt (etwa eine fehlgeschlagene), behält seine Änderung, und ein Filter, der antwortet, ohne den nächsten Schritt aufzurufen, wird unverändert zurückgegeben. Fehlerantworten,Success, das Operations-Handle und die Ids werden nie verändert.CkMethodResponse.ToString()gibt das Ergebnis nie aus, und der Handler-Host schreibt es nie in eine Logzeile, eine Ausnahmemeldung, ein Trace-Tag oder ein Metrik-Label. Ein Filter, hinter dem Ergebnisse gespeichert werden (Idempotenz), hält die geschwärzte Sicht, nie den echten Wert. - Ein Filter kann keine Fingerabdrücke von Geheimnissen bilden. Da er nur die geschwärzte Sicht sieht, kann er die echten Werte sensibler Parameter weder hashen noch vergleichen. Zwei verschiedene Passwörter sehen für einen Filter gleich aus; ein aus der Sicht abgeleiteter Schlüssel darf daher nicht zur Erkennung eines doppelten Aufrufs dienen.
- Ausnahmetext wird in jeder geschriebenen Form maskiert. Ausnahmen, die Pipeline und Dispatcher loggen, sowie Ausnahmemeldungen, die ein Handler wirft, werden für den Klartext und für die Formen maskiert, in denen ein Serialisierer oder eine URL den Wert schreibt: JSON-maskiert (Anführungszeichen, Backslash,
\uXXXX-Formen für Plus, Und-Zeichen, spitze Klammern, Apostroph, Steuer- und Nicht-ASCII-Zeichen, in Groß- und Kleinschreibung der Hex-Ziffern, maskierter Schrägstrich; die Encoder von System.Text.Json und Newtonsoft.Json), dasselbe noch einmal für JSON in einem JSON-String, und prozentkodiert. Eine Form, die kein Serialisierer erzeugt (ein Hash, eine Base64-Kopie, eine Kürzung), wird nicht erkannt: Schreiben Sie nie eine abgeleitete Form eines Geheimnisses in eine Meldung. - Ein Geheimnis im Ergebnis markieren. Ein Ergebnis, das ein Geheimnis enthält, wird im Modell mit
sensitive: truemarkiert (Sensible Ergebnisse); die Plattform schwärzt es dann für Filter, Logs und Traces (siehe nächsten Punkt), während der Aufrufer weiterhin den echten Wert erhält. Schreiben Sie in jedem Fall kein Geheimnis selbst in ein Log, Audit-Ereignis oder eine Outbox-Nutzlast: Die Plattform kann nicht wissen, was ein Handler schreibt.
Canary-Scan an den laufenden Services
Die Regeln oben sind in den Plattform-Bibliotheken in-process getestet. Der Methoden-Canary-Scan prüft sie an den laufenden Services: Bei gestartetem lokalen Stack ruft er Methoden über die typisierte Methoden-Mutation des Asset Repository mit gefälschten Geheimwerten (Canaries) als sensiblem Parameter auf und durchsucht danach jeden Ort, an dem ein Wert landen könnte, nach den Canaries und nach dem Access Token des Aufrufers, in jeder Form, in der ein Serializer oder eine URL sie schreibt (Klartext, JSON-escaped, JSON in JSON, Prozent-kodiert):
| Durchsucht | Was der Scan liest |
|---|---|
| GraphQL-Antworten | den Body jedes Aufrufs |
| Log-Dateien der Services | was jede logFiles/*.log von Start-Octo während des Scans dazubekommen hat |
| Audit- und Event-Log | die Events des Scan-Tenants, die während des Scans geschrieben wurden |
| Exportierte Traces, Metriken und Logs | die Ausgabe eines lokalen OpenTelemetry Collectors mit File-Exporter |
| Der behandelnde Service | Log-Zeilen und Spans des Handler-Hosts |
Zwei Methoden werden gescannt: eine Testmethode des Asset Repository (MethodCanaryScan/CanaryAccount.Rotate-1, behandelt vom eigenen Handler-Host des Scans über den Bus: Erfolg, fehlschlagender Handler, Timeout, Validierungsfehler, ein deklarierter Fehler und abgelehnte Aufrufe) und System.Identity/User.CreateUser-1 (sensibles password) des Identity Service (Erfolg, deklarierte Fehler, Validierung, abgelehnte Aufrufe). Jeder Aufruf prüft zusätzlich, dass er das erwartete Ergebnis bekam, damit ein sauberes Ergebnis nicht von Aufrufen kommt, die den Methodenpfad nie erreicht haben.
Erneut ausführen in octo-asset-repo-services (Einrichtung von Collector, Stack und Scratch-Tenant: tests/AssetRepositoryServices.MethodCanaryScan/README.md):
OCTO_METHOD_CANARY_SCAN=1 OCTO_CANARY_TENANT=<Scratch-Tenant> OCTO_CANARY_OTLP_DIR=<Collector-Ausgabe> \
dotnet test tests/AssetRepositoryServices.MethodCanaryScan -c DebugL
Der Scan schreibt einen Bericht pro Methode (Aufrufe, Senken, Treffer; Geheimwerte und Token-Teile sind durch Bezeichnungen ersetzt). Er schlägt bei jedem Treffer fehl und wenn keine Telemetrie ankam. Jeder Treffer wird ein Bug. Ergebnis des ersten Laufs (2026-11-05): Der Methodenpfad selbst hatte keinen Treffer in GraphQL-Antworten, Log-Dateien, Audit-Log oder Handler-Host; der Identity Service schreibt jedes ausgestellte Access Token auf Log-Level Trace in sein Log (ein bekannter Bug, außerhalb des Methodenpfads). Zweiter Lauf (2026-11-05, Services exportieren an einen lokalen Collector): kein Treffer in den exportierten Traces und Metriken beider Methoden; Logs exportieren die Services nicht über OTLP, ihre Log-Ausgabe decken die Log-Dateien ab. Für den Exporter die Services mit OTLP_ENDPOINT_URL (ohne Präfix OCTO_) starten und für die Identity-Methode mit OCTO_METHODS__IDENTITY__ENABLEPASSWORDMETHODS=true; Details stehen im README des Scans.
Leistung und Replikat-Verteilung
Alle Instanzen eines Dienstes, der eine Methode besitzt, teilen sich eine Queue dafür, und der Broker liefert jeden Aufruf an genau eine davon (Competing Consumers). Der Dispatcher sendet an einen stabilen Exchange und weiß nicht und muss nicht wissen, wie viele Replikate es gibt. Tests gegen einen echten Broker zeigen, dass jeder Aufrufer ein Envelope erhält, dass jeder Aufruf genau einmal läuft, dass sich die Last auf die Replikate verteilt und dass ein Replikat, das mitten in einer Lastspitze geordnet gestoppt wird, keinen Aufruf verliert. Stoppt das letzte Replikat, scheitern neue Aufrufe sofort mit METHOD_HANDLER_NOT_AVAILABLE, und ein neues Replikat wird bedient, sobald es startet.
Der Overhead des Dispatchers selbst ist klein: Mit einem Handler, der nichts tut, auf einer Maschine mit Broker, Gateway und Handlern über Loopback, liegt das 95. Perzentil der Round-Trip-Zeit bei etwa 1 ms, mit einem oder drei Replikaten gleich. Ein Cluster fügt Netzwerk-Hops zum Broker hinzu, und die Zeit des Handlers selbst kommt obendrauf; planen Sie den Methoden-Timeout für den Handler, nicht für die Plattform.
Eine Regel für Betreiber und Autoren von Änderungen: Ändern Sie die Argumente einer bestehenden Methoden-Queue nie an Ort und Stelle. Deklariert ein neuerer Build die Queue anders als ein älterer, lehnt der Broker sie ab, die neue Instanz startet nicht, und das Rollout wartet auf den alten Instanzen, die weiter bedienen. Eine Änderung der Queue-Argumente braucht einen neuen Queue-Namen, damit beide Builds nebeneinander laufen können.
Rolling Update: ein Replikat stoppen
Ein Replikat, das geordnet gestoppt wird (Rolling Update, Herunterskalieren), meldet sich zuerst ab, lässt dann seine laufenden Aufrufe zu Ende laufen und antworten und entfernt seine Methoden-Endpunkte. Ein laufender Aufruf wird nie abgebrochen. Die gemeinsame Queue und die anderen Replikate bedienen weiter, Aufrufer merken normalerweise nichts.
Ein enger Fall bleibt. In dem Moment, in dem der Stopp beginnt, kann der Broker dem stoppenden Replikat schon ein oder zwei Aufrufe zugestellt haben. Das Replikat startet sie nicht, und der Broker gibt sie an ein anderes Replikat als erneut zugestellt gekennzeichnet zurück. Dieses Replikat lehnt eine gekennzeichnete Zustellung als mögliches Duplikat ab (es kann nicht wissen, dass der erste Halter sie nie gestartet hat), und der Aufrufer erhält METHOD_OUTCOME_UNKNOWN, obwohl der Aufruf nicht lief. Nichts läuft doppelt.
| Verkehr beim Stopp | Gekennzeichnete Aufrufe, die nie liefen |
|---|---|
| Gleichmäßig (etwa 80 Aufrufe/s, Handlerzeit 200-600 ms, 30 Stopps, 9000 Aufrufe) | 1, also etwa 0,03 je Stopp |
| Gleichgetaktete Lastspitzen, die mit dem Stopp zusammenfallen (ungünstigster Fall, 10 Stopps, 3000 Aufrufe) | 29, also etwa 3 je Stopp |
Gemessen auf einer Maschine mit zwei Replikaten; die Rate ist die Ankunftsrate des stoppenden Replikats mal die Laufzeit des Cancel-Aufrufs zum Broker, ein stärker ausgelasteter Dienst sieht also proportional mehr. Was das für Sie bedeutet:
- Behandeln Sie
METHOD_OUTCOME_UNKNOWNwie immer: Zustand lesen, bevor Sie erneut aufrufen (R5). Nach einem Rolling Update ist das die erwartete, seltene Ursache für eine Methode, die nichts verändert hat. - Ein Aufruf mit Idempotenzschlüssel verbraucht bei dieser Antwort seinen Schlüssel (R8); senden Sie den nächsten Versuch mit einem neuen Schlüssel, nachdem Sie den Zustand gelesen haben.
- Die Plattform akzeptiert diese Restrate: Die Alternative würde einen Aufruf nach einem Verbindungsverlust doppelt ausführen. Sie zu beseitigen erfordert eine Änderung des Nachrichtentransports (Abholen beenden, bevor der Consumer als gestoppt markiert wird) oder einen Handler-seitigen Claim für Aufrufe mit Schlüssel; beides ist nicht Teil der aktuellen Plattform.
- Der harte Verlust eines Replikats (beendeter Prozess, Verbindungsverlust) erzeugt mehr gekennzeichnete Aufrufe als ein geordneter Stopp, und dann kann die erste Ausführung gelaufen sein; siehe Grenzen.
Timeouts und Größen
execution.timeoutSeconds(1–300, Standard 15) ist die Zeit, die der Aufrufer wartet. Die Frist im Request ist jetzt plus dieser Timeout, und das Abbruch-Token des Handlers wird zu dieser Frist abgebrochen. Der Dispatcher wartet eine kurze Karenzzeit (Standard 2 Sekunden) länger, damit dasMETHOD_TIMEOUTIhres Hosts vor der eigenen Antwort des Dispatchers eintrifft. Siehe Fristen und Timeouts.- Wählen Sie den Timeout für den langsamsten normalen Fall, nicht den Durchschnitt. Arbeit, die länger als das Maximum dauern kann, braucht eine asynchrone Methode, die ein Operation-Handle liefert (siehe Asynchrone Handler); bei einer solchen Methode begrenzt der Timeout nur den Annahmeschritt.
- Halten Sie Ergebnisse klein. Sie reisen in einer Nachricht.
Fehler, die ein Handler zurückgibt
| Sie wollen sagen | Zurückgeben |
|---|---|
| Der Aufrufer darf das nicht (oder Sie können nicht sagen, ob er darf) | METHOD_FORBIDDEN |
| Ein Parameter fehlt oder ist falsch | METHOD_VALIDATION_FAILED, Parameter field |
| Das Ziel ist weg | METHOD_TARGET_NOT_FOUND |
| Eine fachliche Regel hat abgelehnt | ein Code aus den errors der Methode, mit String-Parametern |
| Etwas Unerwartetes ist kaputt gegangen | werfen; der Host liefert METHOD_HANDLER_FAILED mit Korrelations-Id |
| Sie können nicht wissen, ob Ihr Schreibvorgang passiert ist | METHOD_OUTCOME_UNKNOWN |
| Sie haben den Request nach seiner Frist erhalten | METHOD_TIMEOUT ohne Ausführung (das erledigt der Host) |
Die Plattformcodes und was ein Aufrufer mit jedem tut, stehen in der Fehlercode-Tabelle. Deklarieren Sie nie einen Code, der mit METHOD_ beginnt.
Checkliste für eine neue Methode
- Ist es eine Methode, oder habe ich eine Operation zerlegt, die als Ganzes gelingen oder scheitern muss?
- Parameter, die Geheimnisse sind, sind
sensitive: true; keiner gelangt in Log, Audit-Ereignis, Trace, Outbox-Nutzdaten oder Fehlerparameter. -
authorizationist deklariert (Standard: nur Administratoren; der Host setzt es durch, bevor der Handler läuft), der Dienst hat die Token-Validierung aktiviert, und der Handler verwendet diecaller-Daten nicht. - Reihenfolge der Prüfungen: authentifizieren, autorisieren, nachschlagen, validieren, schreiben; dieselbe Antwort für ein fehlendes und ein verbotenes Ziel.
- Deklarierte Fehlercodes decken die fachlichen Ablehnungen ab; das Modell hat keinen
METHOD_-Code. - Der Handler verwendet nichts, was an den Request gebunden ist; der Mandant kommt aus der Mandanten-Id des Requests.
- Schreibvorgänge sind atomar und vor der Antwort übernommen; ein unbekannter Commit-Zustand liefert
METHOD_OUTCOME_UNKNOWN. - Das Abbruch-Token wird vor einem Schreibvorgang geprüft.
- Gleichzeitige Aufrufe auf demselben Ziel sind sicher.
-
idempotentist ehrlich gesetzt. Eine nicht idempotente Methode, die nicht doppelt laufen darf, wird mit Idempotenzschlüssel aufgerufen (R8);idempotentschaltet den Schlüssel nicht ab. - Eine Methode mit
sensitive-Ergebnis wird nie mit Schlüssel aufgerufen (sie wird abgelehnt,result-sensitive); Aufrufer lesen stattdessen den Zustand. - Seiteneffekte nach dem Commit; eine Outbox, wo eine verlorene Nachricht nicht hinnehmbar ist.
-
timeoutSecondspasst zum langsamsten normalen Fall; lange Arbeit ist eine asynchrone Methode (execution.mode: async, Service-Handler), die synchron validiert und ihren Fortschritt meldet. - Tests: jeder Fehlercode, gefälschter Aufrufer, Log-Scan auf Geheimnisse, Überlegung zum Absturz vor der Antwort, Registrierungsprüfung.
Diagnose: welche Handler sind registriert
Welcher Service beantwortet eine Methode, wie viele Instanzen leben und wann wurde jede zuletzt gesehen? Das Asset Repository beantwortet das mit der GraphQL-Root-Query methodHandlers (in der Schema-Beschreibung MethodHandlers; GraphQL-Feldnamen sind camelCase).
Wer darf sie lesen. Nur Systemadministratoren. Das Register gilt plattformweit: Es nennt Services, Instanz-IDs, Service-Versionen und die Mandanten-IDs, die ein Handler bedient, also Plattform-Topologie über alle Mandanten. Die Query verwendet dieselbe Aufrufer-Prüfung wie die mandantenübergreifenden Systemendpunkte (Orphan-Sweep, Reconcile des Mandantenregisters): Das Token muss für den Systemmandanten ausgestellt sein; ein Benutzer-Token braucht zusätzlich die Rolle AdminPanelManagement; ein Client-Credentials-Token des Systemmandanten genügt ohne die Rolle. Jeder andere Aufrufer, auch ein Mandantenadministrator eines Kundenmandanten, erhält methodHandlers: null und den Fehlercode MethodHandlersForbidden; es werden keine Handler-Daten gelesen oder zurückgegeben. Eine reduzierte Ansicht für Mandantenadministratoren gibt es nicht.
{
methodHandlers {
answeredBy {
dispatcherInstanceId serviceVersion snapshotEnabled
snapshotLoadedAtUtc snapshotRowsRestored snapshotLoadFailed lastFlushUtc lastFlushFailed
}
methods(search: "Identity", states: [NO_LIVE_HANDLER, NOT_ANNOUNCED]) {
methodId transport state liveInstanceCount lastSeenUtc
instances {
serviceName instanceId version contractVersion tenants
lastSeenUtc expiresUtc state source persistedLastSeenUtc
}
}
}
}
Methoden. Die Liste ist die Vereinigung dreier Quellen: die Handler-Zeilen, die das antwortende Gateway-Replikat hält, die Methoden, die das Gateway In-Process bedient, und die Methoden des Systemmandanten, die einen Service-Handler deklarieren (execution.handler: service, der Standard) und die keine Instanz angekündigt hat.
state einer Methode | Bedeutung |
|---|---|
LIVE | Mindestens eine Instanz lebt, oder die Methode wird In-Process bedient (transport: IN_PROCESS). |
NO_LIVE_HANDLER | Instanzen sind bekannt, aber alle sind abgelaufen, zurückgezogen oder ohne gebundene Queue. Ein Aufruf endet als METHOD_HANDLER_NOT_AVAILABLE. |
NOT_ANNOUNCED | Das Modell deklariert einen Service-Handler, aber keine Instanz hat die Methode je angekündigt: Der Handler fehlt (Service nicht ausgerollt, nicht gestartet oder die Methode nicht registriert). |
transport ist BUS für Methoden, die ein anderer Service behandelt, und IN_PROCESS für Methoden, die das Gateway selbst behandelt. liveInstanceCount zählt lebende Bus-Instanzen; eine In-Process-Methode hat keine Instanzen. lastSeenUtc einer Methode ist das späteste lastSeenUtc ihrer Instanzen. Die Argumente search (Teil der Methoden-ID oder eines Service-Namens, ohne Beachtung der Groß-/Kleinschreibung) und states schränken die Liste ein.
Instanzen. Jede bekannte Instanz wird aufgelistet, auch abgelaufene und zurückgezogene (Zeilen bleiben 24 Stunden erhalten).
| Feld | Bedeutung |
|---|---|
state | LIVE, EXPIRED (kein Heartbeat innerhalb der angekündigten TTL), WITHDRAWN (geordnetes Beenden) oder NO_QUEUE_BOUND (der Broker hat eine Mandatory-Sendung zurückgegeben). |
source | HEARTBEAT, wenn die Zeile aus einer Ankündigung, einer Discovery-Antwort oder einem Rückzug stammt. SNAPSHOT, wenn sie nach einem Neustart des Gateways aus dem persistierten Snapshot wiederhergestellt wurde und noch kein Heartbeat sie bestätigt hat. Eine SNAPSHOT-Zeile ist nie aus eigener Autorität LIVE: Sie ist ein Zuletzt-gesehen-Eintrag. |
lastSeenUtc / expiresUtc | Letzte empfangene Ankündigung oder letzter Rückzug und das Ende der angekündigten TTL. |
persistedLastSeenUtc | Zuletzt-gesehen-Zeit der Zeile im Snapshot-Speicher, den alle Gateway-Replikate teilen. null, wenn der Speicher keine Zeile für die Instanz hat oder nicht gelesen werden konnte (die Query antwortet trotzdem und der Fehler wird protokolliert). |
tenants | Die Mandanten, die die Instanz bedient (* = alle). |
Ein Replikat antwortet. Jedes Gateway-Replikat hält sein Register im Speicher, die Antwort beschreibt also das Replikat, das die Anfrage bedient hat. answeredBy benennt es: dispatcherInstanceId, serviceVersion, ob der Snapshot aktiviert ist, das letzte Laden des Snapshots (snapshotLoadedAtUtc, snapshotRowsRestored, snapshotLoadFailed) und das letzte erfolgreiche Schreiben (lastFlushUtc, lastFlushFailed). Der Vergleich von lastSeenUtc mit persistedLastSeenUtc zeigt, was andere Replikate geschrieben haben. Eine erneute Anfrage kann ein anderes Replikat erreichen.
Die Antwort enthält nur Servicedaten: IDs, Service-Namen, Versionen, Zeiten, Mandanten-IDs und Flags. Sie enthält nie Methodenparameter, Tokens oder Benutzerdaten, und ein fehlschlagender Snapshot-Speicher wird als Flag gemeldet, nie als Ausnahmetext.
In Refinery Studio
Systemadministratoren sehen dieselben Daten ohne Query: im Systemmandanten unter Operate › Method handlers (Route /<Systemmandant>/diagnostics/method-handlers). Die Seite braucht die Rolle AdminPanelManagement; in jedem anderen Mandanten oder ohne die Rolle ist der Menüeintrag ausgeblendet, und ein direkter Link zeigt statt Daten einen kurzen Hinweis.
Der Kopf lautet „Beantwortet von Replikat X (Version Y)“ mit den Snapshot-Angaben aus answeredBy (geladen um, wiederhergestellte Zeilen, letztes Schreiben und eine Warnung, wenn Laden oder Schreiben fehlschlug; „Snapshot aus“, wenn der Snapshot deaktiviert ist). Die Liste zeigt jede Methode mit Transport, Status (Nicht angekündigt ist mit Symbol und Text hervorgehoben), Anzahl lebender Instanzen und Zuletzt-gesehen-Zeit; Suche und Statusfilter entsprechen den Argumenten search und states. Das Aufklappen einer Methode listet ihre Instanzen mit allen oben genannten Feldern; aus dem Snapshot wiederhergestellte Zeilen sind mit „Zuletzt gesehen, nicht als aktiv bestätigt“ markiert. Die Seite ist schreibgeschützt, wird auf Anforderung aktualisiert und hat eine optionale automatische Aktualisierung (alle 15 Sekunden, standardmäßig aus). Wie die Query zeigt sie, was das antwortende Replikat weiß: Erneut aktualisieren erreicht ein anderes Replikat.