CX_WEB_SERVICE_MANAGER::MorphITServerCommand

CX_WEB_SERVICE_MANAGER::MorphITServerCommand

4.2.0
205954

Beschreibung:

Diese Methode bietet ClassiX eine generische Schnittstelle zur Kommunikation mit dem MorphIT-Server. Der MorphIT-Server definiert eine Reihe von Server-Befehlen, mit denen ClassiX das Verhalten des MorphIT-Servers steuern kann oder Informationen abfragen kann. Die Serverbefehle nutzen das Berechtigungssystem von MorphIT, um zu prüfen, ob ein bestimmter ClassiX-Prozess einen Server-Befehl ausführen darf oder nicht. Die für einen Befehl benötigten Berechtigungen sind bei der Beschreibung der Befehle mit aufgeführt.

Um einen Serverbefehl ausführen zu können, muss die ClassiX-Instanz logischer Weise am MorphIT-Server registriert sein. Sollte der Server auf einen Serverbefehl nicht innerhalb von 60 Sekunden antworten, wird der Aufruf mit einer Fehlermeldung abgebrochen. Diese Dauer lässt sich über die Umgebungsvariable CX_MORPHIT_COMMAND_TIMEOUT anpassen.

Serverbefehle

Der auszuführende Server-Befehl wird über das Feld command im Parameter-JSON angegeben. Je nach Befehl können/müssen weitere Parameter übergeben werden.

• morphit_version
• shutdown_classix
• request_binding
• launch_dedicated_classix
• set_path_map
• lock_launch
• unlock_launch
• send_webservice_request
• classix_status
• move_server

morphit_version

Anfrageformat:

Dieser Befehl benötigt keine Berechtigungen und liefert Versionsinformationen über die MorphIT-Installation im folgenden Format:

Antwortformat:

shutdown_classix

Berechtigungen:

• server_command.shutdown_classix
• server_command.shutdown_classix.role.(Rolle)
• server_command.shutdown_classix.webservice.(Name) (4.16.0)

Anfrageformat:

Mit diesem Befehl können einzelne oder mehrere ClassiX-Instanzen auf einmal beendet werden. In dem Feld reason kann optional eine Nachricht übergeben werden, die den verbundenen MorphIT-Clients angezeigt wird und von den beendeten ClassiX-Prozessen geloggt wird. Die Instanzen, die beendet werden sollen werden in einem JSON-Array im feld instances des Parameter-JSONs übergeben. Dabei gibt es folgende Möglichkeiten die Instanzen zu referenzieren:

[
  "self",         // The ClassiX instance issuing this command
  "all",          // All connected ClassiX instances
  {"id":id},      // The ClassiX instance with the given id
  {"morphit":id}, // The ClassiX instance connected to the specific MorphIT instance
  {"pid":pid, "launcher":host}, // The ClassiX with the given pid and launcher hostname|ip
  {"roles":[role1,role2,...]},  // All ClassiX instances, which have ALL of the given roles
  {"webservice":name} // All ClassiX instances, which are assigned to the webserivce configuration with id='name'
]

Es ist kein Fehler, wenn ein Selektor keine Instanz referenziert, weil beispielsweise die ID nicht (mehr) gültig ist, der Selektor wird dann einfach übergangen. Eine Ausnahme ist die Angabe eines Hosts/IP auf der aktuell kein Launcher läuft für den Selektor: {"pid":pid, "launcher":host}. Dies wird als Fehler zurückgegeben.

Um ein ClassiX zu beenden, muss der aufrufende ClassiX-Prozess die Berechtigung server_command.shutdown_classix sowie server_command.shutdown_classix.role.(Rolle) für jede Rolle des zu beendenden Prozesses haben. Falls die zu beendende ClassiX-Instanz  eine Webservice-Instanz ist, dann benötigt der Prozess zusätzlich die Berechtigung server_command.shutdown_classix.webservice.(Name) für die dazugehörige Webservice-Konfiguration (id). Hat der Prozess nicht ausreichend Berechtigungen, um alle angegebenen Prozesse zu beenden, erhält der aufrufende Prozess eine Fehlerantwort mit einer Liste der fehlenden Berechtigungen. Beispiel:

{
  "type":"error",
  "error":"Missing permissions to shutdown classix instances",
  "permissions":["server_command.shutdown_classix.role.local"]
}

