Aller au contenu

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).

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).

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.

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.

sdk/proto est la source unique de vérité. Trois services concernent tout module :

module.proto
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.proto
service 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.

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.