@kadi.build/tunnel-services 1.0.0

package/src/TunnelManager.js

@@ -0,0 +1,372 @@
+/**
+ * @fileoverview TunnelManager - Main orchestrator for tunnel services
+ *
+ * Provides a unified interface for creating tunnels via multiple providers
+ * with automatic fallback support. KĀDI is the default primary service.
+ */
+
+import { EventEmitter } from 'events';
+import createDebug from 'debug';
+import { TunnelService } from './TunnelService.js';
+import { TransientTunnelError, ConfigurationError, ServiceUnavailableError } from './errors.js';
+
+const debug = createDebug('kadi:tunnel:manager');
+
+/**
+ * TunnelManager - Main orchestrator for tunnel services
+ *
+ * @extends EventEmitter
+ * @example
+ * const manager = new TunnelManager(); // Uses 'kadi' by default
+ * await manager.initialize();
+ * const tunnel = await manager.createTunnel(3000);
+ * console.log(tunnel.publicUrl);
+ */
+export class TunnelManager extends EventEmitter {
+  /**
+   * Create a new TunnelManager
+   * @param {Object} [config={}] - Manager configuration
+   * @param {string} [config.primaryService='kadi'] - Primary tunnel service
+   * @param {string[]|string} [config.fallbackServices] - Fallback services
+   * @param {boolean} [config.autoFallback=true] - Enable automatic fallback
+   * @param {string} [config.ngrokAuthToken] - Ngrok auth token
+   * @param {string} [config.ngrokRegion] - Ngrok region
+   * @param {string} [config.kadiServer] - KĀDI server address
+   * @param {number} [config.kadiPort] - KĀDI frpc port
+   * @param {number} [config.kadiSshPort] - KĀDI SSH port
+   * @param {string} [config.kadiToken] - KĀDI auth token
+   * @param {string} [config.kadiDomain] - KĀDI tunnel domain
+   * @param {string} [config.kadiMode] - KĀDI connection mode
+   * @param {string} [config.kadiAgentId] - KĀDI agent identifier
+   * @param {number} [config.maxConcurrentTunnels=10] - Max concurrent tunnels
+   * @param {number} [config.connectionTimeout=30000] - Default connection timeout
+   */
+  constructor(config = {}) {
+    super();
+    this.config = config;
+
+    // Service configuration (KĀDI is the default primary service)
+    this.primaryService = config.primaryService || config.service || 'kadi';
+    this.fallbackServices = this._parseFallbackServices(
+      config.fallbackServices || 'serveo,ngrok,localtunnel,pinggy'
+    );
+    this.autoFallback = config.autoFallback !== false;
+
+    // Limits
+    this.maxConcurrentTunnels = config.maxConcurrentTunnels || 10;
+    this.connectionTimeout = config.connectionTimeout || 30000;
+
+    // State
+    this.tunnelService = new TunnelService(config);
+    this.activeTunnels = new Map();
+    this.isInitialized = false;
+
+    // Service-specific config (passed through to services)
+    this.serviceConfigs = {
+      ngrok: {
+        authToken: config.ngrokAuthToken || config.authToken,
+        region: config.ngrokRegion || config.region || 'us'
+      },
+      serveo: {
+        subdomain: config.serveoSubdomain || config.subdomain
+      },
+      localtunnel: {
+        subdomain: config.localtunnelSubdomain || config.subdomain
+      },
+      pinggy: {
+        subdomain: config.pinggySubdomain || config.subdomain
+      },
+      'localhost.run': {},
+      kadi: {
+        server: config.kadiServer || 'broker.kadi.build',
+        port: config.kadiPort || 7000,
+        sshPort: config.kadiSshPort || 2200,
+        token: config.kadiToken,
+        domain: config.kadiDomain || 'tunnel.kadi.build',
+        mode: config.kadiMode || 'auto',
+        agentId: config.kadiAgentId || 'kadi'
+      }
+    };
+  }
+
+  /**
+   * Initialize the tunnel service (discovers available services)
+   * @returns {Promise<TunnelManager>} This manager instance
+   */
+  async initialize() {
+    if (this.isInitialized) return this;
+
+    await this.tunnelService.initialize();
+    this._setupEventForwarding();
+    this.isInitialized = true;
+
+    debug('TunnelManager initialized with services: %s', this.tunnelService.getAvailableServices().join(', '));
+    return this;
+  }
+
+  /**
+   * Create a tunnel to expose a local port
+   * @param {number} port - Local port to expose
+   * @param {Object} [options={}] - Tunnel options
+   * @param {string} [options.service] - Specific service to use
+   * @param {string} [options.subdomain] - Requested subdomain
+   * @param {string} [options.region] - Preferred region
+   * @param {number} [options.timeout] - Connection timeout
+   * @param {Object} [options.metadata] - Custom metadata to attach
+   * @returns {Promise<Object>} Tunnel information
+   */
+  async createTunnel(port, options = {}) {
+    await this._ensureInitialized();
+
+    if (this.activeTunnels.size >= this.maxConcurrentTunnels) {
+      throw new ConfigurationError(`Maximum concurrent tunnels (${this.maxConcurrentTunnels}) reached`);
+    }
+
+    const serviceName = options.service || this.primaryService;
+    const servicesToTry = this._getServicesToTry(serviceName);
+
+    debug(`Creating tunnel for port ${port}, services to try: ${servicesToTry.join(', ')}`);
+
+    let lastError = null;
+
+    for (const service of servicesToTry) {
+      try {
+        const tunnel = await this._createTunnelWithService(port, service, options);
+
+        // Normalize tunnel info to a consistent format
+        const tunnelInfo = {
+          id: tunnel.tunnelId || tunnel.id || `tunnel-${Date.now()}`,
+          publicUrl: tunnel.url || tunnel.publicUrl,
+          localPort: tunnel.localPort || port,
+          service: tunnel.service || service,
+          subdomain: tunnel.subdomain,
+          createdAt: tunnel.createdAt || new Date(),
+          metadata: { ...tunnel, ...(options.metadata || {}) }
+        };
+
+        // Store active tunnel
+        this.activeTunnels.set(tunnelInfo.id, tunnelInfo);
+
+        this.emit('tunnelCreated', tunnelInfo);
+        debug(`Tunnel created: ${tunnelInfo.publicUrl} via ${tunnelInfo.service}`);
+        return tunnelInfo;
+
+      } catch (error) {
+        debug(`Service ${service} failed: ${error.message}`);
+        lastError = error;
+
+        // Only continue to fallback for transient errors or when autoFallback is enabled
+        if (!this.autoFallback && !(error instanceof TransientTunnelError)) {
+          throw error;
+        }
+
+        this.emit('serviceFailed', { service, error: error.message });
+      }
+    }
+
+    // All services failed
+    throw lastError || new Error('All tunnel services failed');
+  }
+
+  /**
+   * Create tunnel with a specific service
+   * @private
+   */
+  async _createTunnelWithService(port, serviceName, options) {
+    let service;
+    try {
+      service = this.tunnelService.getService(serviceName);
+    } catch (error) {
+      if (error instanceof ServiceUnavailableError) {
+        throw new TransientTunnelError(`Service '${serviceName}' not available`);
+      }
+      throw error;
+    }
+
+    const serviceConfig = this.serviceConfigs[serviceName] || {};
+
+    const tunnelOptions = {
+      port,
+      subdomain: options.subdomain || serviceConfig.subdomain,
+      region: options.region || serviceConfig.region,
+      timeout: options.timeout || this.connectionTimeout,
+      ...serviceConfig,
+      ...options
+    };
+
+    debug(`Connecting via ${serviceName} on port ${port}`);
+
+    return await service.connect(tunnelOptions);
+  }
+
+  /**
+   * Close a specific tunnel
+   * @param {string} tunnelId - Tunnel ID to close
+   * @returns {Promise<void>}
+   */
+  async closeTunnel(tunnelId) {
+    const tunnel = this.activeTunnels.get(tunnelId);
+    if (!tunnel) {
+      throw new Error(`Tunnel ${tunnelId} not found`);
+    }
+
+    try {
+      const service = this.tunnelService.getService(tunnel.service);
+      await service.disconnect(tunnelId);
+    } catch (error) {
+      debug(`Error during service disconnect for ${tunnelId}: ${error.message}`);
+    }
+
+    this.activeTunnels.delete(tunnelId);
+    this.emit('tunnelClosed', { id: tunnelId });
+  }
+
+  /**
+   * Close all active tunnels
+   * @returns {Promise<void>}
+   */
+  async closeAllTunnels() {
+    const tunnelIds = Array.from(this.activeTunnels.keys());
+
+    for (const id of tunnelIds) {
+      try {
+        await this.closeTunnel(id);
+      } catch (error) {
+        debug(`Error closing tunnel ${id}: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Get status of all active tunnels and services
+   * @returns {Object} Status information
+   */
+  getStatus() {
+    return {
+      isInitialized: this.isInitialized,
+      primaryService: this.primaryService,
+      availableServices: this.isInitialized ? this.tunnelService.getAvailableServices() : [],
+      activeTunnels: Array.from(this.activeTunnels.values()).map(t => ({
+        id: t.id,
+        publicUrl: t.publicUrl,
+        localPort: t.localPort,
+        service: t.service,
+        createdAt: t.createdAt
+      }))
+    };
+  }
+
+  /**
+   * Get list of available tunnel services
+   * @returns {string[]} Array of service names
+   */
+  getAvailableServices() {
+    if (!this.isInitialized) return [];
+    return this.tunnelService.getAvailableServices();
+  }
+
+  /**
+   * Test if a specific service is available
+   * @param {string} serviceName - Service to test
+   * @returns {Promise<Object>} Test result
+   */
+  async testService(serviceName) {
+    await this._ensureInitialized();
+
+    try {
+      const service = this.tunnelService.getService(serviceName);
+      const status = service.getStatus();
+      return { available: true, status };
+    } catch (error) {
+      return { available: false, reason: error.message };
+    }
+  }
+
+  /**
+   * Run diagnostics on all services
+   * @returns {Promise<Object>} Diagnostics results
+   */
+  async runDiagnostics() {
+    await this._ensureInitialized();
+
+    const results = {};
+    const services = this.getAvailableServices();
+
+    for (const serviceName of services) {
+      results[serviceName] = await this.testService(serviceName);
+    }
+
+    return results;
+  }
+
+  /**
+   * Cleanup all resources
+   * @returns {Promise<void>}
+   */
+  async cleanup() {
+    await this.closeAllTunnels();
+    if (this.isInitialized) {
+      await this.tunnelService.shutdown();
+      this.isInitialized = false;
+    }
+  }
+
+  // ============================================================================
+  // HELPER METHODS
+  // ============================================================================
+
+  _parseFallbackServices(fallbackString) {
+    if (Array.isArray(fallbackString)) {
+      return fallbackString;
+    }
+    return fallbackString.split(',').map(s => s.trim()).filter(Boolean);
+  }
+
+  _getServicesToTry(primaryService) {
+    if (primaryService === 'auto') {
+      return ['kadi', ...this.fallbackServices.filter(s => s !== 'kadi')];
+    }
+
+    if (this.autoFallback) {
+      return [primaryService, ...this.fallbackServices.filter(s => s !== primaryService)];
+    }
+
+    return [primaryService];
+  }
+
+  async _ensureInitialized() {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+  }
+
+  _setupEventForwarding() {
+    const services = this.tunnelService.getAvailableServices();
+
+    for (const serviceName of services) {
+      try {
+        const service = this.tunnelService.getService(serviceName);
+
+        service.on('tunnelProgress', (data) => {
+          this.emit('progress', { service: serviceName, ...data });
+        });
+
+        service.on('tunnelError', (data) => {
+          this.emit('serviceError', { service: serviceName, ...data });
+        });
+
+        service.on('tunnelDestroyed', (data) => {
+          this.emit('tunnelDisconnected', { service: serviceName, ...data });
+
+          // Clean up our tracking if tunnel was destroyed externally
+          const tunnelId = data.tunnelId;
+          if (tunnelId && this.activeTunnels.has(tunnelId)) {
+            this.activeTunnels.delete(tunnelId);
+          }
+        });
+      } catch (error) {
+        debug(`Could not set up event forwarding for ${serviceName}: ${error.message}`);
+      }
+    }
+  }
+}

package/src/TunnelService.js

@@ -0,0 +1,316 @@
+/**
+ * @fileoverview Service registration and management interface for tunnel services
+ * Based on TunnelManagerSpec.md Section 3.3 specification
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import createDebug from 'debug';
+import { BaseTunnelService } from './BaseTunnelService.js';
+import { ConfigurationError, ServiceUnavailableError } from './errors.js';
+
+const debug = createDebug('kadi:tunnel');
+
+/**
+ * TunnelService class for managing and registering tunnel service implementations.
+ * This class provides service discovery, registration, and validation capabilities.
+ */
+export class TunnelService {
+  /**
+   * Creates a new TunnelService instance
+   * @param {Object} config - Global tunnel configuration
+   */
+  constructor(config = {}) {
+    this.config = config;
+    this.services = new Map();
+    this.serviceInstances = new Map();
+    this.isInitialized = false;
+  }
+
+  /**
+   * Initializes the service by discovering and loading all available services
+   * @param {string} [servicesDir] - Directory to scan for service files (optional)
+   * @returns {Promise<void>}
+   */
+  async initialize(servicesDir = null) {
+    if (this.isInitialized) {
+      return;
+    }
+
+    // Default to the services directory relative to this file
+    if (!servicesDir) {
+      const __filename = fileURLToPath(import.meta.url);
+      const __dirname = path.dirname(__filename);
+      servicesDir = path.join(__dirname, 'services');
+    }
+
+    await this.discoverServices(servicesDir);
+    this.isInitialized = true;
+  }
+
+  /**
+   * Discovers and loads all service modules from the specified directory
+   * @param {string} servicesDir - Directory to scan for service files
+   * @returns {Promise<void>}
+   */
+  async discoverServices(servicesDir) {
+    try {
+      // Check if services directory exists
+      const stats = await fs.stat(servicesDir);
+      if (!stats.isDirectory()) {
+        debug(`Services directory ${servicesDir} is not a directory`);
+        return;
+      }
+
+      // Read all files in the services directory
+      const files = await fs.readdir(servicesDir);
+
+      // Filter for JavaScript files that likely contain services
+      const serviceFiles = files.filter(file =>
+        file.endsWith('.js') &&
+        file.includes('Service') &&
+        !file.includes('.test.') &&
+        !file.includes('.spec.')
+      );
+
+      debug(`🔍 Discovering tunnel services in ${servicesDir}`);
+      debug(`   Found ${serviceFiles.length} potential service files: ${serviceFiles.join(', ')}`);
+
+      // Load each service module
+      for (const file of serviceFiles) {
+        try {
+          await this.loadService(path.join(servicesDir, file));
+        } catch (error) {
+          debug(`⚠️  Failed to load service from ${file}: ${error.message}`);
+        }
+      }
+
+      debug(`✅ Loaded ${this.services.size} tunnel services: ${Array.from(this.services.keys()).join(', ')}`);
+    } catch (error) {
+      debug(`Warning: Could not access services directory ${servicesDir}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Loads a single service module and registers it
+   * @param {string} servicePath - Full path to the service module file
+   * @returns {Promise<void>}
+   */
+  async loadService(servicePath) {
+    try {
+      // Dynamic import of the service module
+      const absolutePath = path.isAbsolute(servicePath) ? servicePath : path.resolve(servicePath);
+      const importPath = `file://${absolutePath}`;
+      const serviceModule = await import(importPath);
+
+      // Look for the default export or a named export that extends BaseTunnelService
+      let ServiceClass = null;
+
+      if (serviceModule.default && this.isValidServiceClass(serviceModule.default)) {
+        ServiceClass = serviceModule.default;
+      } else {
+        // Look for named exports that extend BaseTunnelService
+        for (const [name, exportedClass] of Object.entries(serviceModule)) {
+          if (this.isValidServiceClass(exportedClass)) {
+            ServiceClass = exportedClass;
+            break;
+          }
+        }
+      }
+
+      if (!ServiceClass) {
+        throw new Error(`No valid service class found in ${servicePath}`);
+      }
+
+      // Register the service class
+      this.registerService(ServiceClass);
+
+    } catch (error) {
+      throw new Error(`Failed to load service from ${servicePath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Validates that a class is a proper tunnel service implementation
+   * @param {Function} ServiceClass - Class to validate
+   * @returns {boolean} True if class is a valid service
+   */
+  isValidServiceClass(ServiceClass) {
+    // Must be a function (class constructor)
+    if (typeof ServiceClass !== 'function') {
+      return false;
+    }
+
+    // Must extend BaseTunnelService
+    if (!ServiceClass.prototype || !(ServiceClass.prototype instanceof BaseTunnelService)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Registers a service class for use
+   * @param {Function|BaseTunnelService} serviceOrClass - Service class or instance
+   * @throws {ConfigurationError} If service class is invalid
+   */
+  registerService(serviceOrClass) {
+    // Allow registering instances directly
+    if (serviceOrClass instanceof BaseTunnelService) {
+      const serviceName = serviceOrClass.name;
+      if (!serviceName || typeof serviceName !== 'string') {
+        throw new ConfigurationError('Service name must be a non-empty string');
+      }
+      this.serviceInstances.set(serviceName, serviceOrClass);
+      // Also register a "class" entry so hasService() works
+      this.services.set(serviceName, serviceOrClass.constructor);
+      debug(`📝 Registered tunnel service instance: ${serviceName}`);
+      return;
+    }
+
+    if (!this.isValidServiceClass(serviceOrClass)) {
+      throw new ConfigurationError('Service class must extend BaseTunnelService');
+    }
+
+    // Create a temporary instance to get the service name
+    let serviceName;
+    try {
+      const tempInstance = new serviceOrClass(this.config);
+      serviceName = tempInstance.name;
+
+      // Validate that name is a non-empty string
+      if (!serviceName || typeof serviceName !== 'string') {
+        throw new ConfigurationError('Service name must be a non-empty string');
+      }
+
+      // Clean up temporary instance
+      tempInstance.removeAllListeners();
+    } catch (error) {
+      if (error instanceof ConfigurationError) throw error;
+      throw new ConfigurationError(`Failed to instantiate service for registration: ${error.message}`);
+    }
+
+    // Register the service class
+    this.services.set(serviceName, serviceOrClass);
+    debug(`📝 Registered tunnel service: ${serviceName}`);
+  }
+
+  /**
+   * Gets a service instance by name, creating it if necessary
+   * @param {string} serviceName - Name of the service to get
+   * @returns {BaseTunnelService} Service instance
+   * @throws {ServiceUnavailableError} If service is not found
+   */
+  getService(serviceName) {
+    if (!this.services.has(serviceName)) {
+      throw new ServiceUnavailableError(serviceName, `Service '${serviceName}' is not registered`);
+    }
+
+    // Return existing instance if available
+    if (this.serviceInstances.has(serviceName)) {
+      return this.serviceInstances.get(serviceName);
+    }
+
+    // Create new instance
+    const ServiceClass = this.services.get(serviceName);
+    const instance = new ServiceClass(this.config);
+
+    this.serviceInstances.set(serviceName, instance);
+    return instance;
+  }
+
+  /**
+   * Checks if a service is available
+   * @param {string} serviceName - Name of the service to check
+   * @returns {boolean} True if service is available
+   */
+  hasService(serviceName) {
+    return this.services.has(serviceName);
+  }
+
+  /**
+   * Gets a list of all registered service names
+   * @returns {string[]} Array of service names
+   */
+  getAvailableServices() {
+    return Array.from(this.services.keys());
+  }
+
+  /**
+   * Gets status information for all services
+   * @returns {Object} Status information keyed by service name
+   */
+  getServicesStatus() {
+    const status = {};
+
+    for (const serviceName of this.services.keys()) {
+      try {
+        if (this.serviceInstances.has(serviceName)) {
+          const instance = this.serviceInstances.get(serviceName);
+          const serviceStatus = instance.getStatus();
+          status[serviceName] = {
+            ...serviceStatus,
+            loaded: true
+          };
+        } else {
+          status[serviceName] = {
+            serviceName,
+            available: true,
+            loaded: false,
+            activeTunnels: 0
+          };
+        }
+      } catch (error) {
+        status[serviceName] = {
+          serviceName,
+          available: false,
+          error: error.message,
+          loaded: this.serviceInstances.has(serviceName)
+        };
+      }
+    }
+
+    return status;
+  }
+
+  /**
+   * Validates a service configuration
+   * @param {string} serviceName - Name of the service
+   * @param {Object} config - Configuration to validate
+   * @throws {ServiceUnavailableError} If service is not found
+   * @throws {ConfigurationError} If configuration is invalid
+   */
+  validateServiceConfig(serviceName, config) {
+    if (!this.hasService(serviceName)) {
+      throw new ServiceUnavailableError(serviceName);
+    }
+
+    const service = this.getService(serviceName);
+    service.validateConfig(config);
+  }
+
+  /**
+   * Shuts down all service instances and cleans up resources
+   * @returns {Promise<void>}
+   */
+  async shutdown() {
+    debug('🔄 Shutting down tunnel services...');
+
+    // Shutdown all service instances
+    const shutdownPromises = Array.from(this.serviceInstances.values()).map(instance =>
+      instance.shutdown().catch(error => {
+        debug(`Warning: Failed to shutdown service ${instance.name}:`, error.message);
+      })
+    );
+
+    await Promise.allSettled(shutdownPromises);
+
+    // Clear all registrations
+    this.services.clear();
+    this.serviceInstances.clear();
+    this.isInitialized = false;
+
+    debug('✅ All tunnel services shut down');
+  }
+}