Hat der aufrufende Prozess alle Berechtigungen, dann sendet der Server an alle erwähnten ClassiX-Prozesse einen shutdown-Befehl und sendet folgende Antwort, sobald alle Prozesse beendet wurden:

{
  "type":"success",
  "affected_instances":[1,2,3,..]
}

Das Feld affected_instances enthält dann ein Array mit den Ids der beendeten ClassiX Instanzen. Für den Fall, dass das aufrufende ClassiX sich über diesen Fall selbst beendet, sendet der Server die Antwort sofort und nicht erst nachdem sich alle Instanzen beendet haben.

Antwortformat

Codebeispiel:

Var(json)

CreateTransObject(CX_JSON_OBJECT) -> json
"shutdown_classix" json Put(command)
"Shutdown command test" json Put(reason)

// shutdown all instances local to the server
"local" json Put(instances[0].roles[0])
json GetManager(WEB_SERVICE) Call(MorphITServerCommand)

request_binding

Berechtigungen:

• server_command.request_binding
• server_command.request_binding.grant_role.(Rolle)
• server_command.request_binding.asset_route.default
• server_command.request_binding.asset_route.(Route)

Anfrageformat:

Dieser Server-Befehl ist der äquivalente Serverbefehl zu RequestMorphITBinding und ist dort dokumentiert. Im Gegensatz zu RequestMorphITBinding wertet der Serverbefehl die Antwort nicht aus und setzt damit auch die Umgebungsvariable CX_MORPHIT_NONCE nicht automatisch.

Antwortformat:

launch_dedicated_classix

Berechtigungen:

• server_command.launch_dedicated_classix
• server_command.launch_dedicated_classix.ip.(IP|Hostname)
• server_command.launch_dedicated_classix.at.self

Anfrageformat:

Dieser Server-Befehl ist der äquivalente Serverbefehl zu LaunchDedicatedClassiX und ist dort dokumentiert. Ein Launcher ist beim Server meist unter mehreren IP-Adressen und einem Hostnamen bekannt. Der aufrufende Prozess muss für mindestens eine der IP-Adressen oder den Hostnamen (in Kleinbuchstaben) die Berechtigung server_command.launch_dedicated_classix.ip.(IP|Hostname) haben, um dort einen Prozess starten zu dürfen. Die Berechtigung server_command.launch_dedicated_classix.at.self erlaubt das Starten von Prozessen auf der Maschine des aufrufenden Prozesses (siehe auch @self), ohne dass eine Berechtigung für den Hostnamen oder die IP-Adresse vorhanden sein muss.

Antwortformat:

set_path_map

4.4.0

Berechtigungen:

• server_command.set_path_map

Anfrageformat:

Dieser Befehl setzt (überschreibt) die aktuelle dynamische Pfadkonfiguration des Servers. Die neue Konfiguration wird sofort übernommen. Dieser Befehl kann nur dann ausgeführt werden, wenn in der config.js des Servers cloud.enabled=true gesetzt ist.

Codebeispiel:

Var(json)
CreateTransObject(CX_JSON_OBJECT) -> json
"set_path_map" json Put(command)


"Y:\\classix\\Evaluate\\WebWidgets" json Put(paths.classix.evaluate.public.widgets.path[0])
"Y:\\classix\\main\\WebWidgets" json Put(paths.classix.evaluate.public.widgets.path[1])

"Y:\\classix\\Evaluate\\bmp" json Put(paths.classix.evaluate.private.bmp.path)
"Y:\\classix\\Evaluate\\icons" json Put(paths.classix.evaluate.private.icons.path)
"Y:\\classix\\Evaluate\\projects\\data\\assets" json Put(paths.classix.evaluate.private.assets.path)

json GetManager(WEB_SERVICE) Call(MorphITServerCommand)

Antwortformat:

lock_launch

4.4.1

Berechtigungen:

• server_command.lock_launch
• server_command.lock_launch.role.(Rolle)
• server_command.lock_launch.global
• server_command.lock_launch.persistent

Anfrageformat:

