Créer un module

Écrire un module est une activité au niveau du code : on travaille depuis les sources et on intervient dans l’orchestrateur. Voici les étapes.

sequenceDiagram
    participant M as Module
    participant O as Orchestrateur
    participant S as SFU
    M->>O: ModuleRegistry.Register(name, version, capabilities, grpc_addr)
    O-->>M: RegisterResponse(accepted, module_id, heartbeat, config_json)
    Note over O,S: wire_hooks_from_store() relie les hooks selon les capacités
    S-->>O: hook (on_command / on_media_out / on_lifecycle...)
    O->>M: appel gRPC vers le module
    M-->>O: Heartbeat (périodique)

Les étapes

1. Définir la capacité. Ajoutez une variante à l’enum Capability dans sdk/traits/src/types.rs (ou utilisez Custom(String)).

2. Définir le service gRPC. Si le module a besoin de ses propres appels, ajoutez un fichier .proto dans sdk/proto/proto/ ; les stubs Rust sont générés à la compilation.

3. Implémenter le module. Écrivez un binaire autonome (un serveur gRPC) qui respecte le contrat du SDK.

4. S’enregistrer. Au démarrage, le module appelle ModuleRegistry.Register en déclarant son nom, sa version, ses capacités et son adresse gRPC. Il doit figurer dans la liste autorisée (VUISIO_MODULES_ENABLED), puis émet un battement de cœur (heartbeat) périodique.

   Le SDK (register_with_retry puis spawn_heartbeat) gère seul les redémarrages de l’orchestrateur : le module se réenregistre quand l’orchestrateur ne le connaît plus, et rétablit sa connexion quand celle-ci est perdue, par exemple lorsque l’orchestrateur est recréé. Un module qui n’utilise pas ce mécanisme disparaît de l’interface après une mise à jour du serveur, sans le signaler, jusqu’à son redémarrage manuel.

   Un nouvel enregistrement remplace le précédent pour le même nom de module : un module redémarré n’apparaît jamais en double.

5. Câbler les hooks. Dans bin/vuisio/src/modules.rs (wire_hooks_from_store()), reliez la capacité du module aux hooks du SFU : l’orchestrateur découvre le module et crée son client gRPC, puis route les hooks pertinents vers lui.

6. Interface optionnelle. Un module peut contribuer une interface en déposant un bundle dans modules/<nom>/ui/dist/ ; l’orchestrateur l’expose via son API de modules.

Le câblage est volontairement explicite

La correspondance entre une capacité et les hooks à relier est écrite dans l’orchestrateur, pas découverte automatiquement. Ajouter une nouvelle capacité implique donc de modifier bin/vuisio/src/modules.rs et de recompiler l’orchestrateur. C’est la contrepartie de la règle d’or : le cœur reste générique, et toute connaissance des modules vit dans l’orchestrateur.

Démarrer avec un assistant IA

Si vous développez avec un assistant de code (par exemple Claude Code), vous pouvez lui donner le contexte du projet d’un seul coup. Téléchargez le fichier ci-dessous et placez-le à la racine de votre copie du dépôt, sous le nom CLAUDE.md : il résume l’architecture, le SDK, les quatre hooks, le flux d’enregistrement et les endroits du code à consulter.

Télécharger le CLAUDE.md de développement de module

Ce fichier prêt à l’emploi vous évite de reconstituer ce contexte à la main.