@kadi.build/tunnel-services 1.0.0

package/src/services/NgrokTunnelService.js

@@ -0,0 +1,322 @@
+/**
+ * @fileoverview Ngrok tunnel service implementation
+ * Uses the modern @ngrok/ngrok SDK (no binary spawning).
+ *
+ * Features:
+ * - HTTP/HTTPS tunneling with automatic HTTPS
+ * - Custom domain support (paid accounts)
+ * - Authentication token support
+ * - Clean listener-based lifecycle (no child process management)
+ */
+
+import createDebug from 'debug';
+import { BaseTunnelService } from '../BaseTunnelService.js';
+import {
+  TransientTunnelError,
+  PermanentTunnelError,
+  ConnectionTimeoutError,
+  AuthenticationFailedError
+} from '../errors.js';
+
+const debug = createDebug('kadi:tunnel:ngrok');
+
+// Modern @ngrok/ngrok SDK — no binary, no child process
+let ngrok;
+try {
+  ngrok = await import('@ngrok/ngrok');
+} catch {
+  // Fall back to legacy 'ngrok' package if @ngrok/ngrok isn't installed
+  try {
+    ngrok = await import('ngrok');
+    ngrok.__legacy = true;
+  } catch {
+    ngrok = null;
+  }
+}
+
+/**
+ * NgrokTunnelService
+ *
+ * Provides an HTTP/HTTPS tunnel via the modern @ngrok/ngrok SDK.
+ * Falls back to the legacy 'ngrok' npm package if @ngrok/ngrok is not installed.
+ *
+ * @extends BaseTunnelService
+ */
+export default class NgrokTunnelService extends BaseTunnelService {
+
+  constructor(config = {}) {
+    super(config);
+    this.DEFAULT_TIMEOUT = 45000;
+    this.authToken = config.ngrokAuthToken || config.authToken ||
+                     process.env.NGROK_AUTHTOKEN || process.env.NGROK_AUTH_TOKEN || null;
+    this.region = config.region || 'us';
+    this._listeners = new Map(); // tunnelId -> Listener
+  }
+
+  get name() {
+    return 'ngrok';
+  }
+
+  async connect(options) {
+    if (!options || typeof options.port !== 'number') {
+      throw new PermanentTunnelError('Port number is required for Ngrok tunnel');
+    }
+
+    if (options.port < 1 || options.port > 65535) {
+      throw new PermanentTunnelError(`Invalid port number: ${options.port}. Must be between 1-65535`);
+    }
+
+    if (!ngrok) {
+      throw new PermanentTunnelError(
+        'Neither @ngrok/ngrok nor ngrok packages are installed. ' +
+        'Install with: npm install @ngrok/ngrok'
+      );
+    }
+
+    const tunnelId = this._generateTunnelId();
+    const timeout = options.timeout || this.DEFAULT_TIMEOUT;
+    const authToken = options.authToken || this.authToken;
+    const protocol = options.protocol || 'http';
+
+    this._emitProgress('connecting', 'Establishing Ngrok tunnel...', tunnelId);
+
+    try {
+      const sdkType = ngrok.__legacy ? 'legacy' : 'modern';
+      debug(`🔗 Creating Ngrok tunnel [${sdkType}]: ${protocol} localhost:${options.port}`);
+
+      let url;
+
+      // ── Modern SDK path (@ngrok/ngrok) ─────────────────────────────
+      if (!ngrok.__legacy) {
+        const forwardOpts = {
+          addr: options.port,
+          authtoken: authToken || undefined,
+          authtoken_from_env: !authToken,
+          proto: protocol === 'tcp' ? 'tcp' : 'http',
+        };
+
+        if (options.subdomain) {
+          forwardOpts.domain = options.subdomain;
+          debug(`   📍 Custom domain: ${options.subdomain}`);
+        }
+
+        const listener = await Promise.race([
+          ngrok.forward(forwardOpts),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new ConnectionTimeoutError(this.name, timeout)), timeout)
+          )
+        ]);
+
+        url = listener.url();
+        this._listeners.set(tunnelId, listener);
+
+      // ── Legacy SDK path (ngrok v4.x wrapper) ──────────────────────
+      } else {
+        const ngrokOptions = {
+          addr: options.port,
+          proto: 'http',
+          authtoken: authToken || undefined,
+          region: options.region || (this.region !== 'us' ? this.region : undefined),
+          subdomain: options.subdomain || undefined,
+          ...(options.ngrokOptions || {})
+        };
+
+        // Defensive cleanup for legacy binary
+        try { await ngrok.disconnect(); } catch {}
+        try { await ngrok.kill(); } catch {}
+
+        try {
+          url = await Promise.race([
+            ngrok.connect(ngrokOptions),
+            new Promise((_, reject) =>
+              setTimeout(() => reject(new ConnectionTimeoutError(this.name, timeout)), timeout)
+            )
+          ]);
+        } catch (firstError) {
+          const msg = (firstError && (firstError.msg || firstError.message)) || String(firstError);
+          const rawBody = firstError && (firstError.body || (firstError.response && firstError.response.body));
+          let bodyString = '';
+          if (typeof rawBody === 'string') bodyString = rawBody;
+          else if (rawBody) {
+            try { bodyString = JSON.stringify(rawBody); } catch { bodyString = ''; }
+          }
+          const alreadyExists = msg.includes('already exists') || bodyString.includes('already exists');
+          const invalidConfig = msg.includes('invalid tunnel configuration') || bodyString.includes('invalid tunnel configuration');
+
+          if (alreadyExists || invalidConfig) {
+            try { await ngrok.disconnect(); } catch {}
+            try { await ngrok.kill(); } catch {}
+            await new Promise((r) => setTimeout(r, 500));
+
+            url = await Promise.race([
+              ngrok.connect(ngrokOptions),
+              new Promise((_, reject) =>
+                setTimeout(() => reject(new ConnectionTimeoutError(this.name, timeout)), timeout)
+              )
+            ]);
+          } else {
+            throw firstError;
+          }
+        }
+      }
+
+      // Store tunnel information
+      const tunnelInfo = {
+        id: tunnelId,
+        serviceName: 'ngrok',
+        localPort: options.port,
+        region: this.region,
+        protocol: protocol,
+        url: url,
+        ngrokUrl: url,
+        createdAt: new Date(),
+        status: 'active',
+      };
+
+      this.activeTunnels.set(tunnelId, tunnelInfo);
+
+      this._emitProgress('connected', 'Ngrok tunnel established', tunnelId);
+      this._emitTunnelCreated(tunnelInfo);
+
+      debug(`✅ Ngrok tunnel established: ${url}`);
+
+      return {
+        tunnelId,
+        url,
+        subdomain: this._extractSubdomain(url),
+        localPort: options.port,
+        createdAt: new Date(),
+        status: 'active',
+        service: 'ngrok',
+        region: this.region,
+        protocol,
+      };
+
+    } catch (error) {
+      this.activeTunnels.delete(tunnelId);
+      this._listeners.delete(tunnelId);
+
+      if (error instanceof ConnectionTimeoutError) {
+        throw error;
+      }
+
+      const errorMessage = error.message || error.toString();
+
+      if (errorMessage.includes('authentication') || errorMessage.includes('authtoken') || errorMessage.includes('ERR_NGROK_') || errorMessage.includes('invalid token')) {
+        throw new AuthenticationFailedError(
+          this.name,
+          `Ngrok authentication failed: ${errorMessage}. Check your NGROK_AUTHTOKEN.`
+        );
+      }
+
+      if (errorMessage.includes('subdomain') && (errorMessage.includes('reserved') || errorMessage.includes('unavailable'))) {
+        throw new PermanentTunnelError(
+          'Subdomain is reserved or unavailable. Try a different subdomain.'
+        );
+      }
+
+      if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('network') || errorMessage.includes('timeout')) {
+        throw new TransientTunnelError(`Network error: ${errorMessage}`);
+      }
+
+      throw new TransientTunnelError(`Ngrok tunnel creation failed: ${errorMessage}`);
+    }
+  }
+
+  async disconnect(tunnelId) {
+    const tunnel = this.activeTunnels.get(tunnelId);
+    if (!tunnel) {
+      throw new Error(`Tunnel ${tunnelId} not found`);
+    }
+
+    this._emitProgress('disconnecting', 'Destroying Ngrok tunnel...', tunnelId);
+
+    try {
+      // Modern SDK: close the listener directly
+      const listener = this._listeners.get(tunnelId);
+      if (listener && typeof listener.close === 'function') {
+        await listener.close();
+        debug(`🔌 Ngrok listener closed: ${tunnel.ngrokUrl}`);
+      } else if (ngrok && !ngrok.__legacy) {
+        await ngrok.disconnect(tunnel.ngrokUrl);
+        debug(`🔌 Ngrok tunnel disconnected: ${tunnel.ngrokUrl}`);
+      } else if (ngrok) {
+        if (tunnel.ngrokUrl) {
+          await ngrok.disconnect(tunnel.ngrokUrl);
+        } else {
+          await ngrok.disconnect();
+        }
+        debug(`🔌 Ngrok tunnel disconnected (legacy): ${tunnel.ngrokUrl}`);
+      }
+
+      this.activeTunnels.delete(tunnelId);
+      this._listeners.delete(tunnelId);
+
+      if (ngrok?.__legacy && this.activeTunnels.size === 0) {
+        try { await ngrok.kill(); } catch {}
+        debug('✅ Ngrok process terminated (legacy)');
+      }
+
+      this._emitProgress('disconnected', 'Ngrok tunnel destroyed', tunnelId);
+      this._emitTunnelDestroyed(tunnelId);
+      debug(`✅ Ngrok tunnel ${tunnelId} disconnected`);
+    } catch (error) {
+      debug(`❌ Error disconnecting Ngrok tunnel ${tunnelId}: ${error.message}`);
+      this.activeTunnels.delete(tunnelId);
+      this._listeners.delete(tunnelId);
+      this._emitTunnelDestroyed(tunnelId);
+      throw error;
+    }
+  }
+
+  getStatus() {
+    return {
+      serviceName: this.name,
+      activeTunnels: this.activeTunnels.size,
+      available: !!ngrok,
+      modern: ngrok ? !ngrok.__legacy : false,
+      status: `${this.activeTunnels.size} active tunnels`,
+      region: this.region,
+      authConfigured: !!this.authToken
+    };
+  }
+
+  _extractSubdomain(url) {
+    try {
+      const parsed = new URL(url);
+      const hostname = parsed.hostname;
+      if (hostname.includes('.ngrok.')) {
+        const parts = hostname.split('.');
+        return parts.length > 2 ? parts[0] : null;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  async shutdown() {
+    debug('🛑 Shutting down Ngrok service...');
+
+    for (const [tunnelId, listener] of this._listeners) {
+      try {
+        if (typeof listener.close === 'function') {
+          await listener.close();
+        }
+      } catch (error) {
+        debug('Warning during listener close:', error.message);
+      }
+    }
+    this._listeners.clear();
+
+    if (ngrok?.__legacy) {
+      try { await ngrok.disconnect(); } catch {}
+      try { await ngrok.kill(); } catch {}
+      debug('✅ Legacy ngrok process terminated');
+    } else if (ngrok) {
+      try { await ngrok.disconnect(); } catch {}
+    }
+
+    await super.shutdown();
+  }
+}

package/src/services/PinggyTunnelService.js

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview Pinggy tunnel service implementation
+ * Provides SSH-based tunneling through pinggy.io
+ */
+
+import createDebug from 'debug';
+import { BaseTunnelService } from '../BaseTunnelService.js';
+import {
+  TransientTunnelError,
+  PermanentTunnelError,
+  SSHUnavailableError,
+  ConnectionTimeoutError
+} from '../errors.js';
+import { spawn } from 'child_process';
+
+const debug = createDebug('kadi:tunnel:pinggy');
+
+/**
+ * Pinggy tunnel service implementation
+ *
+ * Provides SSH-based tunneling through pinggy.io with support for:
+ * - Custom subdomains with {subdomain}.a.pinggy.io format
+ * - 60-minute timeout warnings for free accounts
+ * - Automatic URL extraction from SSH output
+ * - Process management and cleanup
+ * - Comprehensive error handling
+ *
+ * @extends BaseTunnelService
+ */
+export default class PinggyTunnelService extends BaseTunnelService {
+
+  constructor(config) {
+    super(config);
+    this.DEFAULT_TIMEOUT = 30000;
+  }
+
+  get name() {
+    return 'pinggy';
+  }
+
+  async connect(options) {
+    if (!options || typeof options.port !== 'number') {
+      throw new PermanentTunnelError('Port number is required for Pinggy tunnel');
+    }
+
+    const tunnelId = this._generateTunnelId();
+    const timeout = options.timeout || this.DEFAULT_TIMEOUT;
+
+    this._emitProgress('connecting', 'Establishing Pinggy tunnel...', tunnelId);
+
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+      let sshProcess = null;
+      let timeoutHandle = null;
+
+      const sshArgs = this._buildSSHArgs(options.subdomain, options.port);
+
+      debug(`🔗 Creating Pinggy tunnel: ssh ${sshArgs.join(' ')}`);
+
+      try {
+        sshProcess = spawn('ssh', sshArgs, {
+          stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        const tunnelInfo = {
+          id: tunnelId,
+          serviceName: 'pinggy',
+          localPort: options.port,
+          process: sshProcess,
+          createdAt: new Date(),
+          status: 'connecting'
+        };
+
+        this.activeTunnels.set(tunnelId, tunnelInfo);
+
+        let output = '';
+        let tunnelUrl = null;
+
+        const handleOutput = (data) => {
+          const text = data.toString();
+          output += text;
+          debug('Pinggy output:', text.trim());
+
+          tunnelUrl = this._extractPinggyUrl(output);
+          if (tunnelUrl && !resolved) {
+            resolved = true;
+
+            if (timeoutHandle) {
+              clearTimeout(timeoutHandle);
+            }
+
+            tunnelInfo.status = 'active';
+            tunnelInfo.url = tunnelUrl;
+            tunnelInfo.timeoutWarning = 'Tunnel will timeout after 60 minutes on free plan';
+
+            this._emitProgress('connected', 'Pinggy tunnel established', tunnelId);
+            this._emitTunnelCreated(tunnelInfo);
+
+            debug('⚠️  Note: Pinggy free tunnels timeout after 60 minutes');
+
+            resolve({
+              tunnelId: tunnelId,
+              url: tunnelUrl,
+              subdomain: this._extractSubdomain(tunnelUrl),
+              localPort: options.port,
+              createdAt: new Date(),
+              status: 'active',
+              service: 'pinggy',
+              timeoutWarning: 'Tunnel will timeout after 60 minutes on free plan'
+            });
+          }
+        };
+
+        sshProcess.stdout.on('data', handleOutput);
+        sshProcess.stderr.on('data', handleOutput);
+
+        sshProcess.on('error', (error) => {
+          if (!resolved) {
+            resolved = true;
+
+            if (timeoutHandle) {
+              clearTimeout(timeoutHandle);
+            }
+
+            this.activeTunnels.delete(tunnelId);
+
+            if (error.code === 'ENOENT') {
+              reject(new SSHUnavailableError());
+            } else {
+              reject(new TransientTunnelError(`Pinggy tunnel failed: ${error.message}`));
+            }
+          }
+        });
+
+        sshProcess.on('exit', (code) => {
+          if (!resolved) {
+            resolved = true;
+
+            if (timeoutHandle) {
+              clearTimeout(timeoutHandle);
+            }
+
+            this.activeTunnels.delete(tunnelId);
+
+            if (code !== 0) {
+              reject(new TransientTunnelError(`Pinggy tunnel exited with code ${code}. This might be due to the 60-minute timeout.`));
+            }
+          } else {
+            this.activeTunnels.delete(tunnelId);
+            this._emitTunnelDestroyed(tunnelId);
+          }
+        });
+
+        timeoutHandle = setTimeout(() => {
+          if (!resolved) {
+            resolved = true;
+
+            if (sshProcess && !sshProcess.killed) {
+              sshProcess.kill();
+            }
+
+            this.activeTunnels.delete(tunnelId);
+            reject(new ConnectionTimeoutError('pinggy', timeout));
+          }
+        }, timeout);
+
+      } catch (error) {
+        if (!resolved) {
+          resolved = true;
+          reject(new TransientTunnelError(`Failed to start Pinggy tunnel: ${error.message}`));
+        }
+      }
+    });
+  }
+
+  async disconnect(tunnelId) {
+    const tunnelInfo = this.activeTunnels.get(tunnelId);
+
+    if (!tunnelInfo) {
+      return false;
+    }
+
+    try {
+      if (tunnelInfo.process && !tunnelInfo.process.killed) {
+        tunnelInfo.process.kill();
+      }
+
+      this.activeTunnels.delete(tunnelId);
+      this._emitTunnelDestroyed(tunnelId);
+
+      return true;
+    } catch (error) {
+      this.activeTunnels.delete(tunnelId);
+      return false;
+    }
+  }
+
+  getStatus() {
+    return {
+      serviceName: 'pinggy',
+      available: true,
+      isActive: this.activeTunnels.size > 0,
+      activeTunnels: this.activeTunnels.size,
+      tunnels: Array.from(this.activeTunnels.values()).map(tunnel => ({
+        id: tunnel.id,
+        url: tunnel.url,
+        localPort: tunnel.localPort,
+        status: tunnel.status,
+        createdAt: tunnel.createdAt,
+        timeoutWarning: tunnel.timeoutWarning
+      }))
+    };
+  }
+
+  _buildSSHArgs(subdomain, port) {
+    const host = subdomain ? `${subdomain}.a.pinggy.io` : 'a.pinggy.io';
+
+    return [
+      '-p', '443',
+      '-R', `0:localhost:${port}`,
+      `qr@${host}`,
+      '-o', 'StrictHostKeyChecking=no',
+      '-o', 'ServerAliveInterval=30',
+      '-o', 'ExitOnForwardFailure=yes'
+    ];
+  }
+
+  _extractPinggyUrl(output) {
+    const patterns = [
+      /https:\/\/[a-zA-Z0-9-]+\.a\.free\.pinggy\.link/,
+      /https:\/\/[a-zA-Z0-9-]+\.a\.pinggy\.io/,
+      /http:\/\/[a-zA-Z0-9-]+\.a\.free\.pinggy\.link/,
+      /http:\/\/[a-zA-Z0-9-]+\.a\.pinggy\.io/
+    ];
+
+    for (const pattern of patterns) {
+      const match = output.match(pattern);
+      if (match) {
+        return match[0];
+      }
+    }
+
+    return null;
+  }
+
+  _extractSubdomain(url) {
+    if (!url) return null;
+    const patterns = [
+      /https?:\/\/([a-zA-Z0-9-]+)\.a\.free\.pinggy\.link/,
+      /https?:\/\/([a-zA-Z0-9-]+)\.a\.pinggy\.io/
+    ];
+
+    for (const pattern of patterns) {
+      const match = url.match(pattern);
+      if (match) {
+        return match[1];
+      }
+    }
+
+    return null;
+  }
+}