Dieser Befehl setzt ein Launch-Lock im Server, mit dem verhindert werden kann, dass der Server den Start von bestimmten ClassiX-Instanzen durchführt/zulässt. Ein Lock ohne oder mit leerem roles-Parameter wird interpretiert als globales Lock. Hiermit werden alle ClassiX-Starts durch den Server unterbunden (request_binding & vorgestartete Instanzen). Falls Rollen im roles-Parameter gesetzt sind, dann lehnt der Server alle request_binding-Aufrufe mit einem Fehler ab, die eine der im Lock angegebenen Rollen enthalten. Sollte ein globales Lock gesetzt sein, dann wartet der Server mit dem Starten von neuen vorgestarteten ClassiX-Instanzen solange, bis das letzte globale Lock deaktiviert wurde.

Eine ClassiX-Instanz kann beliebig viele Locks gleichzeitig setzen.

Jedes Lock kann jederzeit mit dem Serverbefehl unlock_launch wieder aufgehoben werden.

Codebeispiel:

Var(json)

CreateTransObject(CX_JSON_OBJECT) -> json
"lock_launch" json Put(command)
"client.classix" json Put(roles[0])   // prevent request_binding with roles = client.classix
10000 "timeout" json Call(PutTyped)   // for 10s

json GetManager(WEB_SERVICE) Call(MorphITServerCommand)

Antwortformat:

unlock_launch

4.4.1

Berechtigungen:

• server_command.unlock_launch
• server_command.unlock_launch.issuer_role.(Rolle)

Anfrageformat:

Dieser Befehl dient dazu die Locks, die durch lock_launch gesetzt wurden wieder aufzuheben. Die Parameter issuer_roles, issuer_id  und roles dienen als Lock-Selektoren, mit denen man die Menge der aufzuhebenden Locks einschränken kann. Ist keiner der Parameter gesetzt, dann werden alle im Server gesetzten Locks aufgehoben. Es ist nicht möglich, durch die Angabe von roles die aufzuhebenden Locks nur auf globale Locks einzuschränken.

Jedes Lock, das per lock_launch gesetzt wurde, kennt die Rollen des Prozesses, der das Lock angelegt hat. Um ein Lock wieder zu entfernen, muss der Prozess für jede dieser Rollen die Berechtigung server_command.unlock_launch.issuer_role.Rolle haben. Dies gilt auch für (issuer_id="@self").

Codebeispiel:

Var(json)

CreateTransObject(CX_JSON_OBJECT) -> json
"unlock_launch" json Put(command)
"@self" json Put(issuer_id)    // release all locks, which have been set by this process

json GetManager(WEB_SERVICE) Call(MorphITServerCommand)

Antwortformat:

send_webservice_request

4.16.0

Berechtigungen:

• server_command.send_webservice_request
• server_command.send_webservice_request.path.(Pfad-Id)
• server_command.send_webservice_request.method.(Methode)
• server_command.send_webservice_request.to.webservice.(Id)

Anfrageformat:

Dieser Befehl bietet jeder ClassiX-Instanz, die mit einem MorphIT-Server verbunden ist (und über die entsprechenden Berechtigungen verfügt) die Möglichkeit, Webservice-Anfragen direkt and die Webservice-Instanzen des MorphIT-Servers zu senden, ohne hierfür eine HTTP-Verbindung mit dem externen HTTP-Port des MorphIT-Servers aufbauen zu müssen.

Des weiteren können per instance.webservice Webservice-Anfragen gesendet werden, die von außen gar nicht erreichbar sind, was für interne Steuernachrichten/Abfragen nützlich sein kann.

Antwortformat:

classix_status

4.16.0

Berechtigungen:

• server_command.classix_status
• server_command.classix_status.role.(Rolle)

Anfrageformat:

Dieser Befehl bietet jeder ClassiX-Instanz, die mit einem MorphIT-Server verbunden ist (und über die entsprechenden Berechtigungen verfügt) die Möglichkeit, status-Informationen über sich selbst oder andere ClassiX-Instanzen abzufragen, die nur der MorphIT-Server kennt, wie der Zeitpunkt der letzten Nachricht oder die zugewiesenen Rollen und welche ClassiX-Instanzen welcher Webservice-Konfiguration zugewiesen sind.

Antwortformat:

move_server

4.17.0

Berechtigungen:

• server_command.move_server

Anfrageformat:

