Guide de développement d'extensions

Les 10 vrais hooks de Saba-chan, la spécification de manifest.json, l'injection de slots dans la GUI et les notes d'implémentation des extensions intégrées.

Guide de développement d'extensions

Une extension (plugin) est un module complémentaire qui n'est pas lié à un jeu particulier et se greffe plutôt globalement sur le cycle de vie du démon, ou qui injecte des composants dans la GUI. Le démon Saba-chan passe la main aux extensions activées aux 10 points (hooks) suivants. Les extensions fournies aujourd'hui sont l'installation/mise à jour via SteamCMD (steamcmd) et l'analyseur INI UE4 (ue4-ini).

Le contenu de ce document s'appuie sur les vrais fichiers manifest.json du dépôt saba-chan-extensions et sur le système d'extensions côté démon (src/extension/mod.rs).


1. Structure des fichiers

%APPDATA%\saba-chan\extensions\<extension_id>\
  • manifest.jsonobligatoire. Déclare les hooks, les dépendances, les champsobligatoire. Déclare les hooks, les dépendances, les champs
  • __init__.pypermet aux modules de l'importer sous extensions.<name>permet aux modules de l'importer sous extensions.<name>
  • <python_modules>.pyfichiers référencés par python_modules dans manifest.jsonfichiers référencés par python_modules dans manifest.json
  • icon.pngfacultatiffacultatif
  • gui/facultatif. Source et sortie de build du bundle GUI (UMD)facultatif. Source et sortie de build du bundle GUI (UMD)
  • i18n/facultatif. Défini avec i18n_dir dans le manifeste (<locale>.json)facultatif. Défini avec i18n_dir dans le manifeste (<locale>.json)
  • test_<name>.pyrecommandé. Tests pytestrecommandé. Tests pytest
  • Le nom du dossier doit correspondre à l'id du manifeste. L'id avec les tirets remplacés par des underscores est également accepté (p. ex. id ue4-ini → dossier ue4_ini). Sinon, le démon ne la charge pas et la liste sous failed dans GET /api/extensions.
  • Un id ne peut contenir que des lettres, des chiffres, - et _.

2. Spécification de manifest.json

Le vrai manifeste de l'extension SteamCMD :

{
  "schema_version": 1,                    // avec 1, les clés inconnues et les hooks jamais déclenchés sont des erreurs
  "id": "steamcmd",                       // correspond au nom du dossier
  "name": "SteamCMD",
  "version": "0.1.0",
  "description": "Installs and updates game servers with SteamCMD",
  "descriptions": { "ko": "SteamCMD를 사용한 게임 서버 설치 및 업데이트 자동화" },
  "author": "WareAoba",
  "min_app_version": "0.1.0",
  "dependencies": [],                     // dépendances envers d'autres extensions (tableau ou { "id": ">=x.y.z" })

  "python_modules": {
    "steamcmd": "steamcmd.py"             // nom logique → chemin du fichier
  },

  "hooks": {
    "server.check_update": {
      "module": "steamcmd",
      "function": "check_update",
      "condition": "instance.ext_data.install_method_steamcmd"
    }
  },

  "instance_fields": {
    "install_method_steamcmd": { "type": "boolean", "default": false },
    "steamcmd_app_id": { "type": "number", "optional": true },
    "steamcmd_anonymous": { "type": "boolean", "default": true },
    "steamcmd_beta": { "type": "string", "optional": true },
    "steamcmd_platform": { "type": "string", "optional": true }
  },
  "permissions": { "network": true, "spawn_process": true }
}

