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
- 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'
iddu manifeste. L'id avec les tirets remplacés par des underscores est également accepté (p. ex. idue4-ini→ dossierue4_ini). Sinon, le démon ne la charge pas et la liste sousfaileddansGET /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: Avec1, les clés inconnues, les noms de hooks absents deFIRED_HOOKSet les références à despython_modulesinexistants sont des erreurs. Sans ce champ (0), ce ne sont que des avertissements.id,name,version: Obligatoires.versionsert 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 (ousaba-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é danspython_modulesfunction: le nom de la fonction dans ce fichiercondition(facultatif) : seule la formeinstance.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 dansextensions.settings.<id>deconfig.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
asyncsur les hooks ni demanifest_urldans 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 hook | Moment de l'appel | Utilisation du résultat | Exécution |
|---|---|---|---|
daemon.startup | Juste 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.shutdown | Juste avant l'arrêt du démon | Journalisé uniquement | Synchrone |
server.pre_start | Juste avant le démarrage d'un serveur | handled: true remplace le démarrage par défaut (si success n'est pas vrai dans ce cas, le démarrage échoue) | Synchrone |
server.stop | Juste avant l'arrêt d'un serveur | handled: true prend en charge l'arrêt | Synchrone |
server.status | Lors de la consultation de l'état d'un serveur | handled: true renvoie ce résultat tel quel | Synchrone |
server.list_enrich | Lors du listage des instances | handled: true remplit status et extension_status. Délai de 10 s, cache TTL de 30 s | Synchrone |
server.post_create | Juste après la création d'une instance | Résultat non utilisé | Arrière-plan |
server.pre_delete | Juste avant la suppression d'une instance | Si handled, attend brièvement que les verrous de fichiers soient libérés | Synchrone |
server.settings_changed | Après l'enregistrement des paramètres d'une instance | Résultat non utilisé | Synchrone |
server.check_update | Lorsqu'une vérification de mise à jour est demandée | Le premier résultat réussi devient la réponse | Synchrone |
Des noms comme
server.pre_create,server.pre_install,server.post_install,server.post_start,module.parse_settingsetmodule.write_settingsn'existent pas ; les utiliser dans un manifesteschema_version = 1fait é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 pashandledsauf 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(classeSteamCMD: 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_serverdu module viafrom 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 dossierue4_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 deSABA_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.Reactde 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/:localedans l'espace de nomsext_<id>.
| Id du slot | Emplacement | props |
|---|---|---|
ServerCard.badge | Badge de la carte serveur | server |
ServerCard.headerGauge | Jauge d'en-tête de la carte serveur | server |
ServerCard.provision | Carte serveur pendant le provisionnement | server, provisionProgress, onDismiss, t |
ServerCard.expandedStats | Statistiques de la carte serveur dépliée | server, t |
ServerSettings.tab | Onglet des paramètres du serveur | server, activeTab, setActiveTab, settings, onSettingsChange, t |
AddServer.options | Options d'ajout de serveur | t |
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: falseet 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>pourcondition. 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_PATHet 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'environnementSABA_EXTENSION_DATA_DIR. - Exécutez les tests avec
pytestdepuis la racine du dépôt.