Dieser Befehl ermöglicht es, den MorphIT-Server im laufenden Betrieb ohne Unterbrechung auf eine andere Maschine zu verschieben. Hierzu bauen beide Server eine bidirektionale Verbindung miteinander auf über welche die Server ihren Zustand untereinander austauschen und die Aufgaben schrittweise übertragen.

Der init-Schritt ist der einzige Befehl, der von einer ClassiX-Instanz ausgeführt werden muss, die mit dem Quell-Server verbunden ist. Alle nachfolgenden Schritte können auch von einer ClassiX-Instanz auf dem Ziel-Server ausgeführt werden.

Hauptartikel zum Servermove-Feature von MorphIT.

Schritte:

• init
• move_ls
• cx_status
• ws_status
• move_ws
• abort
• commit

init-Step

Anfrageformat:

Der init-Schritt wird auf dem aktuell (produktiv laufenden) Quellserver ausgeführt und dieser baut eine bidirektionale move_server-Verbindung mit dem angegebenen Zielserver auf. Hierzu wird zunächst eine Admin-Verbindung zu dem Zielserver aufgebaut und der Zielserver hierüber dazu aufgefordert eine Verbindung zu einem neuen move_server-Endpunkt (über einen Nonce-Wert abgesichert) aufzubauen.

Damit die Verbindung aufgebaut werden kann, müssen folgende Konfigurationseinträge auf beiden Servern gesetzt sein:

• ws.move_server.enabled=true
• ws.admin.enabled=true
• ws.admin.allowed_ips - muss auf dem Zielserver die IP des Quellservers enthalten.

Während die move_server-Verbindung aufgebaut wird, werden auf dem Zielserver alle ClassiX-Instanzen beendet, alle MorphIT-Verbindungen getrennt und alle Webservice-Konfigurationen deaktiviert. Alle Änderungen and der Server-Konfiguration, die während des Server-Moves durchgeführt werden, werden beim Abbruch der move_server-Verbindung auf beiden Servern automatisch wieder zurückgerollt und nach einer geringen Unterbrechung sollte der Quellserver wieder wie vor der angefangenen Umstellung verfügbar sein. Während eines Rollbacks (auch bei abort) werden alle auf dem Zielserver gestarteten ClassiX-Instanzen wieder beendet.

Sobald dieser Befehl erfolgreich ausgeführt wurde, arbeitet der Quellserver wie bisher, nur dass nun beim dedizierten Start von ClassiX-Instanzen die Launcher des Zielservers ebenfalls zur Verfügung stehen und ClassiX-Prozesse auch dort gestartet werden können. 

Die ClassiX-Prozesse verbinden sich zu dem MorphIT-Server, der zu dem Launcher gehört, der den ClassiX-Prozess gestartet hat.

MorphIT-Clients können sich mit einem beliebigen MorphIT-Server verbinden ihre Verbindung wird bei Bedarf durch die move_server-Verbindung zum anderen Server und dem dortigen ClassiX-Prozess geleitet.

Falls beide Server über das Internet erreichbar sind, dann kann ab jetzt der DNS-Eintrag vom Quell-Servers auf den Ziel-Server geändert werden.

Antwortformat:

move_ls-Step

Anfrageformat:

Mit diesem Schritt wird die Launch-Strategie - also das automatische Starten von Instanzen - auf den angegebenen Server verschoben und bereits vorgestartete und noch unbenutzte ClassiX-Instanzen beendet. Während einer bestehenden move_server-Verbindung ist die Launch-Strategie immer auf genau einem der beiden Server aktiv und MorphIT-Clients ohne statischen Login werden mit dem Server mit der aktiven Launch-Strategie verbunden.

Da Webservice-Instanzen ohne Angabe eines Startbefehls über die Launch-Strategie gestartet werden, sollte vor dem Verschieben solcher Webservice-Instanzen zunächst immer die Launch-Strategie auf den entsprechenden Server verschoben werden.

Falls der Befehl wiederholt wird und der Launch-Strategie auf diesem Server bereits aktiv ist, dann tut dieser Befehl nichts.

Antwortformat:

cx_status

Anfrageformat:

Dieser Schritt liefert den Serverübergreienden Status der verbundenen ClassiX-Instanzen analog zum Befehl classix_status, mit dem Unterschied, dass es keinen Selektor gibt und immer alle Instanzen zurückgegeben werden und dass die Instanzen beider Server zurückgegeben werden.

