specweave 0.18.0 → 0.20.0

package/plugins/specweave-kafka/lib/multi-cluster/cluster-switcher.ts

@@ -0,0 +1,359 @@
+/**
+ * Cluster Switcher
+ *
+ * Provides context switching between multiple Kafka clusters
+ *
+ * @module cluster-switcher
+ */
+
+import { Kafka, Admin, Producer, Consumer } from 'kafkajs';
+import { ClusterConfigManager, ClusterConfig } from './cluster-config-manager';
+
+/**
+ * Cluster Context
+ *
+ * Active connections to a Kafka cluster
+ */
+export interface ClusterContext {
+  /** Cluster ID */
+  clusterId: string;
+  /** Cluster configuration */
+  config: ClusterConfig;
+  /** Kafka client */
+  kafka: Kafka;
+  /** Admin client (lazy initialized) */
+  admin?: Admin;
+  /** Producer (lazy initialized) */
+  producer?: Producer;
+  /** Consumers (lazy initialized) */
+  consumers: Map<string, Consumer>;
+}
+
+/**
+ * Cluster Switcher
+ *
+ * Manages active connections to multiple Kafka clusters with context switching
+ */
+export class ClusterSwitcher {
+  private configManager: ClusterConfigManager;
+  private contexts: Map<string, ClusterContext> = new Map();
+  private activeContext: ClusterContext | null = null;
+
+  constructor(configManager?: ClusterConfigManager) {
+    this.configManager = configManager || new ClusterConfigManager();
+  }
+
+  /**
+   * Get or create cluster context
+   */
+  private async getContext(clusterId: string): Promise<ClusterContext> {
+    // Return cached context if exists
+    if (this.contexts.has(clusterId)) {
+      return this.contexts.get(clusterId)!;
+    }
+
+    // Get cluster config
+    const config = this.configManager.getCluster(clusterId);
+    if (!config) {
+      throw new Error(`Cluster "${clusterId}" not found`);
+    }
+
+    // Create Kafka client
+    const kafkaConfig = this.buildKafkaConfig(config);
+    const kafka = new Kafka(kafkaConfig);
+
+    // Create context
+    const context: ClusterContext = {
+      clusterId,
+      config,
+      kafka,
+      consumers: new Map(),
+    };
+
+    // Cache context
+    this.contexts.set(clusterId, context);
+
+    return context;
+  }
+
+  /**
+   * Build kafkajs configuration from cluster config
+   */
+  private buildKafkaConfig(config: ClusterConfig): any {
+    const kafkaConfig: any = {
+      clientId: `kafka-client-${config.id}`,
+      brokers: config.bootstrapServers,
+    };
+
+    // Security configuration
+    if (config.securityProtocol !== 'PLAINTEXT') {
+      if (config.securityProtocol === 'SSL' || config.securityProtocol === 'SASL_SSL') {
+        kafkaConfig.ssl = { rejectUnauthorized: true };
+        // Note: In production, load SSL certs from files
+      }
+
+      if (config.securityProtocol.startsWith('SASL')) {
+        kafkaConfig.sasl = {
+          mechanism: config.saslMechanism || 'PLAIN',
+          username: config.saslUsername || '',
+          password: config.saslPassword || '',
+        };
+      }
+    }
+
+    return kafkaConfig;
+  }
+
+  /**
+   * Switch to a different cluster
+   */
+  async switch(clusterId: string): Promise<void> {
+    console.log(`Switching to cluster: ${clusterId}`);
+
+    // Get or create context
+    const context = await this.getContext(clusterId);
+
+    // Disconnect previous context (optional - keep connections alive for faster switching)
+    // if (this.activeContext && this.activeContext.clusterId !== clusterId) {
+    //   await this.disconnectContext(this.activeContext);
+    // }
+
+    // Set active context
+    this.activeContext = context;
+
+    // Update config manager active cluster
+    this.configManager.setActiveCluster(clusterId);
+
+    console.log(`Now connected to cluster: ${context.config.name} (${context.config.environment})`);
+  }
+
+  /**
+   * Get active cluster ID
+   */
+  getActiveClusterId(): string | null {
+    return this.activeContext?.clusterId || null;
+  }
+
+  /**
+   * Get active cluster configuration
+   */
+  getActiveCluster(): ClusterConfig | null {
+    return this.activeContext?.config || null;
+  }
+
+  /**
+   * Get Admin client for active cluster
+   */
+  async getAdmin(): Promise<Admin> {
+    if (!this.activeContext) {
+      throw new Error('No active cluster. Use switch() first.');
+    }
+
+    // Lazy initialize admin
+    if (!this.activeContext.admin) {
+      this.activeContext.admin = this.activeContext.kafka.admin();
+      await this.activeContext.admin.connect();
+    }
+
+    return this.activeContext.admin;
+  }
+
+  /**
+   * Get Producer for active cluster
+   */
+  async getProducer(): Promise<Producer> {
+    if (!this.activeContext) {
+      throw new Error('No active cluster. Use switch() first.');
+    }
+
+    // Lazy initialize producer
+    if (!this.activeContext.producer) {
+      this.activeContext.producer = this.activeContext.kafka.producer();
+      await this.activeContext.producer.connect();
+    }
+
+    return this.activeContext.producer;
+  }
+
+  /**
+   * Get or create Consumer for active cluster
+   */
+  async getConsumer(groupId: string): Promise<Consumer> {
+    if (!this.activeContext) {
+      throw new Error('No active cluster. Use switch() first.');
+    }
+
+    // Return existing consumer
+    if (this.activeContext.consumers.has(groupId)) {
+      return this.activeContext.consumers.get(groupId)!;
+    }
+
+    // Create new consumer
+    const consumer = this.activeContext.kafka.consumer({ groupId });
+    await consumer.connect();
+
+    // Cache consumer
+    this.activeContext.consumers.set(groupId, consumer);
+
+    return consumer;
+  }
+
+  /**
+   * Disconnect all connections for a specific cluster
+   */
+  private async disconnectContext(context: ClusterContext): Promise<void> {
+    console.log(`Disconnecting cluster: ${context.clusterId}`);
+
+    // Disconnect admin
+    if (context.admin) {
+      await context.admin.disconnect();
+      context.admin = undefined;
+    }
+
+    // Disconnect producer
+    if (context.producer) {
+      await context.producer.disconnect();
+      context.producer = undefined;
+    }
+
+    // Disconnect all consumers
+    for (const [groupId, consumer] of context.consumers.entries()) {
+      await consumer.disconnect();
+    }
+    context.consumers.clear();
+  }
+
+  /**
+   * Disconnect all clusters
+   */
+  async disconnectAll(): Promise<void> {
+    for (const context of this.contexts.values()) {
+      await this.disconnectContext(context);
+    }
+
+    this.contexts.clear();
+    this.activeContext = null;
+  }
+
+  /**
+   * List all available clusters
+   */
+  listClusters(): ClusterConfig[] {
+    return this.configManager.getAllClusters();
+  }
+
+  /**
+   * Get cluster health status
+   */
+  async getClusterHealth(clusterId?: string): Promise<{
+    clusterId: string;
+    healthy: boolean;
+    error?: string;
+  }> {
+    const targetClusterId = clusterId || this.activeContext?.clusterId;
+    if (!targetClusterId) {
+      throw new Error('No cluster specified and no active cluster');
+    }
+
+    try {
+      const context = await this.getContext(targetClusterId);
+      const admin = context.kafka.admin();
+      await admin.connect();
+
+      // Simple health check: list topics
+      await admin.listTopics();
+
+      await admin.disconnect();
+
+      return {
+        clusterId: targetClusterId,
+        healthy: true,
+      };
+    } catch (error) {
+      return {
+        clusterId: targetClusterId,
+        healthy: false,
+        error: (error as Error).message,
+      };
+    }
+  }
+
+  /**
+   * Execute operation on specific cluster (without switching context)
+   */
+  async executeOn<T>(
+    clusterId: string,
+    operation: (kafka: Kafka) => Promise<T>
+  ): Promise<T> {
+    const context = await this.getContext(clusterId);
+    return operation(context.kafka);
+  }
+}
+
+/**
+ * Example Usage: Basic Context Switching
+ *
+ * ```typescript
+ * const switcher = new ClusterSwitcher();
+ *
+ * // Switch to dev cluster
+ * await switcher.switch('dev');
+ * const producer = await switcher.getProducer();
+ * await producer.send({
+ *   topic: 'test-topic',
+ *   messages: [{ value: 'Hello from dev!' }],
+ * });
+ *
+ * // Switch to prod cluster
+ * await switcher.switch('prod');
+ * const consumer = await switcher.getConsumer('my-consumer-group');
+ * await consumer.subscribe({ topic: 'events' });
+ * await consumer.run({
+ *   eachMessage: async ({ message }) => {
+ *     console.log(`Prod event: ${message.value?.toString()}`);
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Example Usage: Execute on Specific Cluster
+ *
+ * ```typescript
+ * const switcher = new ClusterSwitcher();
+ *
+ * // Active cluster: dev
+ * await switcher.switch('dev');
+ *
+ * // Execute operation on prod without switching
+ * await switcher.executeOn('prod', async (kafka) => {
+ *   const admin = kafka.admin();
+ *   await admin.connect();
+ *   const topics = await admin.listTopics();
+ *   await admin.disconnect();
+ *   console.log(`Prod topics: ${topics.join(', ')}`);
+ * });
+ *
+ * // Active cluster is still dev
+ * console.log(`Active: ${switcher.getActiveClusterId()}`); // "dev"
+ * ```
+ */
+
+/**
+ * Example Usage: Multi-Cluster Health Check
+ *
+ * ```typescript
+ * const switcher = new ClusterSwitcher();
+ * const clusters = switcher.listClusters();
+ *
+ * for (const cluster of clusters) {
+ *   const health = await switcher.getClusterHealth(cluster.id);
+ *   console.log(`${cluster.name}: ${health.healthy ? 'UP' : 'DOWN'}`);
+ *   if (!health.healthy) {
+ *     console.error(`  Error: ${health.error}`);
+ *   }
+ * }
+ * ```
+ */
+
+export default ClusterSwitcher;

