Zum Hauptinhalt springen

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.

Stand

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-HandlerPipeline-Handler
Deklariert durchexecution.handler: service (Standard)execution.handler: serviceexecution.handler: pipeline
Läuft indem 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 wirdEvent Hub, eine Queue je Methode, geteilt von allen Instanzen des Dienstesdirekter Aufruf im selben Prozess; nichts wird auf dem Bus veröffentlichtder Communication Controller startet die deployte Pipeline, deren Well-known-Name der qualifizierten Methoden-Id entspricht
Sie schreibeneine Handler-Klassedieselbe Handler-Klasse, als In-Process registrierteine 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 als METHOD_TIMEOUT oder METHOD_HANDLER_NOT_AVAILABLE, nie als zweite Zustellung. Ob wiederholt wird, entscheidet der Aufrufer (Wiederholungen); nach METHOD_HANDLER_NOT_AVAILABLE ist es immer sicher, weil nichts lief.
  • Ein Envelope. Erfolg, ein deklarierter Fehler und METHOD_HANDLER_FAILED kommen unverändert vom Handler an, egal welcher Transport den Aufruf bedient hat.

Gemeinsame Regeln​

Diese gelten für jeden Handler, gleich welcher Transport.

  1. Den Aufrufer erneut prüfen. Der Bus ist intern und wird nicht je Nachricht authentifiziert. Der caller im Request ist nur informativ. Autorisieren Sie anhand des weitergereichten Access-Tokens (Signatur, Aussteller, Ablauf, Mandant, Scope und, falls konfiguriert, Audience), nie anhand der caller-Daten. Ein gefälschter caller darf keine Wirkung haben. Die Validierung übernimmt der Host, wenn der Dienst sich dafür entscheidet: siehe Validierung des Aufrufer-Tokens.
  2. In dieser Reihenfolge prüfen: authentifizieren → autorisieren → nachschlagen → Parameter validieren → schreiben. Antworten Sie mit METHOD_FORBIDDEN mit demselben Text, egal ob das Ziel existiert, damit ein Aufrufer ohne Recht nicht nach Entitäten sondieren kann.
  3. 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 UserManager oder 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 der tenantId des Requests, erzeugen Sie, was Sie brauchen, für genau diesen Mandanten und geben Sie es wieder frei.
  4. Schreibvorgänge atomar machen und vor der Antwort übernehmen. Ein Dokument: ein atomares Update. Mehrere: eigene Session und Transaktion. Siehe R3.
  5. 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.
  6. 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ält METHOD_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 zu METHOD_HANDLER_FAILED mit 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.
  7. 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.
  8. Keine Geheimnisse in Logs. Als sensitive: true markierte 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.
  9. Kein Zustand in Instanzfeldern. Der nächste Aufruf kann von einer anderen Instanz bedient werden.
  10. 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).
  11. 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üfungBei Fehler (METHOD_FORBIDDEN, Parameter reason)
1Ein Token ist vorhanden.token-missing
2Signatur 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
3Ablauf, 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)
4Audience, nur wenn ValidAudiences konfiguriert ist: Das Token trägt eine der aufgeführten Audiences.audience-mismatch
5Scope octo_api.token-invalid
6Mandant: 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
7Subjekt: 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:

