tracelattice 1.2.5

package/dist/transport/HttpTransport.js

@@ -0,0 +1,175 @@
+import { createServer } from "node:http";
+import { safeParse } from "valibot";
+import { JsonRpcRequestSchema } from "../schema.js";
+import { BaseTransport } from "./BaseTransport.js";
+import { readRequestBody, sendCorsPreflight, sendJsonRpcError, sendJsonRpcResponse } from "./HttpHelpers.js";
+class HttpTransport extends BaseTransport {
+    _server;
+    _mcpServer = null;
+    _requestTimeout;
+    _bodySizeLimitEnabled;
+    _maxBodySize;
+    _requestCount = 0;
+    _activeRequests = 0;
+    _path;
+    _metrics;
+    _metricsProvider;
+    constructor(options = {}){
+        super(options);
+        this._requestTimeout = options.requestTimeout ?? 30000;
+        this._bodySizeLimitEnabled = options.enableBodySizeLimit ?? true;
+        this._maxBodySize = options.maxBodySize ?? 10485760;
+        this._path = options.path ?? '/messages';
+        this._metrics = options.metrics;
+        this._metricsProvider = options.metricsProvider ?? null;
+        this._server = createServer((req, res)=>this._handleRequest(req, res));
+    }
+    get clientCount() {
+        return this._activeRequests;
+    }
+    async connect(mcpServer) {
+        this._mcpServer = mcpServer;
+        return new Promise((resolve)=>{
+            this._server.listen(this._port, this._host, ()=>{
+                this.log('info', `HTTP transport listening on http://${this._host}:${this._port}`);
+                resolve();
+            });
+        });
+    }
+    _trackError(errorType) {
+        this._metrics?.counter('http_request_errors_total', 1, {
+            transport: 'http',
+            error_type: errorType
+        }, 'Total HTTP request errors');
+    }
+    async _handleRequest(req, res) {
+        const startTime = Date.now();
+        const requestPath = req.url || '/';
+        const requestMethod = req.method || 'GET';
+        this._metrics?.counter('http_requests_total', 1, {}, 'Total HTTP transport requests');
+        this._metrics?.counter('http_transport_requests_total', 1, {
+            transport: 'http',
+            method: requestMethod,
+            path: requestPath
+        }, 'Total HTTP requests by transport');
+        res.once('finish', ()=>{
+            const durationSeconds = (Date.now() - startTime) / 1000;
+            this._metrics?.histogram('http_request_duration_seconds', durationSeconds, {});
+            this._metrics?.histogram('http_transport_request_duration_seconds', durationSeconds, {
+                transport: 'http',
+                path: requestPath
+            });
+        });
+        if (!this.validateHostHeader(req)) {
+            this._trackError('forbidden');
+            sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid host header');
+            return;
+        }
+        if (this.isShuttingDown()) {
+            this._trackError('shutting_down');
+            sendJsonRpcError(res, 503, -32603, 'Server is shutting down');
+            return;
+        }
+        const clientIp = this.getClientIp(req);
+        if (this.checkRateLimit(clientIp)) {
+            this._trackError('rate_limit');
+            res.setHeader('Retry-After', '60');
+            sendJsonRpcError(res, 429, -32000, 'Too many requests');
+            return;
+        }
+        if (!this.validateCorsOrigin(req)) {
+            this._trackError('forbidden');
+            sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid origin');
+            return;
+        }
+        this.setCorsHeaders(res);
+        if ('GET' === req.method && '/metrics' === req.url) return this.handleMetricsEndpoint(res, this._metricsProvider);
+        if ('OPTIONS' === req.method) return sendCorsPreflight(res);
+        if ('GET' === req.method && '/health' === req.url) return this.handleHealthEndpoint(res, {
+            requests: this._requestCount
+        });
+        if ('GET' === req.method && '/ready' === req.url) return this.handleReadinessEndpoint(res);
+        if ('POST' === req.method && req.url === this._path) return this._handlePostRequest(req, res);
+        this._trackError('not_found');
+        sendJsonRpcError(res, 404, -32601, 'Not Found');
+    }
+    async _handlePostRequest(req, res) {
+        this._requestCount++;
+        this._activeRequests++;
+        const timeout = setTimeout(()=>{
+            this._activeRequests--;
+            this._trackError('timeout');
+            sendJsonRpcError(res, 500, -32603, 'Request timeout');
+        }, this._requestTimeout);
+        try {
+            const maxBodySize = this._bodySizeLimitEnabled ? this._maxBodySize : 0;
+            const body = await readRequestBody(req, maxBodySize);
+            if (null === body) {
+                clearTimeout(timeout);
+                this._activeRequests--;
+                this._trackError('payload_too_large');
+                sendJsonRpcError(res, 413, -32000, 'Request body too large');
+                return;
+            }
+            let jsonRpcRequest;
+            try {
+                jsonRpcRequest = JSON.parse(body);
+            } catch  {
+                clearTimeout(timeout);
+                this._activeRequests--;
+                this._trackError('parse_error');
+                sendJsonRpcError(res, 200, -32700, 'Parse error');
+                return;
+            }
+            const parseResult = safeParse(JsonRpcRequestSchema, jsonRpcRequest);
+            if (!parseResult.success) {
+                clearTimeout(timeout);
+                this._activeRequests--;
+                this._trackError('validation');
+                sendJsonRpcError(res, 200, -32600, 'Invalid Request', jsonRpcRequest?.id ?? null, parseResult.issues);
+                return;
+            }
+            if (!this._mcpServer) {
+                clearTimeout(timeout);
+                this._activeRequests--;
+                this._trackError('server_not_ready');
+                sendJsonRpcError(res, 200, -32603, 'Server not ready', jsonRpcRequest?.id ?? null);
+                return;
+            }
+            const response = await this._mcpServer.receive(jsonRpcRequest, {
+                sessionInfo: {}
+            });
+            clearTimeout(timeout);
+            this._activeRequests--;
+            if (response) sendJsonRpcResponse(res, response);
+            else {
+                res.writeHead(204);
+                res.end();
+            }
+        } catch (error) {
+            clearTimeout(timeout);
+            this._activeRequests--;
+            this._trackError('internal_error');
+            sendJsonRpcError(res, 200, -32603, 'Internal error', null, error instanceof Error ? error.message : String(error));
+        }
+    }
+    get requestCount() {
+        return this._requestCount;
+    }
+    async stop() {
+        this._isShuttingDown = true;
+        this._stopRateLimitCleanup();
+        return new Promise((resolve)=>{
+            this._server.close(()=>{
+                this.log('info', 'HTTP transport stopped');
+                resolve();
+            });
+        });
+    }
+}
+function createHttpTransport(options = {}) {
+    return new HttpTransport(options);
+}
+export { HttpTransport, createHttpTransport };
+
+//# sourceMappingURL=HttpTransport.js.map

