@juspay/neurolink 4.0.0 → 4.1.0

package/dist/lib/mcp/session-persistence.js

@@ -0,0 +1,298 @@
+/**
+ * NeuroLink Session Persistence Layer
+ * Provides file-based persistence for sessions with atomic writes and recovery
+ */
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+/**
+ * Session Persistence Manager
+ * Handles saving and loading sessions to/from disk with recovery mechanisms
+ */
+export class SessionPersistence {
+    directory;
+    snapshotInterval;
+    retentionPeriod;
+    enableChecksum;
+    maxRetries;
+    snapshotTimer = null;
+    sessionMap;
+    constructor(sessionMap, options = {}) {
+        this.sessionMap = sessionMap;
+        this.directory = options.directory || ".neurolink/sessions";
+        this.snapshotInterval = options.snapshotInterval || 30000; // 30 seconds
+        this.retentionPeriod = options.retentionPeriod || 86400000; // 24 hours
+        this.enableChecksum = options.enableChecksum ?? true;
+        this.maxRetries = options.maxRetries || 3;
+    }
+    /**
+     * Initialize persistence layer
+     */
+    async initialize() {
+        // Create sessions directory if it doesn't exist
+        await this.ensureDirectory();
+        // Load existing sessions
+        await this.loadSessions();
+        // Start snapshot timer
+        this.startSnapshotTimer();
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionPersistence] Initialized with directory: ${this.directory}`);
+        }
+    }
+    /**
+     * Ensure sessions directory exists
+     */
+    async ensureDirectory() {
+        await fs.mkdir(this.directory, { recursive: true });
+    }
+    /**
+     * Calculate checksum for data integrity
+     */
+    calculateChecksum(data) {
+        return crypto.createHash("sha256").update(data).digest("hex");
+    }
+    /**
+     * Serialize session to JSON with metadata
+     */
+    serializeSession(session) {
+        // Convert Map to array for JSON serialization
+        const sessionData = {
+            ...session,
+            state: Array.from(session.state.entries()),
+        };
+        let fileData = {
+            session: sessionData,
+            checksum: "",
+            version: "1.0",
+            lastSaved: Date.now(),
+        };
+        if (this.enableChecksum) {
+            // First serialization without checksum
+            const tempJsonData = JSON.stringify(fileData, null, 2);
+            // Calculate checksum based on the first serialization
+            fileData.checksum = this.calculateChecksum(tempJsonData);
+        }
+        // Final serialization with checksum included
+        return JSON.stringify(fileData, null, 2);
+    }
+    /**
+     * Deserialize session from JSON
+     */
+    deserializeSession(data) {
+        try {
+            const fileData = JSON.parse(data);
+            // Verify checksum if enabled
+            if (this.enableChecksum && fileData.checksum) {
+                const tempData = { ...fileData, checksum: "" };
+                const expectedChecksum = this.calculateChecksum(JSON.stringify(tempData, null, 2));
+                if (fileData.checksum !== expectedChecksum) {
+                    console.error("[SessionPersistence] Checksum mismatch, session corrupted");
+                    return null;
+                }
+            }
+            // Convert state array back to Map
+            const session = fileData.session;
+            session.state = new Map(session.state);
+            return session;
+        }
+        catch (error) {
+            console.error("[SessionPersistence] Failed to deserialize session:", error);
+            return null;
+        }
+    }
+    /**
+     * Save single session with atomic write
+     */
+    async saveSession(sessionId, session) {
+        const filename = `${sessionId}.json`;
+        const filepath = path.join(this.directory, filename);
+        const tempPath = `${filepath}.tmp`;
+        let retries = 0;
+        while (retries < this.maxRetries) {
+            try {
+                // Serialize session
+                const data = this.serializeSession(session);
+                // Write to temporary file first (atomic write pattern)
+                await fs.writeFile(tempPath, data, "utf8");
+                // Rename temp file to final location (atomic operation)
+                await fs.rename(tempPath, filepath);
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    console.log(`[SessionPersistence] Saved session ${sessionId}`);
+                }
+                return true;
+            }
+            catch (error) {
+                retries++;
+                console.error(`[SessionPersistence] Failed to save session (attempt ${retries}):`, error);
+                // Clean up temp file if it exists
+                try {
+                    await fs.unlink(tempPath);
+                }
+                catch {
+                    // Ignore errors when cleaning up temp file
+                }
+                if (retries < this.maxRetries) {
+                    // Exponential backoff
+                    await new Promise((resolve) => setTimeout(resolve, Math.pow(2, retries) * 100));
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Load single session from disk
+     */
+    async loadSession(sessionId) {
+        const filename = `${sessionId}.json`;
+        const filepath = path.join(this.directory, filename);
+        try {
+            const data = await fs.readFile(filepath, "utf8");
+            return this.deserializeSession(data);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[SessionPersistence] Failed to load session ${sessionId}:`, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Load all sessions from disk on startup
+     */
+    async loadSessions() {
+        try {
+            const files = await fs.readdir(this.directory);
+            const sessionFiles = files.filter((f) => f.endsWith(".json"));
+            let loaded = 0;
+            let expired = 0;
+            for (const file of sessionFiles) {
+                const sessionId = file.replace(".json", "");
+                const session = await this.loadSession(sessionId);
+                if (session) {
+                    // Check if session is expired
+                    if (session.expiresAt < Date.now()) {
+                        expired++;
+                        // Clean up expired session file
+                        await this.deleteSession(sessionId);
+                    }
+                    else {
+                        // Restore to memory
+                        this.sessionMap.set(sessionId, session);
+                        loaded++;
+                    }
+                }
+            }
+            console.log(`[SessionPersistence] Loaded ${loaded} sessions, cleaned ${expired} expired sessions`);
+        }
+        catch (error) {
+            console.error("[SessionPersistence] Failed to load sessions:", error);
+        }
+    }
+    /**
+     * Save all active sessions (snapshot)
+     */
+    async saveAllSessions() {
+        const sessions = Array.from(this.sessionMap.entries());
+        // Filter out expired sessions and create save promises
+        const savePromises = sessions
+            .filter(([_, session]) => session.expiresAt >= Date.now())
+            .map(async ([sessionId, session]) => {
+            return (await this.saveSession(sessionId, session)) ? 1 : 0;
+        });
+        // Execute all save operations concurrently
+        const results = await Promise.all(savePromises);
+        const saved = results.reduce((sum, result) => sum + result, 0);
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionPersistence] Snapshot: saved ${saved}/${sessions.length} sessions`);
+        }
+    }
+    /**
+     * Delete session file
+     */
+    async deleteSession(sessionId) {
+        const filename = `${sessionId}.json`;
+        const filepath = path.join(this.directory, filename);
+        try {
+            await fs.unlink(filepath);
+            // Keep memory and disk state in sync
+            this.sessionMap.delete(sessionId);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[SessionPersistence] Failed to delete session ${sessionId}:`, error);
+            }
+        }
+    }
+    /**
+     * Clean up old session files
+     */
+    async cleanupOldSessions() {
+        try {
+            const files = await fs.readdir(this.directory);
+            const now = Date.now();
+            let cleaned = 0;
+            for (const file of files) {
+                if (!file.endsWith(".json")) {
+                    continue;
+                }
+                const filepath = path.join(this.directory, file);
+                const stats = await fs.stat(filepath);
+                // Remove files older than retention period
+                if (now - stats.mtimeMs > this.retentionPeriod) {
+                    await fs.unlink(filepath);
+                    cleaned++;
+                }
+            }
+            if (cleaned > 0) {
+                console.log(`[SessionPersistence] Cleaned up ${cleaned} old session files`);
+            }
+        }
+        catch (error) {
+            console.error("[SessionPersistence] Cleanup failed:", error);
+        }
+    }
+    /**
+     * Start periodic snapshot timer
+     */
+    startSnapshotTimer() {
+        if (this.snapshotTimer) {
+            clearInterval(this.snapshotTimer);
+        }
+        this.snapshotTimer = setInterval(async () => {
+            await this.saveAllSessions();
+            await this.cleanupOldSessions();
+        }, this.snapshotInterval);
+    }
+    /**
+     * Stop snapshot timer
+     */
+    stopSnapshotTimer() {
+        if (this.snapshotTimer) {
+            clearInterval(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+    }
+    /**
+     * Shutdown persistence layer
+     */
+    async shutdown() {
+        this.stopSnapshotTimer();
+        // Final snapshot before shutdown
+        await this.saveAllSessions();
+        console.log("[SessionPersistence] Shutdown complete");
+    }
+}
+/**
+ * Default session persistence instance
+ */
+export let defaultSessionPersistence = null;
+/**
+ * Initialize default session persistence
+ */
+export async function initializeSessionPersistence(sessionMap, options) {
+    if (!defaultSessionPersistence) {
+        defaultSessionPersistence = new SessionPersistence(sessionMap, options);
+        await defaultSessionPersistence.initialize();
+    }
+    return defaultSessionPersistence;
+}

package/dist/lib/mcp/transport-manager.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Transport Manager for MCP connections
+ * Supports stdio, SSE, and HTTP transports with reconnection logic
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { z } from "zod";
+import { ErrorManager } from "./error-manager.js";
+export declare const TransportConfigSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"stdio">;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    type: "stdio";
+    command: string;
+    args?: string[] | undefined;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    type: "stdio";
+    command: string;
+    args?: string[] | undefined;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"sse">;
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    maxRetryTime: z.ZodDefault<z.ZodNumber>;
+    withCredentials: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "sse";
+    timeout: number;
+    url: string;
+    maxRetryTime: number;
+    withCredentials: boolean;
+    headers?: Record<string, string> | undefined;
+}, {
+    type: "sse";
+    url: string;
+    timeout?: number | undefined;
+    headers?: Record<string, string> | undefined;
+    maxRetryTime?: number | undefined;
+    withCredentials?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"http">;
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "http";
+    timeout: number;
+    url: string;
+    headers?: Record<string, string> | undefined;
+}, {
+    type: "http";
+    url: string;
+    timeout?: number | undefined;
+    headers?: Record<string, string> | undefined;
+}>]>;
+export type TransportConfig = z.infer<typeof TransportConfigSchema>;
+export interface TransportStatus {
+    connected: boolean;
+    type: "stdio" | "sse" | "http";
+    lastConnected?: Date;
+    lastError?: Error;
+    reconnectAttempts: number;
+}
+export interface TransportManagerOptions {
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+    reconnectDelay?: number;
+    healthCheckInterval?: number;
+    jitterEnabled?: boolean;
+    maxJitter?: number;
+}
+/**
+ * Manages MCP transport connections with automatic reconnection and health monitoring
+ */
+export declare class TransportManager {
+    private errorManager;
+    private options;
+    private client?;
+    private config?;
+    private status;
+    private reconnectTimer?;
+    private healthCheckTimer?;
+    private reconnectPromise?;
+    constructor(errorManager: ErrorManager, options?: TransportManagerOptions);
+    /**
+     * Connect to MCP server using specified transport
+     */
+    connect(config: TransportConfig): Promise<Client>;
+    /**
+     * Create transport based on configuration
+     */
+    createTransport(config: TransportConfig): Promise<any>;
+    /**
+     * Create stdio transport
+     */
+    private createStdioTransport;
+    /**
+     * Create SSE transport with reconnection support
+     */
+    private createSSETransport;
+    /**
+     * Create HTTP transport
+     */
+    private createHTTPTransport;
+    /**
+     * Set up health monitoring
+     */
+    private setupHealthMonitoring;
+    /**
+     * Handle connection errors
+     */
+    private handleConnectionError;
+    /**
+     * Schedule reconnection attempt
+     */
+    private scheduleReconnect;
+    /**
+     * Calculate reconnect delay with exponential backoff
+     */
+    private calculateReconnectDelay;
+    /**
+     * Reconnect to server
+     */
+    reconnect(): Promise<void>;
+    private _reconnect;
+    /**
+     * Disconnect from server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get current transport status
+     */
+    getStatus(): TransportStatus;
+    /**
+     * Get connected client
+     */
+    getClient(): Client | undefined;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Reset reconnection attempts
+     */
+    resetReconnectAttempts(): void;
+}