onbuzz 4.9.13 → 4.10.0

package/src/services/serviceRegistry.js

@@ -1,386 +1,386 @@
-/**
- * Service Registry
- *
- * Centralized registry for service discovery. Each service registers itself
- * with its actual port (which may differ from configured if port was taken).
- * Other components query the registry to discover service locations.
- *
- * This registry maintains both in-memory state (for fast access) and
- * file-based persistence (for cross-process discovery via PortRegistry).
- */
-
-import { EventEmitter } from 'events';
-import net from 'net';
-import { getPortRegistry } from './portRegistry.js';
-
-/**
- * Service status enum
- */
-export const ServiceStatus = {
-  STARTING: 'starting',
-  RUNNING: 'running',
-  STOPPING: 'stopping',
-  STOPPED: 'stopped',
-  ERROR: 'error'
-};
-
-/**
- * Service Registry class
- */
-class ServiceRegistry extends EventEmitter {
-  constructor() {
-    super();
-
-    // Registry: serviceName -> ServiceInfo
-    this.services = new Map();
-
-    // Health check interval
-    this.healthCheckInterval = null;
-  }
-
-  /**
-   * Register a service
-   * @param {string} name - Service name (e.g., 'visualEditor', 'backend')
-   * @param {Object} info - Service information
-   * @param {number} info.port - Port the service is running on
-   * @param {string} [info.host='localhost'] - Host address
-   * @param {string} [info.protocol='http'] - Protocol (http, https, ws, wss)
-   * @param {string} [info.status='running'] - Service status
-   * @param {Object} [info.metadata={}] - Additional metadata
-   * @param {boolean} [info.persistToFile=true] - Whether to persist to file registry
-   * @returns {Object} Registered service info
-   */
-  register(name, info) {
-    if (!name) {
-      throw new Error('Service name is required');
-    }
-    if (!info.port) {
-      throw new Error('Service port is required');
-    }
-
-    const serviceInfo = {
-      name,
-      port: info.port,
-      host: info.host || 'localhost',
-      protocol: info.protocol || 'http',
-      status: info.status || ServiceStatus.RUNNING,
-      metadata: info.metadata || {},
-      registeredAt: Date.now(),
-      lastHeartbeat: Date.now()
-    };
-
-    // Build URLs
-    serviceInfo.url = `${serviceInfo.protocol}://${serviceInfo.host}:${serviceInfo.port}`;
-    serviceInfo.wsUrl = `ws://${serviceInfo.host}:${serviceInfo.port}`;
-
-    const isUpdate = this.services.has(name);
-    this.services.set(name, serviceInfo);
-
-    console.log(`[ServiceRegistry] ${isUpdate ? 'Updated' : 'Registered'} service: ${name} at ${serviceInfo.url}`);
-
-    this.emit(isUpdate ? 'service:updated' : 'service:registered', serviceInfo);
-
-    // Persist to file-based registry for cross-process discovery
-    if (info.persistToFile !== false) {
-      this._persistToFile(name, serviceInfo).catch(err => {
-        console.warn(`[ServiceRegistry] Failed to persist ${name} to file registry:`, err.message);
-      });
-    }
-
-    return serviceInfo;
-  }
-
-  /**
-   * Persist service to file-based registry
-   * @private
-   */
-  async _persistToFile(name, serviceInfo) {
-    const portRegistry = getPortRegistry();
-    await portRegistry.registerService(name, {
-      port: serviceInfo.port,
-      host: serviceInfo.host,
-      protocol: serviceInfo.protocol,
-      metadata: serviceInfo.metadata
-    });
-  }
-
-  /**
-   * Unregister a service
-   * @param {string} name - Service name
-   * @param {boolean} [persistToFile=true] - Whether to remove from file registry
-   * @returns {boolean} True if service was removed
-   */
-  unregister(name, persistToFile = true) {
-    const service = this.services.get(name);
-    if (service) {
-      this.services.delete(name);
-      console.log(`[ServiceRegistry] Unregistered service: ${name}`);
-      this.emit('service:unregistered', { name, ...service });
-
-      // Remove from file-based registry
-      if (persistToFile) {
-        this._removeFromFile(name).catch(err => {
-          console.warn(`[ServiceRegistry] Failed to remove ${name} from file registry:`, err.message);
-        });
-      }
-
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * Remove service from file-based registry
-   * @private
-   */
-  async _removeFromFile(name) {
-    const portRegistry = getPortRegistry();
-    await portRegistry.unregisterService(name);
-  }
-
-  /**
-   * Get a service by name
-   * @param {string} name - Service name
-   * @returns {Object|null} Service info or null
-   */
-  get(name) {
-    return this.services.get(name) || null;
-  }
-
-  /**
-   * Get all registered services
-   * @returns {Object} Map of service name to info
-   */
-  getAll() {
-    const result = {};
-    for (const [name, info] of this.services) {
-      result[name] = { ...info };
-    }
-    return result;
-  }
-
-  /**
-   * Get URL for a service
-   * @param {string} name - Service name
-   * @returns {string|null} Service URL or null
-   */
-  getUrl(name) {
-    const service = this.services.get(name);
-    return service?.url || null;
-  }
-
-  /**
-   * Get WebSocket URL for a service
-   * @param {string} name - Service name
-   * @param {string} [path=''] - Optional path to append
-   * @returns {string|null} WebSocket URL or null
-   */
-  getWsUrl(name, path = '') {
-    const service = this.services.get(name);
-    if (!service) return null;
-    return `${service.wsUrl}${path}`;
-  }
-
-  /**
-   * Update service status
-   * @param {string} name - Service name
-   * @param {string} status - New status
-   */
-  updateStatus(name, status) {
-    const service = this.services.get(name);
-    if (service) {
-      service.status = status;
-      service.lastHeartbeat = Date.now();
-      this.emit('service:statusChanged', { name, status });
-    }
-  }
-
-  /**
-   * Record heartbeat for a service
-   * @param {string} name - Service name
-   */
-  heartbeat(name) {
-    const service = this.services.get(name);
-    if (service) {
-      service.lastHeartbeat = Date.now();
-    }
-  }
-
-  /**
-   * Check if a service is registered and running
-   * @param {string} name - Service name
-   * @returns {boolean}
-   */
-  isRunning(name) {
-    const service = this.services.get(name);
-    return service?.status === ServiceStatus.RUNNING;
-  }
-
-  /**
-   * Clear all registered services
-   */
-  clear() {
-    this.services.clear();
-    this.emit('registry:cleared');
-  }
-
-  /**
-   * Get registry statistics
-   * @returns {Object}
-   */
-  getStats() {
-    const services = Array.from(this.services.values());
-    return {
-      totalServices: services.length,
-      runningServices: services.filter(s => s.status === ServiceStatus.RUNNING).length,
-      services: services.map(s => ({ name: s.name, port: s.port, status: s.status }))
-    };
-  }
-
-  /**
-   * Load services from file-based registry
-   * Useful for discovering services started by other processes
-   * @returns {Promise<Object>} Map of service name to info
-   */
-  async loadFromFile() {
-    const portRegistry = getPortRegistry();
-    await portRegistry.cleanupStaleEntries();
-    return portRegistry.getAllServices();
-  }
-
-  /**
-   * Get a service from file-based registry (for cross-process discovery)
-   * @param {string} name - Service name
-   * @returns {Promise<Object|null>} Service info or null
-   */
-  async getFromFile(name) {
-    const portRegistry = getPortRegistry();
-    return portRegistry.getService(name);
-  }
-
-  /**
-   * Setup process exit handlers to cleanup registry on shutdown
-   * Call this after registering services to ensure cleanup on exit
-   */
-  setupExitHandlers() {
-    if (this._exitHandlersSetup) return;
-    this._exitHandlersSetup = true;
-
-    const cleanup = async () => {
-      console.log('[ServiceRegistry] Cleaning up on process exit...');
-      const portRegistry = getPortRegistry();
-
-      // Unregister all services owned by this process
-      for (const [name] of this.services) {
-        try {
-          await portRegistry.unregisterService(name);
-        } catch (err) {
-          // Ignore errors during cleanup
-        }
-      }
-    };
-
-    // Run cleanup when the process is about to exit naturally
-    // Note: Do NOT add SIGINT/SIGTERM handlers here — the main app (index.js)
-    // handles signals and calls shutdown() which already unregisters services.
-    // Adding competing handlers causes race conditions and premature exit.
-    process.on('beforeExit', cleanup);
-  }
-}
-
-// Singleton instance
-const registry = new ServiceRegistry();
-
-/**
- * Find a free port starting from the preferred port
- * @param {number} preferredPort - Port to try first
- * @param {number} [maxAttempts=100] - Maximum ports to try
- * @param {string} [host='127.0.0.1'] - Host to check availability on
- * @returns {Promise<number>} Available port
- */
-export async function findFreePort(preferredPort, maxAttempts = 100, host = '127.0.0.1') {
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const port = preferredPort + attempt;
-    const isFree = await isPortFree(port, host);
-    if (isFree) {
-      if (attempt > 0) {
-        console.log(`[ServiceRegistry] Port ${preferredPort} taken, using ${port}`);
-      }
-      return port;
-    }
-  }
-  throw new Error(`Could not find free port after ${maxAttempts} attempts starting from ${preferredPort}`);
-}
-
-/**
- * Check if a port is free on a specific host
- * @param {number} port - Port to check
- * @param {string} host - Host to check (default: '127.0.0.1')
- * @returns {Promise<boolean>}
- */
-export async function isPortFree(port, host = '127.0.0.1') {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-
-    // Set a timeout to avoid hanging
-    const timeout = setTimeout(() => {
-      try { server.close(); } catch {}
-      resolve(false);
-    }, 1000);
-
-    server.once('error', (err) => {
-      clearTimeout(timeout);
-      // EADDRINUSE = port in use, EACCES = permission denied (WSL2 IPv6 issue)
-      // Any error means we can't use this port
-      resolve(false);
-    });
-
-    server.once('listening', () => {
-      clearTimeout(timeout);
-      server.close(() => {
-        resolve(true);
-      });
-    });
-
-    try {
-      server.listen(port, host);
-    } catch (err) {
-      clearTimeout(timeout);
-      resolve(false);
-    }
-  });
-}
-
-/**
- * Start a service with automatic port fallback
- * @param {string} serviceName - Name to register the service as
- * @param {number} preferredPort - Preferred port
- * @param {Function} startFn - Function that starts the service, receives port, returns server
- * @param {Object} [options={}] - Additional options
- * @returns {Promise<Object>} { server, port, serviceInfo }
- */
-export async function startServiceWithFallback(serviceName, preferredPort, startFn, options = {}) {
-  const port = await findFreePort(preferredPort);
-
-  if (port !== preferredPort) {
-    console.log(`[ServiceRegistry] Port ${preferredPort} taken, using ${port} for ${serviceName}`);
-  }
-
-  // Start the service
-  const server = await startFn(port);
-
-  // Register with registry
-  const serviceInfo = registry.register(serviceName, {
-    port,
-    host: options.host || 'localhost',
-    protocol: options.protocol || 'http',
-    metadata: options.metadata || {}
-  });
-
-  return { server, port, serviceInfo };
-}
-
-// Export singleton and class
-export { registry, ServiceRegistry, ServiceStatus as Status };
-export { getPortRegistry } from './portRegistry.js';
-export default registry;
+/**
+ * Service Registry
+ *
+ * Centralized registry for service discovery. Each service registers itself
+ * with its actual port (which may differ from configured if port was taken).
+ * Other components query the registry to discover service locations.
+ *
+ * This registry maintains both in-memory state (for fast access) and
+ * file-based persistence (for cross-process discovery via PortRegistry).
+ */
+
+import { EventEmitter } from 'events';
+import net from 'net';
+import { getPortRegistry } from './portRegistry.js';
+
+/**
+ * Service status enum
+ */
+export const ServiceStatus = {
+  STARTING: 'starting',
+  RUNNING: 'running',
+  STOPPING: 'stopping',
+  STOPPED: 'stopped',
+  ERROR: 'error'
+};
+
+/**
+ * Service Registry class
+ */
+class ServiceRegistry extends EventEmitter {
+  constructor() {
+    super();
+
+    // Registry: serviceName -> ServiceInfo
+    this.services = new Map();
+
+    // Health check interval
+    this.healthCheckInterval = null;
+  }
+
+  /**
+   * Register a service
+   * @param {string} name - Service name (e.g., 'visualEditor', 'backend')
+   * @param {Object} info - Service information
+   * @param {number} info.port - Port the service is running on
+   * @param {string} [info.host='localhost'] - Host address
+   * @param {string} [info.protocol='http'] - Protocol (http, https, ws, wss)
+   * @param {string} [info.status='running'] - Service status
+   * @param {Object} [info.metadata={}] - Additional metadata
+   * @param {boolean} [info.persistToFile=true] - Whether to persist to file registry
+   * @returns {Object} Registered service info
+   */
+  register(name, info) {
+    if (!name) {
+      throw new Error('Service name is required');
+    }
+    if (!info.port) {
+      throw new Error('Service port is required');
+    }
+
+    const serviceInfo = {
+      name,
+      port: info.port,
+      host: info.host || 'localhost',
+      protocol: info.protocol || 'http',
+      status: info.status || ServiceStatus.RUNNING,
+      metadata: info.metadata || {},
+      registeredAt: Date.now(),
+      lastHeartbeat: Date.now()
+    };
+
+    // Build URLs
+    serviceInfo.url = `${serviceInfo.protocol}://${serviceInfo.host}:${serviceInfo.port}`;
+    serviceInfo.wsUrl = `ws://${serviceInfo.host}:${serviceInfo.port}`;
+
+    const isUpdate = this.services.has(name);
+    this.services.set(name, serviceInfo);
+
+    console.log(`[ServiceRegistry] ${isUpdate ? 'Updated' : 'Registered'} service: ${name} at ${serviceInfo.url}`);
+
+    this.emit(isUpdate ? 'service:updated' : 'service:registered', serviceInfo);
+
+    // Persist to file-based registry for cross-process discovery
+    if (info.persistToFile !== false) {
+      this._persistToFile(name, serviceInfo).catch(err => {
+        console.warn(`[ServiceRegistry] Failed to persist ${name} to file registry:`, err.message);
+      });
+    }
+
+    return serviceInfo;
+  }
+
+  /**
+   * Persist service to file-based registry
+   * @private
+   */
+  async _persistToFile(name, serviceInfo) {
+    const portRegistry = getPortRegistry();
+    await portRegistry.registerService(name, {
+      port: serviceInfo.port,
+      host: serviceInfo.host,
+      protocol: serviceInfo.protocol,
+      metadata: serviceInfo.metadata
+    });
+  }
+
+  /**
+   * Unregister a service
+   * @param {string} name - Service name
+   * @param {boolean} [persistToFile=true] - Whether to remove from file registry
+   * @returns {boolean} True if service was removed
+   */
+  unregister(name, persistToFile = true) {
+    const service = this.services.get(name);
+    if (service) {
+      this.services.delete(name);
+      console.log(`[ServiceRegistry] Unregistered service: ${name}`);
+      this.emit('service:unregistered', { name, ...service });
+
+      // Remove from file-based registry
+      if (persistToFile) {
+        this._removeFromFile(name).catch(err => {
+          console.warn(`[ServiceRegistry] Failed to remove ${name} from file registry:`, err.message);
+        });
+      }
+
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Remove service from file-based registry
+   * @private
+   */
+  async _removeFromFile(name) {
+    const portRegistry = getPortRegistry();
+    await portRegistry.unregisterService(name);
+  }
+
+  /**
+   * Get a service by name
+   * @param {string} name - Service name
+   * @returns {Object|null} Service info or null
+   */
+  get(name) {
+    return this.services.get(name) || null;
+  }
+
+  /**
+   * Get all registered services
+   * @returns {Object} Map of service name to info
+   */
+  getAll() {
+    const result = {};
+    for (const [name, info] of this.services) {
+      result[name] = { ...info };
+    }
+    return result;
+  }
+
+  /**
+   * Get URL for a service
+   * @param {string} name - Service name
+   * @returns {string|null} Service URL or null
+   */
+  getUrl(name) {
+    const service = this.services.get(name);
+    return service?.url || null;
+  }
+
+  /**
+   * Get WebSocket URL for a service
+   * @param {string} name - Service name
+   * @param {string} [path=''] - Optional path to append
+   * @returns {string|null} WebSocket URL or null
+   */
+  getWsUrl(name, path = '') {
+    const service = this.services.get(name);
+    if (!service) return null;
+    return `${service.wsUrl}${path}`;
+  }
+
+  /**
+   * Update service status
+   * @param {string} name - Service name
+   * @param {string} status - New status
+   */
+  updateStatus(name, status) {
+    const service = this.services.get(name);
+    if (service) {
+      service.status = status;
+      service.lastHeartbeat = Date.now();
+      this.emit('service:statusChanged', { name, status });
+    }
+  }
+
+  /**
+   * Record heartbeat for a service
+   * @param {string} name - Service name
+   */
+  heartbeat(name) {
+    const service = this.services.get(name);
+    if (service) {
+      service.lastHeartbeat = Date.now();
+    }
+  }
+
+  /**
+   * Check if a service is registered and running
+   * @param {string} name - Service name
+   * @returns {boolean}
+   */
+  isRunning(name) {
+    const service = this.services.get(name);
+    return service?.status === ServiceStatus.RUNNING;
+  }
+
+  /**
+   * Clear all registered services
+   */
+  clear() {
+    this.services.clear();
+    this.emit('registry:cleared');
+  }
+
+  /**
+   * Get registry statistics
+   * @returns {Object}
+   */
+  getStats() {
+    const services = Array.from(this.services.values());
+    return {
+      totalServices: services.length,
+      runningServices: services.filter(s => s.status === ServiceStatus.RUNNING).length,
+      services: services.map(s => ({ name: s.name, port: s.port, status: s.status }))
+    };
+  }
+
+  /**
+   * Load services from file-based registry
+   * Useful for discovering services started by other processes
+   * @returns {Promise<Object>} Map of service name to info
+   */
+  async loadFromFile() {
+    const portRegistry = getPortRegistry();
+    await portRegistry.cleanupStaleEntries();
+    return portRegistry.getAllServices();
+  }
+
+  /**
+   * Get a service from file-based registry (for cross-process discovery)
+   * @param {string} name - Service name
+   * @returns {Promise<Object|null>} Service info or null
+   */
+  async getFromFile(name) {
+    const portRegistry = getPortRegistry();
+    return portRegistry.getService(name);
+  }
+
+  /**
+   * Setup process exit handlers to cleanup registry on shutdown
+   * Call this after registering services to ensure cleanup on exit
+   */
+  setupExitHandlers() {
+    if (this._exitHandlersSetup) return;
+    this._exitHandlersSetup = true;
+
+    const cleanup = async () => {
+      console.log('[ServiceRegistry] Cleaning up on process exit...');
+      const portRegistry = getPortRegistry();
+
+      // Unregister all services owned by this process
+      for (const [name] of this.services) {
+        try {
+          await portRegistry.unregisterService(name);
+        } catch {
+          // Ignore errors during cleanup
+        }
+      }
+    };
+
+    // Run cleanup when the process is about to exit naturally
+    // Note: Do NOT add SIGINT/SIGTERM handlers here — the main app (index.js)
+    // handles signals and calls shutdown() which already unregisters services.
+    // Adding competing handlers causes race conditions and premature exit.
+    process.on('beforeExit', cleanup);
+  }
+}
+
+// Singleton instance
+const registry = new ServiceRegistry();
+
+/**
+ * Find a free port starting from the preferred port
+ * @param {number} preferredPort - Port to try first
+ * @param {number} [maxAttempts=100] - Maximum ports to try
+ * @param {string} [host='127.0.0.1'] - Host to check availability on
+ * @returns {Promise<number>} Available port
+ */
+export async function findFreePort(preferredPort, maxAttempts = 100, host = '127.0.0.1') {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const port = preferredPort + attempt;
+    const isFree = await isPortFree(port, host);
+    if (isFree) {
+      if (attempt > 0) {
+        console.log(`[ServiceRegistry] Port ${preferredPort} taken, using ${port}`);
+      }
+      return port;
+    }
+  }
+  throw new Error(`Could not find free port after ${maxAttempts} attempts starting from ${preferredPort}`);
+}
+
+/**
+ * Check if a port is free on a specific host
+ * @param {number} port - Port to check
+ * @param {string} host - Host to check (default: '127.0.0.1')
+ * @returns {Promise<boolean>}
+ */
+export async function isPortFree(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    // Set a timeout to avoid hanging
+    const timeout = setTimeout(() => {
+      try { server.close(); } catch { /* swallow */ }
+      resolve(false);
+    }, 1000);
+
+    server.once('error', () => {
+      clearTimeout(timeout);
+      // EADDRINUSE = port in use, EACCES = permission denied (WSL2 IPv6 issue)
+      // Any error means we can't use this port
+      resolve(false);
+    });
+
+    server.once('listening', () => {
+      clearTimeout(timeout);
+      server.close(() => {
+        resolve(true);
+      });
+    });
+
+    try {
+      server.listen(port, host);
+    } catch {
+      clearTimeout(timeout);
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Start a service with automatic port fallback
+ * @param {string} serviceName - Name to register the service as
+ * @param {number} preferredPort - Preferred port
+ * @param {Function} startFn - Function that starts the service, receives port, returns server
+ * @param {Object} [options={}] - Additional options
+ * @returns {Promise<Object>} { server, port, serviceInfo }
+ */
+export async function startServiceWithFallback(serviceName, preferredPort, startFn, options = {}) {
+  const port = await findFreePort(preferredPort);
+
+  if (port !== preferredPort) {
+    console.log(`[ServiceRegistry] Port ${preferredPort} taken, using ${port} for ${serviceName}`);
+  }
+
+  // Start the service
+  const server = await startFn(port);
+
+  // Register with registry
+  const serviceInfo = registry.register(serviceName, {
+    port,
+    host: options.host || 'localhost',
+    protocol: options.protocol || 'http',
+    metadata: options.metadata || {}
+  });
+
+  return { server, port, serviceInfo };
+}
+
+// Export singleton and class
+export { registry, ServiceRegistry, ServiceStatus as Status };
+export { getPortRegistry } from './portRegistry.js';
+export default registry;