@openserv-labs/sdk 1.8.2 → 2.0.0

package/dist/tunnel.js

@@ -0,0 +1,803 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenServTunnel = void 0;
+const ws_1 = __importDefault(require("ws"));
+const node_http_1 = __importDefault(require("node:http"));
+const logger_1 = require("./logger");
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_PROXY_URL = process.env.OPENSERV_PROXY_URL || 'https://agents-proxy.openserv.ai';
+const MAX_RECONNECTION_ATTEMPTS = 10;
+const MAX_RESPONSE_SIZE = 100 * 1024 * 1024; // 100MB max response body
+const WS_TERMINATE_TIMEOUT = 3000; // 3 seconds to wait before force-terminating WebSocket
+// Reusable HTTP agent for local forwarding (keep-alive to avoid TCP connection overhead)
+const localAgent = new node_http_1.default.Agent({ keepAlive: true, maxSockets: 64 });
+/**
+ * Valid state transitions. Maps current state to events and their target states.
+ */
+const VALID_TRANSITIONS = {
+    idle: {
+        START: 'starting',
+        STOP: 'stopped'
+    },
+    starting: {
+        SETUP_COMPLETE: 'connecting',
+        SETUP_FAILED: 'failed',
+        STOP: 'stopping'
+    },
+    connecting: {
+        WS_OPEN: 'authenticating',
+        WS_CLOSE: 'reconnect_delay',
+        WS_ERROR: 'reconnect_delay', // Error triggers reconnect with backoff
+        STOP: 'stopping'
+    },
+    authenticating: {
+        AUTH_SUCCESS: 'connected',
+        AUTH_ERROR: 'failed', // Auth errors are fatal, no retry
+        WS_CLOSE: 'reconnect_delay',
+        WS_ERROR: 'reconnect_delay', // Error triggers reconnect with backoff
+        STOP: 'stopping'
+    },
+    connected: {
+        WS_CLOSE: 'reconnect_delay',
+        WS_ERROR: 'reconnect_delay', // Error triggers reconnect with backoff
+        GRACEFUL_RECONNECT: 'awaiting_reconnect_ack',
+        STOP: 'stopping'
+    },
+    awaiting_reconnect_ack: {
+        RECONNECT_ACK: 'reconnect_delay',
+        ACK_TIMEOUT: 'reconnect_delay',
+        WS_CLOSE: 'reconnect_delay',
+        WS_ERROR: 'reconnect_delay', // Error triggers reconnect with backoff
+        STOP: 'stopping'
+    },
+    reconnect_delay: {
+        DELAY_COMPLETE: 'connecting',
+        MAX_RETRIES: 'failed',
+        STOP: 'stopping'
+    },
+    stopping: {
+        CLEANUP_COMPLETE: 'stopped'
+    },
+    failed: {
+        STOP: 'stopped',
+        START: 'starting' // Allow restart after failure
+    },
+    stopped: {
+        START: 'starting' // Allow restart after stop
+    }
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+async function forwardToLocalAgent(localPort, requestData) {
+    return new Promise((resolve, reject) => {
+        const { method, path, headers, body } = requestData;
+        // Remove hop-by-hop headers that shouldn't be forwarded
+        const cleanHeaders = { ...headers };
+        delete cleanHeaders.connection;
+        delete cleanHeaders.upgrade;
+        delete cleanHeaders['proxy-connection'];
+        delete cleanHeaders['transfer-encoding'];
+        delete cleanHeaders.host; // Don't forward original host - can confuse local routing
+        delete cleanHeaders['content-length']; // Will be set based on actual body bytes
+        delete cleanHeaders['keep-alive'];
+        delete cleanHeaders.te;
+        delete cleanHeaders.trailer;
+        // Handle request body - support binary (base64) encoding from proxy
+        // Headers are case-insensitive, so check common variations
+        const encoding = headers['x-openserv-encoding'] ??
+            headers['X-OpenServ-Encoding'] ??
+            headers['X-Openserv-Encoding'];
+        // Handle body: undefined means no body, null/empty string means empty body
+        const bodyBuffer = body === undefined
+            ? undefined
+            : encoding === 'base64'
+                ? Buffer.from(body, 'base64')
+                : Buffer.from(body, 'utf8');
+        // Always set content-length when body field exists (even if empty)
+        // This ensures POST/PUT with empty body get Content-Length: 0
+        if (bodyBuffer !== undefined) {
+            cleanHeaders['content-length'] = String(bodyBuffer.length);
+        }
+        // Remove encoding headers after processing - they're not for the local agent
+        delete cleanHeaders['x-openserv-encoding'];
+        delete cleanHeaders['X-OpenServ-Encoding'];
+        delete cleanHeaders['X-Openserv-Encoding'];
+        const options = {
+            hostname: 'localhost',
+            port: localPort,
+            path: path,
+            method: method,
+            headers: cleanHeaders,
+            agent: localAgent
+        };
+        const req = node_http_1.default.request(options, res => {
+            const chunks = [];
+            let totalSize = 0;
+            let responseTooLarge = false;
+            res.on('data', (chunk) => {
+                if (responseTooLarge)
+                    return;
+                totalSize += chunk.length;
+                if (totalSize > MAX_RESPONSE_SIZE) {
+                    responseTooLarge = true;
+                    req.destroy();
+                    reject(new Error(`Response too large (exceeds ${MAX_RESPONSE_SIZE / 1024 / 1024}MB limit)`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('error', (error) => {
+                reject(new Error(`Response stream error: ${error.message}`));
+            });
+            res.on('end', () => {
+                if (!responseTooLarge) {
+                    const responseBuffer = Buffer.concat(chunks);
+                    const contentType = res.headers['content-type'] || '';
+                    // Check if content is text-based (can be safely converted to string)
+                    const isTextContent = contentType.includes('text/') ||
+                        contentType.includes('application/json') ||
+                        contentType.includes('application/xml') ||
+                        contentType.includes('application/javascript') ||
+                        contentType.includes('+json') ||
+                        contentType.includes('+xml');
+                    // For text content, convert to UTF-8 string; for binary, use base64
+                    const responseBody = isTextContent
+                        ? responseBuffer.toString('utf8')
+                        : responseBuffer.toString('base64');
+                    // Build clean response headers - strip hop-by-hop headers
+                    const responseHeaders = {
+                        ...res.headers
+                    };
+                    // Remove hop-by-hop headers that shouldn't be forwarded back
+                    delete responseHeaders.connection;
+                    delete responseHeaders['keep-alive'];
+                    delete responseHeaders['transfer-encoding'];
+                    delete responseHeaders.te;
+                    delete responseHeaders.trailer;
+                    delete responseHeaders.upgrade;
+                    // Remove original content-length - will be recalculated based on actual body
+                    delete responseHeaders['content-length'];
+                    // Set correct content-length based on the (possibly re-encoded) body
+                    const bodyBytes = Buffer.byteLength(responseBody, 'utf8');
+                    responseHeaders['content-length'] = String(bodyBytes);
+                    // Add encoding header for binary responses
+                    if (!isTextContent) {
+                        responseHeaders['x-openserv-encoding'] = 'base64';
+                    }
+                    resolve({
+                        status: res.statusCode || 500,
+                        headers: responseHeaders,
+                        body: responseBody
+                    });
+                }
+            });
+        });
+        req.on('error', (error) => {
+            reject(new Error(`Local agent connection failed: ${error.message}`));
+        });
+        // Use explicit setTimeout for more reliable timeout handling
+        // Node's options.timeout behavior can be subtle
+        req.setTimeout(120000, () => {
+            req.destroy(new Error('Request to local agent timed out'));
+        });
+        if (bodyBuffer !== undefined) {
+            req.write(bodyBuffer);
+        }
+        req.end();
+    });
+}
+// ============================================================================
+// OpenServ Tunnel
+// ============================================================================
+/**
+ * OpenServ Tunnel
+ *
+ * Connects local agent servers to the OpenServ proxy service.
+ *
+ * @example
+ * ```typescript
+ * const tunnel = new OpenServTunnel({
+ *   apiKey: process.env.OPENSERV_API_KEY
+ * })
+ *
+ * await tunnel.start(7378)
+ * console.log('Tunnel connected')
+ *
+ * // Later...
+ * await tunnel.stop()
+ * ```
+ */
+class OpenServTunnel {
+    // Configuration
+    proxyUrl;
+    apiKey;
+    localPort = 0;
+    // WebSocket connection
+    ws = null;
+    // State machine
+    state = 'idle';
+    context = {
+        reconnectAttempts: 0,
+        disconnectedAt: null,
+        hasConnectedOnce: false,
+        lastError: null
+    };
+    // Timers (managed by state machine)
+    delayTimeoutId = null;
+    ackTimeoutId = null;
+    // Pending promises for async operations
+    pendingStart = null;
+    pendingGracefulReconnect = null;
+    pendingStop = null;
+    // Callbacks
+    onConnected;
+    onRequest;
+    onError;
+    constructor(options = {}) {
+        this.proxyUrl = options.proxyUrl || DEFAULT_PROXY_URL;
+        this.apiKey = options.apiKey || process.env.OPENSERV_API_KEY || '';
+        this.onConnected = options.onConnected;
+        this.onRequest = options.onRequest;
+        this.onError = options.onError;
+    }
+    // ============================================================================
+    // State Machine Core
+    // ============================================================================
+    /**
+     * Get the current state of the tunnel.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Attempt to transition to a new state based on an event.
+     * Returns true if the transition was valid and executed, false otherwise.
+     */
+    transition(event) {
+        const validTransitions = VALID_TRANSITIONS[this.state];
+        const nextState = validTransitions[event];
+        if (!nextState) {
+            // Invalid transition - log and ignore
+            logger_1.logger.warn(`Invalid transition: ${this.state} + ${event} (no valid target state)`);
+            return false;
+        }
+        const previousState = this.state;
+        logger_1.logger.debug(`State transition: ${previousState} -> ${nextState} (${event})`);
+        // Exit current state
+        this.exitState(previousState);
+        // Update state
+        this.state = nextState;
+        // Enter new state
+        this.enterState(nextState, event, previousState);
+        return true;
+    }
+    /**
+     * Actions to perform when exiting a state.
+     */
+    exitState(state) {
+        switch (state) {
+            case 'reconnect_delay':
+                // Clear delay timer when leaving reconnect_delay state
+                if (this.delayTimeoutId) {
+                    clearTimeout(this.delayTimeoutId);
+                    this.delayTimeoutId = null;
+                }
+                break;
+            case 'awaiting_reconnect_ack':
+                // Clear ack timeout when leaving awaiting_reconnect_ack state
+                if (this.ackTimeoutId) {
+                    clearTimeout(this.ackTimeoutId);
+                    this.ackTimeoutId = null;
+                }
+                break;
+        }
+    }
+    /**
+     * Actions to perform when entering a state.
+     */
+    enterState(state, _event, previousState) {
+        switch (state) {
+            case 'starting':
+                this.doStarting();
+                break;
+            case 'connecting':
+                this.doConnect();
+                break;
+            case 'authenticating':
+                this.doAuthenticate();
+                break;
+            case 'connected':
+                void this.doConnected();
+                break;
+            case 'awaiting_reconnect_ack':
+                this.doAwaitReconnectAck();
+                break;
+            case 'reconnect_delay':
+                this.doReconnectDelay(previousState);
+                break;
+            case 'stopping':
+                this.doStopping();
+                break;
+            case 'failed':
+                this.doFailed();
+                break;
+            case 'stopped':
+                this.doStopped();
+                break;
+        }
+    }
+    // ============================================================================
+    // State Entry Actions
+    // ============================================================================
+    /**
+     * Entry action for 'starting' state: validate and initialize.
+     * Resets context and validates API key before proceeding to connect.
+     */
+    doStarting() {
+        // Reset context for fresh start
+        this.context = {
+            reconnectAttempts: 0,
+            disconnectedAt: null,
+            hasConnectedOnce: false,
+            lastError: null
+        };
+        // Validate API key
+        if (!this.apiKey) {
+            logger_1.logger.error('API key is required. Set OPENSERV_API_KEY environment variable or pass apiKey option.');
+            this.context.lastError = new Error('API key is required');
+            this.transition('SETUP_FAILED');
+            return;
+        }
+        // Proceed to connecting
+        this.transition('SETUP_COMPLETE');
+    }
+    /**
+     * Entry action for 'connecting' state: create WebSocket connection.
+     */
+    doConnect() {
+        this.setupWebSocket();
+    }
+    /**
+     * Entry action for 'authenticating' state: send auth message.
+     */
+    doAuthenticate() {
+        const authMessage = {
+            type: 'auth',
+            apiKey: this.apiKey,
+            localPort: this.localPort
+        };
+        this.ws?.send(JSON.stringify(authMessage));
+        logger_1.logger.info('Authenticating...');
+    }
+    /**
+     * Entry action for 'connected' state: resolve promises, call callbacks.
+     */
+    async doConnected() {
+        // Reset reconnect attempts on successful connection
+        this.context.reconnectAttempts = 0;
+        const isReconnect = this.context.hasConnectedOnce;
+        if (isReconnect) {
+            if (this.context.disconnectedAt) {
+                const duration = ((Date.now() - this.context.disconnectedAt) / 1000).toFixed(2);
+                logger_1.logger.info(`Tunnel reconnected (${duration}s)`);
+                this.context.disconnectedAt = null;
+            }
+            else {
+                logger_1.logger.info('Tunnel reconnected');
+            }
+        }
+        else {
+            logger_1.logger.info('Tunnel connected');
+            this.context.hasConnectedOnce = true;
+        }
+        // Resolve pending promises
+        this.pendingStart?.resolve();
+        this.pendingStart = null;
+        this.pendingGracefulReconnect?.resolve();
+        this.pendingGracefulReconnect = null;
+        // Call user callback
+        await this.onConnected?.(isReconnect);
+    }
+    /**
+     * Entry action for 'awaiting_reconnect_ack' state: send will-reconnect and start timeout.
+     */
+    doAwaitReconnectAck() {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN) {
+            // WebSocket not available, go directly to reconnect_delay
+            this.transition('ACK_TIMEOUT');
+            return;
+        }
+        logger_1.logger.info('Initiating graceful reconnection...');
+        this.ws.send(JSON.stringify({ type: 'will-reconnect' }));
+        logger_1.logger.info('Sent will-reconnect to server...');
+        // Start timeout for ack
+        this.ackTimeoutId = setTimeout(() => {
+            logger_1.logger.info('Will-reconnect ack timeout, proceeding with reconnection');
+            this.transition('ACK_TIMEOUT');
+        }, 2000);
+    }
+    /**
+     * Entry action for 'reconnect_delay' state: calculate backoff and start timer.
+     */
+    doReconnectDelay(previousState) {
+        // Track when we disconnected
+        if (!this.context.disconnectedAt) {
+            this.context.disconnectedAt = Date.now();
+        }
+        // Increment reconnect attempts
+        this.context.reconnectAttempts++;
+        // Check if max retries reached
+        if (this.context.reconnectAttempts > MAX_RECONNECTION_ATTEMPTS) {
+            this.context.lastError = new Error('Max reconnection attempts reached');
+            logger_1.logger.error(this.context.lastError.message);
+            // Transition to failed via proper state machine
+            this.transition('MAX_RETRIES');
+            return;
+        }
+        // Calculate backoff delay: first attempt is instant, then exponential
+        const delay = this.context.reconnectAttempts === 1
+            ? 0
+            : Math.min(1000 * 2 ** (this.context.reconnectAttempts - 2), 30000);
+        if (delay === 0) {
+            logger_1.logger.info(`Reconnection attempt ${this.context.reconnectAttempts}/${MAX_RECONNECTION_ATTEMPTS} (instant)...`);
+        }
+        else {
+            logger_1.logger.info(`Reconnection attempt ${this.context.reconnectAttempts}/${MAX_RECONNECTION_ATTEMPTS} in ${delay / 1000}s...`);
+        }
+        // Close WebSocket if still open (graceful reconnect case)
+        if (previousState === 'awaiting_reconnect_ack' && this.ws) {
+            this.ws.removeAllListeners();
+            this.ws.close();
+            this.ws = null;
+        }
+        // Start delay timer
+        this.delayTimeoutId = setTimeout(() => {
+            this.transition('DELAY_COMPLETE');
+        }, delay);
+    }
+    /**
+     * Entry action for 'stopping' state: clean up resources.
+     * Handles async WebSocket cleanup and transitions to 'stopped' when done.
+     */
+    doStopping() {
+        // Clear any pending timers
+        if (this.delayTimeoutId) {
+            clearTimeout(this.delayTimeoutId);
+            this.delayTimeoutId = null;
+        }
+        if (this.ackTimeoutId) {
+            clearTimeout(this.ackTimeoutId);
+            this.ackTimeoutId = null;
+        }
+        // If no WebSocket, cleanup is instant
+        if (!this.ws) {
+            this.transition('CLEANUP_COMPLETE');
+            return;
+        }
+        // Async WebSocket cleanup
+        this.ws.removeAllListeners();
+        const ws = this.ws;
+        this.ws = null;
+        ws.close();
+        const onCleanupComplete = () => {
+            clearTimeout(terminateTimeout);
+            this.transition('CLEANUP_COMPLETE');
+        };
+        const terminateTimeout = setTimeout(() => {
+            if (ws.readyState !== ws_1.default.CLOSED) {
+                logger_1.logger.warn('WebSocket close timed out, forcing termination');
+                ws.terminate();
+            }
+            onCleanupComplete();
+        }, WS_TERMINATE_TIMEOUT);
+        ws.once('close', onCleanupComplete);
+        ws.once('error', onCleanupComplete);
+    }
+    /**
+     * Entry action for 'failed' state: reject promises, call error callback.
+     */
+    doFailed() {
+        const error = this.context.lastError || new Error('Tunnel failed');
+        // Close WebSocket if still open (e.g., auth failure case)
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            this.ws.close();
+            this.ws = null;
+        }
+        // Reject pending promises
+        this.pendingStart?.reject(error);
+        this.pendingStart = null;
+        this.pendingGracefulReconnect?.reject(error);
+        this.pendingGracefulReconnect = null;
+        // Call error callback
+        this.onError?.(error);
+    }
+    /**
+     * Entry action for 'stopped' state: resolve/reject pending promises.
+     * Cleanup has already been done in 'stopping' state.
+     */
+    doStopped() {
+        // Resolve graceful reconnect (intentional stop)
+        this.pendingGracefulReconnect?.resolve();
+        this.pendingGracefulReconnect = null;
+        // Reject pending start with clear message
+        if (this.pendingStart) {
+            this.pendingStart.reject(new Error('Tunnel stopped'));
+            this.pendingStart = null;
+        }
+        // Resolve pendingStop
+        this.pendingStop?.resolve();
+        this.pendingStop = null;
+        logger_1.logger.info('Tunnel stopped');
+    }
+    // ============================================================================
+    // Public API
+    // ============================================================================
+    /**
+     * Start the tunnel and connect to the proxy.
+     * @param port - The local port to expose
+     */
+    async start(port) {
+        this.localPort = port;
+        return new Promise((resolve, reject) => {
+            // Set pendingStart BEFORE transition so doFailed() can reject it
+            // (transition is synchronous and may reach 'failed' state immediately)
+            this.pendingStart = { resolve, reject };
+            if (!this.transition('START')) {
+                this.pendingStart = null;
+                reject(new Error(`Cannot start tunnel from state: ${this.state}`));
+            }
+        });
+    }
+    /**
+     * Stop the tunnel and clean up resources.
+     * Returns a promise that resolves when cleanup is complete.
+     */
+    async stop() {
+        // If already stopped, return immediately
+        if (this.state === 'stopped') {
+            return;
+        }
+        // If already stopping, wait for existing stop to complete
+        if (this.state === 'stopping') {
+            return new Promise(resolve => {
+                // Chain onto existing pendingStop
+                const existing = this.pendingStop;
+                if (existing) {
+                    const originalResolve = existing.resolve;
+                    existing.resolve = () => {
+                        originalResolve();
+                        resolve();
+                    };
+                }
+                else {
+                    // Shouldn't happen, but handle gracefully
+                    resolve();
+                }
+            });
+        }
+        return new Promise(resolve => {
+            // Set pendingStop BEFORE transition so doStopped() can resolve it
+            // (transition may reach 'stopped' synchronously from idle or when no WebSocket)
+            this.pendingStop = { resolve };
+            if (!this.transition('STOP')) {
+                this.pendingStop = null;
+                resolve();
+            }
+        });
+    }
+    /**
+     * Check if the tunnel is currently connected and authenticated.
+     * Returns true only after the tunnel has successfully registered with the proxy.
+     */
+    isConnected() {
+        return this.state === 'connected' && this.ws?.readyState === ws_1.default.OPEN;
+    }
+    // ============================================================================
+    // WebSocket Setup and Event Handlers
+    // ============================================================================
+    setupWebSocket() {
+        // Clean up old WebSocket if it exists (defensive - shouldn't happen with proper state machine)
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            this.ws.close();
+            this.ws = null;
+        }
+        const wsUrl = this.proxyUrl.replace(/^http/, 'ws') + '/ws';
+        const wsOptions = {
+            headers: {
+                'User-Agent': 'OpenServ-Tunnel-Client/2.0.0'
+            }
+        };
+        this.ws = new ws_1.default(wsUrl, wsOptions);
+        this.ws.on('open', () => this.handleWsOpen());
+        this.ws.on('ping', (data) => this.ws?.pong(data));
+        this.ws.on('message', (data) => this.handleWsMessage(data));
+        this.ws.on('close', (code, reason) => this.handleWsClose(code, reason));
+        this.ws.on('error', (error) => this.handleWsError(error));
+    }
+    /**
+     * Handle WebSocket 'open' event - dispatch WS_OPEN event.
+     */
+    handleWsOpen() {
+        this.transition('WS_OPEN');
+    }
+    /**
+     * Handle WebSocket 'message' event - dispatch appropriate events based on message type.
+     */
+    async handleWsMessage(data) {
+        try {
+            const message = JSON.parse(data.toString());
+            switch (message.type) {
+                case 'error':
+                    this.handleProtocolError(message);
+                    break;
+                case 'registered':
+                    this.transition('AUTH_SUCCESS');
+                    break;
+                case 'will-reconnect-ack':
+                    this.handleReconnectAck(message.data);
+                    break;
+                case 'request':
+                    await this.handleRequest(message.data);
+                    break;
+            }
+        }
+        catch (error) {
+            logger_1.logger.error(`Error processing message: ${error.message}`);
+        }
+    }
+    /**
+     * Handle protocol-level error message from server.
+     */
+    handleProtocolError(message) {
+        const errorMessage = message.message || 'Unknown tunnel error';
+        this.logTunnelError(message);
+        this.context.lastError = new Error(errorMessage);
+        this.transition('AUTH_ERROR');
+    }
+    /**
+     * Handle will-reconnect-ack message from server.
+     */
+    handleReconnectAck(data) {
+        logger_1.logger.info(`Server acknowledged will-reconnect, buffer timeout: ${data.bufferTimeout}ms`);
+        this.transition('RECONNECT_ACK');
+    }
+    /**
+     * Handle incoming request through the tunnel.
+     */
+    async handleRequest(requestData) {
+        this.onRequest?.(requestData.method, requestData.path);
+        await this.forwardRequest(requestData);
+    }
+    /**
+     * Handle WebSocket 'close' event - dispatch WS_CLOSE event.
+     */
+    handleWsClose(code, reason) {
+        logger_1.logger.info(`Disconnected: ${code} ${reason.toString()}`);
+        this.ws = null;
+        this.transition('WS_CLOSE');
+    }
+    /**
+     * Handle WebSocket 'error' event - dispatch WS_ERROR event (informational).
+     */
+    handleWsError(error) {
+        logger_1.logger.error(`Connection error: ${error.message}`);
+        this.context.lastError = error;
+        if (!this.context.disconnectedAt) {
+            this.context.disconnectedAt = Date.now();
+        }
+        this.logConnectionErrorHint(error);
+        this.onError?.(error);
+        // Dispatch event (close will follow, which handles actual state transition)
+        this.transition('WS_ERROR');
+    }
+    logTunnelError(message) {
+        if (message.error === 'AUTH_TIMEOUT' || message.error === 'AUTH_REQUIRED') {
+            logger_1.logger.error(`Authentication error: ${message.message}`);
+        }
+        else if (message.error === 'AUTHENTICATION_FAILED' || message.error === 'AUTH_FAILED') {
+            logger_1.logger.error(`Authentication failed: ${message.message}`);
+            logger_1.logger.info('Check your API key');
+        }
+        else {
+            logger_1.logger.error(`Tunnel error: ${message.message}`);
+        }
+    }
+    logConnectionErrorHint(error) {
+        if (error.message.includes('protocol error')) {
+            logger_1.logger.info('This may be a temporary issue. Retrying...');
+        }
+        else if (error.message.includes('upstream connect error')) {
+            logger_1.logger.info('The proxy server may be starting up. Retrying...');
+        }
+        else if (error.message.includes('400')) {
+            logger_1.logger.info('Server rejected connection. Check your proxy URL.');
+        }
+        else if (error.code === 'ENOTFOUND') {
+            logger_1.logger.info('DNS resolution failed. Check your proxy URL.');
+        }
+        else if (error.code === 'ECONNREFUSED') {
+            logger_1.logger.info('Connection refused. Is the proxy server running?');
+        }
+    }
+    // ============================================================================
+    // Request Forwarding
+    // ============================================================================
+    async forwardRequest(requestData) {
+        const sendResponse = (responseData) => {
+            if (this.ws?.readyState === ws_1.default.OPEN) {
+                this.ws.send(JSON.stringify({
+                    type: 'response',
+                    data: responseData
+                }));
+            }
+            else {
+                logger_1.logger.warn(`Cannot send response for request ${responseData.id}: WebSocket not open`);
+            }
+        };
+        try {
+            const response = await forwardToLocalAgent(this.localPort, requestData);
+            sendResponse({
+                id: requestData.id,
+                status: response.status,
+                headers: response.headers,
+                body: response.body
+            });
+        }
+        catch (error) {
+            logger_1.logger.error(`Error forwarding request: ${error.message}`);
+            sendResponse({
+                id: requestData.id,
+                status: 502,
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    error: 'Bad Gateway',
+                    message: error.message
+                })
+            });
+        }
+    }
+    /**
+     * Initiate a graceful reconnection to the proxy server.
+     * This notifies the server before disconnecting, allowing it to buffer requests.
+     * Returns a promise that resolves when the reconnection is complete.
+     */
+    async gracefulReconnect() {
+        // Only valid from connected state
+        if (this.state !== 'connected') {
+            logger_1.logger.warn(`Cannot graceful reconnect from state: ${this.state}`);
+            return Promise.resolve();
+        }
+        // If there's already a graceful reconnect in progress, wait for it
+        if (this.pendingGracefulReconnect) {
+            return new Promise((resolve, reject) => {
+                const existing = this.pendingGracefulReconnect;
+                const originalResolve = existing.resolve;
+                const originalReject = existing.reject;
+                existing.resolve = () => {
+                    originalResolve();
+                    resolve();
+                };
+                existing.reject = (error) => {
+                    originalReject(error);
+                    reject(error);
+                };
+            });
+        }
+        // Reset reconnect attempts for fresh graceful reconnect
+        this.context.reconnectAttempts = 0;
+        // Create promise that will be resolved when reconnected
+        return new Promise((resolve, reject) => {
+            this.pendingGracefulReconnect = { resolve, reject };
+            this.transition('GRACEFUL_RECONNECT');
+        });
+    }
+}
+exports.OpenServTunnel = OpenServTunnel;