@lspeasy/client 1.0.1

package/dist/client.js

@@ -0,0 +1,692 @@
+/**
+ * LSP Client implementation
+ */
+import { CancellationTokenSource, ConsoleLogger, executeMiddlewarePipeline, LogLevel } from '@lspeasy/core';
+import { DisposableEventEmitter, HandlerRegistry } from '@lspeasy/core/utils';
+import { PendingRequestTracker, TransportAttachment } from '@lspeasy/core/utils/internal';
+import { initializeCapabilityMethods, updateCapabilityMethods } from './capability-proxy.js';
+import { CapabilityGuard, ClientCapabilityGuard } from './capability-guard.js';
+import { ConnectionHealthTracker, ConnectionState, HeartbeatMonitor } from './connection/index.js';
+/**
+ * Interface for dynamically added namespace methods
+ */
+/**
+ * Type alias to add capability-aware methods to LSPClient
+ * These methods are added at runtime via capability-proxy.ts
+ */
+/**
+ * LSP Client for connecting to language servers
+ *
+ * This class dynamically extends with capability-aware methods based on server capabilities.
+ * Use `.expect<ServerCaps>()` after initialization to get typed access to server capabilities.
+ *
+ * @template ClientCaps - Client capabilities (defaults to ClientCapabilities)
+ *
+ * @example
+ * // Create a client, then narrow server capabilities after connecting
+ * const client = new LSPClient<MyClientCaps>();
+ * await client.connect(transport);
+ * const typed = client.expect<{ hoverProvider: true; completionProvider: {} }>();
+ * // typed.textDocument.hover is available (typed)
+ * // typed.textDocument.completion is available (typed)
+ */
+class BaseLSPClient {
+    transport;
+    connected;
+    initialized;
+    pendingRequests;
+    requestHandlers;
+    notificationHandlers;
+    events;
+    transportAttachment;
+    logger;
+    middlewareRegistrations;
+    options;
+    capabilities;
+    serverCapabilities;
+    serverInfo;
+    onValidationError;
+    capabilityGuard;
+    clientCapabilityGuard;
+    healthTracker;
+    heartbeatMonitor;
+    notificationWaiters;
+    constructor(options = {}) {
+        this.connected = false;
+        this.initialized = false;
+        // Set up options with defaults
+        this.options = {
+            name: options.name ?? 'lspeasy-client',
+            version: options.version ?? '1.0.0',
+            logger: options.logger ?? new ConsoleLogger(options.logLevel ?? LogLevel.Info),
+            logLevel: options.logLevel ?? LogLevel.Info,
+            requestTimeout: options.requestTimeout,
+            strictCapabilities: options.strictCapabilities ?? false,
+            heartbeat: options.heartbeat
+        };
+        this.logger = this.options.logger;
+        this.middlewareRegistrations = options.middleware ?? [];
+        this.pendingRequests = new PendingRequestTracker(this.options.requestTimeout);
+        this.requestHandlers = new HandlerRegistry();
+        this.notificationHandlers = new HandlerRegistry();
+        this.events = new DisposableEventEmitter();
+        this.transportAttachment = new TransportAttachment();
+        this.notificationWaiters = new Set();
+        this.healthTracker = new ConnectionHealthTracker();
+        if (options.capabilities) {
+            this.capabilities = options.capabilities;
+        }
+        if (options.onValidationError) {
+            this.onValidationError = options.onValidationError;
+        }
+        // Initialize capability guard for server-to-client handlers
+        this.clientCapabilityGuard = new ClientCapabilityGuard(this.capabilities ?? {}, this.logger, this.options.strictCapabilities);
+        // Initialize capability-aware methods on the client object
+        // These will be empty initially and populated after server capabilities are received
+        initializeCapabilityMethods(this);
+    }
+    /**
+     * Connect to server and complete initialization
+     */
+    async connect(transport) {
+        if (this.connected) {
+            throw new Error('Client is already connected');
+        }
+        this.healthTracker.setState(ConnectionState.Connecting);
+        this.transport = transport;
+        this.connected = true;
+        this.transportAttachment.attach(transport, {
+            onMessage: (message) => this.handleMessage(message),
+            onError: (error) => this.handleError(error),
+            onClose: () => this.handleClose()
+        });
+        try {
+            // Send initialize request
+            this.logger.debug('Sending initialize request');
+            const initializeParams = {
+                processId: process.pid,
+                clientInfo: {
+                    name: this.options.name,
+                    version: this.options.version
+                },
+                capabilities: this.capabilities ?? {},
+                rootUri: null
+            };
+            const result = await this.sendRequest('initialize', initializeParams);
+            this.serverCapabilities = result.capabilities;
+            if (result.serverInfo) {
+                this.serverInfo = result.serverInfo;
+            }
+            this.initialized = true;
+            // Create capability guard to validate outgoing requests
+            this.capabilityGuard = new CapabilityGuard(result.capabilities, this.logger, this.options.strictCapabilities);
+            // Update capability-aware methods based on server capabilities
+            updateCapabilityMethods(this);
+            // Send initialized notification
+            await this.sendNotification('initialized', {});
+            this.healthTracker.setState(ConnectionState.Connected);
+            this.startHeartbeatIfConfigured(this.options.heartbeat);
+            this.logger.info('Client initialized', {
+                serverName: this.serverInfo?.name,
+                serverVersion: this.serverInfo?.version
+            });
+            this.events.emit('connected');
+            return result;
+        }
+        catch (error) {
+            // Ensure we clean up state and transport on initialization failure
+            try {
+                if (this.transport) {
+                    await this.transport.close();
+                }
+            }
+            catch (closeError) {
+                this.logger.error('Error closing transport after failed initialize', closeError);
+            }
+            // Reset client state and detach listeners via common close handler
+            this.handleClose();
+            throw error;
+        }
+    }
+    /**
+     * Disconnect from server
+     */
+    async disconnect() {
+        if (!this.connected) {
+            return;
+        }
+        this.healthTracker.setState(ConnectionState.Disconnecting);
+        try {
+            // Send shutdown request
+            if (this.initialized) {
+                this.logger.debug('Sending shutdown request');
+                await this.sendRequest('shutdown');
+                // Send exit notification
+                this.logger.debug('Sending exit notification');
+                await this.sendNotification('exit');
+            }
+        }
+        catch (error) {
+            this.logger.error('Error during shutdown', error);
+        }
+        finally {
+            // Close transport
+            if (this.transport) {
+                await this.transport.close();
+            }
+            this.handleClose();
+        }
+    }
+    /**
+     * Check if client is connected
+     */
+    isConnected() {
+        return this.connected && this.initialized;
+    }
+    /**
+     * Send a request to the server
+     */
+    async sendRequest(method, params, token) {
+        if (!this.connected || !this.transport) {
+            throw new Error('Client is not connected');
+        }
+        // Validate request against server capabilities
+        if (this.capabilityGuard && !this.capabilityGuard.canSendRequest(method)) {
+            this.logger.warn(`Server does not support request method ${method}`);
+        }
+        // Check if already cancelled before doing anything
+        if (token?.isCancellationRequested) {
+            return Promise.reject(new Error('Request was cancelled'));
+        }
+        const { id, promise } = this.pendingRequests.create(this.options.requestTimeout, method);
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params
+        };
+        this.logger.debug(`Sending request ${method}`, { id, params });
+        let cancellationDisposable;
+        if (token) {
+            cancellationDisposable = token.onCancellationRequested(() => {
+                this.sendNotification('$/cancelRequest', { id }).catch((err) => {
+                    this.logger.error('Failed to send cancellation', err);
+                });
+                // Use process.nextTick to defer rejection slightly
+                // This gives the caller a chance to attach rejection handlers before the rejection occurs
+                process.nextTick(() => {
+                    this.pendingRequests.reject(id, new Error('Request was cancelled'));
+                });
+            });
+        }
+        void promise.then(() => {
+            cancellationDisposable?.dispose();
+        }, () => {
+            cancellationDisposable?.dispose();
+        });
+        this.sendWithMiddleware({
+            direction: 'clientToServer',
+            messageType: 'request',
+            method,
+            message: request,
+            onSend: async () => {
+                this.healthTracker.markMessageSent();
+                await this.transport.send(request);
+            },
+            onShortCircuit: (result) => {
+                this.resolveShortCircuitRequest(id, result);
+            },
+            onError: (error) => {
+                this.pendingRequests.reject(id, error);
+            }
+        });
+        return promise;
+    }
+    /**
+     * Send a notification to the server
+     */
+    async sendNotification(method, params) {
+        if (!this.connected || !this.transport) {
+            throw new Error('Client is not connected');
+        }
+        // Validate notification against server capabilities
+        if (this.capabilityGuard && !this.capabilityGuard.canSendNotification(method)) {
+            this.logger.warn(`Server does not support notification method ${method}`);
+        }
+        const notification = {
+            jsonrpc: '2.0',
+            method,
+            params
+        };
+        this.logger.debug(`Sending notification ${method}`, { params });
+        await this.sendWithMiddleware({
+            direction: 'clientToServer',
+            messageType: 'notification',
+            method,
+            message: notification,
+            onSend: async () => {
+                this.healthTracker.markMessageSent();
+                await this.transport.send(notification);
+            }
+        });
+    }
+    /**
+     * Send a cancellable request
+     */
+    sendCancellableRequest(method, params) {
+        const cancelSource = new CancellationTokenSource();
+        const promise = this.sendRequest(method, params, cancelSource.token);
+        return {
+            promise,
+            cancel: () => cancelSource.cancel()
+        };
+    }
+    /**
+     * Register handler for server-to-client requests
+     */
+    onRequest(method, handler) {
+        if (this.clientCapabilityGuard && !this.clientCapabilityGuard.canRegisterHandler(method)) {
+            this.logger.warn(`Client capability not declared for handler ${method}`);
+        }
+        return this.requestHandlers.register(method, handler);
+    }
+    /**
+     * Register handler for server notifications
+     */
+    onNotification(method, handler) {
+        if (this.clientCapabilityGuard && !this.clientCapabilityGuard.canRegisterHandler(method)) {
+            this.logger.warn(`Client capability not declared for handler ${method}`);
+        }
+        return this.notificationHandlers.register(method, handler);
+    }
+    /**
+     * Wait for the next matching server notification.
+     */
+    waitForNotification(method, options) {
+        return new Promise((resolve, reject) => {
+            let timeoutHandle;
+            const waiter = {
+                method,
+                resolve: (params) => {
+                    resolve(params);
+                },
+                reject: (error) => {
+                    reject(error);
+                },
+                cleanup: () => {
+                    if (timeoutHandle) {
+                        clearTimeout(timeoutHandle);
+                        timeoutHandle = undefined;
+                    }
+                    this.notificationWaiters.delete(waiter);
+                }
+            };
+            if (options.filter) {
+                waiter.filter = options.filter;
+            }
+            this.notificationWaiters.add(waiter);
+            timeoutHandle = setTimeout(() => {
+                waiter.cleanup();
+                reject(new Error(`Timed out waiting for notification '${method}' after ${options.timeout}ms`));
+            }, options.timeout);
+        });
+    }
+    /**
+     * Subscribe to connection events
+     */
+    onConnected(handler) {
+        return this.events.on('connected', handler);
+    }
+    /**
+     * Subscribe to disconnection events
+     */
+    onDisconnected(handler) {
+        return this.events.on('disconnected', handler);
+    }
+    /**
+     * Subscribe to error events
+     */
+    onError(handler) {
+        return this.events.on('error', handler);
+    }
+    onConnectionStateChange(handler) {
+        const dispose = this.healthTracker.onStateChange(handler);
+        return { dispose };
+    }
+    onConnectionHealthChange(handler) {
+        const dispose = this.healthTracker.onHealthChange(handler);
+        return { dispose };
+    }
+    getConnectionHealth() {
+        return this.healthTracker.getHealth();
+    }
+    /**
+     * Get server capabilities
+     */
+    getServerCapabilities() {
+        return this.serverCapabilities;
+    }
+    /**
+     * Get server info
+     */
+    getServerInfo() {
+        return this.serverInfo;
+    }
+    /**
+     * Set client capabilities
+     */
+    setCapabilities(capabilities) {
+        this.capabilities = capabilities;
+        this.clientCapabilityGuard = new ClientCapabilityGuard(capabilities, this.logger, this.options.strictCapabilities);
+        // Note: Client capabilities are sent during initialize, so this only affects
+        // the local reference. To update server-side, would need client/registerCapability request.
+    }
+    /**
+     * Get client capabilities
+     */
+    getClientCapabilities() {
+        return this.capabilities;
+    }
+    /**
+     * Register a single client capability, returning a new typed reference via intersection.
+     * The returned reference is the same instance, with a narrowed type that includes
+     * the newly registered capability.
+     *
+     * Note: This updates the local capability reference. To notify the server of capability
+     * changes, the LSP 3.17 client/registerCapability request should be used separately.
+     *
+     * @template K - The capability key to register
+     * @param key - The client capability key
+     * @param value - The capability value
+     * @returns The same client instance with an expanded capability type
+     *
+     * @example
+     * const client = new LSPClient();
+     * const withWorkspace = client.registerCapability('workspace', { workspaceFolders: true });
+     * // withWorkspace is typed as LSPClient<ClientCaps & Pick<ClientCapabilities, 'workspace'>>
+     */
+    registerCapability(key, value) {
+        const current = this.capabilities ?? {};
+        const updated = { ...current, [key]: value };
+        this.setCapabilities(updated);
+        return this;
+    }
+    /**
+     * Zero-cost type narrowing for server capabilities.
+     * Returns `this` cast to include capability-aware methods for the given ServerCaps.
+     *
+     * @template S - The expected server capabilities shape
+     * @returns The same client instance, typed with capability-aware methods
+     *
+     * @example
+     * const client = new LSPClient<MyClientCaps>();
+     * await client.connect(transport);
+     * const typed = client.expect<{ hoverProvider: true }>();
+     * const result = await typed.textDocument.hover(params);
+     */
+    expect() {
+        return this;
+    }
+    /**
+     * Handle incoming message from transport
+     */
+    handleMessage(message) {
+        this.healthTracker.markMessageReceived();
+        this.heartbeatMonitor?.markPong();
+        if (this.heartbeatMonitor) {
+            this.healthTracker.setHeartbeat(this.heartbeatMonitor.getStatus());
+        }
+        // Response message
+        if ('id' in message && ('result' in message || 'error' in message)) {
+            void this.handleResponse(message).catch((error) => {
+                this.logger.error('Error handling response', error);
+            });
+            return;
+        }
+        // Request message
+        if ('id' in message && 'method' in message) {
+            // Fire and forget with error handling
+            void this.handleRequest(message).catch((error) => {
+                this.logger.error('Error handling server request', error);
+            });
+            return;
+        }
+        // Notification message
+        if ('method' in message && !('id' in message)) {
+            this.handleNotification(message);
+            return;
+        }
+        this.logger.warn('Received unknown message type', message);
+    }
+    /**
+     * Handle response message
+     */
+    async handleResponse(response) {
+        const { id } = response;
+        const method = this.pendingRequests.getMetadata(String(id));
+        if (!method) {
+            this.logger.warn(`Received response for unknown request ${id}`);
+            return;
+        }
+        await this.sendWithMiddleware({
+            direction: 'serverToClient',
+            messageType: 'error' in response ? 'error' : 'response',
+            method,
+            message: response,
+            onSend: async () => {
+                if ('error' in response && response.error) {
+                    this.logger.error(`Request ${method} failed`, response.error);
+                    this.pendingRequests.reject(String(id), new Error(`${response.error.message} (code: ${response.error.code})`));
+                    return;
+                }
+                if ('result' in response) {
+                    this.logger.debug(`Request ${method} succeeded`, { id });
+                    this.pendingRequests.resolve(String(id), response.result);
+                    return;
+                }
+                this.pendingRequests.reject(String(id), new Error('Invalid response message'));
+            },
+            onShortCircuit: (result) => {
+                this.resolveShortCircuitRequest(String(id), result);
+            },
+            onError: (error) => {
+                this.pendingRequests.reject(String(id), error);
+            }
+        });
+    }
+    resolveShortCircuitRequest(id, result) {
+        if (result.error) {
+            this.pendingRequests.reject(id, new Error(`${result.error.error.message} (code: ${result.error.error.code})`));
+            return;
+        }
+        if (result.response && 'error' in result.response && result.response.error) {
+            this.pendingRequests.reject(id, new Error(`${result.response.error.message} (code: ${result.response.error.code})`));
+            return;
+        }
+        if (result.response && 'result' in result.response) {
+            this.pendingRequests.resolve(id, result.response.result);
+            return;
+        }
+        this.pendingRequests.reject(id, new Error('Middleware short-circuit missing response payload'));
+    }
+    buildMiddlewareContext(direction, messageType, method, message) {
+        return {
+            direction,
+            messageType,
+            method,
+            message,
+            metadata: {},
+            transport: this.transport?.constructor.name ?? 'unknown'
+        };
+    }
+    async sendWithMiddleware(options) {
+        const context = this.buildMiddlewareContext(options.direction, options.messageType, options.method, options.message);
+        try {
+            const result = await executeMiddlewarePipeline(this.middlewareRegistrations, context, async () => {
+                await options.onSend();
+                return undefined;
+            });
+            if (result?.shortCircuit && options.onShortCircuit) {
+                options.onShortCircuit(result);
+            }
+        }
+        catch (error) {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            this.handleError(normalized);
+            if (options.onError) {
+                options.onError(normalized);
+                return;
+            }
+            throw normalized;
+        }
+    }
+    /**
+     * Handle request message from server
+     */
+    async handleRequest(request) {
+        const { id, method, params } = request;
+        const handler = this.requestHandlers.get(method);
+        if (!handler) {
+            this.logger.warn(`No handler for server request ${method}`);
+            // Send method not found error
+            const response = {
+                jsonrpc: '2.0',
+                id,
+                error: {
+                    code: -32601,
+                    message: `Method not found: ${method}`
+                }
+            };
+            try {
+                if (this.transport) {
+                    await this.transport.send(response);
+                }
+            }
+            catch (error) {
+                this.logger.error('Failed to send error response', error);
+            }
+            return;
+        }
+        try {
+            const result = await handler(params);
+            const response = {
+                jsonrpc: '2.0',
+                id,
+                result
+            };
+            try {
+                if (this.transport) {
+                    await this.transport.send(response);
+                }
+            }
+            catch (error) {
+                this.logger.error('Failed to send success response', error);
+            }
+        }
+        catch (error) {
+            this.logger.error(`Handler for ${method} threw error`, error);
+            const response = {
+                jsonrpc: '2.0',
+                id,
+                error: {
+                    code: -32603,
+                    message: error instanceof Error ? error.message : 'Internal error'
+                }
+            };
+            try {
+                if (this.transport) {
+                    await this.transport.send(response);
+                }
+            }
+            catch (sendError) {
+                this.logger.error('Failed to send error response', sendError);
+            }
+        }
+    }
+    /**
+     * Handle notification message from server
+     */
+    handleNotification(notification) {
+        const { method, params } = notification;
+        for (const waiter of Array.from(this.notificationWaiters)) {
+            if (waiter.method !== method) {
+                continue;
+            }
+            try {
+                if (waiter.filter && !waiter.filter(params)) {
+                    continue;
+                }
+                waiter.cleanup();
+                waiter.resolve(params);
+            }
+            catch (error) {
+                waiter.cleanup();
+                const normalized = error instanceof Error ? error : new Error(String(error));
+                waiter.reject(normalized);
+            }
+        }
+        const handler = this.notificationHandlers.get(method);
+        if (!handler) {
+            this.logger.debug(`No handler for server notification ${method}`);
+            return;
+        }
+        try {
+            handler(params);
+        }
+        catch (error) {
+            this.logger.error(`Handler for ${method} threw error`, error);
+        }
+    }
+    /**
+     * Handle transport error
+     */
+    handleError(error) {
+        this.logger.error('Transport error', error);
+        this.events.emit('error', error);
+    }
+    /**
+     * Handle connection close
+     */
+    handleClose() {
+        if (!this.connected) {
+            return;
+        }
+        this.logger.info('Connection closed');
+        this.connected = false;
+        this.initialized = false;
+        delete this.transport;
+        this.heartbeatMonitor?.stop();
+        this.heartbeatMonitor = undefined;
+        this.healthTracker.setState(ConnectionState.Disconnected);
+        this.transportAttachment.detach();
+        this.pendingRequests.clear(new Error('Connection closed'));
+        for (const waiter of Array.from(this.notificationWaiters)) {
+            waiter.cleanup();
+            waiter.reject(new Error('Connection closed before notification was received'));
+        }
+        this.events.emit('disconnected');
+    }
+    startHeartbeatIfConfigured(config) {
+        if (!config || !config.enabled) {
+            return;
+        }
+        this.heartbeatMonitor?.stop();
+        this.heartbeatMonitor = new HeartbeatMonitor({
+            config,
+            onPing: () => {
+                this.healthTracker.setHeartbeat(this.heartbeatMonitor.getStatus());
+            },
+            onUnresponsive: () => {
+                this.healthTracker.setHeartbeat(this.heartbeatMonitor.getStatus());
+            },
+            onResponsive: () => {
+                this.healthTracker.setHeartbeat(this.heartbeatMonitor.getStatus());
+            }
+        });
+        this.healthTracker.setHeartbeat(this.heartbeatMonitor.getStatus());
+        this.heartbeatMonitor.start();
+    }
+}
+// Generic constructor that preserves type parameters
+export const LSPClient = BaseLSPClient;
+//# sourceMappingURL=client.js.map