teleportation-cli 1.0.0 → 1.0.1

package/lib/remote/liveport-client.js

@@ -0,0 +1,417 @@
+/**
+ * LivePort Client for remote development environment access
+ *
+ * Handles:
+ * - Creating tunnels to remote machines
+ * - Managing bridge keys for authentication
+ * - Programmatic tunnel control via Agent SDK
+ * - Waiting for connections
+ */
+
+export class LivePortClient {
+  constructor(config = {}) {
+    this.apiKey = config.apiKey || process.env.LIVEPORT_API_KEY;
+    this.apiUrl = config.apiUrl || process.env.LIVEPORT_API_URL || 'https://api.liveport.dev/v1';
+    this.maxRetries = config.maxRetries || 3;
+
+    // Support environment variable override for retry delays
+    const defaultRetries = process.env.LIVEPORT_RETRY_DELAYS
+      ? process.env.LIVEPORT_RETRY_DELAYS.split(',').map(Number)
+      : [1000, 2000, 4000]; // Exponential backoff
+    this.retryDelays = config.retryDelays || defaultRetries;
+
+    this.timeout = config.timeout || 30000; // 30 second default timeout
+    this.debug = config.debug ?? (process.env.LIVEPORT_DEBUG === 'true');
+
+    if (!this.apiKey) {
+      throw new Error('LIVEPORT_API_KEY is required');
+    }
+  }
+
+  /**
+   * Create common headers for all requests
+   */
+  _headers() {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+    };
+  }
+
+  /**
+   * Fetch with timeout support
+   * @private
+   * @param {string} url - URL to fetch
+   * @param {Object} options - Fetch options
+   * @returns {Promise<Response>} Fetch response
+   * @throws {Error} If request times out or fails
+   */
+  async _fetchWithTimeout(url, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timed out after ${this.timeout}ms: ${url}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Log debug messages if debug mode is enabled
+   * @private
+   * @param {string} message - Message to log
+   */
+  _log(message) {
+    if (this.debug) {
+      console.error(`[LivePortClient] ${message}`);
+    }
+  }
+
+  /**
+   * Validate name format (alphanumeric, dashes, underscores)
+   */
+  _validateName(name) {
+    if (!name || name.trim() === '') {
+      throw new Error('name is required');
+    }
+    const trimmed = name.trim();
+    if (!/^[a-zA-Z0-9_-]+$/.test(trimmed)) {
+      throw new Error('Invalid name format: must contain only alphanumeric characters, dashes, and underscores');
+    }
+    return trimmed;
+  }
+
+  /**
+   * Validate keyId is not empty
+   */
+  _validateKeyId(keyId) {
+    if (!keyId || keyId.trim() === '') {
+      throw new Error('keyId is required');
+    }
+    return keyId;
+  }
+
+  /**
+   * Validate expiresAt is in the future
+   */
+  _validateExpiresAt(expiresAt) {
+    if (expiresAt) {
+      const expiryDate = new Date(expiresAt);
+      if (expiryDate <= new Date()) {
+        throw new Error('expiresAt must be in the future');
+      }
+    }
+  }
+
+  /**
+   * Execute fetch with retry logic and exponential backoff
+   */
+  async _fetchWithRetry(url, options, retryCount = 0) {
+    try {
+      const response = await this._fetchWithTimeout(url, options);
+
+      // Don't retry on client errors (4xx)
+      if (!response.ok && response.status >= 400 && response.status < 500) {
+        if (response.status === 401) {
+          throw new Error('Authentication failed: Invalid API key');
+        }
+        if (response.status === 404) {
+          throw new Error('Tunnel not found');
+        }
+        throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+      }
+
+      // Retry on server errors (5xx)
+      if (!response.ok && response.status >= 500) {
+        if (retryCount < this.maxRetries - 1) {
+          const delay = this.retryDelays[retryCount] || 4000;
+          this._log(`Retry attempt ${retryCount + 1} after ${delay}ms due to ${response.status}`);
+          await this._delay(delay);
+          return this._fetchWithRetry(url, options, retryCount + 1);
+        }
+        throw new Error(`Server error: ${response.status} ${response.statusText}`);
+      }
+
+      return response;
+    } catch (error) {
+      // Don't retry client errors (4xx) - they won't succeed on retry
+      if (error.message.includes('Authentication failed') ||
+          error.message.includes('Tunnel not found') ||
+          error.message.includes('Request failed')) {
+        throw error;
+      }
+
+      // Network errors - retry with exponential backoff
+      if (retryCount < this.maxRetries - 1) {
+        const delay = this.retryDelays[retryCount] || 4000;
+        this._log(`Retry attempt ${retryCount + 1} after ${delay}ms due to: ${error.message}`);
+        await this._delay(delay);
+        return this._fetchWithRetry(url, options, retryCount + 1);
+      }
+
+      // Exhausted retries - wrap error
+      throw new Error(`Failed after ${this.maxRetries} retries: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delay helper for exponential backoff
+   */
+  _delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Generate a bridge key for a remote session
+   * @param {Object} options - { name, expiresAt, rateLimit, metadata }
+   * @returns {Object} - { keyId, key, expiresAt }
+   */
+  async createBridgeKey(options = {}) {
+    if (typeof this.apiKey === 'string' && this.apiKey.startsWith('lpk_')) {
+      const expiresAt = options.expiresAt || this._defaultExpiration();
+      this._validateExpiresAt(expiresAt);
+
+      return {
+        keyId: null,
+        key: this.apiKey,
+        expiresAt,
+        metadata: options.metadata || {},
+        rateLimit: options.rateLimit,
+      };
+    }
+
+    // Validate inputs
+    const validName = this._validateName(options.name);
+    const expiresAt = options.expiresAt || this._defaultExpiration();
+    this._validateExpiresAt(expiresAt);
+
+    const response = await this._fetchWithRetry(`${this.apiUrl}/bridge-keys`, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify({
+        name: validName,
+        expiresAt,
+        rateLimit: options.rateLimit,
+        metadata: options.metadata || {},
+      }),
+    });
+
+    return response.json();
+  }
+
+  /**
+   * Default expiration: 24 hours from now
+   */
+  _defaultExpiration() {
+    const tomorrow = new Date();
+    tomorrow.setHours(tomorrow.getHours() + 24);
+    return tomorrow.toISOString();
+  }
+
+  /**
+   * Get tunnel configuration for remote machine
+   * This generates the command that the remote machine should run
+   * @param {string} bridgeKey - Bridge key for authentication
+   * @param {Object} options - { port, subdomain, protocol }
+   */
+  getTunnelCommand(bridgeKey, options = {}) {
+    const port = options.port || 3000;
+    const subdomain = options.subdomain || null;
+    const protocol = options.protocol || 'http';
+
+    let cmd = `bunx @liveport/cli tunnel --port ${port} --key ${bridgeKey}`;
+
+    if (subdomain) {
+      cmd += ` --subdomain ${subdomain}`;
+    }
+
+    if (protocol === 'https') {
+      cmd += ` --https`;
+    }
+
+    return cmd;
+  }
+
+  /**
+   * Get tunnel URL for a session
+   * @param {string} sessionId - Remote session ID
+   * @param {string} subdomain - Custom subdomain (optional)
+   */
+  getTunnelUrl(sessionId, subdomain = null) {
+    if (subdomain) {
+      return `https://${subdomain}.liveport.dev`;
+    }
+
+    // Generate predictable subdomain from session ID
+    const cleanSessionId = sessionId.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+    return `https://${cleanSessionId}.liveport.dev`;
+  }
+
+  /**
+   * Agent SDK configuration for remote machine
+   * This is used by the remote daemon to programmatically control tunnels
+   * @param {string} bridgeKey - Bridge key for authentication
+   * @param {Object} options - Optional configuration overrides
+   * @param {boolean} [options.verbose] - Enable verbose logging on remote machine
+   */
+  getAgentConfig(bridgeKey, options = {}) {
+    return {
+      key: bridgeKey,
+      autoReconnect: true,
+      timeout: options.timeout || 30000,
+      reconnectInterval: options.reconnectInterval || 5000,
+      maxReconnectAttempts: options.maxReconnectAttempts || 10,
+      verbose: options.verbose ?? false,
+    };
+  }
+
+  /**
+   * Generate TypeScript code for remote agent to use LivePort SDK
+   * @param {string} bridgeKey - Bridge key
+   * @param {number} port - Local port to expose
+   * @param {Object} [options] - Optional configuration
+   * @param {boolean} [options.verbose] - Enable verbose logging on remote machine
+   */
+  generateAgentCode(bridgeKey, port = 3000, options = {}) {
+    const config = this.getAgentConfig(bridgeKey, options);
+    const verbose = config.verbose;
+
+    // Helper for conditional logging in generated code
+    const log = (msg) => verbose ? `console.log(${msg});` : '// Logging disabled';
+    const errorLog = (msg) => `console.error(${msg});`; // Always log errors
+
+    return `
+import { LivePortAgent } from '@liveport/cli';
+
+const VERBOSE = ${verbose};
+const log = (msg) => VERBOSE && console.log(msg);
+
+// Initialize LivePort agent with auto-reconnect
+const agent = new LivePortAgent({
+  key: "${bridgeKey}",
+  autoReconnect: ${config.autoReconnect},
+  timeout: ${config.timeout},
+  reconnectInterval: ${config.reconnectInterval},
+  maxReconnectAttempts: ${config.maxReconnectAttempts}
+});
+
+// Reconnection event handlers
+agent.on('reconnecting', (attempt) => {
+  log(\`LivePort reconnecting (attempt \${attempt}/\${${config.maxReconnectAttempts}})...\`);
+});
+
+agent.on('reconnected', () => {
+  log('LivePort reconnected successfully');
+});
+
+agent.on('disconnected', (reason) => {
+  log(\`LivePort disconnected: \${reason}\`);
+});
+
+agent.on('error', (error) => {
+  console.error('LivePort error:', error.message);
+});
+
+// Main tunnel setup
+async function setupTunnel() {
+  try {
+    // Wait for tunnel to be established
+    const tunnel = await agent.waitForTunnel();
+    log(\`Tunnel ready: \${tunnel.url}\`);
+
+    // Expose local port ${port}
+    await agent.createTunnel({
+      port: ${port},
+      protocol: 'http'
+    });
+
+    log('Successfully exposed port ${port} via LivePort tunnel');
+    return tunnel;
+  } catch (error) {
+    console.error('Failed to setup LivePort tunnel:', error.message);
+    process.exit(1);
+  }
+}
+
+// Setup tunnel and handle lifecycle
+setupTunnel().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  log('Shutting down LivePort tunnel...');
+  await agent.close();
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  log('Received SIGTERM, shutting down...');
+  await agent.close();
+  process.exit(0);
+});
+`.trim();
+  }
+
+  /**
+   * Revoke a bridge key
+   * @param {string} keyId - Key ID to revoke
+   */
+  async revokeBridgeKey(keyId) {
+    const validKeyId = this._validateKeyId(keyId);
+
+    try {
+      await this._fetchWithRetry(`${this.apiUrl}/bridge-keys/${validKeyId}`, {
+        method: 'DELETE',
+        headers: this._headers(),
+      });
+
+      return true;
+    } catch (error) {
+      // Handle 404 gracefully - key already deleted
+      if (error.message.includes('Tunnel not found')) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * List active tunnels for a bridge key
+   * @param {string} bridgeKey - Bridge key
+   */
+  async listTunnels(bridgeKey) {
+    const params = new URLSearchParams({ bridgeKey });
+
+    const response = await this._fetchWithRetry(`${this.apiUrl}/tunnels?${params}`, {
+      method: 'GET',
+      headers: this._headers(),
+    });
+
+    return response.json();
+  }
+
+  /**
+   * Get tunnel status
+   * @param {string} tunnelId - Tunnel ID
+   */
+  async getTunnelStatus(tunnelId) {
+    const response = await this._fetchWithRetry(`${this.apiUrl}/tunnels/${tunnelId}`, {
+      method: 'GET',
+      headers: this._headers(),
+    });
+
+    return response.json();
+  }
+}