SkySpark-Integration

Projekte automatisch ermitteln, Funktionen synchronisieren und versionierte Verlaufsdaten jedes Commits speichern.

Die zwei Integrationsoberflächen

Es gibt zwei Möglichkeiten, wie der Server mit SkySpark kommuniziert:

  1. Dateisystem — liest config/ im SkySpark-Verzeichnis, um Projekte aufzuzählen und benutzerdefinierte Funktionen zu extrahieren, ohne dass die Instanz ausgeführt werden muss.
  2. HTTP + Haystack — führt Abfragen aus, bewertet Ausdrücke und committed Funktionen gegen eine laufende Instanz.

Die Dateisystemermittlung wird beim Serverstart ausgeführt. HTTP-Aufrufe erfolgen bei Bedarf, wenn ein Client queryHaystack, executeAxonCode oder commitAxonFunction aufruft.

Automatische Ermittlung

Mit skyspark.autoDiscover: true in der Konfiguration durchsucht der Server das SkySpark-Verzeichnis beim Start:

/path/to/skyspark/
├── config/            ← enumerated
│   ├── project-a/
│   ├── project-b/
│   └── sensorRead/
└── ...

Für jeden gefundenen Projektordner führt der Server folgende Schritte durch:

  1. Liest die Metadatendatei des Projekts, um zu bestätigen, dass es ein gültiges Haystack-Projekt ist.
  2. Ruft die Liste der benutzerdefinierten Funktionen (func-Datensätze) ab.
  3. Indiziert diese Funktionen im lokalen Axon-Index, gekennzeichnet mit project:<name>.

Das Ergebnis: searchAxonExamples kann Funktionen aus echten SkySpark-Projekten neben den statischen Bibliotheksbeispielen anzeigen.

Funktionssynchronisierung

Die Ermittlung zählt nur auf. Die Synchronisierung ruft den eigentlichen Funktionsquellcode ab.

Mit autoSyncFunctions: true wird die Synchronisierung automatisch beim Start ausgeführt. Andernfalls kann ein Client sie über discoverProjectFunctions auslösen:

{
  "tool": "discoverProjectFunctions",
  "arguments": { "project": "sensorRead" }
}

Parallelität

syncConcurrency (Standard 10) steuert, wie viele Funktionen parallel abgerufen werden. Erhöhen Sie den Wert für Instanzen in einem schnellen LAN, senken Sie ihn für langsame oder ratenbegrenzte Instanzen.

Versionierung

Mit functionVersioning: true und maxVersions: 4 (Standardwerte) führt jeder commitAxonFunction-Aufruf folgende Schritte durch:

  1. Liest die aktuelle Version aus SkySpark.
  2. Schreibt die neue Version.
  3. Archiviert die vorherige Version in .data/versions/<project>/<function>-v<N>.axon.
  4. Bereinigt Revisionen, die älter als maxVersions sind.

Das Wiederherstellen einer alten Version ist derzeit ein manuelles Kopieren zurück nach SkySpark — es gibt noch kein restoreFunctionVersion-Tool.

Das Primärprojekt-Konzept

Ausführungs- und Commit-Tools müssen ein einzelnes Projekt auswählen. Das Primärprojekt ist diese Auswahl:

"primaryProject": {
  "instance": "localhost8080",
  "project":  "sensorRead"
}

Clients können es zur Laufzeit wechseln:

{ "tool": "setPrimaryProject", "arguments": { "instance": "localhost8080", "project": "plantRoom" } }

Nachfolgende executeAxonCode- und commitAxonFunction-Aufrufe richten sich an plantRoom, bis zum nächsten Wechsel.

Abfragen ausführen

queryHaystack nimmt eine rohe Haystack-Abfragezeichenkette auf und gibt das resultierende Gitter als JSON zurück:

{
  "tool": "queryHaystack",
  "arguments": {
    "query": "read(site)"
  }
}

Ergebnis:

{
  "meta": { "ver": "3.0" },
  "cols": [ { "name": "id" }, { "name": "dis" }, { "name": "site" } ],
  "rows": [
    { "id": "@p:sensorRead:r:1a2b", "dis": "Main Campus", "site": true }
  ]
}

Abfragen werden mit dem Authentifizierungskontext des Primärprojekts ausgeführt.

Fallback-Anmeldedaten

Wenn die automatische Ermittlung fehlschlägt (falscher Pfad, SkySpark nicht auf demselben Host installiert usw.), greift der Server auf den expliziten Verbindungsblock zurück:

"fallback": {
  "host":     "skyspark.example.com",
  "port":     443,
  "project":  "demo",
  "username": "readonly",
  "password": "<use-env-var>",
  "protocol": "https"
}

Bevorzugen Sie die Substitution durch Umgebungsvariablen für das Passwort (SKYSPARK_PASSWORD), anstatt es in die Konfigurationsdatei einzutragen.

Fehlerbehebung bei Konnektivität

  • SKYSPARK_UNREACHABLE — die Instanz akzeptiert keine Verbindungen unter dem konfigurierten Host/Port. Überprüfen Sie curl http://<host>:<port>/about.
  • SKYSPARK_AUTH_FAILED — Anmeldedaten sind falsch, oder der Benutzer hat keine Berechtigung für das Zielprojekt.
  • PROJECT_NOT_FOUND — das Primärprojekt existiert nicht auf der Instanz. Führen Sie listSkySparkProjects aus, um zu sehen, was verfügbar ist.