@frontmcp/sdk 0.5.1 → 0.6.1

package/src/transport/transport.registry.d.ts

@@ -1,6 +1,7 @@
 import { Transporter, TransportType } from './transport.types';
-import { ServerResponse } from '../common';
+import { ServerResponse, TransportPersistenceConfigInput } from '../common';
 import { Scope } from '../scope';
+import { StoredSession } from '../auth/session';
 export declare class TransportService {
     readonly ready: Promise<void>;
     private readonly byType;
@@ -12,15 +13,64 @@ export declare class TransportService {
      * Used to differentiate between "session never initialized" (HTTP 400) and
      * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
      *
-     * Key: "type:tokenHash:sessionId", Value: creation timestamp
+     * Key: JSON-encoded {type, tokenHash, sessionId}, Value: creation timestamp
+     * Note: We use JSON instead of colon-delimiter because sessionId can contain colons.
      */
     private readonly sessionHistory;
     private readonly MAX_SESSION_HISTORY;
-    constructor(scope: Scope);
+    /**
+     * Session store for transport persistence (Redis or Vercel KV)
+     * Used to persist session metadata across server restarts
+     */
+    private sessionStore?;
+    /**
+     * Transport persistence configuration
+     */
+    private persistenceConfig?;
+    /**
+     * Pending store configuration for async initialization
+     */
+    private pendingStoreConfig?;
+    /**
+     * Mutex map for preventing concurrent transport creation for the same key.
+     * Key: JSON-encoded {t: type, h: tokenHash, s: sessionId}, Value: Promise that resolves when creation completes
+     */
+    private readonly creationMutex;
+    constructor(scope: Scope, persistenceConfig?: TransportPersistenceConfigInput);
     private initialize;
     destroy(): Promise<void>;
     getTransporter(type: TransportType, token: string, sessionId: string): Promise<Transporter | undefined>;
+    /**
+     * Get stored session from Redis (without creating a transport).
+     * Used by flows to check if session exists and can be recreated.
+     *
+     * @param type - Transport type
+     * @param token - Authorization token
+     * @param sessionId - Session ID
+     * @returns Stored session data if exists and token matches, undefined otherwise
+     */
+    getStoredSession(type: TransportType, token: string, sessionId: string): Promise<StoredSession | undefined>;
+    /**
+     * Recreate a transport from stored session data.
+     * Must be called with a valid response object to create the actual transport.
+     *
+     * @param type - Transport type
+     * @param token - Authorization token
+     * @param sessionId - Session ID
+     * @param storedSession - Previously stored session data
+     * @param res - Server response object for the new transport
+     * @returns The recreated transport
+     */
+    recreateTransporter(type: TransportType, token: string, sessionId: string, storedSession: StoredSession, res: ServerResponse): Promise<Transporter>;
+    /**
+     * Internal method to actually recreate the transport (called with mutex protection)
+     */
+    private doRecreateTransporter;
     createTransporter(type: TransportType, token: string, sessionId: string, res: ServerResponse): Promise<Transporter>;
+    /**
+     * Internal method to actually create the transport (called with mutex protection)
+     */
+    private doCreateTransporter;
     destroyTransporter(type: TransportType, token: string, sessionId: string, reason?: string): Promise<void>;
     /**
      * Get or create a shared singleton transport for anonymous stateless requests.
@@ -37,13 +87,31 @@ export declare class TransportService {
      * Used to differentiate between "session never initialized" (HTTP 400) and
      * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
      *
+     * Note: This is synchronous and only checks local history. For async Redis check,
+     * use wasSessionCreatedAsync.
+     *
      * @param type - Transport type (e.g., 'streamable-http', 'sse')
      * @param token - The authorization token
      * @param sessionId - The session ID to check
-     * @returns true if session was ever created, false otherwise
+     * @returns true if session was ever created locally, false otherwise
      */
     wasSessionCreated(type: TransportType, token: string, sessionId: string): boolean;
+    /**
+     * Async version that also checks Redis for session existence.
+     * Used when we need to check if session was ever created across server restarts.
+     */
+    wasSessionCreatedAsync(type: TransportType, token: string, sessionId: string): Promise<boolean>;
     private sha256;
+    /**
+     * Create a history key from components.
+     * Uses JSON encoding to handle sessionIds that contain special characters.
+     */
+    private makeHistoryKey;
+    /**
+     * Parse a history key back into components.
+     * Returns undefined if the key is malformed.
+     */
+    private parseHistoryKey;
     private keyOf;
     private ensureTypeBucket;
     private ensureTokenBucket;

package/src/transport/transport.registry.js

@@ -9,6 +9,8 @@ const transport_local_1 = require("./transport.local");
 const handle_streamable_http_flow_1 = tslib_1.__importDefault(require("./flows/handle.streamable-http.flow"));
 const handle_sse_flow_1 = tslib_1.__importDefault(require("./flows/handle.sse.flow"));
 const handle_stateless_http_flow_1 = tslib_1.__importDefault(require("./flows/handle.stateless-http.flow"));
+const store_1 = require("../store");
+const authorization_class_1 = require("../auth/authorization/authorization.class");
 class TransportService {
     ready;
     byType = new Map();
@@ -20,52 +22,309 @@ class TransportService {
      * Used to differentiate between "session never initialized" (HTTP 400) and
      * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
      *
-     * Key: "type:tokenHash:sessionId", Value: creation timestamp
+     * Key: JSON-encoded {type, tokenHash, sessionId}, Value: creation timestamp
+     * Note: We use JSON instead of colon-delimiter because sessionId can contain colons.
      */
     sessionHistory = new Map();
     MAX_SESSION_HISTORY = 10000;
-    constructor(scope) {
+    /**
+     * Session store for transport persistence (Redis or Vercel KV)
+     * Used to persist session metadata across server restarts
+     */
+    sessionStore;
+    /**
+     * Transport persistence configuration
+     */
+    persistenceConfig;
+    /**
+     * Pending store configuration for async initialization
+     */
+    pendingStoreConfig;
+    /**
+     * Mutex map for preventing concurrent transport creation for the same key.
+     * Key: JSON-encoded {t: type, h: tokenHash, s: sessionId}, Value: Promise that resolves when creation completes
+     */
+    creationMutex = new Map();
+    constructor(scope, persistenceConfig) {
         this.scope = scope;
+        this.persistenceConfig = persistenceConfig;
         this.distributed = false; // get from scope metadata
         this.bus = undefined; // get from scope metadata
         if (this.distributed && !this.bus) {
             throw new Error('TransportRegistry: distributed=true requires a TransportBus implementation.');
         }
+        // Initialize session store if persistence is enabled (Redis or Vercel KV)
+        if (persistenceConfig?.enabled && persistenceConfig.redis) {
+            // Use factory to create appropriate session store based on provider
+            const redisConfig = persistenceConfig.redis;
+            const providerType = 'provider' in redisConfig ? redisConfig.provider : 'redis';
+            // Override keyPrefix for transport persistence (separate from auth sessions)
+            // Cast to RedisOptions since we're modifying the config
+            this.pendingStoreConfig = {
+                ...redisConfig,
+                keyPrefix: redisConfig.keyPrefix ?? 'mcp:transport:',
+                defaultTtlMs: persistenceConfig.defaultTtlMs ?? 3600000, // 1 hour default
+            };
+            this.scope.logger.info(`[TransportService] ${providerType} session store will be initialized for transport persistence`);
+        }
         this.ready = this.initialize();
     }
     async initialize() {
+        // Create session store if configuration is pending
+        if (this.pendingStoreConfig) {
+            try {
+                const store = await (0, store_1.createSessionStore)(this.pendingStoreConfig, this.scope.logger.child('SessionStore'));
+                // Cast to our extended type (both RedisSessionStore and VercelKvSessionStore have ping/disconnect)
+                this.sessionStore = store;
+                this.pendingStoreConfig = undefined;
+            }
+            catch (error) {
+                this.scope.logger.error('[TransportService] Failed to create session store - session persistence disabled', {
+                    error: error.message,
+                });
+            }
+        }
+        // Validate connection if session store is configured
+        if (this.sessionStore) {
+            const isConnected = this.sessionStore.ping ? await this.sessionStore.ping() : true;
+            if (!isConnected) {
+                const providerType = this.persistenceConfig?.redis && 'provider' in this.persistenceConfig.redis
+                    ? this.persistenceConfig.redis.provider
+                    : 'redis';
+                this.scope.logger.error(`[TransportService] Failed to connect to ${providerType} - session persistence disabled`);
+                // Nullify sessionStore to prevent silent failures on all subsequent operations
+                // This ensures clean graceful degradation - sessions will only persist in memory
+                if (this.sessionStore.disconnect) {
+                    await this.sessionStore.disconnect().catch(() => void 0);
+                }
+                this.sessionStore = undefined;
+            }
+            else {
+                this.scope.logger.info('[TransportService] Session store connection validated successfully');
+            }
+        }
         await this.scope.registryFlows(handle_streamable_http_flow_1.default, handle_sse_flow_1.default, handle_stateless_http_flow_1.default);
     }
     async destroy() {
-        /* empty */
+        // Close session store connection if it was created
+        if (this.sessionStore && this.sessionStore.disconnect) {
+            try {
+                await this.sessionStore.disconnect();
+                this.scope.logger.info('[TransportService] Session store disconnected');
+            }
+            catch (error) {
+                this.scope.logger.warn('[TransportService] Error disconnecting session store', {
+                    error: error.message,
+                });
+            }
+        }
     }
     async getTransporter(type, token, sessionId) {
         const key = this.keyOf(type, token, sessionId);
+        // 1. Check local in-memory cache first
         const local = this.lookupLocal(key);
         if (local)
             return local;
+        // 2. Check distributed bus (if enabled)
         if (this.distributed && this.bus) {
             const location = await this.bus.lookup(key);
             if (location) {
                 return new transport_remote_1.RemoteTransporter(key, this.bus);
             }
         }
+        // Note: Redis-stored sessions require recreation via recreateTransporter()
+        // Flows should use getStoredSession() to check if session exists in Redis,
+        // then call recreateTransporter() with the response object.
         return undefined;
     }
+    /**
+     * Get stored session from Redis (without creating a transport).
+     * Used by flows to check if session exists and can be recreated.
+     *
+     * @param type - Transport type
+     * @param token - Authorization token
+     * @param sessionId - Session ID
+     * @returns Stored session data if exists and token matches, undefined otherwise
+     */
+    async getStoredSession(type, token, sessionId) {
+        if (!this.sessionStore || type !== 'streamable-http')
+            return undefined;
+        const tokenHash = this.sha256(token);
+        const stored = await this.sessionStore.get(sessionId);
+        if (!stored)
+            return undefined;
+        // Verify the token hash matches
+        if (stored.authorizationId !== tokenHash) {
+            this.scope.logger.warn('[TransportService] Session token mismatch during lookup', {
+                sessionId: sessionId.slice(0, 20),
+                storedTokenHash: stored.authorizationId.slice(0, 8),
+                requestTokenHash: tokenHash.slice(0, 8),
+            });
+            return undefined;
+        }
+        return stored;
+    }
+    /**
+     * Recreate a transport from stored session data.
+     * Must be called with a valid response object to create the actual transport.
+     *
+     * @param type - Transport type
+     * @param token - Authorization token
+     * @param sessionId - Session ID
+     * @param storedSession - Previously stored session data
+     * @param res - Server response object for the new transport
+     * @returns The recreated transport
+     */
+    async recreateTransporter(type, token, sessionId, storedSession, res) {
+        const key = this.keyOf(type, token, sessionId);
+        // Check if already recreated in memory
+        const existing = this.lookupLocal(key);
+        if (existing)
+            return existing;
+        // Use mutex to prevent concurrent recreation of the same transport
+        // Use JSON encoding for mutex key (consistent with history key format, handles colons in sessionId)
+        const mutexKey = JSON.stringify({ t: type, h: key.tokenHash, s: sessionId });
+        const pendingCreation = this.creationMutex.get(mutexKey);
+        if (pendingCreation) {
+            // Another request is already recreating this transport - wait for it
+            return pendingCreation;
+        }
+        // Recreate the transport with mutex protection
+        const recreationPromise = this.doRecreateTransporter(key, sessionId, storedSession, res);
+        this.creationMutex.set(mutexKey, recreationPromise);
+        try {
+            return await recreationPromise;
+        }
+        catch (error) {
+            // Log recreation errors for debugging
+            this.scope.logger.error('[TransportService] Failed to recreate transport from stored session', {
+                sessionId: sessionId.slice(0, 20),
+                error: error instanceof Error ? { name: error.name, message: error.message } : String(error),
+            });
+            throw error;
+        }
+        finally {
+            this.creationMutex.delete(mutexKey);
+        }
+    }
+    /**
+     * Internal method to actually recreate the transport (called with mutex protection)
+     */
+    async doRecreateTransporter(key, sessionId, storedSession, res) {
+        // Double-check in case another request completed while we were waiting
+        const existing = this.lookupLocal(key);
+        if (existing)
+            return existing;
+        this.scope.logger.info('[TransportService] Recreating transport from stored session', {
+            sessionId: sessionId.slice(0, 20),
+            protocol: storedSession.session.protocol,
+            createdAt: storedSession.createdAt,
+        });
+        // Mark session as recreated in history
+        const historyKey = this.makeHistoryKey(key.type, key.tokenHash, sessionId);
+        this.sessionHistory.set(historyKey, storedSession.createdAt);
+        const sessionStore = this.sessionStore;
+        const persistenceConfig = this.persistenceConfig;
+        // Create new transport
+        const transporter = new transport_local_1.LocalTransporter(this.scope, key, res, () => {
+            key.sessionId = sessionId;
+            this.evictLocal(key);
+            if (this.distributed && this.bus) {
+                this.bus.revoke(key).catch(() => void 0);
+            }
+            // Remove from Redis on dispose
+            if (sessionStore) {
+                sessionStore.delete(sessionId).catch(() => void 0);
+            }
+        });
+        await transporter.ready();
+        this.insertLocal(key, transporter);
+        // Update session access time in Redis
+        if (sessionStore) {
+            const updatedSession = {
+                ...storedSession,
+                lastAccessedAt: Date.now(),
+            };
+            sessionStore.set(sessionId, updatedSession, persistenceConfig?.defaultTtlMs).catch((err) => {
+                this.scope.logger.warn('[TransportService] Failed to update session in Redis', {
+                    sessionId: sessionId.slice(0, 20),
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+        if (this.distributed && this.bus) {
+            await this.bus.advertise(key);
+        }
+        return transporter;
+    }
     async createTransporter(type, token, sessionId, res) {
         const key = this.keyOf(type, token, sessionId);
+        // Check if already exists
         const existing = this.lookupLocal(key);
         if (existing)
             return existing;
+        // Use mutex to prevent concurrent creation of the same transport
+        // Use JSON encoding for mutex key (consistent with history key format, handles colons in sessionId)
+        const mutexKey = JSON.stringify({ t: type, h: key.tokenHash, s: sessionId });
+        const pendingCreation = this.creationMutex.get(mutexKey);
+        if (pendingCreation) {
+            // Another request is already creating this transport - wait for it
+            return pendingCreation;
+        }
+        // Create the transport with mutex protection
+        const creationPromise = this.doCreateTransporter(key, sessionId, res, type);
+        this.creationMutex.set(mutexKey, creationPromise);
+        try {
+            return await creationPromise;
+        }
+        finally {
+            this.creationMutex.delete(mutexKey);
+        }
+    }
+    /**
+     * Internal method to actually create the transport (called with mutex protection)
+     */
+    async doCreateTransporter(key, sessionId, res, type) {
+        // Double-check in case another request completed while we were waiting
+        const existing = this.lookupLocal(key);
+        if (existing)
+            return existing;
+        const sessionStore = this.sessionStore;
+        const persistenceConfig = this.persistenceConfig;
         const transporter = new transport_local_1.LocalTransporter(this.scope, key, res, () => {
             key.sessionId = sessionId;
             this.evictLocal(key);
             if (this.distributed && this.bus) {
                 this.bus.revoke(key).catch(() => void 0);
             }
+            // Remove from Redis on dispose
+            if (sessionStore) {
+                sessionStore.delete(sessionId).catch(() => void 0);
+            }
         });
         await transporter.ready();
         this.insertLocal(key, transporter);
+        // Persist session to Redis (streamable-http only for now)
+        if (sessionStore && type === 'streamable-http') {
+            const storedSession = {
+                session: {
+                    id: sessionId,
+                    authorizationId: key.tokenHash,
+                    protocol: 'streamable-http',
+                    createdAt: Date.now(),
+                    nodeId: (0, authorization_class_1.getMachineId)(),
+                },
+                authorizationId: key.tokenHash,
+                createdAt: Date.now(),
+                lastAccessedAt: Date.now(),
+            };
+            sessionStore.set(sessionId, storedSession, persistenceConfig?.defaultTtlMs).catch((err) => {
+                this.scope.logger.warn('[TransportService] Failed to persist session to Redis', {
+                    sessionId: sessionId.slice(0, 20),
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
         if (this.distributed && this.bus) {
             await this.bus.advertise(key);
         }
@@ -138,20 +397,63 @@ class TransportService {
      * Used to differentiate between "session never initialized" (HTTP 400) and
      * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
      *
+     * Note: This is synchronous and only checks local history. For async Redis check,
+     * use wasSessionCreatedAsync.
+     *
      * @param type - Transport type (e.g., 'streamable-http', 'sse')
      * @param token - The authorization token
      * @param sessionId - The session ID to check
-     * @returns true if session was ever created, false otherwise
+     * @returns true if session was ever created locally, false otherwise
      */
     wasSessionCreated(type, token, sessionId) {
         const tokenHash = this.sha256(token);
-        const historyKey = `${type}:${tokenHash}:${sessionId}`;
+        const historyKey = this.makeHistoryKey(type, tokenHash, sessionId);
         return this.sessionHistory.has(historyKey);
     }
+    /**
+     * Async version that also checks Redis for session existence.
+     * Used when we need to check if session was ever created across server restarts.
+     */
+    async wasSessionCreatedAsync(type, token, sessionId) {
+        // Check local history first (fast path)
+        if (this.wasSessionCreated(type, token, sessionId)) {
+            return true;
+        }
+        // Check Redis if available - use getStoredSession() to verify token hash
+        // (sessionStore.exists() would leak session existence to unauthorized callers)
+        if (this.sessionStore && type === 'streamable-http') {
+            const stored = await this.getStoredSession(type, token, sessionId);
+            return stored !== undefined;
+        }
+        return false;
+    }
     /* --------------------------------- internals -------------------------------- */
     sha256(value) {
         return (0, crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
     }
+    /**
+     * Create a history key from components.
+     * Uses JSON encoding to handle sessionIds that contain special characters.
+     */
+    makeHistoryKey(type, tokenHash, sessionId) {
+        return JSON.stringify({ t: type, h: tokenHash, s: sessionId });
+    }
+    /**
+     * Parse a history key back into components.
+     * Returns undefined if the key is malformed.
+     */
+    parseHistoryKey(key) {
+        try {
+            const parsed = JSON.parse(key);
+            if (typeof parsed.t === 'string' && typeof parsed.h === 'string' && typeof parsed.s === 'string') {
+                return { type: parsed.t, tokenHash: parsed.h, sessionId: parsed.s };
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     keyOf(type, token, sessionId, sessionIdSse) {
         return {
             type,
@@ -191,15 +493,44 @@ class TransportService {
         const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);
         tokenBucket.set(key.sessionId, t);
         // Record session creation in history for HTTP 404 detection
-        const historyKey = `${key.type}:${key.tokenHash}:${key.sessionId}`;
+        const historyKey = this.makeHistoryKey(key.type, key.tokenHash, key.sessionId);
         this.sessionHistory.set(historyKey, Date.now());
-        // Evict oldest entries if cache exceeds max size (LRU-like eviction)
+        // Evict oldest entries if cache exceeds max size
+        // Only evict entries that don't have active transports (to avoid inconsistent state)
         if (this.sessionHistory.size > this.MAX_SESSION_HISTORY) {
             const entries = [...this.sessionHistory.entries()].sort((a, b) => a[1] - b[1]);
-            // Remove oldest 10% of entries
-            const toEvict = Math.ceil(this.MAX_SESSION_HISTORY * 0.1);
-            for (let i = 0; i < toEvict && i < entries.length; i++) {
-                this.sessionHistory.delete(entries[i][0]);
+            // Try to remove oldest 10% of entries (skip those with active transports)
+            const targetEvictions = Math.ceil(this.MAX_SESSION_HISTORY * 0.1);
+            let evicted = 0;
+            for (const [histKey] of entries) {
+                if (evicted >= targetEvictions)
+                    break;
+                // Parse history key to check if transport still exists
+                const parsed = this.parseHistoryKey(histKey);
+                if (!parsed) {
+                    // Invalid key format - safe to evict
+                    this.sessionHistory.delete(histKey);
+                    evicted++;
+                    continue;
+                }
+                const { type, tokenHash, sessionId } = parsed;
+                const typeBucket = this.byType.get(type);
+                const tokenBucket = typeBucket?.get(tokenHash);
+                const hasActiveTransport = tokenBucket?.has(sessionId) ?? false;
+                // Only evict if there's no active transport for this session
+                if (!hasActiveTransport) {
+                    this.sessionHistory.delete(histKey);
+                    evicted++;
+                }
+            }
+            // Log warning if we couldn't evict enough entries (all have active transports)
+            if (evicted < targetEvictions) {
+                this.scope.logger.warn('[TransportService] Session history eviction: unable to free target memory', {
+                    targetEvictions,
+                    actualEvictions: evicted,
+                    currentSize: this.sessionHistory.size,
+                    maxSize: this.MAX_SESSION_HISTORY,
+                });
             }
         }
     }