package/plugins/specweave-kafka/lib/multi-cluster/health-aggregator.js

@@ -0,0 +1,195 @@
+class HealthAggregator {
+  constructor(switcher) {
+    this.switcher = switcher;
+  }
+  /**
+   * Collect health metrics for a single cluster
+   */
+  async collectClusterHealth(clusterId) {
+    try {
+      const clusters = this.switcher.listClusters();
+      const clusterConfig = clusters.find((c) => c.id === clusterId);
+      if (!clusterConfig) {
+        throw new Error(`Cluster "${clusterId}" not found`);
+      }
+      const metrics = await this.switcher.executeOn(clusterId, async (kafka) => {
+        const admin = kafka.admin();
+        await admin.connect();
+        try {
+          const cluster = await admin.describeCluster();
+          const topics = await admin.listTopics();
+          const groups = await admin.listGroups();
+          const metadata = await admin.fetchTopicMetadata({ topics });
+          let totalPartitions = 0;
+          let underReplicatedPartitions = 0;
+          let offlinePartitions = 0;
+          for (const topic of metadata.topics) {
+            for (const partition of topic.partitions) {
+              totalPartitions++;
+              if (partition.isr.length < partition.replicas.length) {
+                underReplicatedPartitions++;
+              }
+              if (partition.isr.length === 0) {
+                offlinePartitions++;
+              }
+            }
+          }
+          return {
+            clusterId,
+            clusterName: clusterConfig.name,
+            environment: clusterConfig.environment,
+            status: this.determineStatus(underReplicatedPartitions, offlinePartitions),
+            brokerCount: cluster.brokers.length,
+            onlineBrokerCount: cluster.brokers.length,
+            // All in describeCluster are online
+            topicCount: topics.length,
+            partitionCount: totalPartitions,
+            underReplicatedPartitions,
+            offlinePartitions,
+            consumerGroupCount: groups.groups.length,
+            controllerId: cluster.controller ? Number(cluster.controller) : void 0,
+            lastCheck: /* @__PURE__ */ new Date()
+          };
+        } finally {
+          await admin.disconnect();
+        }
+      });
+      return metrics;
+    } catch (error) {
+      const clusters = this.switcher.listClusters();
+      const clusterConfig = clusters.find((c) => c.id === clusterId);
+      return {
+        clusterId,
+        clusterName: clusterConfig.name,
+        environment: clusterConfig.environment,
+        status: "down",
+        brokerCount: 0,
+        onlineBrokerCount: 0,
+        topicCount: 0,
+        partitionCount: 0,
+        underReplicatedPartitions: 0,
+        offlinePartitions: 0,
+        consumerGroupCount: 0,
+        lastCheck: /* @__PURE__ */ new Date(),
+        error: error.message
+      };
+    }
+  }
+  /**
+   * Determine cluster status based on metrics
+   */
+  determineStatus(underReplicatedPartitions, offlinePartitions) {
+    if (offlinePartitions > 0) {
+      return "down";
+    }
+    if (underReplicatedPartitions > 0) {
+      return "degraded";
+    }
+    return "healthy";
+  }
+  /**
+   * Collect health metrics for all clusters
+   */
+  async collectAllClusters() {
+    const clusters = this.switcher.listClusters();
+    const promises = clusters.map((c) => this.collectClusterHealth(c.id));
+    return Promise.all(promises);
+  }
+  /**
+   * Aggregate health across all clusters
+   */
+  async aggregateHealth() {
+    const clusterMetrics = await this.collectAllClusters();
+    let totalBrokers = 0;
+    let totalTopics = 0;
+    let totalPartitions = 0;
+    let totalUnderReplicatedPartitions = 0;
+    let healthyClusters = 0;
+    let degradedClusters = 0;
+    let downClusters = 0;
+    for (const metrics of clusterMetrics) {
+      totalBrokers += metrics.brokerCount;
+      totalTopics += metrics.topicCount;
+      totalPartitions += metrics.partitionCount;
+      totalUnderReplicatedPartitions += metrics.underReplicatedPartitions;
+      if (metrics.status === "healthy") healthyClusters++;
+      else if (metrics.status === "degraded") degradedClusters++;
+      else if (metrics.status === "down") downClusters++;
+    }
+    return {
+      totalClusters: clusterMetrics.length,
+      healthyClusters,
+      degradedClusters,
+      downClusters,
+      totalBrokers,
+      totalTopics,
+      totalPartitions,
+      totalUnderReplicatedPartitions,
+      clusterMetrics,
+      lastUpdate: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Get health summary as formatted text
+   */
+  async getHealthSummaryText() {
+    const summary = await this.aggregateHealth();
+    const lines = [];
+    lines.push("=== Kafka Multi-Cluster Health Summary ===");
+    lines.push("");
+    lines.push(`Total Clusters: ${summary.totalClusters}`);
+    lines.push(`  \u2713 Healthy:  ${summary.healthyClusters}`);
+    lines.push(`  \u26A0 Degraded: ${summary.degradedClusters}`);
+    lines.push(`  \u2717 Down:     ${summary.downClusters}`);
+    lines.push("");
+    lines.push(`Total Brokers:  ${summary.totalBrokers}`);
+    lines.push(`Total Topics:   ${summary.totalTopics}`);
+    lines.push(`Total Partitions: ${summary.totalPartitions}`);
+    if (summary.totalUnderReplicatedPartitions > 0) {
+      lines.push(`\u26A0 Under-Replicated Partitions: ${summary.totalUnderReplicatedPartitions}`);
+    }
+    lines.push("");
+    lines.push("=== Per-Cluster Status ===");
+    for (const cluster of summary.clusterMetrics) {
+      const icon = cluster.status === "healthy" ? "\u2713" : cluster.status === "degraded" ? "\u26A0" : "\u2717";
+      lines.push("");
+      lines.push(
+        `${icon} ${cluster.clusterName} (${cluster.environment}) - ${cluster.status.toUpperCase()}`
+      );
+      lines.push(`  Brokers: ${cluster.onlineBrokerCount}/${cluster.brokerCount}`);
+      lines.push(`  Topics: ${cluster.topicCount}`);
+      lines.push(`  Partitions: ${cluster.partitionCount}`);
+      if (cluster.underReplicatedPartitions > 0) {
+        lines.push(`  \u26A0 Under-Replicated: ${cluster.underReplicatedPartitions}`);
+      }
+      if (cluster.offlinePartitions > 0) {
+        lines.push(`  \u2717 Offline: ${cluster.offlinePartitions}`);
+      }
+      if (cluster.error) {
+        lines.push(`  Error: ${cluster.error}`);
+      }
+    }
+    lines.push("");
+    lines.push(`Last Updated: ${summary.lastUpdate.toISOString()}`);
+    return lines.join("\n");
+  }
+  /**
+   * Check if any cluster is unhealthy
+   */
+  async hasUnhealthyClusters() {
+    const summary = await this.aggregateHealth();
+    return summary.degradedClusters > 0 || summary.downClusters > 0;
+  }
+  /**
+   * Get list of unhealthy clusters
+   */
+  async getUnhealthyClusters() {
+    const clusterMetrics = await this.collectAllClusters();
+    return clusterMetrics.filter((c) => c.status !== "healthy");
+  }
+}
+var health_aggregator_default = HealthAggregator;
+export {
+  HealthAggregator,
+  health_aggregator_default as default
+};