@iworkforces/tracelattice 2.0.3

package/dist/transport/StreamableHttpTransport.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Streamable HTTP Transport implementation (MCP spec recommended transport).
+ *
+ * This transport implements the MCP Streamable HTTP specification, which replaces
+ * the deprecated SSE transport as the recommended HTTP-based transport since March 2025.
+ *
+ * Key features:
+ * - POST /mcp for JSON-RPC requests (main MCP endpoint)
+ * - GET /mcp for optional SSE server-to-client notifications
+ * - Session management via Mcp-Session-Id header
+ * - Supports both stateful (session-based) and stateless (per-request) modes
+ * - Health endpoints (/health, /ready)
+ *
+ * @example
+ * ```typescript
+ * const transport = new StreamableHttpTransport({
+ *   port: 3000,
+ *   host: 'localhost',
+ *   stateful: true,
+ * });
+ * await transport.connect(server);
+ * ```
+ */
+import type { McpServer } from 'tmcp';
+import type { IMetrics } from '../contracts/interfaces.js';
+import { BaseTransport, type TransportOptions } from './BaseTransport.js';
+import type { ITransport, TransportKind } from '../contracts/transport.js';
+/**
+ * MCP Streamable HTTP transport options extending base TransportOptions.
+ */
+export interface StreamableHttpTransportOptions extends TransportOptions {
+    /**
+     * Path for the MCP endpoint
+     * @default '/mcp'
+     */
+    path?: string;
+    /**
+     * Metrics collector for transport telemetry
+     */
+    metrics?: IMetrics;
+    /**
+     * Prometheus metrics provider function
+     */
+    metricsProvider?: () => string;
+    /**
+     * Enable stateful session-based mode.
+     * When true, sessions are tracked via Mcp-Session-Id header.
+     * When false, each request is processed independently (stateless).
+     * @default true
+     */
+    stateful?: boolean;
+    /**
+     * Custom session ID generator function.
+     * @default () => randomUUID()
+     */
+    sessionIdGenerator?: () => string;
+    /**
+     * Enable request body size limit
+     * @default true
+     */
+    enableBodySizeLimit?: boolean;
+    /**
+     * Maximum request body size in bytes
+     * @default 10485760 (10MB)
+     */
+    maxBodySize?: number;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    requestTimeout?: number;
+}
+/**
+ * Streamable HTTP Transport for MCP server.
+ *
+ * This transport implements the MCP Streamable HTTP specification,
+ * providing JSON-RPC over HTTP with optional session management
+ * and server-to-client SSE notification streams.
+ *
+ * @remarks
+ * **Security Features (inherited from BaseTransport):**
+ * - Session ID validation (alphanumeric, max 64 chars)
+ * - Query parameter sanitization (whitelist allowed keys)
+ * - Rate limiting per IP (configurable, default 100 req/min)
+ * - CORS origin validation
+ * - Host header validation
+ *
+ * **MCP Streamable HTTP Spec Compliance:**
+ * - POST /mcp — JSON-RPC method calls
+ * - GET /mcp — SSE notification stream (server-to-client)
+ * - Mcp-Session-Id header for session management
+ * - Content-Type: application/json for JSON-RPC responses
+ * - Content-Type: text/event-stream for SSE notification streams
+ *
+ * **HTTP Status Code Mapping:**
+ * - 200: Success (JSON-RPC response or SSE stream)
+ * - 202: Accepted (JSON-RPC notification, no response body)
+ * - 204: CORS Preflight (empty body)
+ * - 400: Bad Request (invalid JSON, invalid session ID)
+ * - 403: Forbidden (invalid CORS, invalid host)
+ * - 404: Not Found
+ * - 405: Method Not Allowed
+ * - 413: Payload Too Large
+ * - 429: Too Many Requests
+ * - 500: Internal Server Error
+ * - 503: Server Not Ready / Shutting Down
+ */
+export declare class StreamableHttpTransport extends BaseTransport implements ITransport {
+    get kind(): TransportKind;
+    private _server;
+    private _mcpServer;
+    private _path;
+    private _stateful;
+    private _sessionIdGenerator;
+    private _sessions;
+    private _requestCount;
+    private _activeRequests;
+    private _bodySizeLimitEnabled;
+    private _maxBodySize;
+    private _requestTimeout;
+    private _metrics?;
+    private _metricsProvider;
+    private readonly _lifecycleFailureReporter;
+    private readonly _acceptedWork;
+    private _stopPromise;
+    constructor(options?: StreamableHttpTransportOptions);
+    private _requireMcpServer;
+    /**
+     * Get number of active sessions (stateful) or active requests (stateless).
+     */
+    get clientCount(): number;
+    /**
+     * Get the total number of requests handled.
+     */
+    get requestCount(): number;
+    /**
+     * Connects MCP server to this transport and starts listening.
+     */
+    connect(mcpServer: McpServer): Promise<void>;
+    /**
+     * Route and handle incoming HTTP requests.
+     */
+    private _handleRequest;
+    /**
+     * Send a JSON-RPC error response.
+     */
+    private _sendJsonRpcError;
+    /**
+     * Handle POST /mcp — JSON-RPC method calls.
+     *
+     * Per the MCP Streamable HTTP spec:
+     * - Accepts JSON-RPC request bodies
+     * - Returns Mcp-Session-Id header for new sessions (stateful mode)
+     * - Validates Mcp-Session-Id for existing sessions (stateful mode)
+     * - Content-Type: application/json for responses
+     */
+    private _handleMcpPost;
+    private _receiveAndFinalize;
+    /**
+     * Handle GET /mcp — Optional SSE notification stream.
+     *
+     * Per the MCP Streamable HTTP spec, clients may open a GET request
+     * to receive server-initiated notifications as SSE events.
+     * Requires a valid Mcp-Session-Id in stateful mode.
+     */
+    private _handleMcpGet;
+    /**
+     * Resolve or create a session for a stateful request.
+     *
+     * @returns Session ID string on success, or the response error to finalize.
+     */
+    private _resolveSession;
+    /**
+     * Extract Mcp-Session-Id from request headers.
+     */
+    private _getSessionIdFromHeader;
+    /**
+     * Send an SSE event to a specific client response stream.
+     */
+    private _sendSseEvent;
+    /**
+     * Broadcast a notification to all SSE streams in a given session.
+     *
+     * @param sessionId - Target session ID
+     * @param event - SSE event name
+     * @param data - Event payload
+     */
+    broadcastToSession(sessionId: string, event: string, data: unknown): void;
+    /**
+     * Handle GET /metrics endpoint.
+     */
+    private _handleMetrics;
+    /**
+     * Handle GET /health — Liveness check.
+     */
+    private _handleHealthCheck;
+    /**
+     * Handle GET /ready — Readiness check.
+     */
+    private _handleReadinessCheck;
+    /**
+     * Update session-related metrics.
+     */
+    private _updateSessionMetrics;
+    /**
+     * Stop transport server with graceful shutdown.
+     *
+     * @param timeout - Maximum time before force-closing HTTP connections (default: 30s)
+     */
+    stop(timeout?: number): Promise<void>;
+}
+/**
+ * Create a Streamable HTTP transport with given options.
+ *
+ * @param options - Transport configuration
+ * @returns A configured Streamable HTTP transport
+ *
+ * @example
+ * ```typescript
+ * const transport = createStreamableHttpTransport({ port: 3000, stateful: true });
+ * await transport.connect(server);
+ * ```
+ */
+export declare function createStreamableHttpTransport(options?: StreamableHttpTransportOptions): StreamableHttpTransport;
+//# sourceMappingURL=StreamableHttpTransport.d.ts.map

