@kadi.build/tunnel-services 1.0.0

package/README.md

@@ -0,0 +1,343 @@
+# @kadi.build/tunnel-services
+
+> Unified tunnel service manager for exposing local ports to the internet. Supports 6 tunnel providers with automatic failover, KĀDI as the default primary service.
+
+## Features
+
+- 🚇 **6 Tunnel Providers** — KĀDI, Serveo, ngrok, LocalTunnel, Pinggy, localhost.run
+- 🔄 **Automatic Fallback** — Seamlessly switches to the next provider on failure
+- 🎯 **KĀDI-First** — KĀDI is the default primary tunnel service
+- 📡 **Event-Driven** — Rich event system for monitoring tunnel lifecycle
+- 🔧 **Diagnostic Tools** — Built-in diagnostics for troubleshooting
+- 🧩 **Pluggable** — Register custom tunnel services easily
+- 📦 **Zero Config** — Works out of the box with sensible defaults
+
+## Installation
+
+```bash
+npm install @kadi.build/tunnel-services
+```
+
+### Optional Dependencies
+
+Install based on which providers you want to use:
+
+```bash
+# For ngrok support
+npm install @ngrok/ngrok
+
+# For localtunnel support  
+npm install localtunnel
+
+# SSH-based providers (serveo, pinggy, localhost.run, kadi) 
+# require `ssh` on your PATH — no extra packages needed
+```
+
+## Quick Start
+
+### One-Liner
+
+```js
+import { expose } from '@kadi.build/tunnel-services';
+
+// Expose port 3000 to the internet
+const url = await expose(3000);
+console.log(`Public URL: ${url}`);
+```
+
+### With Tunnel Management
+
+```js
+import { createTunnel } from '@kadi.build/tunnel-services';
+
+const tunnel = await createTunnel(3000, {
+  service: 'kadi',         // or 'serveo', 'ngrok', 'localtunnel', 'pinggy', 'localhost.run'
+  subdomain: 'my-app',     // optional
+  autoFallback: true        // try next provider on failure
+});
+
+console.log(`Public URL: ${tunnel.publicUrl}`);
+console.log(`Local Port: ${tunnel.localPort}`);
+console.log(`Service:    ${tunnel.service}`);
+
+// When done
+await tunnel.close();
+```
+
+### Full Control with TunnelManager
+
+```js
+import { TunnelManager } from '@kadi.build/tunnel-services';
+
+const manager = new TunnelManager({
+  primaryService: 'kadi',
+  fallbackServices: ['serveo', 'ngrok', 'localtunnel', 'pinggy'],
+  autoFallback: true,
+  maxConcurrentTunnels: 10,
+  connectionTimeout: 30000
+});
+
+await manager.initialize();
+
+// Listen for events
+manager.on('tunnelCreated', ({ id, publicUrl, service }) => {
+  console.log(`Tunnel ${id} created on ${service}: ${publicUrl}`);
+});
+
+manager.on('tunnelDestroyed', ({ id }) => {
+  console.log(`Tunnel ${id} closed`);
+});
+
+manager.on('serviceFailed', ({ service, error }) => {
+  console.warn(`${service} failed: ${error.message}, trying next...`);
+});
+
+// Create tunnels
+const tunnel1 = await manager.createTunnel(3000);
+const tunnel2 = await manager.createTunnel(8080, { service: 'ngrok' });
+
+// Check status
+console.log(manager.getStatus());
+
+// Close specific tunnel
+await manager.closeTunnel(tunnel1.id);
+
+// Cleanup everything
+await manager.cleanup();
+```
+
+## API Reference
+
+### Factory Functions
+
+#### `expose(port, service?)` → `Promise<string>`
+
+Returns a public URL string. Simplest way to expose a port.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `port` | `number` | — | Local port to expose |
+| `service` | `string` | `'kadi'` | Tunnel service to use |
+
+#### `createTunnel(port, options?)` → `Promise<TunnelInfo>`
+
+Creates a tunnel and returns a `TunnelInfo` object with a `close()` method.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `port` | `number` | — | Local port to expose |
+| `options.service` | `string` | `'kadi'` | Preferred service |
+| `options.subdomain` | `string` | — | Requested subdomain |
+| `options.autoFallback` | `boolean` | `true` | Enable fallback |
+
+### TunnelManager
+
+The main orchestrator class. Extends `EventEmitter`.
+
+#### Constructor Options
+
+```js
+new TunnelManager({
+  primaryService: 'kadi',           // Default primary service
+  fallbackServices: ['serveo', 'ngrok', 'localtunnel', 'pinggy'],
+  autoFallback: true,               // Auto-fallback on failure
+  maxConcurrentTunnels: 10,         // Max simultaneous tunnels
+  connectionTimeout: 30000,         // Connection timeout (ms)
+  ngrokAuthToken: '',               // Ngrok auth token
+  kadiServer: '',                   // KĀDI tunnel server
+  kadiMode: 'ssh'                   // 'ssh' or 'frpc'
+})
+```
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `initialize()` | `Promise<void>` | Discover and load services |
+| `createTunnel(port, options?)` | `Promise<TunnelInfo>` | Create a new tunnel |
+| `closeTunnel(id)` | `Promise<void>` | Close specific tunnel |
+| `closeAllTunnels()` | `Promise<void>` | Close all active tunnels |
+| `getStatus()` | `object` | Manager status + active tunnels |
+| `getAvailableServices()` | `string[]` | List discovered services |
+| `testService(name)` | `Promise<object>` | Test if a service is available |
+| `runDiagnostics()` | `Promise<object>` | Run diagnostics on all services |
+| `cleanup()` | `Promise<void>` | Full shutdown |
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `tunnelCreated` | `TunnelInfo` | Tunnel successfully created |
+| `tunnelDestroyed` | `{ id }` | Tunnel closed |
+| `serviceFailed` | `{ service, error }` | Service failed, falling back |
+| `error` | `Error` | Unrecoverable error |
+
+### TunnelInfo Object
+
+```js
+{
+  id: 'tunnel-abc123',          // Unique tunnel ID
+  publicUrl: 'https://...',      // Public URL
+  localPort: 3000,              // Local port being exposed
+  service: 'kadi',              // Service that created it
+  subdomain: 'my-app',         // Subdomain (if requested)
+  createdAt: Date,              // Creation timestamp
+  metadata: {}                  // Service-specific metadata
+}
+```
+
+### BaseTunnelService
+
+Abstract base class for all tunnel services. Extend this to create custom providers.
+
+```js
+import { BaseTunnelService } from '@kadi.build/tunnel-services';
+
+class MyTunnelService extends BaseTunnelService {
+  get name() { return 'my-tunnel'; }
+
+  async connect(port, options = {}) {
+    // Connect and return { url, port, ... }
+  }
+
+  async disconnect() {
+    // Clean up
+  }
+
+  getStatus() {
+    return { connected: this._connected, service: this.name };
+  }
+}
+```
+
+### Error Classes
+
+| Error | Fallback? | Description |
+|-------|-----------|-------------|
+| `TunnelError` | — | Base tunnel error |
+| `TransientTunnelError` | ✅ Yes | Temporary failure, try next service |
+| `PermanentTunnelError` | ❌ No | Permanent failure, do not fallback |
+| `CriticalTunnelError` | ❌ No | Critical system-level failure |
+| `ConfigurationError` | ❌ No | Invalid configuration |
+| `ServiceUnavailableError` | ✅ Yes | Service not available/installed |
+| `ConnectionTimeoutError` | ✅ Yes | Connection timed out |
+| `SSHUnavailableError` | ✅ Yes | SSH binary not found |
+| `AuthenticationFailedError` | ❌ No | Authentication failed |
+
+## Tunnel Providers
+
+### KĀDI (default)
+
+SSH or frpc-based tunnel to KĀDI infrastructure.
+
+```js
+const manager = new TunnelManager({
+  primaryService: 'kadi',
+  kadiServer: 'tunnel.kadi.build',
+  kadiMode: 'ssh'  // or 'frpc'
+});
+```
+
+**Environment Variables:** `KADI_TUNNEL_SERVER`, `KADI_TUNNEL_PORT`
+
+### Serveo
+
+Free SSH-based tunneling via serveo.net. No account required.
+
+```js
+await manager.createTunnel(3000, { service: 'serveo' });
+```
+
+**Requires:** `ssh` on PATH
+
+### ngrok
+
+Industry-standard tunnel service. Requires auth token for extended use.
+
+```js
+const manager = new TunnelManager({
+  primaryService: 'ngrok',
+  ngrokAuthToken: process.env.NGROK_AUTH_TOKEN
+});
+```
+
+**Requires:** `@ngrok/ngrok` or legacy `ngrok` package  
+**Environment Variables:** `NGROK_AUTH_TOKEN`
+
+### LocalTunnel
+
+Open-source tunneling via localtunnel.me.
+
+```js
+await manager.createTunnel(3000, { service: 'localtunnel' });
+```
+
+**Requires:** `localtunnel` npm package
+
+### Pinggy
+
+SSH-based tunneling via pinggy.io.
+
+```js
+await manager.createTunnel(3000, { service: 'pinggy' });
+```
+
+**Requires:** `ssh` on PATH
+
+### localhost.run
+
+SSH-based tunneling via localhost.run. No account required.
+
+```js
+await manager.createTunnel(3000, { service: 'localhost.run' });
+```
+
+**Requires:** `ssh` on PATH
+
+## Fallback Order
+
+When `autoFallback: true` (default), the manager tries services in this order:
+
+1. **KĀDI** (primary)
+2. **Serveo**
+3. **ngrok**
+4. **LocalTunnel**
+5. **Pinggy**
+
+If a service throws a `TransientTunnelError` or `ServiceUnavailableError`, the next service in the chain is attempted. `PermanentTunnelError` stops the fallback chain.
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test suite
+npm run test:manager
+npm run test:kadi
+npm run test:ngrok
+npm run test:serveo
+
+# Integration tests (require credentials/tools)
+NGROK_AUTH_TOKEN=xxx npm run test:ngrok
+KADI_TUNNEL_SERVER=tunnel.kadi.build npm run test:kadi
+```
+
+## Environment Variables
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `NGROK_AUTH_TOKEN` | ngrok | Authentication token |
+| `KADI_TUNNEL_SERVER` | KĀDI | Tunnel server hostname |
+| `KADI_TUNNEL_PORT` | KĀDI | Tunnel server port |
+| `DEBUG` | all | Debug logging (e.g., `kadi:tunnel:*`) |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- SSH on PATH (for serveo, pinggy, localhost.run, kadi)
+- Optional: `@ngrok/ngrok`, `localtunnel` npm packages
+
+## License
+
+MIT © KĀDI

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@kadi.build/tunnel-services",
+  "version": "1.0.0",
+  "description": "Unified tunnel management for exposing local ports via ngrok, serveo, localtunnel, KĀDI, and more",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node tests/run-all-tests.js",
+    "test:integration": "node tests/test-kadi-integration.js",
+    "test:manager": "node tests/test-tunnel-manager.js",
+    "test:ngrok": "node tests/test-ngrok-tunnel.js",
+    "test:serveo": "node tests/test-serveo-tunnel.js",
+    "test:localtunnel": "node tests/test-localtunnel.js",
+    "test:pinggy": "node tests/test-pinggy-tunnel.js",
+    "test:kadi": "node tests/test-kadi-tunnel.js",
+    "test:all-services": "node tests/test-all-tunnels.js"
+  },
+  "keywords": [
+    "tunnel",
+    "ngrok",
+    "serveo",
+    "localtunnel",
+    "pinggy",
+    "kadi",
+    "localhost",
+    "expose",
+    "port-forwarding"
+  ],
+  "dependencies": {
+    "@kadi.build/tunnel-client": "^0.3.0",
+    "debug": "^4.3.4"
+  },
+  "optionalDependencies": {
+    "@ngrok/ngrok": "^1.4.1",
+    "localtunnel": "^2.0.2"
+  },
+  "peerDependencies": {
+    "ssh2": "^1.15.0"
+  },
+  "peerDependenciesMeta": {
+    "ssh2": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}

package/src/BaseTunnelService.js

@@ -0,0 +1,300 @@
+/**
+ * @fileoverview Abstract base class for all tunnel services
+ * Based on TunnelManagerSpec.md Section 3.2 specification
+ */
+
+import EventEmitter from 'events';
+import {
+  TransientTunnelError,
+  PermanentTunnelError,
+  CriticalTunnelError,
+  ConfigurationError,
+  SSHUnavailableError,
+  ConnectionTimeoutError,
+  AuthenticationFailedError
+} from './errors.js';
+
+/**
+ * Abstract base class that defines the contract for all tunnel service implementations.
+ * This class MUST NOT be instantiated directly - it serves as an interface specification.
+ *
+ * All concrete tunnel services must extend this class and implement its abstract methods.
+ *
+ * @abstract
+ * @extends EventEmitter
+ */
+export class BaseTunnelService extends EventEmitter {
+  /**
+   * Constructor for the base tunnel service
+   * @param {Object} config - Global tunnel configuration object
+   * @throws {Error} If instantiated directly (must be subclassed)
+   */
+  constructor(config) {
+    super();
+
+    // Prevent direct instantiation of abstract class
+    if (this.constructor === BaseTunnelService) {
+      throw new Error('BaseTunnelService is abstract and cannot be instantiated directly');
+    }
+
+    this.config = config || {};
+    this.activeTunnels = new Map();
+    this.isShuttingDown = false;
+
+    // Validate that subclass implements required abstract methods
+    this._validateImplementation();
+  }
+
+  /**
+   * Validates that the subclass properly implements all abstract methods
+   * @private
+   */
+  _validateImplementation() {
+    const requiredMethods = ['name', 'connect', 'disconnect', 'getStatus'];
+
+    for (const method of requiredMethods) {
+      if (method === 'name') {
+        // Check getter exists and returns string
+        const descriptor = Object.getOwnPropertyDescriptor(this.constructor.prototype, method);
+        if (!descriptor || !descriptor.get) {
+          throw new Error(`Subclass must implement getter '${method}'`);
+        }
+      } else {
+        // Check method exists and is not the abstract implementation
+        if (typeof this[method] !== 'function' || this[method] === BaseTunnelService.prototype[method]) {
+          throw new Error(`Subclass must implement method '${method}'`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Abstract getter that returns the unique service name identifier
+   * @abstract
+   * @returns {string} The service name (e.g., 'serveo', 'pinggy', 'localtunnel')
+   * @throws {Error} Must be implemented by subclass
+   */
+  get name() {
+    throw new Error('Abstract getter "name" must be implemented by subclass');
+  }
+
+  /**
+   * Abstract method to establish a tunnel connection
+   * @abstract
+   * @param {Object} options - Connection options specific to the service
+   * @param {number} options.port - Local port to tunnel
+   * @param {string} [options.subdomain] - Requested subdomain (if supported)
+   * @param {string} [options.region] - Preferred region (if supported)
+   * @param {number} [options.timeout=30000] - Connection timeout in milliseconds
+   * @returns {Promise<Object>} Promise that resolves with tunnel information
+   * @throws {TransientTunnelError} For temporary failures that should trigger fallback
+   * @throws {PermanentTunnelError} For permanent failures that should not trigger fallback
+   * @throws {CriticalTunnelError} For critical failures that should stop all operations
+   */
+  async connect(options) {
+    throw new Error('Abstract method "connect" must be implemented by subclass');
+  }
+
+  /**
+   * Abstract method to disconnect and destroy a tunnel
+   * @abstract
+   * @param {string} tunnelId - Unique identifier of the tunnel to destroy
+   * @returns {Promise<void>} Promise that resolves when tunnel is destroyed
+   * @throws {Error} If tunnel ID is not found or destruction fails
+   */
+  async disconnect(tunnelId) {
+    throw new Error('Abstract method "disconnect" must be implemented by subclass');
+  }
+
+  /**
+   * Abstract method to get current service status
+   * @abstract
+   * @returns {Object} Current status of the service
+   */
+  getStatus() {
+    throw new Error('Abstract method "getStatus" must be implemented by subclass');
+  }
+
+  /**
+   * Shutdown method for cleanup when service is no longer needed
+   * Can be overridden by subclasses for specific cleanup logic
+   * @returns {Promise<void>} Promise that resolves when shutdown is complete
+   */
+  async shutdown() {
+    this.isShuttingDown = true;
+
+    // Disconnect all active tunnels
+    const disconnectPromises = Array.from(this.activeTunnels.keys()).map(tunnelId =>
+      this.disconnect(tunnelId).catch(error => {
+        // Silently handle shutdown errors
+      })
+    );
+
+    await Promise.allSettled(disconnectPromises);
+    this.activeTunnels.clear();
+    this.removeAllListeners();
+  }
+
+  /**
+   * Validates configuration object for the service
+   * Can be overridden by subclasses for service-specific validation
+   * @param {Object} config - Configuration to validate
+   * @throws {ConfigurationError} If configuration is invalid
+   */
+  validateConfig(config) {
+    if (!config || typeof config !== 'object') {
+      throw new ConfigurationError('Configuration must be an object');
+    }
+
+    // Base validation - subclasses can override for specific requirements
+    if (config.timeout !== undefined && (typeof config.timeout !== 'number' || config.timeout <= 0)) {
+      throw new ConfigurationError('Timeout must be a positive number', 'timeout', config.timeout);
+    }
+  }
+
+  /**
+   * Determines if an error is transient (should trigger fallback)
+   * @param {Error} error - Error to categorize
+   * @returns {boolean} True if error is transient
+   */
+  isTransientError(error) {
+    if (error instanceof TransientTunnelError) return true;
+    if (error instanceof PermanentTunnelError || error instanceof CriticalTunnelError) return false;
+
+    const message = error.message ? error.message.toLowerCase() : '';
+    const transientPatterns = [
+      'timeout',
+      'connection refused',
+      'network unreachable',
+      'host unreachable',
+      'temporarily unavailable',
+      'service unavailable',
+      'econnrefused',
+      'enotfound',
+      'etimedout'
+    ];
+
+    return transientPatterns.some(pattern => message.includes(pattern));
+  }
+
+  /**
+   * Determines if an error is permanent (should not trigger fallback)
+   * @param {Error} error - Error to categorize
+   * @returns {boolean} True if error is permanent
+   */
+  isPermanentError(error) {
+    if (error instanceof PermanentTunnelError) return true;
+    if (error instanceof TransientTunnelError) return false;
+
+    const message = error.message ? error.message.toLowerCase() : '';
+    const permanentPatterns = [
+      'ssh: command not found',
+      'permission denied',
+      'authentication failed',
+      'invalid configuration',
+      'command not found',
+      'access denied',
+      'unauthorized',
+      'forbidden',
+      'invalid subdomain',
+      'malformed',
+      'eacces'
+    ];
+
+    return permanentPatterns.some(pattern => message.includes(pattern));
+  }
+
+  /**
+   * Determines if an error is critical (should stop all operations)
+   * @param {Error} error - Error to categorize
+   * @returns {boolean} True if error is critical
+   */
+  isCriticalError(error) {
+    if (error instanceof CriticalTunnelError) return true;
+
+    const message = error.message ? error.message.toLowerCase() : '';
+    const criticalPatterns = [
+      'out of memory',
+      'file descriptor',
+      'resource exhaustion',
+      'security violation',
+      'corrupted',
+      'system error',
+      'emfile',
+      'enomem'
+    ];
+
+    return criticalPatterns.some(pattern => message.includes(pattern));
+  }
+
+  /**
+   * Generates a unique tunnel ID
+   * @protected
+   * @returns {string} Unique tunnel identifier
+   */
+  _generateTunnelId() {
+    return `tunnel_${this.name}_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+  }
+
+  /**
+   * Emits a standardized progress event
+   * @protected
+   * @param {string} status - Status identifier (e.g., 'connecting', 'connected', 'disconnecting')
+   * @param {string} message - Human-readable progress message
+   * @param {string} [tunnelId] - Associated tunnel ID if applicable
+   */
+  _emitProgress(status, message, tunnelId = null) {
+    this.emit('tunnelProgress', {
+      service: this.name,
+      status,
+      message,
+      tunnelId,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Emits a standardized error event
+   * @protected
+   * @param {Error} error - Error that occurred
+   * @param {string} [tunnelId] - Associated tunnel ID if applicable
+   */
+  _emitError(error, tunnelId = null) {
+    this.emit('tunnelError', {
+      service: this.name,
+      error: error.message || String(error),
+      type: error.constructor ? error.constructor.name : 'Error',
+      tunnelId,
+      timestamp: new Date().toISOString(),
+      isTransient: this.isTransientError(error instanceof Error ? error : new Error(String(error))),
+      isPermanent: this.isPermanentError(error instanceof Error ? error : new Error(String(error))),
+      isCritical: this.isCriticalError(error instanceof Error ? error : new Error(String(error)))
+    });
+  }
+
+  /**
+   * Emits a tunnel created event
+   * @protected
+   * @param {Object} tunnelInfo - Information about the created tunnel
+   */
+  _emitTunnelCreated(tunnelInfo) {
+    this.emit('tunnelCreated', {
+      ...tunnelInfo,
+      service: this.name,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Emits a tunnel destroyed event
+   * @protected
+   * @param {string} tunnelId - ID of the destroyed tunnel
+   */
+  _emitTunnelDestroyed(tunnelId) {
+    this.emit('tunnelDestroyed', {
+      service: this.name,
+      tunnelId,
+      timestamp: new Date().toISOString()
+    });
+  }
+}