feat(backend): implement global event bus for plugin communication

Author: Lasim

services/backend/src/events/eventBus.ts

@@ -0,0 +1,202 @@
+/**
+ * DeployStack Global Event Bus
+ * 
+ * Core event management system built on Node.js EventEmitter.
+ * Provides type-safe event emission and plugin listener management.
+ */
+
+import { EventEmitter } from 'events';
+import { type FastifyBaseLogger } from 'fastify';
+import { type EventName, type EventData, type EventContext, type EventHandler } from './types';
+
+/**
+ * DeployStack Event Bus - Central event management system
+ * 
+ * Features:
+ * - Type-safe event emission with compile-time validation
+ * - Plugin listener registration and cleanup
+ * - Error isolation (failed listeners don't affect others)
+ * - Memory efficient (fire-and-forget processing)
+ * - Audit trail for plugin listener registrations
+ */
+export class DeployStackEventBus extends EventEmitter {
+  private logger?: FastifyBaseLogger;
+  private pluginListeners: Map<string, Set<string>> = new Map();
+
+  constructor(logger?: FastifyBaseLogger) {
+    super();
+    this.logger = logger;
+    
+    // Support many plugins listening to events
+    this.setMaxListeners(100);
+    
+    // Prevent crashes from unhandled errors in event listeners
+    this.on('error', (error) => {
+      this.logger?.error('EventBus error:', error);
+    });
+  }
+
+  /**
+   * Emit an event with typed data and context
+   * 
+   * @param eventName - Type-safe event name constant
+   * @param data - Strongly-typed event data
+   * @param context - Event context with database, logger, user info
+   * @returns true if event had listeners, false otherwise
+   */
+  emitWithContext<T extends EventName>(
+    eventName: T,
+    data: EventData<T>,
+    context: EventContext
+  ): boolean {
+    try {
+      this.logger?.debug(`Emitting event: ${eventName}`);
+
+      // Emit the event with data and context
+      const hasListeners = this.emit(eventName, data, context);
+      
+      if (!hasListeners) {
+        this.logger?.debug(`No listeners for event: ${eventName}`);
+      }
+
+      return hasListeners;
+    } catch (error) {
+      this.logger?.error(`Failed to emit event ${eventName}: ${error}`);
+      // Don't throw - event emission failures should not break core operations
+      return false;
+    }
+  }
+
+  /**
+   * Register a plugin event listener
+   * 
+   * @param pluginId - Unique plugin identifier
+   * @param eventName - Event name to listen for
+   * @param handler - Event handler function
+   */
+  registerPluginListener<T extends EventName>(
+    pluginId: string,
+    eventName: T,
+    handler: EventHandler<T>
+  ): void {
+    try {
+      // Track plugin listeners for cleanup
+      if (!this.pluginListeners.has(pluginId)) {
+        this.pluginListeners.set(pluginId, new Set());
+      }
+      this.pluginListeners.get(pluginId)!.add(eventName);
+
+      // Wrap handler with error isolation
+      const wrappedHandler = async (data: EventData<T>, context: EventContext) => {
+        try {
+          await handler(data, context);
+        } catch (error) {
+          this.logger?.error(`Plugin ${pluginId} event handler failed for ${eventName}: ${error}`);
+          // Don't re-throw - plugin failures should not affect other plugins or core operations
+        }
+      };
+
+      // Register the wrapped listener
+      this.on(eventName, wrappedHandler);
+      
+      this.logger?.info(`Plugin ${pluginId} registered for event: ${eventName}`);
+    } catch (error) {
+      this.logger?.error(`Failed to register plugin listener for ${pluginId}: ${error}`);
+      throw error; // This is a setup error, should be thrown
+    }
+  }
+
+  /**
+   * Unregister all event listeners for a plugin
+   * 
+   * @param pluginId - Plugin identifier to clean up
+   */
+  unregisterPlugin(pluginId: string): void {
+    try {
+      const events = this.pluginListeners.get(pluginId);
+      if (!events) {
+        this.logger?.debug(`No listeners found for plugin: ${pluginId}`);
+        return;
+      }
+
+      let removedCount = 0;
+      events.forEach(eventName => {
+        const listenerCount = this.listenerCount(eventName);
+        this.removeAllListeners(eventName);
+        removedCount += listenerCount;
+      });
+
+      this.pluginListeners.delete(pluginId);
+      
+      this.logger?.info(`Unregistered ${removedCount} listeners for plugin: ${pluginId}`);
+    } catch (error) {
+      this.logger?.error(`Failed to unregister plugin ${pluginId}: ${error}`);
+      // Don't throw - cleanup failures should not break plugin unloading
+    }
+  }
+
+  /**
+   * Get statistics about registered listeners
+   * 
+   * @returns Event bus statistics
+   */
+  getStats(): {
+    totalPlugins: number;
+    totalListeners: number;
+    eventCounts: Record<string, number>;
+  } {
+    const eventCounts: Record<string, number> = {};
+    
+    // Get listener counts for each event
+    this.eventNames().forEach(eventName => {
+      if (typeof eventName === 'string') {
+        eventCounts[eventName] = this.listenerCount(eventName);
+      }
+    });
+
+    return {
+      totalPlugins: this.pluginListeners.size,
+      totalListeners: Object.values(eventCounts).reduce((sum, count) => sum + count, 0),
+      eventCounts
+    };
+  }
+
+  /**
+   * Check if a plugin has registered listeners
+   * 
+   * @param pluginId - Plugin identifier to check
+   * @returns true if plugin has registered listeners
+   */
+  hasPluginListeners(pluginId: string): boolean {
+    return this.pluginListeners.has(pluginId);
+  }
+
+  /**
+   * Get list of events a plugin is listening to
+   * 
+   * @param pluginId - Plugin identifier
+   * @returns Set of event names the plugin is listening to
+   */
+  getPluginEvents(pluginId: string): Set<string> {
+    return this.pluginListeners.get(pluginId) || new Set();
+  }
+
+  /**
+   * Shutdown the event bus and clean up all listeners
+   */
+  shutdown(): void {
+    try {
+      this.logger?.info('Shutting down EventBus...');
+      
+      // Remove all listeners
+      this.removeAllListeners();
+      
+      // Clear plugin tracking
+      this.pluginListeners.clear();
+      
+      this.logger?.info('EventBus shutdown complete');
+    } catch (error) {
+      this.logger?.error(`Error during EventBus shutdown: ${error}`);
+    }
+  }
+}

