xcraft-core-busclient 5.9.0 → 5.11.0

package/README.md

@@ -1,10 +1,330 @@
-# xcraft-core-busclient
+# 📘 Documentation du module xcraft-core-busclient
 
-Client for the Xcraft bus.
+## Aperçu
 
-This module provides the interfaces in order to connect to a server, send
-commands and send or subscribe to events.
+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.
 
-It provides the global busClient too. This handler must be used between the
-modules in order to have always the same connection everywhere. Otherwise
-you can connect to several servers by instancing a new busClient for each one.
+## Sommaire
+
+- [Structure du module](#structure-du-module)
+- [Fonctionnement global](#fonctionnement-global)
+- [Exemples d'utilisation](#exemples-dutilisation)
+- [Interactions avec d'autres modules](#interactions-avec-dautres-modules)
+- [Configuration avancée](#configuration-avancée)
+- [Détails des sources](#détails-des-sources)
+
+## Structure du module
+
+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
+
+## Fonctionnement global
+
+### Architecture de communication
+
+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
+
+### Mécanisme d'autoconnexion
+
+Le client peut fonctionner en deux modes :
+
+1. **Mode serveur** : Connexion directe avec un token fourni
+2. **Mode client** : Autoconnexion automatique via le mécanisme de heartbeat
+
+Le processus d'autoconnexion :
+
+1. Le client s'abonne aux événements `greathall::*`
+2. Il attend le heartbeat du serveur (`greathall::heartbeat`)
+3. Il envoie une commande `autoconnect` avec un token temporaire
+4. Le serveur répond avec le token définitif et les informations de configuration
+
+### Gestion des reconnexions
+
+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
+
+### Sécurité et authentification
+
+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é
+
+## Exemples d'utilisation
+
+### Utilisation du client global
+
+```javascript
+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');
+});
+```
+
+### Envoi de commandes
+
+```javascript
+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);
+```
+
+### Gestion des événements
+
+```javascript
+// 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();
+```
+
+### Instance personnalisée avec TLS
+
+```javascript
+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
+});
+```
+
+### Gestion des reconnexions
+
+```javascript
+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);
+});
+```
+
+## Interactions avec d'autres modules
+
+### Modules de transport
+
+- **[xcraft-core-transport]** : Fournit les sockets Router pour la communication
+- **[xcraft-core-bus]** : Interface serveur complémentaire
+
+### Modules de configuration
+
+- **[xcraft-core-etc]** : Gestion de la configuration du bus
+- **[xcraft-core-host]** : Informations sur l'environnement d'exécution
+
+### Modules utilitaires
+
+- **[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
+
+## Configuration avancée
+
+| Option   | Description                                    | Type     | Valeur par défaut |
+| -------- | ---------------------------------------------- | -------- | ----------------- |
+| `caPath` | Chemin vers le certificat serveur (format PEM) | `string` | `''`              |
+
+### Variables d'environnement
+
+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`            |
+
+## Détails des sources
+
+### `index.js`
+
+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
+
+#### Méthodes publiques
+
+- **`connect(backend, busToken, callback)`** — Établit la connexion au serveur avec le backend spécifié (ee ou axon)
+- **`stop(callback)`** — Ferme proprement les connexions au bus
+- **`newMessage(topic, which)`** — Crée un nouveau message formaté pour les commandes
+- **`patchMessage(msg)`** — Modifie un message pour le retransmettre à un autre serveur
+- **`registerEvents(topic, handler)`** — Enregistre un gestionnaire d'événements avec support des expressions régulières
+- **`unregisterEvents(topic)`** — Supprime un gestionnaire d'événements
+- **`isConnected()`** — Retourne l'état de connexion
+- **`getToken()`** — Retourne le token d'authentification actuel
+- **`getOrcName()`** — Retourne le nom de l'orc (identifiant du client)
+- **`getCommandsRegistry()`** — Retourne le registre des commandes disponibles
+- **`getCommandsRegistryTime()`** — Retourne l'horodatage du dernier registre de commandes
+- **`getCommandsNames()`** — Retourne la liste des noms de commandes avec leurs prédictions de ranking
+- **`isServerSide()`** — Indique si le client fonctionne côté serveur
+- **`getNice()`** — Retourne la valeur de priorité (nice) du client
+- **`destroyPushSocket()`** — Détruit le socket de commandes
+- **`lastErrorReason`** — Propriété getter retournant la dernière raison d'erreur
+
+### `lib/command.js`
+
+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
+
+#### Méthodes publiques
+
+- **`send(cmd, data, which, finishHandler, options, msgContext)`** — Envoie une commande sur le bus avec gestion optionnelle des callbacks
+- **`retry(msg)`** — Retente l'envoi d'un message précédemment échoué
+- **`newMessage(cmd, which)`** — Crée un nouveau message de commande
+- **`connectedWith()`** — Retourne les informations de connexion du socket
+
+#### Méthodes statiques
+
+- **`abort(commandId)`** — Annule une commande RPC spécifique
+- **`abortAll(err)`** — Annule toutes les commandes RPC en cours
+
+### `lib/events.js`
+
+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é
+
+#### Méthodes publiques
+
+- **`subscribe(topic, handler, backend, orcName, options)`** — S'abonne à un événement avec un gestionnaire spécifique
+- **`unsubscribeAll(topic, backend, orcName)`** — Se désabonne complètement d'un topic
+- **`send(topic, data, serialize, routing, msgContext)`** — Publie un événement (côté serveur uniquement)
+- **`catchAll(handler, proxy)`** — Capture tous les événements avec un gestionnaire global
+- **`heartbeat()`** — Envoie un heartbeat (côté serveur uniquement)
+- **`lastPerf()`** — Retourne les dernières métriques de performance
+- **`connectedWith()`** — Retourne les informations de connexion du socket
+
+#### Propriétés
+
+- **`status`** — Énumération des statuts d'événements (succeeded: 1, failed: 2, canceled: 3)
+
+### `lib/resp.js`
+
+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
+
+#### Classes internes
+
+**Events** (dans resp.js) :
+
+- **`subscribe(topic, handler)`** — Souscription simplifiée avec préfixage automatique du namespace
+- **`send(topic, data, serialize, forwarding, context)`** — Publication avec support du forwarding
+- **`catchAll(handler)`** — Capture globale des événements
+- **`unsubscribeAll(topic)`** — Désabonnement simplifié
+
+**Command** (dans resp.js) :
+
+- **`sendAsync(cmd, data)`** — Version asynchrone moderne de l'envoi de commandes
+- **`send(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
+
+#### Méthodes publiques de Resp
+
+- **`onTokenChanged(callback)`** — Écoute les changements de token d'authentification
+- **`onOrcnameChanged(callback)`** — Écoute les changements de nom d'orc
+- **`onReconnect(callback)`** — Écoute les tentatives et succès de reconnexion
+- **`onCommandsRegistry(callback, data)`** — Écoute les mises à jour du registre de commandes
+- **`hasCommand(cmdName)`** — Vérifie la disponibilité d'une commande
+- **`getCommandsRegistry()`** — Retourne le registre des commandes disponibles
+- **`getCommandsRegistryTime()`** — Retourne l'horodatage du registre
+- **`getCommandsNames()`** — Retourne les noms de commandes avec métadonnées
+- **`isConnected()`** — Retourne l'état de connexion
+
+#### Propriétés
+
+- **`orcName`** — Nom de l'orc associé à cette instance de Resp
+- **`log`** — Logger contextualisé pour le module
+- **`msgContext`** — Contexte de message (setter)
+
+---
+
+_Ce document a été mis à jour pour refléter la structure et les fonctionnalités actuelles du module._
+
+[xcraft-core-transport]: https://github.com/Xcraft-Inc/xcraft-core-transport
+[xcraft-core-bus]: https://github.com/Xcraft-Inc/xcraft-core-bus
+[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc
+[xcraft-core-host]: https://github.com/Xcraft-Inc/xcraft-core-host
+[xcraft-core-log]: https://github.com/Xcraft-Inc/xcraft-core-log
+[xcraft-core-utils]: https://github.com/Xcraft-Inc/xcraft-core-utils

package/index.js

@@ -429,13 +429,10 @@ class BusClient extends EventEmitter {
    * @param {Function} callback - Callback.
    */
   connect(backend, busToken, callback) {
-    const fs = require('fs');
-    const path = require('path');
+    const fse = require('fs-extra');
+    const path = require('node:path');
     const xEtc = require('xcraft-core-etc')();
-    const xHost = require('xcraft-core-host');
-
-    const {resourcesPath} = xHost;
-    const appArgs = xHost.appArgs();
+    const xHost = xEtc ? require('xcraft-core-host') : null;
 
     xLog.verb('Connecting...');
 
@@ -466,6 +463,7 @@ class BusClient extends EventEmitter {
     if (!busConfig) {
       busConfig = xEtc.load('xcraft-core-bus');
     } else if (
+      xEtc &&
       !Object.prototype.hasOwnProperty.call(busConfig, 'clientKeepAlive')
     ) {
       const {clientKeepAlive} = xEtc.load('xcraft-core-bus');
@@ -474,13 +472,15 @@ class BusClient extends EventEmitter {
 
     /* The TLS certificate is ignored in case of unix socket use */
     if (
-      appArgs.tls !== false &&
+      xHost &&
+      xHost.resourcesPath &&
+      xHost.appArgs().tls !== false &&
       !busConfig.noTLS &&
       !busConfig.unixSocketId &&
       !busConfig.caPath
     ) {
-      const resCaPath = path.join(resourcesPath, 'server-cert.pem');
-      if (fs.existsSync(resCaPath)) {
+      const resCaPath = path.join(xHost.resourcesPath, 'server-cert.pem');
+      if (fse.existsSync(resCaPath)) {
         busConfig.caPath = resCaPath;
         xEtc.saveRun('xcraft-core-busclient', busConfig);
       }
@@ -496,6 +496,7 @@ class BusClient extends EventEmitter {
     };
 
     if (
+      xHost &&
       busConfig.gatekeeper &&
       busConfig.hordeId &&
       !busConfig.keyPath &&
@@ -518,10 +519,12 @@ class BusClient extends EventEmitter {
       .filter((key) => busConfig[key])
       .forEach((key) => {
         if (
+          xHost &&
+          xHost.resourcesPath &&
           !busConfig[key].startsWith('base64:') &&
           !path.isAbsolute(busConfig[key])
         ) {
-          options[key] = path.join(resourcesPath, busConfig[key]);
+          options[key] = path.join(xHost.resourcesPath, busConfig[key]);
         } else {
           options[key] = busConfig[key];
         }

package/lib/command.js

@@ -2,20 +2,22 @@
 
 const moduleName = 'busclient/command';
 
-const xBus = require('xcraft-core-bus');
 const xLog = require('xcraft-core-log')(moduleName, null);
 
 class Command {
   static #unsubList = new Map(); /* Only for _xcraftRPC messages */
+  _routingKey;
 
   constructor(busClient, pushSocket) {
     this._busClient = busClient;
     this._push = pushSocket;
 
-    const {appId, appArgs} = require('xcraft-core-host');
-    const {tribe} = appArgs();
-
-    this._routingKey = tribe ? `${appId}-${tribe}` : appId;
+    const xEtc = require('xcraft-core-etc')();
+    if (xEtc) {
+      const {appId, appArgs} = require('xcraft-core-host');
+      const {tribe} = appArgs();
+      this._routingKey = tribe ? `${appId}-${tribe}` : appId;
+    }
 
     this._push
       .on('close', (err) => this.#onNetworkChange(err))
@@ -102,7 +104,9 @@ class Command {
     }
 
     if (!busMessage.arp) {
-      let token = xBus.getToken();
+      let token = require('xcraft-core-etc')()
+        ? require('xcraft-core-bus').getToken()
+        : null;
       let nodeName = this._routingKey;
       let {orcName} = busMessage;
       let nice = 0;

package/lib/events.js

@@ -3,7 +3,6 @@
 const moduleName = 'busclient/events';
 
 const xLog = require('xcraft-core-log')(moduleName, null);
-const xBus = require('xcraft-core-bus');
 
 class Events {
   constructor(busClient, subSocket) {
@@ -140,6 +139,7 @@ class Events {
     }
 
     const topic = 'greathall::heartbeat';
+    const xBus = require('xcraft-core-bus');
     const notifier = xBus.getNotifier();
 
     notifier.send(topic);
@@ -172,6 +172,7 @@ class Events {
     }
 
     const which = topic.split('::', 1)[0];
+    const xBus = require('xcraft-core-bus');
     const notifier = xBus.getNotifier();
 
     let busMessage = data;

package/lib/resp.js

@@ -1,12 +1,11 @@
 'use strict';
 
 const {promisify} = require('node:util');
-const watt = require('gigawatts');
 
 class Events {
-  constructor(busClient, log, orcName, routing, msgContext) {
-    this._log = log;
-    this._busClient = busClient;
+  constructor(resp, orcName, routing, msgContext) {
+    this._resp = resp;
+    this._busClient = resp._busClient;
     this._orcName = orcName;
     this._routing = routing;
     this._msgContext = msgContext;
@@ -28,7 +27,7 @@ class Events {
 
   catchAll(handler) {
     if (!this._busClient) {
-      this._log.err('events.catchAll not available');
+      this._resp.log.err('events.catchAll not available');
       return;
     }
     this._busClient.events.catchAll(handler);
@@ -36,7 +35,7 @@ class Events {
 
   subscribe(topic, handler) {
     if (!this._busClient) {
-      this._log.err('events.subscribe not available');
+      this._resp.log.err('events.subscribe not available');
       return;
     }
 
@@ -50,7 +49,7 @@ class Events {
 
   unsubscribeAll(topic) {
     if (!this._busClient) {
-      this._log.err('events.unsubscribe not available');
+      this._resp.log.err('events.unsubscribe not available');
       return;
     }
 
@@ -59,7 +58,7 @@ class Events {
 
   send(topic, data, serialize, forwarding = null, context = null) {
     if (!this._busClient) {
-      this._log.err('events.send not available');
+      this._resp.log.err('events.send not available');
       return;
     }
 
@@ -97,9 +96,9 @@ class Events {
 }
 
 class Command {
-  constructor(busClient, log, orcName, msgContext) {
-    this._log = log;
-    this._busClient = busClient;
+  constructor(resp, orcName, msgContext) {
+    this._resp = resp;
+    this._busClient = resp._busClient;
     this._orcName = orcName;
     this._msgContext = msgContext;
     this._sendAsync = promisify(this._send).bind(this);
@@ -111,7 +110,7 @@ class Command {
 
   retry(msg) {
     if (!this._busClient) {
-      this._log.err('command.retry not available');
+      this._resp.log.err('command.retry not available');
       return;
     }
 
@@ -120,7 +119,7 @@ class Command {
 
   _send(cmd, data, options, finishHandler) {
     if (!this._busClient) {
-      this._log.err('command.send not available');
+      this._resp.log.err('command.send not available');
       return;
     }
 
@@ -152,6 +151,9 @@ class Command {
 }
 
 class Resp {
+  #moduleName;
+  #log;
+
   constructor(
     busClient,
     moduleName,
@@ -159,6 +161,7 @@ class Resp {
     routing = null,
     msgContext = null
   ) {
+    this.#moduleName = moduleName;
     this._busClient = busClient;
     this._orcName = orcName;
     /* Add a way for sending with the token server instead of an orcName */
@@ -172,11 +175,8 @@ class Resp {
       orcName = 'greathall@' + token;
     }
 
-    this.log = require('xcraft-core-log')(moduleName, this);
-    this.events = new Events(busClient, this.log, orcName, routing, msgContext);
-    this.command = new Command(busClient, this.log, orcName, msgContext);
-
-    watt.wrapAll(this, 'connect', 'stop');
+    this.events = new Events(this, orcName, routing, msgContext);
+    this.command = new Command(this, orcName, msgContext);
   }
 
   set msgContext(value) {
@@ -188,12 +188,11 @@ class Resp {
     return this._orcName;
   }
 
-  *connect(next) {
-    yield this._busClient.connect('axon', null, next);
-  }
-
-  *stop(next) {
-    yield this._busClient.stop(next);
+  get log() {
+    if (!this.#log) {
+      this.#log = require('xcraft-core-log')(this.#moduleName, this);
+    }
+    return this.#log;
   }
 
   isConnected() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xcraft-core-busclient",
-  "version": "5.9.0",
+  "version": "5.11.0",
   "description": "Xcraft bus client",
   "main": "index.js",
   "engines": {
@@ -19,8 +19,7 @@
     "url": "git+https://github.com/Xcraft-Inc/xcraft-core-busclient.git"
   },
   "dependencies": {
-    "fs-extra": "^9.1.0",
-    "gigawatts": "^4.0.1",
+    "fs-extra": "^11.3.0",
     "uuid": "^8.3.2",
     "xcraft-core-bus": "^5.0.0",
     "xcraft-core-host": "^3.0.0",