📚 Bus Event Protocol Documentation

Complete reference for LatamDrop Bus events and integration

🚀 Quick Start

Connect your service to the Bus using Socket.IO:

const { io } = require('socket.io-client');

const socket = io('http://localhost:7440', {
  query: { app: 'My Service' },
  auth: { appId: 'my_service', appName: 'My Service', appPort: 3000 }
});

// Register with the bus
socket.emit('bus:register', {
  id: 'my_service',
  name: 'My Service',
  type: 'platform-app',
  port: 3000,
  version: '1.0.0',
  capabilities: [{ name: 'users', description: 'User management' }]
});

📡 Bus Events

Event	Direction	Description	Payload
bus:register	Client → Bus	Service announces itself to the bus	{ id, name, type, port, version, capabilities }
bus:heartbeat	Client → Bus	Periodic health check (every 10s recommended)	{ uptime, memory, cpu, timestamp }
bus:request	Client ↔ Bus	Request to another service via capability	{ requestId, capability, action, payload }
bus:response	Client → Bus	Response to a request	{ requestId, success, data/error }
bus:notify	Client → Bus	Broadcast event to all services	{ event, data }
bus:restart	Bus → Client	Admin command to restart service	{ reason, timestamp }
bus:shutdown	Bus → Client	Admin command to shutdown service	{ reason, timestamp }
bus:ping	Bus → Client	Ping request from admin	{ timestamp }
config:request	Client → Bus	Request central configuration	(callback returns config)
config:updated	Bus → All	Config was updated	(full config object)
service:online	Bus → All	A service came online	{ id, name }
service:offline	Bus → All	A service went offline	{ id, name }
bus:reregister-request	Bus → All	Request services to re-register (sent after Bus restart)	{ reason, timestamp }

🔌 REST API

Method	Endpoint	Description
GET	/api/services	List all registered services
GET	/api/services/:id	Get service details
PUT	/api/services/:id	Update service metadata
DELETE	/api/services/:id	Remove service from registry
POST	/api/services/:id/restart	Send restart command to service
POST	/api/services/:id/ping	Ping service
POST	/api/services/restart-all	Restart all connected services
GET	/api/stats	Get bus statistics
GET	/api/config	Get central configuration
POST	/api/config	Update central configuration

💡 Full Client Example

const { io } = require('socket.io-client');
const os = require('os');

class BusClient {
  constructor(config) {
    this.config = config;
    this.socket = null;
  }

  connect() {
    this.socket = io(this.config.busUrl, {
      query: { app: this.config.name },
      auth: {
        appId: this.config.id,
        appName: this.config.name,
        appPort: this.config.port
      }
    });

    this.socket.on('connect', () => {
      console.log('Connected to Bus');
      this.register();
      this.startHeartbeat();
    });

    // Listen for restart command
    this.socket.on('bus:restart', (data) => {
      console.log('Restart requested:', data.reason);
      process.exit(0); // PM2 will restart
    });

    // Listen for config updates
    this.socket.on('config:updated', (config) => {
      console.log('Config updated:', config);
      // Apply new config...
    });
  }

  register() {
    this.socket.emit('bus:register', {
      id: this.config.id,
      name: this.config.name,
      type: 'platform-app',
      port: this.config.port,
      version: this.config.version,
      capabilities: this.config.capabilities || []
    });
  }

  startHeartbeat() {
    setInterval(() => {
      const mem = process.memoryUsage();
      this.socket.emit('bus:heartbeat', {
        uptime: process.uptime(),
        memory: Math.round(mem.heapUsed / 1024 / 1024),
        cpu: os.loadavg()[0],
        timestamp: Date.now()
      });
    }, 10000);
  }
}

module.exports = BusClient;