Garnet API

Die IGarnetApi-Schnittstelle enthält die für die öffentliche API bereitgestellten Operatoren, die letztendlich Operationen über die in Garnet gespeicherten Schlüssel ausführen. Sie erbt von IGarnetReadApi (read-only Befehlsschnittstelle) und IGarnetAdvancedApi (erweiterte API-Aufrufe).

Um einen neuen Operator oder Befehl zur API hinzuzufügen, fügen Sie eine neue Methodensignatur zur IGarnetReadApi-Schnittstelle hinzu, falls der Befehl nur Leseoperationen durchführt, andernfalls zur IGarnetApi.

Hinzufügen eines neuen Befehls zu Garnet

Wenn Sie versuchen, einen Befehl für Ihre spezifische Garnet-Serverinstanz hinzuzufügen, siehe Benutzerdefinierte Befehle

Um einen neuen Befehl zu Garnet hinzuzufügen, gehen Sie wie folgt vor:

1. Wenn Ihr Befehl auf einem Objekt (d. h. Liste, sortierter Satz usw.) operiert, fügen Sie einen neuen Enum-Wert zu der [ObjectName]Operation-Enum in Garnet.server/Objects/[ObjectName]/[ObjectName]Object.cs hinzu.
   Andernfalls fügen Sie einen neuen Enum-Wert zur RespCommand-Enum in Garnet.server/Resp/RespCommand.cs hinzu.
