@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/services/session/session-manager.d.ts

@@ -0,0 +1,352 @@
+import { SessionState } from '../../../shared/models/session.model.js';
+import type { Session } from './types.js';
+/**
+ * Enhanced MCP Session Manager with comprehensive persistence and lifecycle management.
+ *
+ * This service manages MCP sessions with full state persistence, automatic cleanup,
+ * and graceful shutdown handling. It provides session isolation through unique
+ * server and transport instances per session while maintaining shared resources
+ * for efficiency.
+ *
+ * Key features include:
+ * - Session state persistence to disk with individual session files and index
+ * - Dirty tracking with 5-second batch flushing to minimize I/O operations
+ * - Automatic cleanup of stale sessions based on configurable timeout (default 30 minutes)
+ * - Graceful shutdown handling with SIGTERM/SIGINT signal capture
+ * - Client metadata integration from client tracker service
+ * - Environment variable controlled debugging (SESSION_DEBUG)
+ *
+ * Session storage structure:
+ * ```
+ * ~/.mcp-hub-lite/
+ * └── sessions/
+ *     ├── index.json          # Session index file
+ *     └── {sessionId}.json    # Individual session state files
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = new McpSessionManager();
+ * const session = await sessionManager.getSession('my-session-id');
+ * // Use session.server and session.transport for MCP communication
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare class McpSessionManager {
+    private sessions;
+    private sessionStates;
+    private dirtySessions;
+    private sessionsPath;
+    private flushTimeout;
+    private isInitialized;
+    private get SESSION_TIMEOUT();
+    private get CLEANUP_INTERVAL();
+    constructor();
+    /**
+     * Registers process shutdown handlers for graceful session cleanup.
+     *
+     * This method sets up event listeners for SIGTERM and SIGINT signals to ensure
+     * that all dirty sessions are flushed to disk before the process terminates.
+     * This prevents data loss during unexpected shutdowns or service restarts.
+     *
+     * The shutdown handler performs a final flush of all dirty sessions and
+     * clears any pending flush timeouts to ensure clean termination.
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // Called automatically in constructor
+     * sessionManager.registerShutdownHandler();
+     * ```
+     */
+    private registerShutdownHandler;
+    /**
+     * Marks a session as dirty, indicating it needs to be persisted to disk.
+     *
+     * This method adds the session ID to the dirty sessions set and initiates
+     * a delayed batch flush operation with a 5-second timeout. This optimization
+     * prevents excessive I/O operations by batching multiple session updates
+     * that occur in quick succession.
+     *
+     * When the SESSION_DEBUG environment variable is set, detailed logging
+     * is enabled for debugging session persistence behavior.
+     *
+     * @param {string} sessionId - Unique identifier of the session to mark as dirty
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * sessionManager.markAsDirty('my-session-id');
+     * // Session will be flushed to disk within 5 seconds
+     * ```
+     */
+    private markAsDirty;
+    /**
+     * Loads the complete session store from disk, including all individual session files.
+     *
+     * This method reads the sessions index file and loads each individual session state
+     * file, validating each session state against the SessionStateSchema. Invalid
+     * session states are skipped with warning logs, ensuring robust recovery from
+     * corrupted data.
+     *
+     * The method creates the sessions directory and index file if they don't exist,
+     * providing a clean initialization path for first-time usage.
+     *
+     * @returns {Promise<SessionStore>} Complete session store with all valid sessions
+     * @throws {Error} If critical I/O operations fail (non-recoverable errors)
+     *
+     * @example
+     * ```typescript
+     * const store = await sessionManager.loadSessionStore();
+     * console.log(`Loaded ${Object.keys(store.sessions).length} sessions`);
+     * ```
+     */
+    private loadSessionStore;
+    /**
+     * Saves the complete session store to disk, writing individual session files and index.
+     *
+     * This method persists all session states by writing individual JSON files for each
+     * session and updating the sessions index file. The operation is atomic at the
+     * file level, ensuring data integrity even if the process is interrupted.
+     *
+     * @param {SessionStore} store - Complete session store to persist
+     * @returns {Promise<void>} Resolves when all files are successfully written
+     * @throws {Error} If any file write operations fail
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.saveSessionStore(mySessionStore);
+     * console.log('Session store saved successfully');
+     * ```
+     */
+    private saveSessionStore;
+    /**
+     * Restores all sessions from disk during service startup.
+     *
+     * This method is called automatically during initialization to recover session states
+     * from persistent storage. It loads the session store, validates each session state,
+     * and populates the in-memory session state cache. Invalid sessions are skipped
+     * with warning logs to ensure robust startup even with corrupted data.
+     *
+     * The method ensures idempotent execution by checking the initialization flag,
+     * preventing multiple restoration attempts.
+     *
+     * @returns {Promise<void>} Resolves when all valid sessions are restored
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.restoreSessions();
+     * console.log('Sessions restored from disk');
+     * ```
+     */
+    restoreSessions(): Promise<void>;
+    /**
+     * Flushes all dirty sessions to disk in a single batch operation.
+     *
+     * This method collects all sessions marked as dirty, loads the current session store,
+     * updates it with the dirty sessions, and saves the complete store back to disk.
+     * This batch approach minimizes I/O operations and ensures data consistency.
+     *
+     * The method includes comprehensive error handling to prevent partial writes and
+     * maintains detailed logging for debugging and monitoring purposes.
+     *
+     * @returns {Promise<void>} Resolves when all dirty sessions are successfully flushed
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.flushDirtySessions();
+     * console.log('All dirty sessions flushed to disk');
+     * ```
+     */
+    private flushDirtySessions;
+    /**
+     * Updates session metadata by retrieving client information from the client tracker service.
+     *
+     * This method fetches current client information including name, version, working directory,
+     * and project context from the client tracker service and returns a partial session state
+     * update object containing only the relevant metadata fields.
+     *
+     * @param {string} sessionId - Unique identifier of the session to update
+     * @returns {Partial<SessionState>} Partial session state with updated client metadata
+     *
+     * @example
+     * ```typescript
+     * const metadata = sessionManager.updateSessionMetadataFromClient('my-session-id');
+     * console.log('Updated client metadata:', metadata);
+     * ```
+     */
+    private updateSessionMetadataFromClient;
+    /**
+     * Creates or updates a session state with current metadata and timestamps.
+     *
+     * This method merges existing session state (if any) with current client metadata
+     * from the client tracker service, updates access timestamps, and ensures proper
+     * session state structure. The updated state is stored in memory and marked as dirty
+     * for persistence.
+     *
+     * @param {string} sessionId - Unique identifier of the session to create or update
+     * @returns {SessionState} Complete updated session state object
+     *
+     * @example
+     * ```typescript
+     * const state = sessionManager.upsertSessionState('my-session-id');
+     * console.log('Session state updated:', state);
+     * ```
+     */
+    private upsertSessionState;
+    /**
+     * Updates session metadata explicitly with provided key-value pairs.
+     *
+     * This method merges the provided metadata object with existing session metadata,
+     * updates the last accessed timestamp, and marks the session as dirty for persistence.
+     * It's useful for storing custom session-specific information that needs to be persisted.
+     *
+     * @param {string} sessionId - Unique identifier of the session to update
+     * @param {Record<string, unknown>} metadata - Key-value pairs to merge into session metadata
+     * @returns {Promise<void>} Resolves when metadata is updated and marked for persistence
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.updateSessionMetadata('my-session-id', {
+     *   userPreferences: { theme: 'dark' },
+     *   lastProject: 'my-project'
+     * });
+     * ```
+     */
+    updateSessionMetadata(sessionId: string, metadata: Record<string, unknown>): Promise<void>;
+    /**
+     * Retrieves an existing session or creates a new one if it doesn't exist.
+     *
+     * This method provides access to active sessions, creating new ones on demand with
+     * proper initialization based on the requireInitialize parameter. It updates session
+     * access timestamps and persists session state changes to ensure data consistency.
+     *
+     * The method includes optimization to prevent excessive timestamp updates for rapid
+     * successive requests by only updating when at least 100ms have passed since the last access.
+     *
+     * @param {string} sessionId - Unique identifier of the session to retrieve or create
+     * @param {boolean} [requireInitialize=true] - Whether to require MCP protocol initialization
+     * @returns {Promise<Session>} Active session object with server and transport
+     *
+     * @example
+     * ```typescript
+     * // Get or create session with default initialization
+     * const session = await sessionManager.getSession('my-session-id');
+     *
+     * // Get or create session without requiring initialization (for restored sessions)
+     * const restoredSession = await sessionManager.getSession('restored-session-id', false);
+     * ```
+     */
+    getSession(sessionId: string, requireInitialize?: boolean): Promise<Session>;
+    /**
+     * Retrieves all persisted session states for API exposure.
+     *
+     * This method returns an array of all current session states, providing a complete
+     * snapshot of all active sessions and their metadata. It's primarily used by the
+     * web API to expose session information to clients.
+     *
+     * @returns {SessionState[]} Array of all current session states
+     *
+     * @example
+     * ```typescript
+     * const allStates = sessionManager.getAllSessionStates();
+     * console.log(`Total active sessions: ${allStates.length}`);
+     * ```
+     */
+    getAllSessionStates(): SessionState[];
+    /**
+     * Retrieves a specific session state by session ID for API exposure.
+     *
+     * This method returns the current state of a specific session or undefined if
+     * the session doesn't exist. It's primarily used by the web API to provide
+     * detailed information about individual sessions.
+     *
+     * @param {string} sessionId - Unique identifier of the session to retrieve
+     * @returns {SessionState | undefined} Session state object or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const state = sessionManager.getSessionState('my-session-id');
+     * if (state) {
+     *   console.log('Session client:', state.clientName);
+     * }
+     * ```
+     */
+    getSessionState(sessionId: string): SessionState | undefined;
+    /**
+     * Checks if a session object exists in the active sessions map.
+     *
+     * @param sessionId - Unique identifier of the session to check
+     * @returns {boolean} True if the session object exists, false otherwise
+     */
+    hasSession(sessionId: string): boolean;
+    /**
+     * Deletes a session and removes it from persistent storage.
+     *
+     * This method gracefully closes the session's MCP server, removes it from memory,
+     * and ensures it's removed from persistent storage by marking it as dirty and
+     * performing an immediate flush. It returns true if the session existed and was deleted.
+     *
+     * @param {string} sessionId - Unique identifier of the session to delete
+     * @returns {Promise<boolean>} True if session existed and was deleted, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const deleted = await sessionManager.deleteSession('my-session-id');
+     * if (deleted) {
+     *   console.log('Session deleted successfully');
+     * }
+     * ```
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Creates a new MCP session with proper initialization and transport setup.
+     *
+     * This method sets up a complete MCP session including server, transport, and
+     * communication logging. It handles both fresh sessions and restored sessions,
+     * with special logic for skipping initialization when appropriate.
+     *
+     * Key features:
+     * - Creates StreamableHTTPServerTransport with custom session ID generation
+     * - Sets up comprehensive message logging for debugging
+     * - Handles restored sessions by manually initializing transport state
+     * - Integrates with client tracker service for metadata
+     * - Creates/updates session state and marks as dirty for persistence
+     *
+     * @param {string} sessionId - Unique identifier for the new session
+     * @param {boolean} [requireInitialize=true] - Whether to require MCP protocol initialization
+     * @returns {Promise<Session>} Newly created session object
+     * @throws {Error} If session creation or connection fails
+     *
+     * @example
+     * ```typescript
+     * const session = await sessionManager.createSession('new-session-id');
+     * // Use session.server and session.transport for MCP communication
+     * ```
+     */
+    private createSession;
+    /**
+     * Cleans up stale sessions based on the configured session timeout.
+     *
+     * This method is called periodically (every 60 seconds) to identify and close
+     * sessions that haven't been accessed within the configured timeout period
+     * (default 30 minutes). It gracefully closes MCP servers and removes sessions
+     * from memory to prevent resource leaks.
+     *
+     * The method logs detailed information about cleaned sessions and maintains
+     * active session count for monitoring purposes.
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // Called automatically every 60 seconds
+     * sessionManager.cleanup();
+     * ```
+     */
+    private cleanup;
+}
+export declare const mcpSessionManager: McpSessionManager;
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/server/src/services/session/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/session/session-manager.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,YAAY,EAIb,MAAM,iCAAiC,CAAC;AAMzC,OAAO,KAAK,EAA4B,OAAO,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,aAAa,CAAS;IAE9B,OAAO,KAAK,eAAe,GAE1B;IAED,OAAO,KAAK,gBAAgB,GAE3B;;IA4BD;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,WAAW;IAgBnB;;;;;;;;;;;;;;;;;;;OAmBG;YACW,gBAAgB;IA8D9B;;;;;;;;;;;;;;;;OAgBG;YACW,gBAAgB;IA8B9B;;;;;;;;;;;;;;;;;;OAkBG;IACU,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IA6D7C;;;;;;;;;;;;;;;;;OAiBG;YACW,kBAAkB;IA+ChC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,+BAA+B;IAavC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,kBAAkB;IAyB1B;;;;;;;;;;;;;;;;;;OAkBG;IACU,qBAAqB,CAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC;IAqBhB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,GAAE,OAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IA0F/F;;;;;;;;;;;;;;OAcG;IACI,mBAAmB,IAAI,YAAY,EAAE;IAI5C;;;;;;;;;;;;;;;;;OAiBG;IACI,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAInE;;;;;OAKG;IACI,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;;;;;;;;;;;;;;OAiBG;IACU,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB/D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;YACW,aAAa;IA8I3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,OAAO;CAqDhB;AAED,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}