Antwortformat:

ws_status

Anfrageformat:

Dieser Befehl dient als Hilfestellung für das Verschieben von Webservice-Instanzen und liefert eine Übersicht, welche Webservice-Konfiguration auf welchem Server aktiv ist. Bevor ein Servermove abgeschlossen werden kann, müssen alle Webservices auf den Zielserver verschoben werden. 

Dieser Schritt entfällt, falls Webservices in der Server-Konfiguration deaktiviert sind.

Antwortformat:

move_ws-Step

Dieser Schritt verschiebt die angegebenen Webservice-Konfigurationen auf den angegebenen Zielserver, indem die Konfigurationen auf dem Zielserver aktiviert und Webservice-Instanzen gestartet werden. Sobald die Webservices auf dem Zielserver bereit sind, werden die Webservice-Konfigurationen auf dem Quellserver deaktiviert (und die ClassiX-Instanzen beendet) und alle Webservice-Anfragen für diese Konfigurationen auf den Zielserver umgeleitet. Diese Vorgehensweise ermöglicht ein unterbrechungsfreies Verschieben der Webservice-Konfiguration.

Falls to_source auf true gesetzt ist, dann werden die Instanzen in die umgekehrte Richtung verschoben.

Die bei move_ws angegebenen Konfigurationen müssen nicht zwangsläufig auf beiden Servern vorhanden sein. Existiert eine Konfiguration nur auf dem Quell-Server, dann wird sie dort nur deaktiviert. Existiert eine Konfiguration nur auf dem Zielserver, dann wird sie dort nur aktiviert.

Die Anfrage kehrt erst zurück, wenn die angegebenen Instanzen erfolgreich verschoben wurden. Da hierfür pro Konfiguration mindestens eine ClassiX-Instanz gestartet werden muss, wird empfohlen die Konfigurationen einzeln zu verschieben, oder CX_MORPHIT_COMMAND_TIMEOUT hochzusetzen, da der Aufruf ansonsten mit einem Timeout fehlschlagen kann und man nicht erfährt, ob und wann das Verschieben erfolgreich war.

Antwortformat:

abort-Step

Anfrageformat:

Dieser Befehl bricht einen laufenden Server-Move ab, indem die move_server-Verbindung zwischen den beiden MorphIT-Servern einfach geschlossen wird. Dieser Schritt kann nach dem init-Schritt und VOR dem commit-Schritt ausgeführt werden. Beide MorphIT-Server führen im Anschluss einen automatischen Rollback der bisherigen Schritte durch.

Da dieser Befehl die Verbindung sofort schließt, kann es hierdurch zu einer Unterbrechung für die Clients kommen, falls ein Großteil der Funktionalität bereits auf den Ziel-Server verschoben wurde. Um die Unterbrechnung zu vermeiden, sollten alle bereits durchgeführten Schritte nach Möglichkeit vorher manuell zurückgerollt werden.

Antwortformat:

commit-Step

Anfrageformat:

Dieser Befehl stellt den letzten Schritt eines Server-Moves dar und prüft zunächste, ob folgende Vorbedingungen erfüllt sind:

1. Die Launch-Strategie wurde auf den Zielserver verschoben
2. Alle Webservice-Konfigurationen des Quellservers sind deaktiviert und alle Webservice-Konfigurationen des Zielservers sind aktiviert.

Falls eine der Bedingungen nicht erfüllt ist, bricht der Befehl mit einer entsprechenden Fehlermeldung ab.

Ansonsten wird auf beiden Servern vermerkt, dass ab sofort bei einem Abbruch der move_server-Verbindung kein Rollback der Konfiguration mehr durchgeführt wird, stattdessen schaltet der Zielserver dann in den vollen Echtbetrieb um.

Der Quellserver wartet bis die letzte auf dem Server aktive (potenziell weitergeleitete) MorphIT/ClassiX-Verbindung geschlossen wurde, schließt dann die move_server-Verbindung und wechselt in den Wartungsmodus. Der Server-Wechsel ist damit abgeschlossen.

Antwortformat:

Liste aller Berechtigungen:

Funktionsaufruf: Call(MorphITServerCommand)