touchdesigner-mcp-server/dist/transport/sessionManager.d.ts

MCP server for TouchDesigner

import type { ILogger } from "../core/logger.js";
import type { Result } from "../core/result.js";
import type { SessionConfig } from "./config.js";
/**
 * Session metadata
 */
export interface Session {
    /**
     * Unique session identifier (UUID v4)
     */
    id: string;
    /**
     * Timestamp when session was created (milliseconds since epoch)
     */
    createdAt: number;
    /**
     * Timestamp when session was last accessed (milliseconds since epoch)
     */
    lastAccessedAt: number;
    /**
     * Optional metadata associated with the session
     */
    metadata?: Record<string, unknown>;
}
/**
 * Session manager interface
 */
export interface ISessionManager {
    /**
     * Create a new session with auto-generated ID
     */
    create(metadata?: Record<string, unknown>): string;
    /**
     * Refresh last access time for a session
     */
    touch(sessionId: string): Result<void, Error>;
    /**
     * Register a callback invoked when a session expires via TTL cleanup.
     */
    setExpirationHandler(handler: (sessionId: string) => Promise<void> | void): void;
    /**
     * Register an existing session (created by SDK)
     */
    register(sessionId: string, metadata?: Record<string, unknown>): void;
    /**
     * Clean up a session by ID
     */
    cleanup(sessionId: string): Result<void, Error>;
    /**
     * List all active sessions
     */
    list(): Session[];
    /**
     * Start automatic TTL-based cleanup
     */
    startTTLCleanup(): void;
    /**
     * Stop automatic TTL-based cleanup
     */
    stopTTLCleanup(): void;
    /**
     * Get number of active sessions
     */
    getActiveSessionCount(): number;
    /**
     * Clear all sessions (for testing or emergency cleanup)
     */
    clearAll(): void;
}
/**
 * Session Manager
 *
 * Manages client sessions for Streamable HTTP transport.
 * Provides session creation, validation, TTL-based expiration, and automatic cleanup.
 *
 * Note: Session validation (checking if session ID exists) is now handled by
 * StreamableHTTPServerTransport.handleRequest(). This SessionManager focuses on:
 * - Session creation via SDK callbacks (onsessioninitialized)
 * - Session cleanup via SDK callbacks (onsessionclosed) and TTL-based cleanup
 * - Session tracking for health checks and monitoring
 *
 * @example
 * ```typescript
 * const sessionManager = new SessionManager(
 *   { enabled: true, ttl: 60 * 60 * 1000 }, // 1 hour TTL
 *   logger
 * );
 *
 * // Create session (typically called from SDK callback)
 * const sessionId = sessionManager.create({ clientVersion: '1.0' });
 *
 * // Start automatic TTL-based cleanup
 * sessionManager.startTTLCleanup();
 *
 * // Stop cleanup when done
 * sessionManager.stopTTLCleanup();
 * ```
 */
export declare class SessionManager implements ISessionManager {
    private readonly sessions;
    private readonly config;
    private readonly logger;
    private cleanupInterval;
    private onSessionExpired;
    constructor(config: SessionConfig, logger: ILogger);
    /**
     * Create a new session with optional metadata
     *
     * @param metadata - Optional metadata to associate with the session
     * @returns Session ID (UUID v4)
     */
    create(metadata?: Record<string, unknown>): string;
    /**
     * Update lastAccessedAt when a session receives activity
     *
     * @param sessionId - Session ID to refresh
     */
    touch(sessionId: string): Result<void, Error>;
    /**
     * Register a callback to run when TTL cleanup expires a session.
     *
     * @param handler - Callback invoked with expired session ID
     */
    setExpirationHandler(handler: (sessionId: string) => Promise<void> | void): void;
    /**
     * Register an SDK-created session for tracking
     *
     * This method registers sessions that were created by the MCP SDK's
     * StreamableHTTPServerTransport. The SDK generates session IDs via the
     * sessionIdGenerator callback, and then calls onsessioninitialized.
     * This method creates a new tracking entry with current timestamps
     * so the session can be managed for TTL cleanup and monitoring.
     *
     * @param sessionId - Session ID generated by SDK
     * @param metadata - Optional metadata to associate with the session
     */
    register(sessionId: string, metadata?: Record<string, unknown>): void;
    /**
     * Clean up (delete) a session by ID
     *
     * @param sessionId - Session ID to clean up
     * @returns Result indicating success or failure
     */
    cleanup(sessionId: string): Result<void, Error>;
    /**
     * List all active sessions
     *
     * @returns Array of all active sessions
     */
    list(): Session[];
    /**
     * Start automatic TTL-based cleanup
     *
     * Runs cleanup task at an interval of TTL/2 to remove expired sessions.
     * Does nothing if TTL is not configured or cleanup is already running.
     */
    startTTLCleanup(): void;
    /**
     * Stop automatic TTL-based cleanup
     */
    stopTTLCleanup(): void;
    /**
     * Run a single cleanup task to remove expired sessions
     *
     * @private
     */
    private runCleanupTask;
    /**
     * Get number of active sessions
     *
     * @returns Number of active sessions
     */
    getActiveSessionCount(): number;
    /**
     * Clear all sessions
     *
     * Useful for testing or emergency cleanup.
     */
    clearAll(): void;
}