Le module xcraft-core-busclient est le client principal pour le bus de communication Xcraft. Il fournit les interfaces nécessaires pour se connecter à un serveur Xcraft, envoyer des commandes et gérer les événements (publication et souscription). Ce module constitue la couche de communication fondamentale entre les différents composants de l'écosystème Xcraft.
- Structure du module
- Fonctionnement global
- Exemples d'utilisation
- Interactions avec d'autres modules
- Configuration avancée
- Détails des sources
Le module s'articule autour de plusieurs composants principaux :
- BusClient : Classe principale gérant la connexion au bus Xcraft
- Command : Gestionnaire pour l'envoi de commandes
- Events : Gestionnaire pour la publication et souscription d'événements
- Resp : Interface de réponse unifiée combinant commandes et événements
- Instance globale : Client partagé entre tous les modules
Le BusClient utilise deux sockets distincts basés sur le module xcraft-core-transport :
- Socket SUB : Pour recevoir les événements et notifications
- Socket PUSH : Pour envoyer les commandes
Le client peut fonctionner en deux modes :
- Mode serveur : Connexion directe avec un token fourni
- Mode client : Autoconnexion automatique via le mécanisme de heartbeat
Le processus d'autoconnexion :
- Le client s'abonne aux événements
greathall::* - Il attend le heartbeat du serveur (
greathall::heartbeat) - Il envoie une commande
autoconnectavec un token temporaire - Le serveur répond avec le token définitif et les informations de configuration
Le système détecte automatiquement les déconnexions et tente de se reconnecter :
- Détection des pertes de connexion sur les deux sockets
- Mécanisme de reconnexion automatique avec gestion des timeouts
- Émission d'événements pour notifier les changements d'état
- Protection spéciale pour les nœuds internes (localhost) qui provoquent un arrêt complet en cas de perte
Le module supporte plusieurs mécanismes de sécurité :
- TLS : Chiffrement des communications avec certificats
- Tokens : Authentification par tokens dynamiques
- Certificats clients : Authentification mutuelle pour les hordes
- Gatekeeper : Système de contrôle d'accès avancé
const xBusClient = require('xcraft-core-busclient');
// Initialisation du client global
const globalClient = xBusClient.initGlobal();
// Connexion au serveur
globalClient.connect('ee', null, (err) => {
if (err) {
console.error('Erreur de connexion:', err);
return;
}
console.log('Connecté au bus Xcraft');
});const resp = xBusClient.newResponse('mon-module', 'greathall');
// Envoi d'une commande avec callback
resp.command.send('warehouse.get', {path: 'app.name'}, (err, result) => {
if (err) {
console.error('Erreur:', err);
return;
}
console.log('Résultat:', result.data);
});
// Envoi asynchrone
const result = await resp.command.sendAsync('warehouse.get', {
path: 'app.name',
});
console.log('Résultat:', result);// Souscription à un événement
const unsubscribe = resp.events.subscribe('warehouse::changed', (msg) => {
console.log('Warehouse modifié:', msg.data);
});
// Publication d'un événement (côté serveur uniquement)
resp.events.send('mon-module::status.changed', {status: 'ready'});
// Désabonnement
unsubscribe();const {BusClient} = require('xcraft-core-busclient');
// Configuration personnalisée avec TLS
const customConfig = {
host: 'remote-server.com',
commanderPort: 3001,
notifierPort: 3002,
caPath: '/path/to/server-cert.pem',
keyPath: '/path/to/client-key.pem',
certPath: '/path/to/client-cert.pem',
};
const customClient = new BusClient(customConfig);
customClient.connect('axon', null, (err) => {
// Gestion de la connexion
});const resp = xBusClient.newResponse('mon-module', 'greathall');
// Écoute des événements de reconnexion
const unsubReconnect = resp.onReconnect((status) => {
if (status === 'attempt') {
console.log('Tentative de reconnexion...');
} else if (status === 'done') {
console.log('Reconnexion réussie');
}
});
// Écoute des changements de token
const unsubToken = resp.onTokenChanged((busConfig) => {
console.log('Token changé, nouvelle configuration:', busConfig);
});- xcraft-core-transport : Fournit les sockets Router pour la communication
- xcraft-core-bus : Interface serveur complémentaire
- xcraft-core-etc : Gestion de la configuration du bus
- xcraft-core-host : Informations sur l'environnement d'exécution
- xcraft-core-log : Système de logging
- xcraft-core-utils : Utilitaires pour la cryptographie et les expressions régulières
- fs-extra : Opérations sur le système de fichiers
- uuid : Génération d'identifiants uniques
| Option | Description | Type | Valeur par défaut |
|---|---|---|---|
caPath |
Chemin vers le certificat serveur (format PEM) | string |
'' |
Le module utilise les variables d'environnement via la configuration du bus (xcraft-core-bus) :
| Variable | Description | Exemple | Valeur par défaut |
|---|---|---|---|
XCRAFT_TLS |
Active/désactive TLS | false |
true |
Fichier principal exportant la classe BusClient et les fonctions utilitaires. La classe BusClient hérite d'EventEmitter et gère :
- Connexion : Établissement et maintien de la connexion au serveur
- Autoconnexion : Mécanisme automatique de connexion via heartbeat
- Registre des commandes : Cache des commandes disponibles sur le serveur
- Gestion des tokens : Authentification et autorisation
- Reconnexion : Détection et récupération des déconnexions
- Sécurité TLS : Gestion des certificats et chiffrement
- Gestion des certificats clients : Support pour l'authentification mutuelle
connect(backend, busToken, callback)— Établit la connexion au serveur avec le backend spécifié (ee ou axon)stop(callback)— Ferme proprement les connexions au busnewMessage(topic, which)— Crée un nouveau message formaté pour les commandespatchMessage(msg)— Modifie un message pour le retransmettre à un autre serveurregisterEvents(topic, handler)— Enregistre un gestionnaire d'événements avec support des expressions régulièresunregisterEvents(topic)— Supprime un gestionnaire d'événementsisConnected()— Retourne l'état de connexiongetToken()— Retourne le token d'authentification actuelgetOrcName()— Retourne le nom de l'orc (identifiant du client)getCommandsRegistry()— Retourne le registre des commandes disponiblesgetCommandsRegistryTime()— Retourne l'horodatage du dernier registre de commandesgetCommandsNames()— Retourne la liste des noms de commandes avec leurs prédictions de rankingisServerSide()— Indique si le client fonctionne côté serveurgetNice()— Retourne la valeur de priorité (nice) du clientdestroyPushSocket()— Détruit le socket de commandeslastErrorReason— Propriété getter retournant la dernière raison d'erreur
Gestionnaire pour l'envoi de commandes sur le bus. Cette classe encapsule la logique d'envoi de commandes avec :
- Gestion des callbacks : Souscription automatique aux événements de fin de commande
- Support RPC : Mécanisme d'appel de procédure distante avec gestion des timeouts
- Routage : Gestion du routage des messages entre différents nœuds
- Gestion d'erreurs : Traitement des erreurs et exceptions avec stack traces
- Annulation de commandes : Mécanisme d'annulation pour les commandes RPC
- Gestion des déconnexions : Annulation automatique des commandes en cours lors de déconnexions
send(cmd, data, which, finishHandler, options, msgContext)— Envoie une commande sur le bus avec gestion optionnelle des callbacksretry(msg)— Retente l'envoi d'un message précédemment échouénewMessage(cmd, which)— Crée un nouveau message de commandeconnectedWith()— Retourne les informations de connexion du socket
abort(commandId)— Annule une commande RPC spécifiqueabortAll(err)— Annule toutes les commandes RPC en cours
Gestionnaire pour la publication et souscription d'événements. Cette classe fournit :
- Souscription multiple : Support de plusieurs handlers par topic avec gestion fine des désabonnements
- Sérialisation : Sérialisation/désérialisation automatique des objets complexes incluant les fonctions
- Filtrage : Support des expressions régulières pour les topics
- Performance : Optimisations pour réduire le bruit des logs
- Gestion des activités : Support pour les événements d'activité
subscribe(topic, handler, backend, orcName, options)— S'abonne à un événement avec un gestionnaire spécifiqueunsubscribeAll(topic, backend, orcName)— Se désabonne complètement d'un topicsend(topic, data, serialize, routing, msgContext)— Publie un événement (côté serveur uniquement)catchAll(handler, proxy)— Capture tous les événements avec un gestionnaire globalheartbeat()— Envoie un heartbeat (côté serveur uniquement)lastPerf()— Retourne les dernières métriques de performanceconnectedWith()— Retourne les informations de connexion du socket
status— Énumération des statuts d'événements (succeeded: 1, failed: 2, canceled: 3)
Interface unifiée combinant les fonctionnalités de commandes et d'événements. Cette classe encapsule :
- Interface simplifiée : API unifiée pour commandes et événements
- Gestion du contexte : Propagation automatique du contexte des messages
- Logging intégré : Système de logs contextualisé par module
- Callbacks de lifecycle : Notifications des changements d'état de connexion
- Support des tokens spéciaux : Gestion du token 'token' pour les communications serveur
Events (dans resp.js) :
subscribe(topic, handler)— Souscription simplifiée avec préfixage automatique du namespacesend(topic, data, serialize, forwarding, context)— Publication avec support du forwardingcatchAll(handler)— Capture globale des événementsunsubscribeAll(topic)— Désabonnement simplifié
Command (dans resp.js) :
sendAsync(cmd, data)— Version asynchrone moderne de l'envoi de commandessend(cmd, data, finishHandler)— Version legacy avec callback (dépréciée)nestedSend(cmd, data, finishHandler)— Version legacy pour commandes imbriquées (dépréciée)retry(msg)— Nouvelle tentative d'envoi
onTokenChanged(callback)— Écoute les changements de token d'authentificationonOrcnameChanged(callback)— Écoute les changements de nom d'orconReconnect(callback)— Écoute les tentatives et succès de reconnexiononCommandsRegistry(callback, data)— Écoute les mises à jour du registre de commandeshasCommand(cmdName)— Vérifie la disponibilité d'une commandegetCommandsRegistry()— Retourne le registre des commandes disponiblesgetCommandsRegistryTime()— Retourne l'horodatage du registregetCommandsNames()— Retourne les noms de commandes avec métadonnéesisConnected()— Retourne l'état de connexion
orcName— Nom de l'orc associé à cette instance de Resplog— Logger contextualisé pour le modulemsgContext— Contexte de message (setter)
Ce document a été mis à jour pour refléter la structure et les fonctionnalités actuelles du module.