Résumé des champs :

  • schema_version : Avec 1, les clés inconnues, les noms de hooks absents de FIRED_HOOKS et les références à des python_modules inexistants sont des erreurs. Sans ce champ (0), ce ne sont que des avertissements.
  • id, name, version : Obligatoires. version sert aux comparaisons de mises à jour et de dépendances.
  • description / descriptions : Description en anglais et descriptions par langue. L'API de liste choisit celle qui correspond à la langue de la GUI.
  • min_app_version : L'extension ne peut pas être activée ni installée sur un Saba-chan plus ancien.
  • dependencies : Dépendances envers d'autres extensions (ou saba-core). Seules les exigences de version >= sont prises en charge. L'activation vérifie que les dépendances sont activées ; elle ne les active pas automatiquement.
  • python_modules : Enregistre, par nom logique, les fichiers Python référencés par les hooks et les commandes. Les fichiers non enregistrés ici ne peuvent pas être appelés par les hooks.
  • hooks.<nom du hook>
    • module : un nom logique déclaré dans python_modules
    • function : le nom de la fonction dans ce fichier
    • condition (facultatif) : seule la forme instance.ext_data.<key> est prise en charge. Le hook ne s'exécute que pour les instances où cette valeur est vraie, un nombre non nul ou une chaîne non vide.
  • instance_fields : Valeurs par instance utilisées par cette extension (extension_data). Si une instance a une valeur définie, la désactivation ou la suppression de l'extension est refusée (in_use).
  • config_fields : Champs de paramètres globaux de l'extension. Les valeurs sont stockées dans extensions.settings.<id> de config.json.
  • gui : bundle (chemin du bundle UMD), styles (chemin du CSS). Voir la section 5 ci-dessous.
  • cli : Déclarations de slots CLI (cli.slots).
  • commands : Commandes ajoutées à la liste des commandes de l'instance (name, label, risk, inputs, module, function, condition).
  • priority : Ordre lorsque plusieurs extensions ont le même hook (la plus basse s'exécute en premier, 100 par défaut).
  • i18n_dir : Dossier des fichiers de traduction.
  • permissions : Déclare les capacités à risque utilisées par le code (même table que [permissions] d'un module).

Il n'y a pas de champ async sur les hooks ni de manifest_url dans le manifeste. La liste des extensions et leurs mises à jour proviennent uniquement du manifeste de versions signé de Saba-chan.


3. Les 10 vrais hooks

Les fonctions de hook s'exécutent de la même manière que les modules. Le démon lance python <file>.py <nom de fonction>, écrit le JSON de contexte sur stdin et lit le JSON de stdout (en entier ou la dernière ligne) comme résultat. Le code de sortie doit être 0. La liste ci-dessous est identique à FIRED_HOOKS dans le code du démon.

Nom du hookMoment de l'appelUtilisation du résultatExécution
daemon.startupJuste après le démarrage du démon / juste après l'activation d'une extension (cette extension uniquement)success/message vont dans l'état d'initialisation (/api/extensions/init-status)Arrière-plan
daemon.shutdownJuste avant l'arrêt du démonJournalisé uniquementSynchrone
server.pre_startJuste avant le démarrage d'un serveurhandled: true remplace le démarrage par défaut (si success n'est pas vrai dans ce cas, le démarrage échoue)Synchrone
server.stopJuste avant l'arrêt d'un serveurhandled: true prend en charge l'arrêtSynchrone
server.statusLors de la consultation de l'état d'un serveurhandled: true renvoie ce résultat tel quelSynchrone
server.list_enrichLors du listage des instanceshandled: true remplit status et extension_status. Délai de 10 s, cache TTL de 30 sSynchrone
server.post_createJuste après la création d'une instanceRésultat non utiliséArrière-plan
server.pre_deleteJuste avant la suppression d'une instanceSi handled, attend brièvement que les verrous de fichiers soient libérésSynchrone
server.settings_changedAprès l'enregistrement des paramètres d'une instanceRésultat non utiliséSynchrone
server.check_updateLorsqu'une vérification de mise à jour est demandéeLe premier résultat réussi devient la réponseSynchrone

Des noms comme server.pre_create, server.pre_install, server.post_install, server.post_start, module.parse_settings et module.write_settings n'existent pas ; les utiliser dans un manifeste schema_version = 1 fait échouer le chargement.

3.1 Contexte et point d'entrée

Une fonction de hook prend un dictionnaire de contexte et renvoie un dictionnaire. Selon le hook, le contexte contient instance_id, instance_name, module, instance_dir, extension_data, etc., et chaque hook reçoit aussi les paramètres globaux des extensions sous extension_config. Le fichier Python doit gérer lui-même le nom de fonction et stdin dans __main__. Un exemple abrégé de la structure de steamcmd.py :

import json, sys, traceback

def check_update(ctx: dict) -> dict:
    """
    ctx example (server.check_update):
      {
        "instance_id": "…",
        "instance_name": "My Palworld",
        "module": "palworld",
        "instance_dir": "…",
        "install_dir": "…",
        "app_id": 2394010,
        "extension_data": {"install_method_steamcmd": true, ...},
        "extension_config": {...}
      }
    """
    ...
    return {"success": True, "update_available": False}

FUNCTIONS = {"check_update": check_update}

if __name__ == "__main__":
    name = sys.argv[1] if len(sys.argv) > 1 else ""
    try:
        raw = sys.stdin.read()
        ctx = json.loads(raw) if raw.strip() else {}
        result = FUNCTIONS[name](ctx) if name in FUNCTIONS else \
            {"success": False, "message": f"Unknown function: {name}"}
    except Exception as e:
        traceback.print_exc(file=sys.stderr)      # les logs vont sur stderr
        result = {"success": False, "message": str(e)}
    print(json.dumps(result, ensure_ascii=False))  # les échecs aussi : JSON + code de sortie 0

3.2 handled et ordre d'exécution

  • Les extensions ayant le même hook s'exécutent une par une, triées par priority, puis par id.
  • Si un résultat contient handled: true, les extensions restantes sont ignorées. N'incluez pas handled sauf si vous remplacez le comportement par défaut de ce hook.
  • Si une extension échoue, l'erreur est enregistrée et l'extension suivante s'exécute.
  • La limite de temps par défaut est de 120 secondes. Le chemin des hooks n'affiche pas de progression (PROGRESS:).

3.3 Cache TTL de server.list_enrich

Ce hook peut être appelé pour chaque instance qui possède des extension_data, l'une après l'autre, à chaque demande de la liste des instances ; le démon met donc en cache les résultats réussis pendant 30 secondes. Tant que le cache est valide, il réutilise le résultat précédent sans lancer de processus Python. Chaque appel a un délai de 10 secondes ; concevez-le donc pour qu'il se termine rapidement. Le status_line du résultat est un état court d'une ligne affiché dans l'état Discord ; n'y mettez donc ni chemins ni secrets.


4. Les 3 extensions fournies

steamcmd

  • id : steamcmd
  • Python : steamcmd.py (classe SteamCMD : installation portable de SteamCMD, installation/mise à jour du serveur de jeu, vérification des mises à jour)
  • Hook : uniquement server.check_update (condition: instance.ext_data.install_method_steamcmd).
  • L'installation proprement dite est effectuée directement par le install_server du module via from extensions.steamcmd import SteamCMD.
  • instance_fields : install_method_steamcmd, steamcmd_app_id, steamcmd_anonymous, steamcmd_beta, steamcmd_platform. Le démon les remplit à partir de la section [install] du module selon une règle générique (install_method_<method>, <method>_<field>).
  • Pas de GUI.

ue4-ini

  • id : ue4-ini (nom de dossier ue4_ini)
  • Python : ue4_ini.py (parse_option_settings, write_option_settings)
  • Rôle : fournit aux modules des utilitaires pour lire et écrire le OptionSettings=(...) des fichiers INI des jeux UE4 comme Palworld.
  • C'est une bibliothèque pure qui ne déclare aucun hook ; les modules l'importent sous extensions.ue4_ini.

xna

  • id : xna
  • Python : xna.py (install, present, XnaError)
  • Rôle : place la version figée de Microsoft XNA Framework 4.0 Refresh à côté du dossier du serveur de jeu, sans l'installer sur le PC. Le serveur Windows de Terraria l'utilise. Le MSI officiel est téléchargé une fois, vérifié avec un SHA-256 figé, puis seuls les fichiers nécessaires en sont extraits.
  • C'est une bibliothèque pure qui ne déclare aucun hook ; les modules l'utilisent avec from extensions.xna import install, present.

Les modules ne peuvent pas importer des extensions désactivées. La garde d'import du démon bloque l'import de tout extensions.<name> absent de SABA_ENABLED_EXTENSIONS.


5. Bundle GUI (injection de slots)

Si manifest.json déclare gui.bundle, la GUI récupère ce fichier via GET /api/extensions/:id/gui et l'exécute (et injecte aussi le CSS si gui.styles est défini).

"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" }   // chemins d'exemple
  • Le bundle est au format UMD et doit créer la variable globale window.SabaExt<id en PascalCase>. Retirez - et _ de l'id et mettez en majuscule la lettre qui suit (p. ex. steamcmd → window.SabaExtSteamcmd, ue4-ini → window.SabaExtUe4Ini).
  • Lorsque la fonction registerSlots() de cette variable globale renvoie { slotId: Component | Component[] }, la GUI les monte dans les slots correspondants.
  • React est référencé comme dépendance externe via le window.React de l'hôte. Les composants doivent fonctionner uniquement avec les props transmises par le slot.
  • Les traductions sont chargées via GET /api/extensions/:id/i18n/:locale dans l'espace de noms ext_<id>.