services/backend/src/events/eventNames.ts

@@ -0,0 +1,46 @@
+/**
+ * Event name constants for the DeployStack Global Event Bus
+ * 
+ * Event names are aligned with the existing permission structure:
+ * - users.* permissions → user.* events
+ * - teams.* permissions → team.* events
+ * - settings.* permissions → settings.* events
+ * - mcp.* permissions → mcp.* events
+ */
+
+export const EVENT_NAMES = {
+  // User Events (aligned with users.* permissions)
+  USER_REGISTERED: 'user.registered',
+  USER_LOGIN: 'user.login',
+  USER_LOGOUT: 'user.logout',
+  USER_CREATED: 'user.created',        // matches users.create permission
+  USER_UPDATED: 'user.updated',        // matches users.edit permission
+  USER_DELETED: 'user.deleted',        // matches users.delete permission
+  USER_PASSWORD_RESET: 'user.password_reset',
+  USER_EMAIL_VERIFIED: 'user.email_verified',
+
+  // Team Events (aligned with teams.* permissions)
+  TEAM_CREATED: 'team.created',        // matches teams.create permission
+  TEAM_UPDATED: 'team.updated',        // matches teams.edit permission
+  TEAM_DELETED: 'team.deleted',        // matches teams.delete permission
+  TEAM_MEMBER_ADDED: 'team.member_added',
+  TEAM_MEMBER_REMOVED: 'team.member_removed',
+
+  // Settings Events (aligned with settings.* permissions)
+  SETTINGS_UPDATED: 'settings.updated', // matches settings.edit permission
+  SETTINGS_DELETED: 'settings.deleted', // matches settings.delete permission
+  SETTINGS_GROUP_CREATED: 'settings.group_created',
+
+  // MCP Events (aligned with mcp.* permissions)
+  MCP_INSTALLATION_CREATED: 'mcp.installation_created', // matches mcp.installations.create
+  MCP_INSTALLATION_UPDATED: 'mcp.installation_updated', // matches mcp.installations.edit
+  MCP_INSTALLATION_DELETED: 'mcp.installation_deleted', // matches mcp.installations.delete
+
+  // System Events
+  SYSTEM_STARTUP: 'system.startup',
+  SYSTEM_SHUTDOWN: 'system.shutdown',
+  SYSTEM_ERROR: 'system.error',
+} as const;
+
+// Type-safe event names
+export type EventName = typeof EVENT_NAMES[keyof typeof EVENT_NAMES];

services/backend/src/events/index.ts

@@ -0,0 +1,59 @@
+/**
+ * DeployStack Global Event Bus - Module Exports
+ * 
+ * This file provides a clean API for consuming the event system.
+ * Import everything you need from this single entry point.
+ */
+
+// Core EventBus class
+export { DeployStackEventBus } from './eventBus';
+
+// Event name constants
+export { EVENT_NAMES } from './eventNames';
+import { EVENT_NAMES } from './eventNames';
+
+// Type definitions
+export type {
+  EventName,
+  EventContext,
+  EventData,
+  EventHandler,
+  GenericEventHandler,
+  EventListeners,
+  CoreEventData
+} from './types';
+
+// Re-export specific event names for convenience
+export const {
+  // User Events
+  USER_REGISTERED,
+  USER_LOGIN,
+  USER_LOGOUT,
+  USER_CREATED,
+  USER_UPDATED,
+  USER_DELETED,
+  USER_PASSWORD_RESET,
+  USER_EMAIL_VERIFIED,
+  
+  // Team Events
+  TEAM_CREATED,
+  TEAM_UPDATED,
+  TEAM_DELETED,
+  TEAM_MEMBER_ADDED,
+  TEAM_MEMBER_REMOVED,
+  
+  // Settings Events
+  SETTINGS_UPDATED,
+  SETTINGS_DELETED,
+  SETTINGS_GROUP_CREATED,
+  
+  // MCP Events
+  MCP_INSTALLATION_CREATED,
+  MCP_INSTALLATION_UPDATED,
+  MCP_INSTALLATION_DELETED,
+  
+  // System Events
+  SYSTEM_STARTUP,
+  SYSTEM_SHUTDOWN,
+  SYSTEM_ERROR
+} = EVENT_NAMES;