package/dist/transport/HttpTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport/HttpTransport.js","sources":["../../src/transport/HttpTransport.ts"],"sourcesContent":["/**\n * HTTP Transport implementation.\n *\n * This transport provides a stateless, REST-like API interface for MCP tool invocations\n * using standard HTTP request-response patterns.\n *\n * @example\n * ```typescript\n * const transport = new HttpTransport({\n *   port: 3000,\n *   host: 'localhost'\n * });\n * await transport.connect(server);\n * ```\n */\n\nimport { createServer, IncomingMessage, ServerResponse } from 'node:http';\nimport type { McpServer } from 'tmcp';\nimport { safeParse } from 'valibot';\nimport type { IMetrics } from '../contracts/index.js';\nimport { JsonRpcRequestSchema } from '../schema.js';\nimport { BaseTransport, type TransportOptions } from './BaseTransport.js';\nimport {\n\treadRequestBody,\n\tsendCorsPreflight,\n\tsendJsonRpcError,\n\tsendJsonRpcResponse,\n} from './HttpHelpers.js';\n\nexport interface HttpTransportOptions extends TransportOptions {\n\t/**\n\t * Path for messages endpoint\n\t * @default '/messages'\n\t */\n\tpath?: string;\n\tmetrics?: IMetrics;\n\tmetricsProvider?: () => string;\n\n\t/**\n\t * Enable request body size limit\n\t * @default true\n\t */\n\tenableBodySizeLimit?: boolean;\n\n\t/**\n\t * Maximum request body size in bytes\n\t * @default 10485760 (10MB)\n\t */\n\tmaxBodySize?: number;\n\n\t/**\n\t * Request timeout in milliseconds\n\t * @default 30000 (30 seconds)\n\t */\n\trequestTimeout?: number;\n}\n\n/**\n * HTTP Transport for MCP server.\n *\n * This transport provides a stateless, REST-like API interface for MCP tool invocations\n * using standard HTTP request-response patterns.\n *\n * @remarks\n * **Security Features:**\n * - Session ID validation (alphanumeric, max 64 chars)\n * - Query parameter sanitization (whitelist allowed keys)\n * - Rate limiting per IP (configurable, default 100 req/min)\n * - CORS origin validation\n * - Request body size limits (configurable, default 10MB)\n * - Request timeout (configurable, default 30s)\n *\n * **Rate Limiting:**\n * - Tracks requests per IP address within a time window\n * - Returns 429 Too Many Requests when limit exceeded\n * - Can be disabled via `enableRateLimit: false`\n *\n * **HTTP Status Code Mapping:**\n * - 200: Success (JSON-RPC response)\n * - 204: CORS Preflight (empty body)\n * - 400: Bad Request\n * - 403: Forbidden (invalid CORS)\n * - 404: Not Found\n * - 413: Payload Too Large\n * - 429: Too Many Requests\n * - 500: Internal Server Error\n * - 503: Server Not Ready\n */\nexport class HttpTransport extends BaseTransport {\n\tprivate _server: ReturnType<typeof createServer>;\n\tprivate _mcpServer: McpServer | null = null;\n\tprivate _requestTimeout: number;\n\tprivate _bodySizeLimitEnabled: boolean;\n\tprivate _maxBodySize: number;\n\tprivate _requestCount: number = 0;\n\tprivate _activeRequests: number = 0;\n\tprivate _path: string;\n\tprivate _metrics?: IMetrics;\n\tprivate _metricsProvider: (() => string) | null;\n\n\tconstructor(options: HttpTransportOptions = {}) {\n\t\tsuper(options);\n\n\t\tthis._requestTimeout = options.requestTimeout ?? 30000;\n\t\tthis._bodySizeLimitEnabled = options.enableBodySizeLimit ?? true;\n\t\tthis._maxBodySize = options.maxBodySize ?? 10 * 1024 * 1024;\n\t\tthis._path = options.path ?? '/messages';\n\t\tthis._metrics = options.metrics;\n\t\tthis._metricsProvider = options.metricsProvider ?? null;\n\t\tthis._server = createServer((req, res) => this._handleRequest(req, res));\n\t}\n\n\t/**\n\t * Get number of active HTTP connections.\n\t */\n\tget clientCount(): number {\n\t\treturn this._activeRequests;\n\t}\n\n\t/**\n\t * Connects MCP server to this transport.\n\t */\n\tasync connect(mcpServer: McpServer): Promise<void> {\n\t\tthis._mcpServer = mcpServer;\n\t\treturn new Promise((resolve) => {\n\t\t\tthis._server.listen(this._port, this._host, () => {\n\t\t\t\tthis.log('info', `HTTP transport listening on http://${this._host}:${this._port}`);\n\t\t\t\tresolve();\n\t\t\t});\n\t\t});\n\t}\n\n\t/**\n\t * Track an error in metrics.\n\t */\n\tprivate _trackError(errorType: string): void {\n\t\tthis._metrics?.counter(\n\t\t\t'http_request_errors_total',\n\t\t\t1,\n\t\t\t{ transport: 'http', error_type: errorType },\n\t\t\t'Total HTTP request errors'\n\t\t);\n\t}\n\n\t/**\n\t * Route and handle incoming HTTP requests.\n\t *\n\t * Performs security checks (host, shutdown, rate limit, CORS) then\n\t * dispatches to the appropriate endpoint handler.\n\t */\n\tprivate async _handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {\n\t\tconst startTime = Date.now();\n\t\tconst requestPath = req.url || '/';\n\t\tconst requestMethod = req.method || 'GET';\n\t\tthis._metrics?.counter('http_requests_total', 1, {}, 'Total HTTP transport requests');\n\t\tthis._metrics?.counter(\n\t\t\t'http_transport_requests_total',\n\t\t\t1,\n\t\t\t{ transport: 'http', method: requestMethod, path: requestPath },\n\t\t\t'Total HTTP requests by transport'\n\t\t);\n\t\tres.once('finish', () => {\n\t\t\tconst durationSeconds = (Date.now() - startTime) / 1000;\n\t\t\tthis._metrics?.histogram('http_request_duration_seconds', durationSeconds, {});\n\t\t\tthis._metrics?.histogram('http_transport_request_duration_seconds', durationSeconds, {\n\t\t\t\ttransport: 'http',\n\t\t\t\tpath: requestPath,\n\t\t\t});\n\t\t});\n\n\t\t// Security middleware chain\n\t\tif (!this.validateHostHeader(req)) {\n\t\t\tthis._trackError('forbidden');\n\t\t\tsendJsonRpcError(res, 403, -32000, 'Forbidden - invalid host header');\n\t\t\treturn;\n\t\t}\n\n\t\tif (this.isShuttingDown()) {\n\t\t\tthis._trackError('shutting_down');\n\t\t\tsendJsonRpcError(res, 503, -32603, 'Server is shutting down');\n\t\t\treturn;\n\t\t}\n\n\t\tconst clientIp = this.getClientIp(req);\n\t\tif (this.checkRateLimit(clientIp)) {\n\t\t\tthis._trackError('rate_limit');\n\t\t\tres.setHeader('Retry-After', '60');\n\t\t\tsendJsonRpcError(res, 429, -32000, 'Too many requests');\n\t\t\treturn;\n\t\t}\n\n\t\tif (!this.validateCorsOrigin(req)) {\n\t\t\tthis._trackError('forbidden');\n\t\t\tsendJsonRpcError(res, 403, -32000, 'Forbidden - invalid origin');\n\t\t\treturn;\n\t\t}\n\n\t\tthis.setCorsHeaders(res);\n\n\t\t// Static endpoints\n\t\tif (req.method === 'GET' && req.url === '/metrics')\n\t\t\treturn this.handleMetricsEndpoint(res, this._metricsProvider);\n\t\tif (req.method === 'OPTIONS') return sendCorsPreflight(res);\n\t\tif (req.method === 'GET' && req.url === '/health')\n\t\t\treturn this.handleHealthEndpoint(res, { requests: this._requestCount });\n\t\tif (req.method === 'GET' && req.url === '/ready') return this.handleReadinessEndpoint(res);\n\n\t\t// MCP endpoint\n\t\tif (req.method === 'POST' && req.url === this._path) return this._handlePostRequest(req, res);\n\n\t\t// 404\n\t\tthis._trackError('not_found');\n\t\tsendJsonRpcError(res, 404, -32601, 'Not Found');\n\t}\n\n\t/**\n\t * Handle POST to the MCP messages endpoint.\n\t *\n\t * Reads the request body, validates JSON-RPC format, and delegates\n\t * processing to the MCP server.\n\t */\n\tprivate async _handlePostRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {\n\t\tthis._requestCount++;\n\t\tthis._activeRequests++;\n\n\t\tconst timeout = setTimeout(() => {\n\t\t\tthis._activeRequests--;\n\t\t\tthis._trackError('timeout');\n\t\t\tsendJsonRpcError(res, 500, -32603, 'Request timeout');\n\t\t}, this._requestTimeout);\n\n\t\ttry {\n\t\t\tconst maxBodySize = this._bodySizeLimitEnabled ? this._maxBodySize : 0;\n\t\t\tconst body = await readRequestBody(req, maxBodySize);\n\n\t\t\tif (body === null) {\n\t\t\t\tclearTimeout(timeout);\n\t\t\t\tthis._activeRequests--;\n\t\t\t\tthis._trackError('payload_too_large');\n\t\t\t\tsendJsonRpcError(res, 413, -32000, 'Request body too large');\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlet jsonRpcRequest;\n\t\t\ttry {\n\t\t\t\tjsonRpcRequest = JSON.parse(body);\n\t\t\t} catch {\n\t\t\t\tclearTimeout(timeout);\n\t\t\t\tthis._activeRequests--;\n\t\t\t\tthis._trackError('parse_error');\n\t\t\t\tsendJsonRpcError(res, 200, -32700, 'Parse error');\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst parseResult = safeParse(JsonRpcRequestSchema, jsonRpcRequest);\n\t\t\tif (!parseResult.success) {\n\t\t\t\tclearTimeout(timeout);\n\t\t\t\tthis._activeRequests--;\n\t\t\t\tthis._trackError('validation');\n\t\t\t\tsendJsonRpcError(\n\t\t\t\t\tres,\n\t\t\t\t\t200,\n\t\t\t\t\t-32600,\n\t\t\t\t\t'Invalid Request',\n\t\t\t\t\tjsonRpcRequest?.id ?? null,\n\t\t\t\t\tparseResult.issues\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (!this._mcpServer) {\n\t\t\t\tclearTimeout(timeout);\n\t\t\t\tthis._activeRequests--;\n\t\t\t\tthis._trackError('server_not_ready');\n\t\t\t\tsendJsonRpcError(res, 200, -32603, 'Server not ready', jsonRpcRequest?.id ?? null);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst response = await this._mcpServer.receive(jsonRpcRequest, {\n\t\t\t\tsessionInfo: {},\n\t\t\t});\n\n\t\t\tclearTimeout(timeout);\n\t\t\tthis._activeRequests--;\n\n\t\t\tif (response) {\n\t\t\t\tsendJsonRpcResponse(res, response);\n\t\t\t} else {\n\t\t\t\tres.writeHead(204);\n\t\t\t\tres.end();\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tclearTimeout(timeout);\n\t\t\tthis._activeRequests--;\n\t\t\tthis._trackError('internal_error');\n\t\t\tsendJsonRpcError(\n\t\t\t\tres,\n\t\t\t\t200,\n\t\t\t\t-32603,\n\t\t\t\t'Internal error',\n\t\t\t\tnull,\n\t\t\t\terror instanceof Error ? error.message : String(error)\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Returns number of requests handled.\n\t */\n\tget requestCount(): number {\n\t\treturn this._requestCount;\n\t}\n\n\t/**\n\t * Stops transport server.\n\t */\n\tasync stop(): Promise<void> {\n\t\tthis._isShuttingDown = true;\n\t\tthis._stopRateLimitCleanup();\n\n\t\treturn new Promise((resolve) => {\n\t\t\tthis._server.close(() => {\n\t\t\t\tthis.log('info', 'HTTP transport stopped');\n\t\t\t\tresolve();\n\t\t\t});\n\t\t});\n\t}\n}\n\n/**\n * Create an HTTP transport with given options.\n *\n * @param options - Transport configuration\n * @returns A configured HTTP transport\n *\n * @example\n * ```typescript\n * const transport = new HttpTransport({ port: 3000 });\n * await transport.connect(server);\n * ```\n */\nexport function createHttpTransport(options: HttpTransportOptions = {}): HttpTransport {\n\treturn new HttpTransport(options);\n}\n"],"names":["HttpTransport","BaseTransport","options","createServer","req","res","mcpServer","Promise","resolve","errorType","startTime","Date","requestPath","requestMethod","durationSeconds","sendJsonRpcError","clientIp","sendCorsPreflight","timeout","setTimeout","maxBodySize","body","readRequestBody","clearTimeout","jsonRpcRequest","JSON","parseResult","safeParse","JsonRpcRequestSchema","response","sendJsonRpcResponse","error","Error","String","createHttpTransport"],"mappings":"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"}

package/dist/transport/SseTransport.d.ts

@@ -0,0 +1,133 @@
+/**
+ * SSE (Server-Sent Events) Transport implementation.
+ *
+ * This transport allows multiple concurrent connections over HTTP using Server-Sent Events,
+ * enabling multi-user scenarios and horizontal scaling.
+ *
+ * When a ConnectionPool is provided, each SSE client gets an isolated session with its own
+ * thought history. Without a pool, all clients share a single server instance (backward compatible).
+ *
+ * @example
+ * ```typescript
+ * const transport = new SseTransport({
+ *   port: 3000,
+ *   host: 'localhost'
+ * });
+ * await transport.connect(server);
+ * ```
+ */
+import type { McpServer } from 'tmcp';
+import type { IMetrics } from '../contracts/index.js';
+import type { ConnectionPool } from '../pool/ConnectionPool.js';
+import { BaseTransport, type TransportOptions } from './BaseTransport.js';
+/**
+ * SSE-specific transport options extending base TransportOptions.
+ */
+export interface SseTransportOptions extends TransportOptions {
+    path?: string;
+    metrics?: IMetrics;
+    /**
+     * Optional connection pool for per-session state isolation.
+     * When provided, each SSE client gets an isolated thought history.
+     * When omitted, all clients share a single server instance (backward compatible).
+     */
+    connectionPool?: ConnectionPool;
+}
+/**
+ * SSE Transport for MCP server over HTTP.
+ *
+ * This transport uses Server-Sent Events (SSE) to communicate with clients,
+ * allowing multiple concurrent connections and web-based clients.
+ *
+ * @remarks
+ * **Security Features:**
+ * - 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
+ *
+ * **Rate Limiting:**
+ * - Tracks requests per IP address within a time window
+ * - Returns 429 Too Many Requests when limit exceeded
+ * - Can be disabled via `enableRateLimit: false`
+ */
+export declare class SseTransport extends BaseTransport {
+    private _server;
+    private _path;
+    private _clients;
+    private _clientSessionMap;
+    private _messageQueue;
+    private _metrics?;
+    private _connectionPool?;
+    constructor(options?: SseTransportOptions);
+    /**
+     * Connect MCP server to this transport.
+     *
+     * @param mcpServer - The MCP server instance
+     */
+    connect(mcpServer: McpServer): Promise<void>;
+    private _mcpServer;
+    /**
+     * Handle incoming HTTP requests
+     */
+    private _handleRequest;
+    /**
+     * Handle health check (liveness) endpoint
+     */
+    private _handleHealthCheck;
+    /**
+     * Handle readiness check endpoint
+     */
+    private _handleReadinessCheck;
+    /**
+     * Handle new SSE connection
+     */
+    private _handleSseConnection;
+    /**
+     * Handle incoming message from client
+     */
+    private _handleMessage;
+    /**
+     * Send an SSE event to a specific client
+     */
+    private _sendSseEvent;
+    private _updateActiveConnectionsMetric;
+    private _updatePoolMetrics;
+    /**
+     * Broadcast a message to all connected clients
+     */
+    broadcast(event: string, data: unknown): void;
+    /**
+     * Generate a unique client ID
+     */
+    private _generateClientId;
+    /**
+     * Get number of connected clients
+     */
+    get clientCount(): number;
+    /**
+     * Get the connection pool, if one was configured.
+     */
+    get connectionPool(): ConnectionPool | undefined;
+    /**
+     * Stop the transport server with graceful shutdown.
+     *
+     * @param timeout - Maximum time to wait for requests to drain (not used for SSE)
+     * @returns Promise that resolves when shutdown is complete
+     */
+    stop(_timeout?: number): Promise<void>;
+}
+/**
+ * Create an SSE transport with given options.
+ *
+ * @param options - Transport configuration
+ * @returns A configured SSE transport
+ *
+ * @example
+ * ```typescript
+ * const transport = createSseTransport({ port: 3000 });
+ * await transport.connect(mcpServer);
+ * ```
+ */
+export declare function createSseTransport(options?: SseTransportOptions): SseTransport;
+//# sourceMappingURL=SseTransport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SseTransport.d.ts","sourceRoot":"","sources":["../../src/transport/SseTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC1E;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAa,SAAQ,aAAa;IAC9C,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,aAAa,CAAqC;IAC1D,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,eAAe,CAAC,CAAiB;gBAE7B,OAAO,GAAE,mBAAwB;IAU7C;;;;OAIG;IACG,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlD,OAAO,CAAC,UAAU,CAA0B;IAE5C;;OAEG;YACW,cAAc;IA2F5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;YACW,qBAAqB;IAYnC;;OAEG;YACW,oBAAoB;IA6DlC;;OAEG;YACW,cAAc;IAyD5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,8BAA8B;IAStC,OAAO,CAAC,kBAAkB;IAyB1B;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAM7C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,cAAc,GAAG,SAAS,CAE/C;IAED;;;;;OAKG;IACG,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA6B5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAElF"}

package/dist/transport/SseTransport.js

@@ -0,0 +1,318 @@
+import { createServer } from "node:http";
+import { URL } from "node:url";
+import { safeParse } from "valibot";
+import { JsonRpcRequestSchema } from "../schema.js";
+import { BaseTransport } from "./BaseTransport.js";
+class SseTransport extends BaseTransport {
+    _server;
+    _path;
+    _clients = new Set();
+    _clientSessionMap = new Map();
+    _messageQueue = new Map();
+    _metrics;
+    _connectionPool;
+    constructor(options = {}){
+        super(options);
+        this._path = options.path ?? '/sse';
+        this._metrics = options.metrics;
+        this._connectionPool = options.connectionPool;
+        this._updateActiveConnectionsMetric();
+        this._server = createServer((req, res)=>this._handleRequest(req, res));
+    }
+    async connect(mcpServer) {
+        this._mcpServer = mcpServer;
+        return new Promise((resolve)=>{
+            this._server.listen(this._port, this._host, ()=>{
+                this.log('info', `SSE transport listening on http://${this._host}:${this._port}`);
+                resolve();
+            });
+        });
+    }
+    _mcpServer = null;
+    async _handleRequest(req, res) {
+        const startTime = Date.now();
+        const requestPath = req.url || '/';
+        const requestMethod = req.method || 'GET';
+        this._metrics?.counter('http_requests_total', 1, {
+            transport: 'sse',
+            method: requestMethod,
+            path: requestPath
+        }, 'Total HTTP requests');
+        res.once('finish', ()=>{
+            const durationSeconds = (Date.now() - startTime) / 1000;
+            this._metrics?.histogram('http_request_duration_seconds', durationSeconds, {
+                transport: 'sse',
+                path: requestPath
+            });
+        });
+        if (!this.validateHostHeader(req)) {
+            this._metrics?.counter('http_request_errors_total', 1, {
+                transport: 'sse',
+                error_type: 'forbidden'
+            }, 'Total HTTP request errors');
+            res.writeHead(403, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                error: 'Forbidden - invalid host header'
+            }));
+            return;
+        }
+        const url = new URL(req.url || '', `http://${req.headers.host}`);
+        const clientIp = this.getClientIp(req);
+        if (this.checkRateLimit(clientIp)) {
+            this._metrics?.counter('http_request_errors_total', 1, {
+                transport: 'sse',
+                error_type: 'rate_limit'
+            }, 'Total HTTP request errors');
+            res.writeHead(429, {
+                'Content-Type': 'application/json',
+                'Retry-After': '60'
+            });
+            res.end(JSON.stringify({
+                error: 'Too many requests'
+            }));
+            return;
+        }
+        if (!this.validateCorsOrigin(req)) {
+            this._metrics?.counter('http_request_errors_total', 1, {
+                transport: 'sse',
+                error_type: 'forbidden'
+            }, 'Total HTTP request errors');
+            res.writeHead(403, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                error: 'Forbidden - invalid origin'
+            }));
+            return;
+        }
+        this.setCorsHeaders(res);
+        const sanitizedParams = this.sanitizeQueryParams(url);
+        if (sanitizedParams.session || sanitizedParams.sessionId) {
+            const sessionId = sanitizedParams.session ?? sanitizedParams.sessionId;
+            if (!this.validateSessionId(sessionId)) {
+                this._metrics?.counter('http_request_errors_total', 1, {
+                    transport: 'sse',
+                    error_type: 'validation'
+                }, 'Total HTTP request errors');
+                res.writeHead(400, {
+                    'Content-Type': 'application/json'
+                });
+                res.end(JSON.stringify({
+                    error: 'Invalid session ID format'
+                }));
+                return;
+            }
+        }
+        if (this._enableCors && 'OPTIONS' === req.method) {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (url.pathname === this._path && 'GET' === req.method) return void await this._handleSseConnection(req, res, sanitizedParams);
+        if (url.pathname === `${this._path}/message` && 'POST' === req.method) return void await this._handleMessage(req, res, sanitizedParams);
+        if ('/health' === url.pathname) return void this._handleHealthCheck(res);
+        if ('/ready' === url.pathname) return void await this._handleReadinessCheck(res);
+        res.writeHead(404, {
+            'Content-Type': 'text/plain'
+        });
+        res.end('Not Found');
+    }
+    _handleHealthCheck(res) {
+        const healthData = {
+            status: 'healthy',
+            clients: this._clients.size
+        };
+        if (this._connectionPool) {
+            const poolStats = this._connectionPool.getStats();
+            healthData.pool = poolStats;
+        }
+        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: {}
+            }));
+        }
+    }
+    async _handleSseConnection(req, res, params) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive'
+        });
+        let sessionId;
+        if (this._connectionPool) {
+            const requestedSession = params.session ?? params.sessionId;
+            if (requestedSession && this._connectionPool.getSessionInfo(requestedSession)) sessionId = requestedSession;
+            else try {
+                sessionId = await this._connectionPool.createSession();
+            } catch (error) {
+                res.write(`event: error\n`);
+                res.write(`data: ${JSON.stringify({
+                    error: error instanceof Error ? error.message : 'Failed to create session'
+                })}\n\n`);
+                res.end();
+                return;
+            }
+            this._clientSessionMap.set(res, sessionId);
+            this._updatePoolMetrics();
+        }
+        const connectedPayload = {
+            timestamp: Date.now()
+        };
+        if (sessionId) connectedPayload.sessionId = sessionId;
+        this._sendSseEvent(res, 'connected', connectedPayload);
+        this._clients.add(res);
+        this._updateActiveConnectionsMetric();
+        req.on('close', ()=>{
+            this._clients.delete(res);
+            this._clientSessionMap.delete(res);
+            this._updateActiveConnectionsMetric();
+        });
+        const clientId = this._generateClientId();
+        const queued = this._messageQueue.get(clientId);
+        if (queued) {
+            for (const message of queued)this._sendSseEvent(res, 'message', message);
+            this._messageQueue.delete(clientId);
+        }
+    }
+    async _handleMessage(req, res, _params) {
+        let body = '';
+        for await (const chunk of req)body += chunk.toString();
+        try {
+            const jsonRpcRequest = JSON.parse(body);
+            const parseResult = safeParse(JsonRpcRequestSchema, jsonRpcRequest);
+            if (!parseResult.success) {
+                this._metrics?.counter('http_request_errors_total', 1, {
+                    transport: 'sse',
+                    error_type: 'validation'
+                }, 'Total HTTP request errors');
+                res.writeHead(200, {
+                    'Content-Type': 'application/json'
+                });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: jsonRpcRequest?.id ?? null,
+                    error: {
+                        code: -32600,
+                        message: 'Invalid Request',
+                        data: parseResult.issues
+                    }
+                }));
+                return;
+            }
+            if (this._mcpServer) {
+                const response = await this._mcpServer.receive(jsonRpcRequest, {
+                    sessionInfo: {}
+                });
+                res.writeHead(200, {
+                    'Content-Type': 'application/json'
+                });
+                if (response) res.end(JSON.stringify(response));
+                else res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: jsonRpcRequest?.id ?? null,
+                    result: null
+                }));
+            } else {
+                this._metrics?.counter('http_request_errors_total', 1, {
+                    transport: 'sse',
+                    error_type: 'server_not_ready'
+                }, 'Total HTTP request errors');
+                res.writeHead(503, {
+                    'Content-Type': 'application/json'
+                });
+                res.end(JSON.stringify({
+                    error: 'Server not ready'
+                }));
+            }
+        } catch  {
+            this._metrics?.counter('http_request_errors_total', 1, {
+                transport: 'sse',
+                error_type: 'parse_error'
+            }, 'Total HTTP request errors');
+            res.writeHead(400, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                error: 'Invalid JSON'
+            }));
+        }
+    }
+    _sendSseEvent(res, event, data) {
+        try {
+            res.write(`event: ${event}\n`);
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        } catch  {
+            this._clients.delete(res);
+            this._updateActiveConnectionsMetric();
+        }
+    }
+    _updateActiveConnectionsMetric() {
+        this._metrics?.gauge('sse_active_connections', this._clients.size, {}, 'Current active SSE connections');
+    }
+    _updatePoolMetrics() {
+        if (!this._connectionPool || !this._metrics) return;
+        const stats = this._connectionPool.getStats();
+        this._metrics.gauge('sse_pool_active_sessions', stats.activeSessions, {}, 'Active sessions in connection pool');
+        this._metrics.gauge('sse_pool_total_sessions', stats.totalSessions, {}, 'Total sessions in connection pool');
+        this._metrics.gauge('sse_pool_max_sessions', stats.maxSessions, {}, 'Maximum sessions in connection pool');
+    }
+    broadcast(event, data) {
+        for (const client of this._clients)this._sendSseEvent(client, event, data);
+    }
+    _generateClientId() {
+        return `client_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+    }
+    get clientCount() {
+        return this._clients.size;
+    }
+    get connectionPool() {
+        return this._connectionPool;
+    }
+    async stop(_timeout) {
+        this._isShuttingDown = true;
+        this._stopRateLimitCleanup();
+        if (this._connectionPool) await this._connectionPool.terminate();
+        return new Promise((resolve)=>{
+            for (const client of this._clients)try {
+                client.end();
+            } catch  {}
+            this._clients.clear();
+            this._clientSessionMap.clear();
+            this._updateActiveConnectionsMetric();
+            this._server.close(()=>{
+                this.log('info', 'SSE transport stopped');
+                resolve();
+            });
+        });
+    }
+}
+function createSseTransport(options = {}) {
+    return new SseTransport(options);
+}
+export { SseTransport, createSseTransport };
+
+//# sourceMappingURL=SseTransport.js.map