Id du slotEmplacementprops
ServerCard.badgeBadge de la carte serveurserver
ServerCard.headerGaugeJauge d'en-tête de la carte serveurserver
ServerCard.provisionCarte serveur pendant le provisionnementserver, provisionProgress, onDismiss, t
ServerCard.expandedStatsStatistiques de la carte serveur dépliéeserver, t
ServerSettings.tabOnglet des paramètres du serveurserver, activeTab, setActiveTab, settings, onSettingsChange, t
AddServer.optionsOptions d'ajout de serveurt

server correspond aux informations du serveur issues de /api/servers ; les composants peuvent lire extension_data et extension_status[<extension_id>] (le résultat de server.list_enrich).


6. Gérer les extensions via l'API REST

GET    /api/extensions                   Liste installée (+ échecs de chargement)
GET    /api/extensions/init-status       Résultats de daemon.startup
POST   /api/extensions/rescan            Relire le dossier
GET    /api/extensions/manifest          Catalogue distant (manifeste de versions signé)
GET    /api/extensions/updates           Liste des mises à jour
POST   /api/extensions/:id/install       Installer (depuis le catalogue, sha256 vérifié)
POST   /api/extensions/:id/enable        Activer → exécute le daemon.startup de cette extension
POST   /api/extensions/:id/disable       Désactiver
POST   /api/extensions/:id/mount         Enregistrer en mémoire
POST   /api/extensions/:id/unmount       Retirer de la mémoire
DELETE /api/extensions/:id               Supprimer
GET    /api/extensions/:id/config        Valeurs de config_fields
PUT    /api/extensions/:id/config        Mettre à jour les valeurs
GET    /api/extensions/:id/gui           Bundle GUI (JS)
GET    /api/extensions/:id/gui/styles    Styles GUI (CSS)
GET    /api/extensions/:id/icon          Icône
GET    /api/extensions/:id/audit         Comparer les capacités utilisées par le code avec les permissions
GET    /api/extensions/:id/i18n/:locale  JSON de langue