SchrittWasBei Fehler
1Den 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
2Auf 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
3Mandantenkontext aus der Mandanten-Id des Requests bestimmen; prüfen, dass der Mandant das Identity-Modell hat.METHOD_HANDLER_FAILED
4Den 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
5Parameter validieren: newPassword vorhanden; currentPassword bei Selbstbedienung vorhanden.METHOD_VALIDATION_FAILED mit Parameter field
6Einen gesperrten Benutzer ablehnen.USER_LOCKED_OUT
7Abbruch-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
8Ergebnis 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üsselUmgebungsvariableStandard
Methods:HeartbeatIntervalOCTO_Methods__HeartbeatInterval00:00:15
Methods:TtlOCTO_Methods__Ttl00:00:45
  • Regeln. HeartbeatInterval muss mindestens 1 Sekunde betragen, Ttl mindestens das Doppelte von HeartbeatInterval (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 Beispiel Methods: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_AVAILABLE fehlschlä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​

TestBeweist
Unit-Tests des Service mit gefälschter Token-Prüfungjeden 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-Testkein Passwort und kein Token in irgendeiner Logzeile, auch auf Fehlerpfaden
Integrationstest gegen eine echte Datenbankdas Passwort ist geändert, der Security Stamp ändert sich, die Sperre zählt; ein abgebrochenes Token vor Schritt 7 schreibt nichts
Test der Handler-Registrierungeine falsche Methoden-Id scheitert beim Start
FehlertestHandler 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 AsyncLocal hält (die Request-Session des Gateways, ein Principal-Scope, ein Logging-Scope), ist im Handler leer, auch nach dessen erstem await, 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.

RegistrierungAngekündigt, Bus-QueueEin anderer Prozess ruft aufDieser Prozess ruft auf
m.Handle<THandler>(methodId) in AddCkMethodHandlersjaüber den Busin-process (nichts wird gesendet)
m.HandleLocalOnly<THandler>(methodId) in AddCkMethodHandlersneinMETHOD_HANDLER_NOT_AVAILABLE (keine Queue)in-process
m.Handle<THandler>(methodId) in AddCkInProcessMethodHandlersneinMETHOD_HANDLER_NOT_AVAILABLEin-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:

ErgebnisStandard-Status
Erfolg mit Ergebnis / ohne Ergebnis200 mit dem Ergebnis-JSON / 204
angenommen (asynchroner Aufruf, Operation-Handle gesetzt)202 mit dem Operation-Handle
METHOD_VALIDATION_FAILED400
METHOD_FORBIDDEN403
METHOD_TARGET_NOT_FOUND404
METHOD_REQUEST_IN_PROGRESS409
METHOD_PARAMETERS_TOO_LARGE413
METHOD_HANDLER_FAILED, METHOD_OUTCOME_UNKNOWN, ein unbekannter METHOD_*-Code500
METHOD_HANDLER_NOT_AVAILABLE, METHOD_CONTRACT_VERSION_UNSUPPORTED, METHOD_NOT_SUPPORTED_BY_HANDLER_VERSION503
METHOD_TIMEOUT504
ein Code, den die Methode deklariert400

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:

  1. Der Communication Controller kündigt sich als Handler jeder Methode an, deren kompilierte Definition handler: pipeline sagt.
  2. 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_AVAILABLE mit reason pipeline-not-deployed. Eine geänderte Pipeline wirkt, nachdem sie erneut deployt wurde.
  3. 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.
  4. Die Pipeline beginnt mit dem Execute-Command-Trigger und endet mit SetPipelineExecutionResult, dessen Ausgabe zum Ergebnis-Record der Methode passen muss.
  5. 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_FAILED mit 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_TIMEOUT kann 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 Compiler handler: pipeline fü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 (reason sensitive-parameters-not-supported). Dasselbe gilt für ein als sensitive: true markiertes Ergebnis, das der Compiler für eine Pipeline-Methode mit Meldung 134 ablehnt (Sensible Ergebnisse); der Pipeline-Handler lehnt es zur Laufzeit ebenfalls ab, mit reason sensitive-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 Failed mit METHOD_OUTCOME_UNKNOWN (reason handler-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 zu METHOD_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.
  • Accepted aus einer Methode, die nicht mit execution.mode: async deklariert ist, ist ein Handler-Fehler: Der Aufruf wird mit METHOD_HANDLER_FAILED beantwortet, 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​

  1. Der Handler gibt Accepted(work) zurück.
  2. Der Host schreibt den Operationsdatensatz, bevor er antwortet. Scheitert das Schreiben, erhält der Aufrufer METHOD_HANDLER_NOT_AVAILABLE (reason operation-store-unavailable), und die Arbeit startet nie. Ein Host, der herunterfährt, zeichnet nichts auf und antwortet METHOD_HANDLER_NOT_AVAILABLE (reason host-stopping), sodass der Aufrufer es erneut versuchen kann.
  3. Der Aufrufer erhält success: true mit operation { operationId, acceptedAtUtc, retryAfterSeconds }; expiresAtUtc bleibt leer, bis die Operation abgeschlossen ist.
  4. Die Arbeit startet: Zustand RUNNING, Fortschritt und ein Heartbeat alle HeartbeatInterval.
  5. Die Arbeit endet: SUCCEEDED mit dem Ergebnis (keines bei einem Ergebnis, das das Modell als sensitive markiert) oder FAILED mit dem Code und seinen Parametern; expiresAtUtc ist der Abschlusszeitpunkt plus die Aufbewahrungsdauer. Ein abgeschlossener Datensatz ändert sich nie mehr.
  6. Ein Handler, der stirbt (beendet, abgestürzt), sendet keinen Heartbeat. Nach StaleAfter beendet der Sweep eines beliebigen Replikats den Datensatz mit FAILED / 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__*):

EinstellungStandardGrenzen
Retention7 Tage1 Stunde bis 30 Tage
HeartbeatInterval15 smindestens 1 s
StaleAfter2 minmindestens 3 × HeartbeatInterval
SweepInterval1 minmindestens 1 s
RetryAfterSeconds51 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: true lä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 ist null. 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 mit METHOD_VALIDATION_FAILED abgelehnt (field nennt 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 sensitive markiert ist (und für eine Methode, die die Plattform nicht kennt), erhalten die Filter die Antwort mit ResultJson ersetzt 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: true markiert (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):

DurchsuchtWas der Scan liest
GraphQL-Antwortenden Body jedes Aufrufs
Log-Dateien der Serviceswas jede logFiles/*.log von Start-Octo während des Scans dazubekommen hat
Audit- und Event-Logdie Events des Scan-Tenants, die während des Scans geschrieben wurden
Exportierte Traces, Metriken und Logsdie Ausgabe eines lokalen OpenTelemetry Collectors mit File-Exporter
Der behandelnde ServiceLog-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 StoppGekennzeichnete 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_UNKNOWN wie 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 das METHOD_TIMEOUT Ihres 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 sagenZurückgeben
Der Aufrufer darf das nicht (oder Sie können nicht sagen, ob er darf)METHOD_FORBIDDEN
Ein Parameter fehlt oder ist falschMETHOD_VALIDATION_FAILED, Parameter field
Das Ziel ist wegMETHOD_TARGET_NOT_FOUND
Eine fachliche Regel hat abgelehntein Code aus den errors der Methode, mit String-Parametern
Etwas Unerwartetes ist kaputt gegangenwerfen; der Host liefert METHOD_HANDLER_FAILED mit Korrelations-Id
Sie können nicht wissen, ob Ihr Schreibvorgang passiert istMETHOD_OUTCOME_UNKNOWN
Sie haben den Request nach seiner Frist erhaltenMETHOD_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.
  • authorization ist 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 die caller-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.
  • idempotent ist ehrlich gesetzt. Eine nicht idempotente Methode, die nicht doppelt laufen darf, wird mit Idempotenzschlüssel aufgerufen (R8); idempotent schaltet 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.
  • timeoutSeconds passt 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 MethodeBedeutung
LIVEMindestens eine Instanz lebt, oder die Methode wird In-Process bedient (transport: IN_PROCESS).
NO_LIVE_HANDLERInstanzen sind bekannt, aber alle sind abgelaufen, zurückgezogen oder ohne gebundene Queue. Ein Aufruf endet als METHOD_HANDLER_NOT_AVAILABLE.
NOT_ANNOUNCEDDas 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).

FeldBedeutung
stateLIVE, EXPIRED (kein Heartbeat innerhalb der angekündigten TTL), WITHDRAWN (geordnetes Beenden) oder NO_QUEUE_BOUND (der Broker hat eine Mandatory-Sendung zurückgegeben).
sourceHEARTBEAT, 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 / expiresUtcLetzte empfangene Ankündigung oder letzter Rückzug und das Ende der angekündigten TTL.
persistedLastSeenUtcZuletzt-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).
tenantsDie 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.

Siehe auch​