@daniel.stefan/metalink 1.3.1

package/packages/core/dist/http-client.js

@@ -0,0 +1,704 @@
+/**
+ * HTTP Client for MCP Streamable HTTP Protocol
+ *
+ * Implements MCP 2025-06-18 Streamable HTTP transport for communicating with
+ * remote HTTP-based MCP servers (e.g., Windmill, custom HTTP endpoints).
+ *
+ * Features:
+ * - Session management with Mcp-Session-Id header
+ * - SSE (Server-Sent Events) streaming support
+ * - HTTP-stream response batching
+ * - Authentication (Bearer, API-Key, OAuth2)
+ * - Automatic session resumption via Last-Event-ID
+ * - Request/response correlation with JSON-RPC IDs
+ * - Request concurrency limits (max 10 concurrent requests)
+ */
+import { EventEmitter } from 'events';
+import { Agent, fetch as undiciFetch } from 'undici';
+/**
+ * HTTP status codes that indicate retryable errors
+ */
+const RETRYABLE_STATUS_CODES = new Set([502, 503, 504]);
+/**
+ * HTTP status codes that should never be retried
+ * Note: 404 is handled specially for session-related errors (auto-reinitialize)
+ */
+const NON_RETRYABLE_STATUS_CODES = new Set([400, 401, 403, 404]);
+/**
+ * Patterns in response body that indicate session-related 404 errors
+ * Per MCP spec, client MUST reinitialize when receiving 404 for invalid session
+ */
+const SESSION_ERROR_PATTERNS = [
+    'session',
+    'Session',
+    'SESSION',
+    'not found',
+    'Not Found',
+    'invalid',
+    'Invalid',
+    'expired',
+    'Expired',
+];
+/**
+ * Network error patterns that are retryable
+ */
+const RETRYABLE_ERROR_PATTERNS = [
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ERR_HTTP2_STREAM_RESET',
+];
+/**
+ * HTTP Client for remote MCP servers
+ * Handles Streamable HTTP protocol with session management and request concurrency limits
+ */
+export class HttpClient extends EventEmitter {
+    constructor(config, circuitBreaker) {
+        super();
+        this.session = null;
+        this.pendingRequests = new Map();
+        this.requestId = 1;
+        this.sseEventBuffer = '';
+        this.isConnected = false;
+        this.isConnecting = false;
+        // Concurrency control
+        this.requestQueue = [];
+        this.activeRequests = 0;
+        this.MAX_CONCURRENT_REQUESTS = 10;
+        // Connection pooling
+        this.agent = null;
+        this.poolMetrics = {
+            activeSockets: 0,
+            freeSockets: 0,
+            pendingRequests: 0,
+            totalConnections: 0,
+        };
+        // Retry configuration
+        this.retryConfig = {
+            maxRetries: 3,
+            initialDelayMs: 100,
+            maxDelayMs: 30000,
+            jitterMs: 1000,
+        };
+        // P1: Stream management for SSE/HTTP-stream
+        this.activeStreams = new Map();
+        this.streamTimeouts = new Map();
+        this.config = config;
+        this.circuitBreaker = circuitBreaker;
+        this.initializeSession();
+        this.initializeAgent();
+    }
+    /**
+     * Initialize or restore session
+     */
+    initializeSession() {
+        // Check if we need to restore from previous session
+        const sessionId = this.session?.id || this.generateSessionId();
+        this.session = {
+            id: sessionId,
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+        };
+        this.emit('session:created', { sessionId });
+    }
+    /**
+     * Generate unique session ID (UUID v4)
+     */
+    generateSessionId() {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+    /**
+     * Initialize undici Agent with connection pooling
+     */
+    initializeAgent() {
+        const poolConfig = this.config.connectionPool || {};
+        const agentOptions = {
+            keepAliveTimeout: poolConfig.keepAliveMsecs || 30000,
+            keepAliveMaxTimeout: poolConfig.keepAliveMsecs || 30000,
+            keepAliveTimeoutThreshold: 1000,
+            connections: poolConfig.maxSockets || 256,
+            pipelining: 0, // Disable pipelining for MCP (request/response pairs)
+            connect: {
+                timeout: poolConfig.timeout || 60000,
+                keepAlive: poolConfig.keepAlive !== false,
+            },
+        };
+        this.agent = new Agent(agentOptions);
+        this.emit('agent:initialized', {
+            config: poolConfig,
+            serverName: this.config.name
+        });
+    }
+    /**
+     * Set retry configuration
+     */
+    setRetryConfig(config) {
+        this.retryConfig = { ...this.retryConfig, ...config };
+    }
+    /**
+     * Check if an error or response is retryable
+     */
+    isRetryable(error) {
+        // Handle Response objects (failed fetch)
+        if (error instanceof Response) {
+            if (NON_RETRYABLE_STATUS_CODES.has(error.status)) {
+                return false;
+            }
+            return RETRYABLE_STATUS_CODES.has(error.status);
+        }
+        // Handle Error objects
+        if (error instanceof Error) {
+            const message = error.message;
+            const httpError = error;
+            // Check if status code is set (from HTTP response)
+            if (httpError.statusCode) {
+                if (NON_RETRYABLE_STATUS_CODES.has(httpError.statusCode)) {
+                    return false;
+                }
+                return RETRYABLE_STATUS_CODES.has(httpError.statusCode);
+            }
+            // Check for retryable network error patterns
+            return RETRYABLE_ERROR_PATTERNS.some(pattern => message.includes(pattern));
+        }
+        return false;
+    }
+    /**
+     * Calculate exponential backoff delay with jitter
+     */
+    calculateBackoffDelay(attempt) {
+        const baseDelay = this.retryConfig.initialDelayMs * Math.pow(2, attempt);
+        const jitter = Math.random() * this.retryConfig.jitterMs;
+        const delayWithJitter = baseDelay + jitter;
+        return Math.min(delayWithJitter, this.retryConfig.maxDelayMs);
+    }
+    /**
+     * Sleep for specified duration
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Execute function with concurrency limit
+     * Queues requests when at max concurrency, releases from queue on completion
+     *
+     * @param fn - Async function to execute
+     * @returns Promise resolving to function result
+     */
+    async executeWithConcurrencyLimit(fn) {
+        // If under limit, execute immediately
+        if (this.activeRequests < this.MAX_CONCURRENT_REQUESTS) {
+            this.activeRequests++;
+            try {
+                return await fn();
+            }
+            finally {
+                this.activeRequests--;
+                this.processQueue();
+            }
+        }
+        // At limit, queue the request
+        return new Promise((resolve, reject) => {
+            const queuedFn = async () => {
+                this.activeRequests++;
+                try {
+                    const result = await fn();
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+                finally {
+                    this.activeRequests--;
+                    this.processQueue();
+                }
+            };
+            this.requestQueue.push(queuedFn);
+        });
+    }
+    /**
+     * Process queued requests, executing them in FIFO order
+     */
+    processQueue() {
+        // Only process if we have capacity and pending requests
+        if (this.activeRequests >= this.MAX_CONCURRENT_REQUESTS || this.requestQueue.length === 0) {
+            return;
+        }
+        const nextFn = this.requestQueue.shift();
+        if (nextFn) {
+            // Execute without awaiting to allow further queue processing
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            nextFn().catch((error) => {
+                this.emit('queue:error', { error, queueLength: this.requestQueue.length });
+            });
+        }
+    }
+    /**
+     * Build HTTP headers with auth and session info
+     */
+    buildHeaders() {
+        const headers = {
+            'Accept': 'application/json, text/event-stream',
+            'Content-Type': 'application/json',
+            'MCP-Protocol-Version': '2025-06-18',
+        };
+        // Add session header
+        if (this.session?.id) {
+            const sessionHeaderName = this.config.session?.headerName || 'Mcp-Session-Id';
+            headers[sessionHeaderName] = this.session.id;
+        }
+        // Add Last-Event-ID for stream resumption
+        if (this.session?.lastEventId) {
+            headers['Last-Event-ID'] = String(this.session.lastEventId);
+        }
+        // Add authentication
+        if (this.config.auth?.token) {
+            const token = this.resolveSecret(this.config.auth.token);
+            const headerName = this.config.auth.headerName || 'Authorization';
+            if (this.config.auth.type === 'bearer') {
+                headers[headerName] = `Bearer ${token}`;
+            }
+            else if (this.config.auth.type === 'api-key') {
+                headers[headerName] = token;
+            }
+            else if (this.config.auth.type === 'oauth2') {
+                headers[headerName] = `Bearer ${token}`;
+            }
+        }
+        // Add CORS headers if configured
+        if (this.config.cors?.enabled) {
+            headers['Origin'] = this.config.cors.allowOrigin || '*';
+        }
+        return headers;
+    }
+    /**
+     * Resolve ${secret:name} syntax to actual values
+     * (In production, this would fetch from secure storage)
+     */
+    resolveSecret(value) {
+        const match = value.match(/\$\{secret:([^}]+)\}/);
+        if (match) {
+            const secretName = match[1];
+            return process.env[`METALINK_SECRET_${secretName}`] || value;
+        }
+        return value;
+    }
+    /**
+     * Execute a tool via HTTP call with concurrency limit
+     */
+    async call(method, params) {
+        // P1 FIX: Check circuit breaker before request
+        if (this.circuitBreaker) {
+            if (!this.circuitBreaker.canExecute()) {
+                const state = this.circuitBreaker.getState();
+                throw new Error(`Circuit breaker is ${state} for ${this.config.url}. ` +
+                    `Requests temporarily blocked to failing server.`);
+            }
+        }
+        if (!this.isConnected && !this.isConnecting) {
+            await this.connect();
+        }
+        // Execute with concurrency limit
+        return this.executeWithConcurrencyLimit(async () => {
+            const requestId = this.requestId++;
+            const request = {
+                jsonrpc: '2.0',
+                method,
+                params,
+                id: requestId,
+            };
+            return new Promise((resolve, reject) => {
+                // Set up timeout
+                const timeout = setTimeout(() => {
+                    this.pendingRequests.delete(requestId);
+                    reject(new Error(`Request timeout after ${this.config.requestTimeoutMs || 30000}ms for ${method} (ID: ${requestId})`));
+                }, this.config.requestTimeoutMs || 30000);
+                // Store pending request
+                this.pendingRequests.set(requestId, { resolve, reject, timeout });
+                // Send request
+                this.sendRequest(request).catch(err => {
+                    clearTimeout(timeout);
+                    this.pendingRequests.delete(requestId);
+                    reject(err);
+                });
+            });
+        });
+    }
+    /**
+     * Send HTTP request to server with exponential backoff retry
+     * Includes automatic session reinitialize on 404 session errors (MCP spec compliance)
+     *
+     * @param request - The MCP request to send
+     * @param sessionReinitAttempted - Flag to prevent infinite reinitialize loops (max 1 per request)
+     */
+    async sendRequest(request, sessionReinitAttempted = false) {
+        const headers = this.buildHeaders();
+        let lastError = null;
+        const requestId = request.id || 'notification';
+        // Retry loop with exponential backoff
+        for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+            // P1 FIX: Create AbortController for this request
+            const abortController = new AbortController();
+            this.activeStreams.set(requestId, abortController);
+            // P1 FIX: Set stream timeout
+            const streamTimeout = setTimeout(() => {
+                abortController.abort();
+                this.activeStreams.delete(requestId);
+            }, this.config.streamTimeoutMs || 120000);
+            this.streamTimeouts.set(requestId, streamTimeout);
+            try {
+                const response = await undiciFetch(this.config.url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(request),
+                    dispatcher: this.agent || undefined,
+                    signal: abortController.signal,
+                });
+                // Success: process response
+                if (response.ok) {
+                    // Extract session ID from response headers (MCP servers return this)
+                    const serverSessionId = response.headers.get('mcp-session-id') || response.headers.get('Mcp-Session-Id');
+                    if (serverSessionId && this.session) {
+                        // Use the server's session ID instead of our generated one
+                        this.session.id = serverSessionId;
+                    }
+                    // Update session activity
+                    if (this.session) {
+                        this.session.lastActivity = Date.now();
+                    }
+                    // Handle response based on transport type
+                    if (this.config.transport === 'sse' || this.config.transport === 'sse-first') {
+                        await this.handleSSEResponse(response);
+                    }
+                    else {
+                        // http or http-stream
+                        await this.handleStreamResponse(response);
+                    }
+                    return; // Success - exit retry loop
+                }
+                // Non-retryable status code: check for special cases first
+                if (!this.isRetryable(response)) {
+                    // Special handling for 404: check if it's a session-related error
+                    // Per MCP spec, client MUST reinitialize when receiving 404 for invalid session
+                    if (response.status === 404 && !sessionReinitAttempted) {
+                        const responseBody = await response.text();
+                        const isSessionError = SESSION_ERROR_PATTERNS.some(pattern => responseBody.includes(pattern));
+                        if (isSessionError) {
+                            const expiredSessionId = this.session?.id;
+                            this.emit('session:expired', {
+                                sessionId: expiredSessionId,
+                                responseBody,
+                            });
+                            // Clear session and reinitialize
+                            this.session = null;
+                            this.isConnected = false;
+                            this.isConnecting = false;
+                            // Reinitialize session
+                            this.initializeSession();
+                            // Reconnect (sends initialize request)
+                            await this.connect();
+                            // Retry the original request with new session (only once)
+                            // Note: session is guaranteed to exist after connect() succeeds
+                            const newSession = this.session;
+                            this.emit('session:reinitialized', {
+                                newSessionId: newSession?.id,
+                                originalRequest: request.method,
+                            });
+                            // Retry with flag set to prevent infinite loops
+                            return this.sendRequest(request, true);
+                        }
+                    }
+                    const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+                    error.statusCode = response.status;
+                    throw error;
+                }
+                // Retryable status code - will retry below
+                lastError = response;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Handle AbortError specifically
+                if (error instanceof Error && error.name === 'AbortError') {
+                    lastError = new Error(`Stream cancelled/timeout for ${this.config.url}`);
+                }
+                // Non-retryable error: throw immediately
+                if (!this.isRetryable(lastError)) {
+                    throw lastError;
+                }
+            }
+            finally {
+                // P1 FIX: Always clean up stream resources after each attempt
+                clearTimeout(this.streamTimeouts.get(requestId));
+                this.streamTimeouts.delete(requestId);
+                this.activeStreams.delete(requestId);
+            }
+            // If this was the last attempt, throw
+            if (attempt === this.retryConfig.maxRetries) {
+                const message = lastError instanceof Response
+                    ? `HTTP ${lastError.status} after ${this.retryConfig.maxRetries} retries`
+                    : lastError instanceof Error
+                        ? lastError.message
+                        : 'Unknown error';
+                throw new Error(`Failed to call ${this.config.url}: ${message}`);
+            }
+            // Calculate backoff and wait before retry
+            const delayMs = this.calculateBackoffDelay(attempt);
+            this.emit('retry', {
+                attempt: attempt + 1,
+                maxRetries: this.retryConfig.maxRetries,
+                delayMs,
+                error: lastError,
+            });
+            await this.sleep(delayMs);
+        }
+        // Should not reach here, but satisfy TypeScript
+        throw lastError || new Error('Unknown error in retry loop');
+    }
+    /**
+     * Handle SSE (Server-Sent Events) streaming response
+     */
+    async handleSSEResponse(response) {
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw new Error('No response body for SSE stream');
+        }
+        const decoder = new TextDecoder();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                const text = decoder.decode(value, { stream: true });
+                this.sseEventBuffer += text;
+                // Process complete events in buffer
+                const lines = this.sseEventBuffer.split('\n');
+                this.sseEventBuffer = lines.pop() || ''; // Keep incomplete line
+                let currentEvent = {};
+                for (const line of lines) {
+                    if (line === '') {
+                        // Empty line = event boundary
+                        if (currentEvent.data) {
+                            this.handleSSEEvent(currentEvent);
+                        }
+                        currentEvent = {};
+                    }
+                    else if (line.startsWith('id: ')) {
+                        currentEvent.id = line.slice(4).trim();
+                    }
+                    else if (line.startsWith('data: ')) {
+                        currentEvent.data = line.slice(6);
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Handle individual SSE event
+     */
+    handleSSEEvent(event) {
+        if (!event.data)
+            return;
+        // Update last event ID for resumption
+        if (event.id && this.session) {
+            this.session.lastEventId = parseInt(event.id, 10);
+        }
+        try {
+            const response = JSON.parse(event.data);
+            this.resolveRequest(response);
+        }
+        catch (error) {
+            console.error('Failed to parse SSE data:', error);
+        }
+    }
+    /**
+     * Handle HTTP-stream response (batch of JSON objects)
+     */
+    async handleStreamResponse(response) {
+        const text = await response.text();
+        const lines = text.trim().split('\n');
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const response = JSON.parse(line);
+                this.resolveRequest(response);
+            }
+            catch (error) {
+                console.error('Failed to parse stream response:', error);
+            }
+        }
+    }
+    /**
+     * Resolve pending request with response
+     */
+    resolveRequest(response) {
+        const requestId = response.id;
+        if (requestId === null || requestId === undefined) {
+            // Notification (no response expected)
+            return;
+        }
+        const pending = this.pendingRequests.get(requestId);
+        if (!pending) {
+            console.warn(`Received response for unknown request ID: ${requestId}`);
+            return;
+        }
+        this.pendingRequests.delete(requestId);
+        clearTimeout(pending.timeout);
+        if (response.error) {
+            // P1 FIX: Record failure in circuit breaker
+            if (this.circuitBreaker) {
+                this.circuitBreaker.recordFailure();
+            }
+            pending.reject(new Error(`RPC Error (${response.error.code}): ${response.error.message}`));
+        }
+        else {
+            // P1 FIX: Record success in circuit breaker
+            if (this.circuitBreaker) {
+                this.circuitBreaker.recordSuccess();
+            }
+            pending.resolve(response);
+        }
+    }
+    /**
+     * Connect to HTTP server
+     */
+    async connect() {
+        if (this.isConnected || this.isConnecting)
+            return;
+        this.isConnecting = true;
+        try {
+            // Send initialize request to validate connection
+            const response = await this.call('initialize', {
+                protocolVersion: '2025-06-18',
+                capabilities: {},
+                clientInfo: {
+                    name: 'metalink-http-client',
+                    version: '1.0.0',
+                },
+            });
+            if (!response.result) {
+                throw new Error('Initialize response missing result');
+            }
+            this.isConnected = true;
+            this.isConnecting = false;
+            this.emit('connected', { session: this.session });
+        }
+        catch (error) {
+            this.isConnecting = false;
+            this.isConnected = false;
+            throw error;
+        }
+    }
+    /**
+     * Disconnect from HTTP server
+     */
+    async disconnect() {
+        this.isConnected = false;
+        // P1 FIX: Cancel all active streams
+        for (const [requestId, controller] of this.activeStreams) {
+            controller.abort();
+            clearTimeout(this.streamTimeouts.get(requestId));
+        }
+        this.activeStreams.clear();
+        this.streamTimeouts.clear();
+        // Destroy agent and close all connections
+        if (this.agent) {
+            await this.agent.close();
+            this.agent = null;
+            this.emit('agent:destroyed', { serverName: this.config.name });
+        }
+        // Cancel all pending requests
+        for (const [, pending] of this.pendingRequests) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error('Disconnected'));
+        }
+        this.pendingRequests.clear();
+        // Clear queued requests
+        this.requestQueue = [];
+        this.activeRequests = 0;
+        // Send notifications for any open sessions
+        this.emit('disconnected');
+        // P1 FIX: Clean up all event listeners to prevent memory leaks
+        const eventNames = this.eventNames();
+        for (const event of eventNames) {
+            this.removeAllListeners(event);
+        }
+    }
+    /**
+     * Health check - ping the server
+     */
+    async healthCheck() {
+        try {
+            // Try to call a simple method that servers typically support
+            const response = await this.call('ping');
+            return !!response.result || !response.error;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if client is connected
+     */
+    getConnected() {
+        return this.isConnected;
+    }
+    /**
+     * Get session info
+     */
+    getSession() {
+        return this.session;
+    }
+    /**
+     * Get concurrency metrics for monitoring
+     */
+    getConcurrencyMetrics() {
+        return {
+            activeRequests: this.activeRequests,
+            queuedRequests: this.requestQueue.length,
+            maxConcurrentRequests: this.MAX_CONCURRENT_REQUESTS,
+        };
+    }
+    /**
+     * Collect connection pool metrics from agent
+     */
+    collectPoolMetrics() {
+        if (!this.agent)
+            return;
+        const stats = this.agent.stats?.() || {};
+        this.poolMetrics = {
+            activeSockets: stats.connected || 0,
+            freeSockets: stats.free || 0,
+            pendingRequests: stats.pending || 0,
+            totalConnections: (stats.connected || 0) + (stats.free || 0),
+        };
+        this.emit('pool:metrics', {
+            serverName: this.config.name,
+            metrics: this.poolMetrics,
+        });
+    }
+    /**
+     * Get connection pool metrics
+     */
+    getPoolMetrics() {
+        this.collectPoolMetrics();
+        return { ...this.poolMetrics };
+    }
+}
+/**
+ * Factory for creating HTTP clients from config
+ * @param config - HTTP server configuration
+ * @param circuitBreaker - Optional circuit breaker for resilience
+ */
+export function createHttpClient(config, circuitBreaker) {
+    return new HttpClient(config, circuitBreaker);
+}
+//# sourceMappingURL=http-client.js.map