Intégration SkySpark

Découvrez automatiquement les projets, synchronisez les fonctions et conservez un historique versionnné de chaque commit.

Les deux surfaces d'intégration

Il y a deux façons dont le serveur communique avec SkySpark :

  1. Système de fichiers — lit config/ sous le répertoire d'accueil SkySpark pour énumérer les projets et extraire les fonctions définies par l'utilisateur sans avoir besoin que l'instance soit en cours d'exécution.
  2. HTTP + Haystack — exécute des requêtes, évalue les expressions et valide les fonctions contre une instance en cours d'exécution.

La découverte du système de fichiers s'exécute au démarrage du serveur. Les appels HTTP se produisent à la demande lorsqu'un client appelle queryHaystack, executeAxonCode ou commitAxonFunction.

Découverte automatique

Avec skyspark.autoDiscover: true dans la configuration, le serveur parcourt le répertoire d'accueil SkySpark au démarrage :

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

Pour chaque dossier de projet trouvé, le serveur :

  1. Lit le fichier de métadonnées du projet pour confirmer qu'il s'agit d'un projet Haystack valide.
  2. Récupère la liste des fonctions définies par l'utilisateur (enregistrements func).
  3. Index ces fonctions dans l'index Axon local, balisées avec project:<name>.

Le résultat : searchAxonExamples peut surface les fonctions des projets SkySpark réels aux côtés des exemples de la bibliothèque statique.

Synchronisation des fonctions

La découverte énumère uniquement. La synchronisation récupère le code source de la fonction réelle.

Avec autoSyncFunctions: true, la synchronisation s'exécute automatiquement au démarrage. Sinon, un client peut la déclencher via discoverProjectFunctions :

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

Concurrence

syncConcurrency (par défaut 10) contrôle le nombre de fonctions extraites en parallèle. Augmentez-le pour les instances sur un LAN rapide, réduisez-le pour les instances lentes ou limitées en débit.

Versioning

Avec functionVersioning: true et maxVersions: 4 (valeurs par défaut), chaque appel commitAxonFunction :

  1. Lit la version actuelle de SkySpark.
  2. Écrit la nouvelle version.
  3. Archive la version précédente dans .data/versions/<project>/<function>-v<N>.axon.
  4. Supprime les révisions plus anciennes que maxVersions.

La restauration d'une ancienne version est actuellement une copie de fichier manuel dans SkySpark — il n'y a pas encore d'outil restoreFunctionVersion.

Le concept de projet principal

Les outils d'exécution et de validation doivent choisir un seul projet. Le projet principal est ce choix :

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

Les clients peuvent le changer à l'exécution :

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

Les appels executeAxonCode et commitAxonFunction suivants ciblent plantRoom jusqu'au prochain changement.

Exécution de requêtes

queryHaystack prend une chaîne de requête Haystack brute et retourne la grille résultante en JSON :

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

Résultat :

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

Les requêtes sont exécutées avec le contexte d'authentification du projet principal.

Identifiants de secours

Si la découverte automatique échoue (mauvais chemin, SkySpark non installé sur le même hôte, etc.), le serveur revient au bloc de connexion explicite :

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

Privilégiez la substitution par variable d'environnement pour le mot de passe (SKYSPARK_PASSWORD) plutôt que de le valider dans le fichier de configuration.

Dépannage de la connectivité

  • SKYSPARK_UNREACHABLE — l'instance n'accepte pas les connexions à l'hôte/port configuré. Vérifiez curl http://<host>:<port>/about.
  • SKYSPARK_AUTH_FAILED — les identifiants sont incorrects ou l'utilisateur n'a pas les permissions pour le projet cible.
  • PROJECT_NOT_FOUND — le projet principal n'existe pas sur l'instance. Exécutez listSkySparkProjects pour voir ce qui est disponible.