La liste des extensions activées est stockée dans extensions.enabled de config.json, et les valeurs des paramètres globaux dans extensions.settings.


7. Règles de développement

  • Les extensions ne doivent pas non plus dépendre du code du démon. N'utilisez que le contexte et les variables d'environnement transmis par le démon.
  • Construisez les chemins avec os.path.join ; ne les codez pas en dur.
  • Les fonctions de hook répondent elles aussi aux échecs par du JSON (success: false et une raison) avec le code de sortie 0, et envoient les logs et les tracebacks sur stderr.
  • N'utilisez que la forme instance.ext_data.<key> pour condition. Toute autre forme est toujours évaluée à faux.
  • Les dépendances Python utilisent l'environnement partagé du démon. Il n'y a pas de déclaration de dépendances par extension.
  • Extensions non vérifiées : les extensions qui n'ont pas été téléchargées depuis le catalogue signé, ou qui ont été modifiées après le téléchargement, s'exécutent dans le même environnement isolé que les modules (AppContainer sous Windows, bubblewrap sous Linux). Aucune analyse antivirus n'est effectuée. Ce qui suit vaut pour Windows. Elles ne peuvent pas atteindre le loopback (comme l'API du démon), ne reçoivent pas SABA_TOKEN_PATH et ne peuvent que lire les dossiers d'instance. Placez les données que vous devez écrire dans le dossier dédié désigné par la variable d'environnement SABA_EXTENSION_DATA_DIR.
  • Exécutez les tests avec pytest depuis la racine du dépôt.