package/dist/transport/StreamableHttpTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamableHttpTransport.d.ts","sourceRoot":"","sources":["../../src/transport/StreamableHttpTransport.ts"],"names":[],"mappings":"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"}

package/dist/transport/StreamableHttpTransport.js

@@ -0,0 +1,449 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { safeParse } from "valibot";
+import { getErrorMessage } from "../errors.js";
+import { JsonRpcRequestSchema } from "../schema.js";
+import { BaseTransport } from "./BaseTransport.js";
+import { asSessionId } from "../contracts/ids.js";
+import { readRequestBody } from "./HttpHelpers.js";
+import { runWithContext } from "../context/RequestContext.js";
+import { AcceptedWorkTracker, LifecycleFailureReporter, ResponseFinalizer } from "./HttpRequestLifecycle.js";
+class StreamableHttpTransport extends BaseTransport {
+    get kind() {
+        return 'streamable-http';
+    }
+    _server = null;
+    _mcpServer = null;
+    _path;
+    _stateful;
+    _sessionIdGenerator;
+    _sessions = new Map();
+    _requestCount = 0;
+    _activeRequests = 0;
+    _bodySizeLimitEnabled;
+    _maxBodySize;
+    _requestTimeout;
+    _metrics;
+    _metricsProvider;
+    _lifecycleFailureReporter;
+    _acceptedWork;
+    _stopPromise = null;
+    constructor(options = {}){
+        super(options);
+        this._path = options.path ?? '/mcp';
+        this._stateful = options.stateful ?? true;
+        this._sessionIdGenerator = options.sessionIdGenerator ?? (()=>randomUUID());
+        this._bodySizeLimitEnabled = options.enableBodySizeLimit ?? true;
+        this._maxBodySize = options.maxBodySize ?? 10485760;
+        this._requestTimeout = options.requestTimeout ?? 30000;
+        this._metrics = options.metrics;
+        this._metricsProvider = options.metricsProvider ?? null;
+        this._lifecycleFailureReporter = new LifecycleFailureReporter((error)=>{
+            this.log('error', 'Streamable HTTP request lifecycle failed', {
+                error: getErrorMessage(error)
+            });
+        });
+        this._acceptedWork = new AcceptedWorkTracker(this._lifecycleFailureReporter);
+    }
+    _requireMcpServer() {
+        if (!this._mcpServer) throw new Error('MCP server not initialized. Did you call connect()?');
+        return this._mcpServer;
+    }
+    get clientCount() {
+        return this._stateful ? this._sessions.size : this._activeRequests;
+    }
+    get requestCount() {
+        return this._requestCount;
+    }
+    async connect(mcpServer) {
+        this._mcpServer = mcpServer;
+        const server = createServer((req, res)=>{
+            const responseFinalizer = new ResponseFinalizer(res, this._lifecycleFailureReporter);
+            this._handleRequest(req, res).catch((error)=>{
+                this._lifecycleFailureReporter.report(error);
+                responseFinalizer.finalize((response)=>{
+                    this._sendJsonRpcError(response, 500, -32603, 'Internal error', null, {
+                        data: getErrorMessage(error)
+                    });
+                });
+            });
+        });
+        this._server = server;
+        return new Promise((resolve, reject)=>{
+            const cleanup = ()=>{
+                server.off('error', onError);
+                server.off('listening', onListening);
+            };
+            const onError = (error)=>{
+                cleanup();
+                reject(error);
+            };
+            const onListening = ()=>{
+                cleanup();
+                this.log('info', `Streamable HTTP transport listening on http://${this._host}:${this._port}`);
+                resolve();
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            try {
+                server.listen(this._port, this._host);
+            } catch (error) {
+                cleanup();
+                reject(error);
+            }
+        });
+    }
+    async _handleRequest(req, res) {
+        const startTime = Date.now();
+        this._metrics?.counter('streamable_http_requests_total', 1, {}, 'Total Streamable HTTP transport requests');
+        res.once('finish', ()=>{
+            const durationSeconds = (Date.now() - startTime) / 1000;
+            this._metrics?.histogram('streamable_http_request_duration_seconds', durationSeconds, {});
+        });
+        if (!this.validateHostHeader(req)) return void this._sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid host header');
+        if (this.isShuttingDown) return void this._sendJsonRpcError(res, 503, -32603, 'Server is shutting down');
+        const clientIp = this.getClientIp(req);
+        if (this.checkRateLimit(clientIp)) {
+            res.setHeader('Retry-After', '60');
+            this._sendJsonRpcError(res, 429, -32000, 'Too many requests');
+            return;
+        }
+        if (!this.validateCorsOrigin(req)) return void this._sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid origin');
+        this.setCorsHeaders(res);
+        if ('OPTIONS' === req.method) {
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const urlPath = req.url?.split('?')[0] ?? '/';
+        if ('GET' === req.method && '/metrics' === urlPath) return void this._handleMetrics(res);
+        if ('GET' === req.method && '/health' === urlPath) return void this._handleHealthCheck(res);
+        if ('GET' === req.method && '/ready' === urlPath) return void await this._handleReadinessCheck(res);
+        if (urlPath === this._path) {
+            if ('POST' === req.method) return void this._acceptedWork.track(this._handleMcpPost(req, res));
+            if ('GET' === req.method) return void this._handleMcpGet(req, res);
+            res.writeHead(405, {
+                'Content-Type': 'application/json',
+                Allow: 'GET, POST'
+            });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32601,
+                    message: 'Method not allowed'
+                }
+            }));
+            return;
+        }
+        this._sendJsonRpcError(res, 404, -32601, 'Not Found');
+    }
+    _sendJsonRpcError(res, statusCode, code, message, id = null, extra) {
+        const error = {
+            code,
+            message
+        };
+        if (extra) Object.assign(error, extra);
+        res.writeHead(statusCode, {
+            'Content-Type': 'application/json'
+        });
+        res.end(JSON.stringify({
+            jsonrpc: '2.0',
+            id,
+            error
+        }));
+    }
+    async _handleMcpPost(req, res) {
+        this._requestCount++;
+        this._activeRequests++;
+        const responseFinalizer = new ResponseFinalizer(res, this._lifecycleFailureReporter);
+        const timeout = setTimeout(()=>{
+            responseFinalizer.finalize((response)=>{
+                this._sendJsonRpcError(response, 500, -32603, 'Request timeout');
+            });
+        }, this._requestTimeout);
+        try {
+            const body = await readRequestBody(req, this._bodySizeLimitEnabled ? this._maxBodySize : 0);
+            if (null === body) return void responseFinalizer.finalize((response)=>{
+                this._sendJsonRpcError(response, 413, -32000, 'Request body too large');
+            });
+            let rawBody;
+            try {
+                rawBody = JSON.parse(body);
+            } catch  {
+                responseFinalizer.finalize((response)=>{
+                    this._sendJsonRpcError(response, 200, -32700, 'Parse error');
+                });
+                return;
+            }
+            const parseResult = safeParse(JsonRpcRequestSchema, rawBody);
+            const rawId = rawBody && 'object' == typeof rawBody && 'id' in rawBody ? rawBody.id ?? null : null;
+            if (!parseResult.success) return void responseFinalizer.finalize((response)=>{
+                this._sendJsonRpcError(response, 200, -32600, 'Invalid Request', rawId, {
+                    data: parseResult.issues
+                });
+            });
+            const jsonRpcRequest = parseResult.output;
+            let sessionId;
+            if (this._stateful) {
+                const sessionResult = this._resolveSession(req);
+                if ('string' != typeof sessionResult) return void responseFinalizer.finalize((response)=>{
+                    this._sendJsonRpcError(response, sessionResult.statusCode, sessionResult.code, sessionResult.message);
+                });
+                sessionId = sessionResult;
+            }
+            if (!this._mcpServer) return void responseFinalizer.finalize((response)=>{
+                this._sendJsonRpcError(response, 503, -32603, 'Server not ready', jsonRpcRequest?.id ?? null);
+            });
+            await this._receiveAndFinalize(jsonRpcRequest, sessionId, responseFinalizer);
+        } catch (error) {
+            responseFinalizer.finalize((response)=>{
+                this._sendJsonRpcError(response, 200, -32603, 'Internal error', null, {
+                    data: getErrorMessage(error)
+                });
+            });
+        } finally{
+            clearTimeout(timeout);
+            this._activeRequests--;
+        }
+    }
+    async _receiveAndFinalize(jsonRpcRequest, sessionId, responseFinalizer) {
+        const owner = this._stateful ? sessionId ?? randomUUID() : randomUUID();
+        const response = await runWithContext({
+            requestId: randomUUID(),
+            owner
+        }, ()=>this._requireMcpServer().receive(jsonRpcRequest, {
+                sessionInfo: {}
+            }));
+        const responseHeaders = {
+            'Content-Type': 'application/json'
+        };
+        if (sessionId) responseHeaders['Mcp-Session-Id'] = sessionId;
+        responseFinalizer.finalize((httpResponse)=>{
+            if (response) {
+                httpResponse.writeHead(200, responseHeaders);
+                httpResponse.end(JSON.stringify(response));
+                return;
+            }
+            if (sessionId) httpResponse.setHeader('Mcp-Session-Id', sessionId);
+            httpResponse.writeHead(202);
+            httpResponse.end();
+        });
+    }
+    _handleMcpGet(req, res) {
+        if (!this._stateful) {
+            res.writeHead(405, {
+                'Content-Type': 'application/json',
+                Allow: 'POST'
+            });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32601,
+                    message: 'GET not supported in stateless mode'
+                }
+            }));
+            return;
+        }
+        const sessionId = this._getSessionIdFromHeader(req);
+        if (!sessionId) {
+            res.writeHead(400, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32600,
+                    message: 'Missing Mcp-Session-Id header'
+                }
+            }));
+            return;
+        }
+        const session = this._sessions.get(asSessionId(sessionId));
+        if (!session) {
+            res.writeHead(404, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32001,
+                    message: 'Session not found'
+                }
+            }));
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'Mcp-Session-Id': sessionId
+        });
+        this._sendSseEvent(res, 'connected', {
+            sessionId,
+            timestamp: Date.now()
+        });
+        session.notificationStreams.add(res);
+        session.lastActivityAt = Date.now();
+        this._updateSessionMetrics();
+        req.on('close', ()=>{
+            session.notificationStreams.delete(res);
+            this._updateSessionMetrics();
+        });
+    }
+    _resolveSession(req) {
+        const headerSessionId = this._getSessionIdFromHeader(req);
+        if (headerSessionId) {
+            if (!this.validateSessionId(headerSessionId)) return {
+                statusCode: 400,
+                code: -32600,
+                message: 'Invalid Mcp-Session-Id format'
+            };
+            const session = this._sessions.get(asSessionId(headerSessionId));
+            if (session) {
+                session.lastActivityAt = Date.now();
+                return headerSessionId;
+            }
+            return {
+                statusCode: 404,
+                code: -32001,
+                message: 'Session not found'
+            };
+        }
+        const newSessionId = this._sessionIdGenerator();
+        const sessionState = {
+            id: newSessionId,
+            createdAt: Date.now(),
+            lastActivityAt: Date.now(),
+            notificationStreams: new Set()
+        };
+        this._sessions.set(asSessionId(newSessionId), sessionState);
+        this.log('info', `New session created: ${newSessionId}`);
+        this._updateSessionMetrics();
+        return newSessionId;
+    }
+    _getSessionIdFromHeader(req) {
+        const value = req.headers['mcp-session-id'];
+        if ('string' == typeof value && value.length > 0) return value;
+    }
+    _sendSseEvent(res, event, data) {
+        try {
+            res.write(`event: ${event}\n`);
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        } catch  {}
+    }
+    broadcastToSession(sessionId, event, data) {
+        const session = this._sessions.get(asSessionId(sessionId));
+        if (!session) return;
+        for (const stream of session.notificationStreams)this._sendSseEvent(stream, event, data);
+    }
+    _handleMetrics(res) {
+        if (!this._metricsProvider) {
+            res.writeHead(404, {
+                'Content-Type': 'text/plain'
+            });
+            res.end('Not Found');
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/plain; version=0.0.4; charset=utf-8'
+        });
+        res.end(this._metricsProvider());
+    }
+    _handleHealthCheck(res) {
+        const healthData = {
+            status: 'healthy',
+            requests: this._requestCount,
+            sessions: this._sessions.size,
+            transport: 'streamable-http'
+        };
+        if (this._healthChecker) {
+            const liveness = this._healthChecker.checkLiveness();
+            healthData.liveness = liveness;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'application/json'
+        });
+        res.end(JSON.stringify(healthData));
+    }
+    async _handleReadinessCheck(res) {
+        if (this._healthChecker) {
+            const readiness = await this._healthChecker.checkReadiness();
+            const statusCode = 'ok' === readiness.status ? 200 : 503;
+            res.writeHead(statusCode, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify(readiness));
+        } else {
+            res.writeHead(200, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                status: 'ok',
+                timestamp: new Date().toISOString(),
+                components: {}
+            }));
+        }
+    }
+    _updateSessionMetrics() {
+        this._metrics?.gauge('streamable_http_active_sessions', this._sessions.size, {}, 'Active Streamable HTTP sessions');
+        let totalStreams = 0;
+        for (const session of this._sessions.values())totalStreams += session.notificationStreams.size;
+        this._metrics?.gauge('streamable_http_notification_streams', totalStreams, {}, 'Active SSE notification streams');
+    }
+    stop(timeout) {
+        if (this._stopPromise) return this._stopPromise;
+        this._isShuttingDown = true;
+        this._stopRateLimitCleanup();
+        const shutdownTimeout = timeout ?? 30000;
+        for (const session of this._sessions.values()){
+            for (const stream of session.notificationStreams)try {
+                stream.end();
+            } catch  {}
+            session.notificationStreams.clear();
+        }
+        this._sessions.clear();
+        const server = this._server;
+        const serverClosed = new Promise((resolve, reject)=>{
+            if (!server?.listening) return void resolve();
+            let settled = false;
+            let forceClose = null;
+            server.close((error)=>{
+                if (settled) return;
+                settled = true;
+                if (forceClose) clearTimeout(forceClose);
+                if (error) return void reject(error);
+                resolve();
+            });
+            if (settled) return;
+            forceClose = setTimeout(()=>{
+                if (settled) return;
+                settled = true;
+                this.log('warn', 'Streamable HTTP transport force-closing after timeout');
+                server.closeAllConnections();
+                resolve();
+            }, shutdownTimeout);
+        });
+        const stopPromise = Promise.all([
+            serverClosed,
+            this._acceptedWork.join()
+        ]).then(()=>{
+            this.log('info', 'Streamable HTTP transport stopped');
+        });
+        this._stopPromise = stopPromise;
+        stopPromise.catch(()=>{
+            if (this._stopPromise === stopPromise) this._stopPromise = null;
+        });
+        return stopPromise;
+    }
+}
+function createStreamableHttpTransport(options = {}) {
+    return new StreamableHttpTransport(options);
+}
+export { StreamableHttpTransport, createStreamableHttpTransport };
+
+//# sourceMappingURL=StreamableHttpTransport.js.map