2. Fügen Sie die Parsing-Logik für den neuen Befehlsnamen zu Garnet.server/Resp/RespCommand.cs hinzu. Wenn der Befehl eine feste Anzahl von Argumenten hat, fügen Sie die Parsing-Logik zur FastParseCommand-Methode hinzu. Andernfalls fügen Sie die Parsing-Logik zur FastParseArrayCommand-Methode hinzu.
3. Fügen Sie eine neue Methodensignatur zu IGarnetReadApi hinzu, falls der Befehl nur Leseoperationen durchführt, andernfalls zu IGarnetApi (Garnet.server/API/IGarnetAPI.cs).
4. Fügen Sie eine neue Methode zur RespServerSession-Klasse hinzu. Diese Methode analysiert den Befehl aus dem Netzwerkpuffer, ruft die Storage-Layer-API auf (Methode in Schritt #3 deklariert) und schreibt die RESP-formatierte Antwort zurück in den Netzwerkpuffer (beachten Sie, dass die RespServerSession-Klasse über mehrere .cs-Dateien verteilt ist; objektspezifische Befehle befinden sich unter Garnet.server/Resp/Objects/[ObjectName]Commands.cs, während andere je nach Befehlstyp unter Garnet.server/Resp/[Admin|Array|Basic|etc...]Commands.cs zu finden sind).
5. Zurück in Garnet.server/Resp/RespCommand.cs, fügen Sie den neuen Befehlsfall zu der ProcessBasicCommands- oder ProcessArrayCommands-Methode hinzu, indem Sie die in Schritt #4 hinzugefügte Methode aufrufen.
6. Fügen Sie eine neue Methode zur StorageSession-Klasse hinzu. Diese Methode ist Teil des Storage Layers. Diese Storage-API führt NUR die RMW- oder Leseaufrufe durch und umschließt die Tsavorite-API. (Beachten Sie, dass die StorageSession-Klasse über mehrere .cs-Dateien verteilt ist; Objektspeicher-Operationen befinden sich unter Garnet.server/Storage/Session/ObjectStore/[ObjectName]Ops.cs, während Hauptspeicher-Operationen hauptsächlich unter Garnet.server/Storage/Session/MainStore/MainStoreOps.cs zu finden sind, mit einigen Ausnahmen).
   Befolgen Sie die folgenden Richtlinien gemäß dem neuen Befehlstyp, um die Logik des neuen Befehls auf Storage-Ebene zu implementieren:
   • Single-Key Object Store Befehl: Wenn Sie einen Befehl hinzufügen, der auf einem einzelnen Objekt operiert, wird die Implementierung dieser Methode einfach ein Aufruf von [Read|RMW]ObjectStoreOperation[WithOutput] sein, der wiederum die Operate-Methode in Garnet.server/Objects/[ObjectName]/[ObjectName]Object.cs aufruft, wo Sie einen neuen Fall für den Befehl und die objektspezifische Befehlsimplementierung in Garnet.server/Objects/[ObjectName]/[ObjectName]ObjectImpl.cs hinzufügen müssen.
   • Multi-Key Object Store Befehl: Wenn Sie einen Befehl hinzufügen, der auf mehreren Objekten operiert, müssen Sie möglicherweise eine Transaktion erstellen, in der Sie die Schlüssel entsprechend sperren (mithilfe der TransactionManager-Instanz). Sie können dann auf mehrere Objekte zugreifen (z. B. mithilfe der GET & SET-Operationen).
   • Main-Store Befehl: Wenn Sie einen Befehl hinzufügen, der auf dem Hauptspeicher operiert, müssen Sie die Read- oder RMW-Methoden von Tsavorite aufrufen. Wenn Sie RMW aufrufen, müssen Sie die Initialisierungs- und In-place / Copy-Update-Funktionalität des neuen Befehls in Garnet.server/Storage/Functions/MainStore/RMWMethods.cs implementieren.
7. Wenn der Befehl im Transaktionskontext aufgerufen werden kann, fügen Sie einen neuen Fall für den Befehl in der Methode TransactionManager.GetKeys hinzu und geben Sie die entsprechenden Schlüssel-Locks zurück, die vom Befehl benötigt werden (Garnet.server/Transaction/TxnKeyManager.cs).
8. Fügen Sie Tests hinzu, die den Befehl ausführen und seine Ausgabe unter gültigen und ungültigen Bedingungen überprüfen. Testen Sie, wenn möglich, sowohl mit SE.Redis als auch mit LightClient. Für Objektbefehle fügen Sie Tests zu Garnet.test/Resp[ObjectName]Tests.cs hinzu. Für andere Befehle fügen Sie je nach Befehlstyp Tests zu Garnet.test/RespTests.cs oder Garnet.test/Resp[AdminCommands|etc...]Tests.cs hinzu.
9. Fügen Sie neu unterstützte Befehlsdokumentation zur entsprechenden Markdown-Datei unter website/docs/commands/ hinzu und geben Sie den Befehl als unterstützt in website/docs/commands/api-compatibility.md an.
10. Befehlsinformationen hinzufügen, indem Sie dem nächsten Abschnitt folgen

Tipp

Bevor Sie mit der Implementierung Ihrer Befehlslogik beginnen, fügen Sie einen grundlegenden Test hinzu, der den neuen Befehl aufruft. So lässt sich fehlende Logik leichter debuggen und während der Implementierung ergänzen.

Hinzufügen von Befehlsinformationen

Jeder unterstützte RESP-Befehl in Garnet sollte einen Eintrag in Garnet.server/Resp/RespCommandsInfo.json haben, der die Informationen des Befehls angibt.
Befehlsinformationen können manuell hinzugefügt werden, wir empfehlen jedoch die Verwendung des CommandInfoUpdater-Tools zur Aktualisierung der JSON-Datei (zu finden unter playground/).

Das Tool CommandInfoUpdater berechnet die Differenz zwischen vorhandenen Befehlen in Garnet.server/Resp/RespCommandsInfo.json und Befehlen, die in CommandInfoUpdater/SupportedCommands.cs angegeben sind. Anschließend versucht es, die Befehlsinformationen nach Bedarf hinzuzufügen/zu entfernen.
Informationen für Garnet-spezifische Befehle werden aus CommandInfoUpdater/GarnetCommandsInfo.json bezogen, während Informationen für andere RESP-Befehle von einem externen RESP-Server bezogen werden (den Sie lokal ausführen oder darauf Zugriff haben müssen, um dieses Tool auszuführen).

Um Befehlsinformationen zu Garnet hinzuzufügen, gehen Sie wie folgt vor:

1. Fügen Sie den unterstützten Befehl und seine unterstützten Unterbefehle (falls zutreffend) zu CommandInfoUpdater/SupportedCommands.cs hinzu.
2. Wenn Sie einen Garnet-spezifischen Befehl hinzufügen, fügen Sie dessen Informationen zu CommandInfoUpdater/GarnetCommandsInfo.json hinzu.
3. Starten Sie einen RESP-Server lokal.
4. Bauen und führen Sie das Tool aus (für Syntaxhilfe führen Sie das Tool mit -h oder --help aus).

cd playground/CommandInfoUpdater
dotnet run -- --output ../../libs/resources