Le contrat de module
Le SDK définit le contrat qu’un module respecte. Il tient en trois crates :
sdk/traits (les types Rust), sdk/proto (les définitions Protobuf) et
sdk/grpc-adapter (le pont gRPC).
Le trait Module
Section intitulée « Le trait Module »Défini dans sdk/traits, c’est le contrat de cycle de vie d’un module côté
Rust :
#[async_trait]pub trait Module: Send + Sync { fn info(&self) -> ModuleInfo; async fn on_start(&self) -> Result<(), ModuleError>; async fn on_event(&self, event: SfuEvent) -> Result<(), ModuleError>; async fn health_check(&self) -> Result<HealthStatus, ModuleError>; async fn on_stop(&self) -> Result<(), ModuleError>;}info() renvoie un ModuleInfo { name, version, capabilities }. Les erreurs
sont des ModuleError (Connection, Transport, Internal, NotReady).
Les capacités
Section intitulée « Les capacités »Un module déclare ce qu’il sait faire avec l’enum Capability :
pub enum Capability { Recording, Analytics, Stun, Custom(String),}Sur le réseau, en revanche, RegisterRequest.capabilities est une liste de
chaînes (recording, transcription, whiteboard, breakout, quizz…).
L’orchestrateur compare ces chaînes telles quelles pour décider quels hooks lui
relier ; LookupModule fait la même comparaison exacte.
Les événements du SFU
Section intitulée « Les événements du SFU »Côté Rust, sdk/traits décrit les événements du SFU par l’enum SfuEvent :
pub enum SfuEvent { RoomCreated { room_id: String }, RoomDestroyed { room_id: String }, ParticipantJoined { room_id: String, participant_id: String, display_name: String }, ParticipantLeft { room_id: String, participant_id: String }, TrackPublished { room_id: String, participant_id: String, track_info: TrackInfo }, TrackUnpublished { room_id: String, participant_id: String, track_id: String },}Un TrackInfo porte track_id, kind (Audio ou Video), codec et
is_screen_share. La santé d’un module s’exprime par HealthStatus
(Healthy, Degraded(String), Unhealthy(String)).
Sur le réseau, le service gRPC EventStream n’utilise pas cette enum : son
SfuEvent est un message protobuf (sequence, type, room_id,
payload_json, timestamp_ms) dont le type est une chaîne de la forme
domaine.evenement. Un abonné filtre par type exact ou par préfixe (room.* ;
une liste vide laisse tout passer) et, à la reconnexion, rejoue ce qu’il a
manqué avec last_seen_seq. L’orchestrateur garde les 1 000 derniers
événements pour ce rejeu. Types émis : room.created, room.ended,
room.participant_joined, room.participant_left, room.track_opened,
room.track_closed, room.chat_message, room.chat_edited,
room.hand_raise, room.reaction, room.waiting_decision,
recording.started, recording.stopped, recording.paused,
recording.resumed, recording.completed, whiteboard.started et
whiteboard.stopped.
Pour le média, sdk/traits définit aussi le format de trame que les modules
échangent avec l’orchestrateur (MediaFrame, FrameHeader, MediaCodec,
MediaTransport) : un en-tête de 10 octets (longueur de la charge sur 4 octets,
horodatage en millisecondes sur 4, indicateur de keyframe, codec), puis la
charge, plafonnée à 4 Mio.
Les services gRPC
Section intitulée « Les services gRPC »sdk/proto est la source unique de vérité. Trois services concernent tout
module :
service ModuleRegistry { rpc Register(RegisterRequest) returns (RegisterResponse); rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse); rpc Deregister(DeregisterRequest) returns (DeregisterResponse); rpc LookupModule(LookupModuleRequest) returns (LookupModuleResponse);}
service EventStream { rpc Subscribe(SubscribeRequest) returns (stream SfuEvent);}
// room.protoservice RoomManagement { rpc CreateRoom(...) returns (...); rpc EndRoom(...) returns (...); rpc IsRoomRunning(...) returns (...); rpc GetRoomInfo(...) returns (...); rpc ListRooms(...) returns (...); rpc SendChatMessage(...) returns (...); rpc NotifyWhiteboardActive(...) returns (...); rpc GetSessionData(...) returns (...); rpc BroadcastRoomMessage(...) returns (...); // + quatre méthodes de gestion des enregistrements publiés}L’enregistrement déclare l’essentiel :
message RegisterRequest { string name = 1; string version = 2; repeated string capabilities = 3; string grpc_addr = 4; repeated string depends_on = 5;}Un module qui a besoin de ses propres appels distants définit son service dans
sdk/proto.
Le pont gRPC
Section intitulée « Le pont gRPC »sdk/grpc-adapter fournit les briques d’intégration utilisées par
l’orchestrateur : le serveur de registre (ModuleRegistryService, ModuleStore,
RegisteredModule), le bus d’événements (EventBus, EventStreamService), et
un point de relai média (ForwardHandle).
Côté module, ModuleRegistration s’enregistre auprès de l’orchestrateur
(register_with_retry, qui réessaie pendant 30 secondes) puis tient
l’enregistrement en vie (spawn_heartbeat, un battement toutes les 10
secondes, avec réenregistrement automatique). deregister_module désenregistre
à l’arrêt propre. Les appels de l’orchestrateur vers un module sont bornés par
VUISIO_MODULE_CONNECT_TIMEOUT_MS et VUISIO_MODULE_CALL_TIMEOUT_MS, voir les
variables d’environnement.