@iworkforces/tracelattice 2.0.3

package/dist/transport/BaseTransport.js

@@ -0,0 +1,199 @@
+import { MAX_SESSION_ID_LENGTH, SESSION_ID_PATTERN } from "../core/ids.js";
+class NoopLogger {
+    _level = 'info';
+    info(_message, _meta) {}
+    warn(_message, _meta) {}
+    error(_message, _meta) {}
+    debug(_message, _meta) {}
+    setLevel(level) {
+        this._level = level;
+    }
+    getLevel() {
+        return this._level;
+    }
+}
+const ALLOWED_QUERY_PARAMS = new Set([
+    'session',
+    'sessionId',
+    'client',
+    'clientId'
+]);
+const RATE_LIMIT_REQUESTS = 100;
+const RATE_LIMIT_WINDOW_MS = 60000;
+class BaseTransport {
+    _port;
+    _host;
+    _corsOrigin;
+    _enableCors;
+    _rateLimitEnabled;
+    _maxRequestsPerMinute;
+    _allowedHosts;
+    _rateLimitMap = new Map();
+    _rateLimitCleanupIntervalId = null;
+    _wasHostExplicitlySet;
+    _isShuttingDown = false;
+    _logger;
+    _healthChecker;
+    constructor(options = {}){
+        this._port = options.port ?? 9108;
+        this._host = options.host ?? '127.0.0.1';
+        this._wasHostExplicitlySet = void 0 !== options.host;
+        this._corsOrigin = options.corsOrigin ?? '*';
+        this._enableCors = options.enableCors ?? true;
+        this._rateLimitEnabled = options.enableRateLimit ?? true;
+        this._maxRequestsPerMinute = options.maxRequestsPerMinute ?? RATE_LIMIT_REQUESTS;
+        this._allowedHosts = this._buildAllowedHosts(options.allowedHosts);
+        this._isShuttingDown = false;
+        this._logger = options.logger ?? new NoopLogger();
+        this._healthChecker = options.healthChecker ?? null;
+        if (this._rateLimitEnabled) this._startRateLimitCleanup();
+    }
+    get serverUrl() {
+        const host = this._wasHostExplicitlySet || '127.0.0.1' !== this._host ? this._host : 'localhost';
+        return `http://${host}:${this._port}`;
+    }
+    validateSessionId(sessionId) {
+        if (sessionId.length > MAX_SESSION_ID_LENGTH) return false;
+        return SESSION_ID_PATTERN.test(sessionId);
+    }
+    sanitizeQueryParams(url) {
+        const sanitized = {};
+        for (const [key, value] of url.searchParams.entries())if (ALLOWED_QUERY_PARAMS.has(key)) sanitized[key] = value;
+        return sanitized;
+    }
+    checkRateLimit(ip) {
+        if (!this._rateLimitEnabled) return false;
+        const now = Date.now();
+        this._cleanupExpiredRateLimitEntries(now);
+        const record = this._rateLimitMap.get(ip);
+        if (!record || now > record.resetTime) {
+            this._rateLimitMap.set(ip, {
+                count: 1,
+                resetTime: now + RATE_LIMIT_WINDOW_MS
+            });
+            return false;
+        }
+        if (record.count >= this._maxRequestsPerMinute) return true;
+        record.count++;
+        return false;
+    }
+    _cleanupExpiredRateLimitEntries(now = Date.now()) {
+        for (const [ip, record] of this._rateLimitMap.entries())if (record.resetTime <= now) this._rateLimitMap.delete(ip);
+    }
+    _startRateLimitCleanup() {
+        if (null !== this._rateLimitCleanupIntervalId) clearInterval(this._rateLimitCleanupIntervalId);
+        this._rateLimitCleanupIntervalId = setInterval(()=>{
+            this._cleanupExpiredRateLimitEntries();
+        }, RATE_LIMIT_WINDOW_MS);
+    }
+    _stopRateLimitCleanup() {
+        if (null !== this._rateLimitCleanupIntervalId) {
+            clearInterval(this._rateLimitCleanupIntervalId);
+            this._rateLimitCleanupIntervalId = null;
+        }
+    }
+    getClientIp(req) {
+        const forwardedFor = req.headers['x-forwarded-for'];
+        if (forwardedFor && 'string' == typeof forwardedFor) return forwardedFor.split(',')[0].trim();
+        const remoteAddress = req.socket.remoteAddress;
+        return remoteAddress || 'unknown';
+    }
+    validateCorsOrigin(req) {
+        if ('*' === this._corsOrigin) return true;
+        const origin = req.headers.origin;
+        if (!origin) return true;
+        if (this._corsOrigin === origin) return true;
+        if (this._corsOrigin.includes('*')) {
+            const escaped = this._corsOrigin.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[a-zA-Z0-9.-]*');
+            const regex = new RegExp(`^${escaped}$`);
+            return regex.test(origin);
+        }
+        return false;
+    }
+    setCorsHeaders(res) {
+        if (this._enableCors) {
+            res.setHeader('Access-Control-Allow-Origin', this._corsOrigin);
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        }
+    }
+    validateHostHeader(req) {
+        const rawHost = req.headers.host;
+        if (!rawHost) return true;
+        const hostWithoutPort = rawHost.split(':')[0].trim().toLowerCase();
+        if (!hostWithoutPort) return false;
+        if (0 === this._allowedHosts.size) return true;
+        return this._allowedHosts.has(hostWithoutPort);
+    }
+    _buildAllowedHosts(configuredHosts) {
+        if (configuredHosts && configuredHosts.length > 0) return new Set(configuredHosts.map((host)=>host.toLowerCase().trim()).filter(Boolean));
+        const boundHost = this._host.toLowerCase();
+        const localHosts = [
+            'localhost',
+            '127.0.0.1',
+            '::1'
+        ];
+        if (localHosts.includes(boundHost)) return new Set(localHosts);
+        if ('0.0.0.0' === boundHost || '::' === boundHost) return new Set(localHosts);
+        return new Set([
+            boundHost
+        ]);
+    }
+    log(level, message, meta) {
+        if ('info' === level) this._logger.info(message, meta);
+        else if ('warn' === level) this._logger.warn(message, meta);
+        else this._logger.error(message, meta);
+    }
+    get isShuttingDown() {
+        return this._isShuttingDown;
+    }
+    handleHealthEndpoint(res, extraData) {
+        const healthData = {
+            status: 'healthy',
+            ...extraData
+        };
+        if (this._healthChecker) {
+            const liveness = this._healthChecker.checkLiveness();
+            healthData.liveness = liveness;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'application/json'
+        });
+        res.end(JSON.stringify(healthData));
+    }
+    async handleReadinessEndpoint(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: {}
+            }));
+        }
+    }
+    handleMetricsEndpoint(res, metricsProvider) {
+        if (!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(metricsProvider());
+    }
+}
+export { BaseTransport };
+
+//# sourceMappingURL=BaseTransport.js.map

package/dist/transport/BaseTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport/BaseTransport.js","sources":["../../src/transport/BaseTransport.ts"],"sourcesContent":["/**\n * Base transport implementation.\n *\n * This class provides shared functionality for all transport implementations,\n * including session validation, rate limiting, CORS handling, and IP extraction.\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 *\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\nimport type { IncomingMessage, ServerResponse } from 'node:http';\nimport type { URL } from 'node:url';\nimport type { HealthChecker } from '../health/HealthChecker.js';\nimport type { Logger, LogLevel } from '../logger/StructuredLogger.js';\nimport { SESSION_ID_PATTERN, MAX_SESSION_ID_LENGTH } from '../core/ids.js';\nimport type { McpServer } from 'tmcp';\n\n/**\n * No-op logger that does nothing. Used when no logger is provided.\n */\nclass NoopLogger implements Logger {\n\tprivate _level: LogLevel = 'info';\n\n\tinfo(_message: string, _meta?: Record<string, unknown>): void {}\n\twarn(_message: string, _meta?: Record<string, unknown>): void {}\n\terror(_message: string, _meta?: Record<string, unknown>): void {}\n\tdebug(_message: string, _meta?: Record<string, unknown>): void {}\n\tsetLevel(level: LogLevel): void {\n\t\tthis._level = level;\n\t}\n\tgetLevel(): LogLevel {\n\t\treturn this._level;\n\t}\n}\n\n/**\n * Allowed query parameter names (whitelist for security).\n */\nconst ALLOWED_QUERY_PARAMS = new Set(['session', 'sessionId', 'client', 'clientId']);\n\n\n\n/**\n * Rate limit settings (requests per minute per IP).\n */\nconst RATE_LIMIT_REQUESTS = 100;\nconst RATE_LIMIT_WINDOW_MS = 60 * 1000; // 1 minute\n\nexport interface TransportOptions {\n\treadonly port?: number;\n\treadonly host?: string;\n\treadonly allowedHosts?: string[];\n\treadonly corsOrigin?: string;\n\treadonly enableCors?: boolean;\n\treadonly enableRateLimit?: boolean;\n\treadonly maxRequestsPerMinute?: number;\n\treadonly logger?: Logger;\n\treadonly healthChecker?: HealthChecker;\n}\n\nexport abstract class BaseTransport {\n\tprotected _port: number;\n\tprotected _host: string;\n\tprotected _corsOrigin: string;\n\tprotected _enableCors: boolean;\n\tprotected _rateLimitEnabled: boolean;\n\tprotected _maxRequestsPerMinute: number;\n\tprotected _allowedHosts: Set<string>;\n\tprotected _rateLimitMap: Map<string, { count: number; resetTime: number }> = new Map();\n\tprotected _rateLimitCleanupIntervalId: NodeJS.Timeout | null = null;\n\tprotected _wasHostExplicitlySet: boolean;\n\t/** Shutdown state for graceful shutdown. */\n\tprotected _isShuttingDown: boolean = false;\n\tprivate _logger: Logger | NoopLogger;\n\tprotected _healthChecker: HealthChecker | null;\n\n\tconstructor(options: TransportOptions = {}) {\n\t\tthis._port = options.port ?? 9108;\n\t\tthis._host = options.host ?? '127.0.0.1';\n\t\tthis._wasHostExplicitlySet = options.host !== undefined;\n\t\tthis._corsOrigin = options.corsOrigin ?? '*';\n\t\tthis._enableCors = options.enableCors ?? true;\n\t\tthis._rateLimitEnabled = options.enableRateLimit ?? true;\n\t\tthis._maxRequestsPerMinute = options.maxRequestsPerMinute ?? RATE_LIMIT_REQUESTS;\n\t\tthis._allowedHosts = this._buildAllowedHosts(options.allowedHosts);\n\t\tthis._isShuttingDown = false;\n\t\tthis._logger = options.logger ?? new NoopLogger();\n\t\tthis._healthChecker = options.healthChecker ?? null;\n\n\t\tif (this._rateLimitEnabled) {\n\t\t\tthis._startRateLimitCleanup();\n\t\t}\n\t}\n\n\t/**\n\t * Get the server URL with localhost substitution for default host.\n\t */\n\tget serverUrl(): string {\n\t\tconst host =\n\t\t\t!this._wasHostExplicitlySet && this._host === '127.0.0.1' ? 'localhost' : this._host;\n\t\treturn `http://${host}:${this._port}`;\n\t}\n\n\t/**\n\t * Validate session ID format.\n\t *\n\t * @param sessionId - The session ID to validate\n\t * @returns true if valid, false otherwise\n\t */\n\tprotected validateSessionId(sessionId: string): boolean {\n\t\tif (sessionId.length > MAX_SESSION_ID_LENGTH) {\n\t\t\treturn false;\n\t\t}\n\t\treturn SESSION_ID_PATTERN.test(sessionId);\n\t}\n\n\t/**\n\t * Sanitize query parameters by removing any not in whitelist.\n\t *\n\t * @param url - The URL object containing query parameters\n\t * @returns A sanitized record of allowed query parameters\n\t */\n\tprotected sanitizeQueryParams(url: URL): Record<string, string> {\n\t\tconst sanitized: Record<string, string> = {};\n\n\t\tfor (const [key, value] of url.searchParams.entries()) {\n\t\t\tif (ALLOWED_QUERY_PARAMS.has(key)) {\n\t\t\t\tsanitized[key] = value;\n\t\t\t}\n\t\t}\n\n\t\treturn sanitized;\n\t}\n\n\t/**\n\t * Check rate limit for a given IP address.\n\t *\n\t * @param ip - The IP address to check\n\t * @returns true if rate limit exceeded, false otherwise\n\t */\n\tprotected checkRateLimit(ip: string): boolean {\n\t\tif (!this._rateLimitEnabled) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst now = Date.now();\n\t\tthis._cleanupExpiredRateLimitEntries(now);\n\t\tconst record = this._rateLimitMap.get(ip);\n\n\t\tif (!record || now > record.resetTime) {\n\t\t\tthis._rateLimitMap.set(ip, {\n\t\t\t\tcount: 1,\n\t\t\t\tresetTime: now + RATE_LIMIT_WINDOW_MS,\n\t\t\t});\n\t\t\treturn false;\n\t\t}\n\n\t\tif (record.count >= this._maxRequestsPerMinute) {\n\t\t\treturn true; // Rate limit exceeded\n\t\t}\n\n\t\trecord.count++;\n\t\treturn false;\n\t}\n\n\tprotected _cleanupExpiredRateLimitEntries(now = Date.now()): void {\n\t\tfor (const [ip, record] of this._rateLimitMap.entries()) {\n\t\t\tif (record.resetTime <= now) {\n\t\t\t\tthis._rateLimitMap.delete(ip);\n\t\t\t}\n\t\t}\n\t}\n\n\tprotected _startRateLimitCleanup(): void {\n\t\tif (this._rateLimitCleanupIntervalId !== null) {\n\t\t\tclearInterval(this._rateLimitCleanupIntervalId);\n\t\t}\n\n\t\tthis._rateLimitCleanupIntervalId = setInterval(() => {\n\t\t\tthis._cleanupExpiredRateLimitEntries();\n\t\t}, RATE_LIMIT_WINDOW_MS);\n\t}\n\n\tprotected _stopRateLimitCleanup(): void {\n\t\tif (this._rateLimitCleanupIntervalId !== null) {\n\t\t\tclearInterval(this._rateLimitCleanupIntervalId);\n\t\t\tthis._rateLimitCleanupIntervalId = null;\n\t\t}\n\t}\n\n\t/**\n\t * Get client IP address from request.\n\t *\n\t * @param req - The incoming request\n\t * @returns The client IP address\n\t */\n\tprotected getClientIp(req: IncomingMessage): string {\n\t\tconst forwardedFor = req.headers['x-forwarded-for'];\n\t\tif (forwardedFor && typeof forwardedFor === 'string') {\n\t\t\treturn forwardedFor.split(',')[0]!.trim();\n\t\t}\n\t\tconst remoteAddress = req.socket.remoteAddress;\n\t\treturn remoteAddress || 'unknown';\n\t}\n\n\t/**\n\t * Validate CORS origin from request headers.\n\t *\n\t * @param req - The incoming request\n\t * @returns true if origin is valid, false otherwise\n\t */\n\tprotected validateCorsOrigin(req: IncomingMessage): boolean {\n\t\tif (this._corsOrigin === '*') {\n\t\t\treturn true;\n\t\t}\n\n\t\tconst origin = req.headers.origin;\n\t\tif (!origin) {\n\t\t\treturn true; // No origin header is acceptable\n\t\t}\n\n\t\t// Exact match\n\t\tif (this._corsOrigin === origin) {\n\t\t\treturn true;\n\t\t}\n\n\t\t// Check if configured origin is a wildcard pattern\n\t\tif (this._corsOrigin.includes('*')) {\n\t\t\t// Escape all regex metacharacters EXCEPT *,\n\t\t\t// then replace * with a hostname-safe pattern (alphanumeric, hyphens, dots)\n\t\t\tconst escaped = this._corsOrigin\n\t\t\t\t.replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&') // escape metacharacters (not *)\n\t\t\t\t.replace(/\\*/g, '[a-zA-Z0-9.-]*');    // * matches valid hostname chars only\n\t\t\tconst regex = new RegExp(`^${escaped}$`);\n\t\t\treturn regex.test(origin);\n\t\t}\n\n\t\treturn false;\n\t}\n\n\t/**\n\t * Set CORS headers on response.\n\t *\n\t * @param res - The server response\n\t */\n\tprotected setCorsHeaders(res: ServerResponse): void {\n\t\tif (this._enableCors) {\n\t\t\tres.setHeader('Access-Control-Allow-Origin', this._corsOrigin);\n\t\t\tres.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');\n\t\t\tres.setHeader('Access-Control-Allow-Headers', 'Content-Type');\n\t\t}\n\t}\n\n\tprotected validateHostHeader(req: IncomingMessage): boolean {\n\t\tconst rawHost = req.headers.host;\n\t\tif (!rawHost) {\n\t\t\treturn true;\n\t\t}\n\n\t\tconst hostWithoutPort = rawHost.split(':')[0]!.trim().toLowerCase();\n\t\tif (!hostWithoutPort) {\n\t\t\treturn false;\n\t\t}\n\n\t\tif (this._allowedHosts.size === 0) {\n\t\t\treturn true;\n\t\t}\n\n\t\treturn this._allowedHosts.has(hostWithoutPort);\n\t}\n\n\tprivate _buildAllowedHosts(configuredHosts?: string[]): Set<string> {\n\t\tif (configuredHosts && configuredHosts.length > 0) {\n\t\t\treturn new Set(configuredHosts.map((host) => host.toLowerCase().trim()).filter(Boolean));\n\t\t}\n\n\t\tconst boundHost = this._host.toLowerCase();\n\t\tconst localHosts = ['localhost', '127.0.0.1', '::1'];\n\n\t\tif (localHosts.includes(boundHost)) {\n\t\t\treturn new Set(localHosts);\n\t\t}\n\n\t\tif (boundHost === '0.0.0.0' || boundHost === '::') {\n\t\t\treturn new Set(localHosts);\n\t\t}\n\n\t\treturn new Set([boundHost]);\n\t}\n\n\t/**\n\t * Log a message using the configured logger.\n\t *\n\t * @param level - Log level\n\t * @param message - Message to log\n\t * @param meta - Optional metadata\n\t */\n\tprotected log(\n\t\tlevel: 'info' | 'warn' | 'error',\n\t\tmessage: string,\n\t\tmeta?: Record<string, unknown>\n\t): void {\n\t\tif (level === 'info') {\n\t\t\tthis._logger.info(message, meta);\n\t\t} else if (level === 'warn') {\n\t\t\tthis._logger.warn(message, meta);\n\t\t} else {\n\t\t\tthis._logger.error(message, meta);\n\t\t}\n\t}\n\n\t/**\n\t * Check if transport is shutting down.\n\t * @returns true if in shutdown phase\n\t */\n\tpublic get isShuttingDown(): boolean {\n\t\treturn this._isShuttingDown;\n\t}\n\n\t/**\n\t * Handle GET /health endpoint — liveness check.\n\t *\n\t * Builds a standard health response with optional liveness data from the health checker.\n\t * Transports can pass extra data (e.g. client counts, session info).\n\t *\n\t * @param res - The server response\n\t * @param extraData - Optional additional health metadata\n\t */\n\tprotected handleHealthEndpoint(res: ServerResponse, extraData?: Record<string, unknown>): void {\n\t\tconst healthData: Record<string, unknown> = { status: 'healthy', ...extraData };\n\t\tif (this._healthChecker) {\n\t\t\tconst liveness = this._healthChecker.checkLiveness();\n\t\t\thealthData.liveness = liveness;\n\t\t}\n\t\tres.writeHead(200, { 'Content-Type': 'application/json' });\n\t\tres.end(JSON.stringify(healthData));\n\t}\n\n\t/**\n\t * Handle GET /ready endpoint — readiness check.\n\t *\n\t * Delegates to the health checker if available, otherwise returns a default OK response.\n\t *\n\t * @param res - The server response\n\t */\n\tprotected async handleReadinessEndpoint(res: ServerResponse): Promise<void> {\n\t\tif (this._healthChecker) {\n\t\t\tconst readiness = await this._healthChecker.checkReadiness();\n\t\t\tconst statusCode = readiness.status === 'ok' ? 200 : 503;\n\t\t\tres.writeHead(statusCode, { 'Content-Type': 'application/json' });\n\t\t\tres.end(JSON.stringify(readiness));\n\t\t} else {\n\t\t\tres.writeHead(200, { 'Content-Type': 'application/json' });\n\t\t\tres.end(\n\t\t\t\tJSON.stringify({ status: 'ok', timestamp: new Date().toISOString(), components: {} })\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Handle GET /metrics endpoint — Prometheus metrics.\n\t *\n\t * Returns 404 if no metrics provider is configured.\n\t *\n\t * @param res - The server response\n\t * @param metricsProvider - Function that returns Prometheus-format metrics text\n\t */\n\tprotected handleMetricsEndpoint(res: ServerResponse, metricsProvider: (() => string) | null): void {\n\t\tif (!metricsProvider) {\n\t\t\tres.writeHead(404, { 'Content-Type': 'text/plain' });\n\t\t\tres.end('Not Found');\n\t\t\treturn;\n\t\t}\n\t\tres.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' });\n\t\tres.end(metricsProvider());\n\t}\n\n\t/**\n\t * Connect to MCP server.\n\t */\n\tabstract connect(mcpServer: McpServer): Promise<void>;\n\n\t/**\n\t * Stop transport server with graceful shutdown.\n\t *\n\t * This method should:\n\t * 1. Set shutdown flag to prevent new connections\n\t * 2. Wait for in-flight requests to complete (configurable timeout)\n\t * 3. Close server connections\n\t * 4. Release resources\n\t *\n\t * @param timeout - Maximum time to wait for requests to drain (default: 30 seconds)\n\t * @returns Promise that resolves when shutdown is complete\n\t */\n\tabstract stop(timeout?: number): Promise<void>;\n\n\t/**\n\t * Get number of clients connected.\n\t */\n\tabstract get clientCount(): number;\n\n}\n"],"names":["NoopLogger","_message","_meta","level","ALLOWED_QUERY_PARAMS","Set","RATE_LIMIT_REQUESTS","RATE_LIMIT_WINDOW_MS","BaseTransport","Map","options","undefined","host","sessionId","MAX_SESSION_ID_LENGTH","SESSION_ID_PATTERN","url","sanitized","key","value","ip","now","Date","record","clearInterval","setInterval","req","forwardedFor","remoteAddress","origin","escaped","regex","RegExp","res","rawHost","hostWithoutPort","configuredHosts","Boolean","boundHost","localHosts","message","meta","extraData","healthData","liveness","JSON","readiness","statusCode","metricsProvider"],"mappings":"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"}

package/dist/transport/HttpHelpers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared HTTP helper utilities for MCP transport implementations.
+ *
+ * Centralizes JSON-RPC response formatting, request body reading,
+ * and common HTTP response patterns to eliminate duplication across
+ * HttpTransport, StreamableHttpTransport, and SseTransport.
+ *
+ * @module transport/HttpHelpers
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Send a JSON-RPC 2.0 error response.
+ *
+ * Standardizes error response formatting across all transport implementations.
+ * All JSON-RPC errors use the standard `{ jsonrpc, id, error }` shape.
+ *
+ * @param res - The server response to write to
+ * @param statusCode - HTTP status code (e.g. 400, 403, 429, 500)
+ * @param code - JSON-RPC error code (e.g. -32700, -32600, -32603)
+ * @param message - Human-readable error message
+ * @param id - Optional JSON-RPC request ID (defaults to null)
+ * @param data - Optional additional error data
+ */
+export declare function sendJsonRpcError(res: ServerResponse, statusCode: number, code: number, message: string, id?: string | number | null, data?: unknown): void;
+/**
+ * Send a JSON-RPC 2.0 success response.
+ *
+ * @param res - The server response to write to
+ * @param response - The JSON-RPC response object to send
+ * @param statusCode - HTTP status code (default: 200)
+ * @param headers - Optional additional response headers
+ */
+export declare function sendJsonRpcResponse(res: ServerResponse, response: unknown, statusCode?: number, headers?: Record<string, string>): void;
+/**
+ * Send a CORS preflight (OPTIONS) response.
+ *
+ * @param res - The server response to write to
+ * @param extraAllowHeaders - Optional extra Access-Control-Allow-Headers values
+ */
+export declare function sendCorsPreflight(res: ServerResponse, extraAllowHeaders?: string[]): void;
+/**
+ * Read the full request body with optional size limit enforcement.
+ *
+ * Streams the request body chunks, tracking total size.
+ * If the body exceeds `maxBodySize`, reading stops and `null` is returned
+ * to indicate the payload is too large.
+ *
+ * @param req - The incoming HTTP request
+ * @param maxBodySize - Maximum allowed body size in bytes (0 = unlimited)
+ * @returns The body string, or `null` if the body exceeded the size limit
+ */
+export declare function readRequestBody(req: IncomingMessage, maxBodySize: number): Promise<string | null>;
+//# sourceMappingURL=HttpHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HttpHelpers.d.ts","sourceRoot":"","sources":["../../src/transport/HttpHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,MAAM,GAAG,MAAM,GAAG,IAAW,EACjC,IAAI,CAAC,EAAE,OAAO,GACZ,IAAI,CAWN;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,OAAO,EACjB,UAAU,GAAE,MAAY,EACxB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,IAAI,CAIN;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAMzF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACpC,GAAG,EAAE,eAAe,EACpB,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBxB"}

package/dist/transport/HttpHelpers.js

@@ -0,0 +1,44 @@
+function sendJsonRpcError(res, statusCode, code, message, id = null, data) {
+    const body = {
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code,
+            message
+        }
+    };
+    if (void 0 !== data) body.error.data = data;
+    res.writeHead(statusCode, {
+        'Content-Type': 'application/json'
+    });
+    res.end(JSON.stringify(body));
+}
+function sendJsonRpcResponse(res, response, statusCode = 200, headers = {}) {
+    const defaultHeaders = {
+        'Content-Type': 'application/json'
+    };
+    res.writeHead(statusCode, {
+        ...defaultHeaders,
+        ...headers
+    });
+    res.end(JSON.stringify(response));
+}
+function sendCorsPreflight(res, extraAllowHeaders) {
+    if (extraAllowHeaders && extraAllowHeaders.length > 0) res.setHeader('Access-Control-Allow-Headers', `Content-Type, ${extraAllowHeaders.join(', ')}`);
+    res.writeHead(204);
+    res.end();
+}
+async function readRequestBody(req, maxBodySize) {
+    let body = '';
+    let bodySize = 0;
+    for await (const chunk of req){
+        const chunkStr = 'string' == typeof chunk ? chunk : chunk.toString();
+        bodySize += chunkStr.length;
+        if (maxBodySize > 0 && bodySize > maxBodySize) return null;
+        body += chunkStr;
+    }
+    return body;
+}
+export { readRequestBody, sendCorsPreflight, sendJsonRpcError, sendJsonRpcResponse };
+
+//# sourceMappingURL=HttpHelpers.js.map

package/dist/transport/HttpHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport/HttpHelpers.js","sources":["../../src/transport/HttpHelpers.ts"],"sourcesContent":["/**\n * Shared HTTP helper utilities for MCP transport implementations.\n *\n * Centralizes JSON-RPC response formatting, request body reading,\n * and common HTTP response patterns to eliminate duplication across\n * HttpTransport, StreamableHttpTransport, and SseTransport.\n *\n * @module transport/HttpHelpers\n */\n\nimport type { IncomingMessage, ServerResponse } from 'node:http';\n\n/**\n * Send a JSON-RPC 2.0 error response.\n *\n * Standardizes error response formatting across all transport implementations.\n * All JSON-RPC errors use the standard `{ jsonrpc, id, error }` shape.\n *\n * @param res - The server response to write to\n * @param statusCode - HTTP status code (e.g. 400, 403, 429, 500)\n * @param code - JSON-RPC error code (e.g. -32700, -32600, -32603)\n * @param message - Human-readable error message\n * @param id - Optional JSON-RPC request ID (defaults to null)\n * @param data - Optional additional error data\n */\nexport function sendJsonRpcError(\n\tres: ServerResponse,\n\tstatusCode: number,\n\tcode: number,\n\tmessage: string,\n\tid: string | number | null = null,\n\tdata?: unknown\n): void {\n\tconst body: Record<string, unknown> = {\n\t\tjsonrpc: '2.0',\n\t\tid,\n\t\terror: { code, message },\n\t};\n\tif (data !== undefined) {\n\t\t(body.error as Record<string, unknown>).data = data;\n\t}\n\tres.writeHead(statusCode, { 'Content-Type': 'application/json' });\n\tres.end(JSON.stringify(body));\n}\n\n/**\n * Send a JSON-RPC 2.0 success response.\n *\n * @param res - The server response to write to\n * @param response - The JSON-RPC response object to send\n * @param statusCode - HTTP status code (default: 200)\n * @param headers - Optional additional response headers\n */\nexport function sendJsonRpcResponse(\n\tres: ServerResponse,\n\tresponse: unknown,\n\tstatusCode: number = 200,\n\theaders: Record<string, string> = {}\n): void {\n\tconst defaultHeaders: Record<string, string> = { 'Content-Type': 'application/json' };\n\tres.writeHead(statusCode, { ...defaultHeaders, ...headers });\n\tres.end(JSON.stringify(response));\n}\n\n/**\n * Send a CORS preflight (OPTIONS) response.\n *\n * @param res - The server response to write to\n * @param extraAllowHeaders - Optional extra Access-Control-Allow-Headers values\n */\nexport function sendCorsPreflight(res: ServerResponse, extraAllowHeaders?: string[]): void {\n\tif (extraAllowHeaders && extraAllowHeaders.length > 0) {\n\t\tres.setHeader('Access-Control-Allow-Headers', `Content-Type, ${extraAllowHeaders.join(', ')}`);\n\t}\n\tres.writeHead(204);\n\tres.end();\n}\n\n/**\n * Read the full request body with optional size limit enforcement.\n *\n * Streams the request body chunks, tracking total size.\n * If the body exceeds `maxBodySize`, reading stops and `null` is returned\n * to indicate the payload is too large.\n *\n * @param req - The incoming HTTP request\n * @param maxBodySize - Maximum allowed body size in bytes (0 = unlimited)\n * @returns The body string, or `null` if the body exceeded the size limit\n */\nexport async function readRequestBody(\n\treq: IncomingMessage,\n\tmaxBodySize: number\n): Promise<string | null> {\n\tlet body = '';\n\tlet bodySize = 0;\n\n\tfor await (const chunk of req) {\n\t\tconst chunkStr = typeof chunk === 'string' ? chunk : (chunk as Buffer).toString();\n\t\tbodySize += chunkStr.length;\n\n\t\tif (maxBodySize > 0 && bodySize > maxBodySize) {\n\t\t\treturn null;\n\t\t}\n\n\t\tbody += chunkStr;\n\t}\n\n\treturn body;\n}\n\n"],"names":["sendJsonRpcError","res","statusCode","code","message","id","data","body","undefined","JSON","sendJsonRpcResponse","response","headers","defaultHeaders","sendCorsPreflight","extraAllowHeaders","readRequestBody","req","maxBodySize","bodySize","chunk","chunkStr"],"mappings":"AAyBO,SAASA,iBACfC,GAAmB,EACnBC,UAAkB,EAClBC,IAAY,EACZC,OAAe,EACfC,KAA6B,IAAI,EACjCC,IAAc;IAEd,MAAMC,OAAgC;QACrC,SAAS;QACTF;QACA,OAAO;YAAEF;YAAMC;QAAQ;IACxB;IACA,IAAIE,AAASE,WAATF,MACFC,KAAK,KAAK,CAA6B,IAAI,GAAGD;IAEhDL,IAAI,SAAS,CAACC,YAAY;QAAE,gBAAgB;IAAmB;IAC/DD,IAAI,GAAG,CAACQ,KAAK,SAAS,CAACF;AACxB;AAUO,SAASG,oBACfT,GAAmB,EACnBU,QAAiB,EACjBT,aAAqB,GAAG,EACxBU,UAAkC,CAAC,CAAC;IAEpC,MAAMC,iBAAyC;QAAE,gBAAgB;IAAmB;IACpFZ,IAAI,SAAS,CAACC,YAAY;QAAE,GAAGW,cAAc;QAAE,GAAGD,OAAO;IAAC;IAC1DX,IAAI,GAAG,CAACQ,KAAK,SAAS,CAACE;AACxB;AAQO,SAASG,kBAAkBb,GAAmB,EAAEc,iBAA4B;IAClF,IAAIA,qBAAqBA,kBAAkB,MAAM,GAAG,GACnDd,IAAI,SAAS,CAAC,gCAAgC,CAAC,cAAc,EAAEc,kBAAkB,IAAI,CAAC,OAAO;IAE9Fd,IAAI,SAAS,CAAC;IACdA,IAAI,GAAG;AACR;AAaO,eAAee,gBACrBC,GAAoB,EACpBC,WAAmB;IAEnB,IAAIX,OAAO;IACX,IAAIY,WAAW;IAEf,WAAW,MAAMC,SAASH,IAAK;QAC9B,MAAMI,WAAW,AAAiB,YAAjB,OAAOD,QAAqBA,QAASA,MAAiB,QAAQ;QAC/ED,YAAYE,SAAS,MAAM;QAE3B,IAAIH,cAAc,KAAKC,WAAWD,aACjC,OAAO;QAGRX,QAAQc;IACT;IAEA,OAAOd;AACR"}

package/dist/transport/HttpRequestLifecycle.d.ts

@@ -0,0 +1,37 @@
+import type { ServerResponse } from 'node:http';
+type ResponseWriter = (response: ServerResponse) => void;
+type WorkFailureHandler = (error: unknown) => void;
+export type LifecycleReportingFailure = {
+    readonly lifecycleError: unknown;
+    readonly reportingError: unknown;
+};
+/** Maximum number of reporting failures retained for diagnostics. */
+export declare const LIFECYCLE_REPORTING_FAILURE_CAPACITY = 32;
+export declare class LifecycleFailureReporter {
+    private readonly _onFailure;
+    private readonly _reportingFailures;
+    private _reportingFailureCount;
+    private _droppedReportingFailureCount;
+    constructor(_onFailure: WorkFailureHandler);
+    get reportingFailures(): readonly LifecycleReportingFailure[];
+    get reportingFailureCount(): number;
+    get droppedReportingFailureCount(): number;
+    report(error: unknown): void;
+}
+export declare class ResponseFinalizer {
+    private readonly _response;
+    private readonly _failureReporter;
+    private _isFinalized;
+    constructor(_response: ServerResponse, _failureReporter: LifecycleFailureReporter);
+    finalize(writer: ResponseWriter): boolean;
+}
+export declare class AcceptedWorkTracker {
+    private readonly _failureReporter;
+    private readonly _work;
+    constructor(_failureReporter: LifecycleFailureReporter);
+    get size(): number;
+    track(work: Promise<void>): void;
+    join(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=HttpRequestLifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HttpRequestLifecycle.d.ts","sourceRoot":"","sources":["../../src/transport/HttpRequestLifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;AACzD,KAAK,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAEnD,MAAM,MAAM,yBAAyB,GAAG;IACvC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,oCAAoC,KAAK,CAAC;AAEvD,qBAAa,wBAAwB;IAKxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJvC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAmC;IACtE,OAAO,CAAC,sBAAsB,CAAK;IACnC,OAAO,CAAC,6BAA6B,CAAK;gBAEb,UAAU,EAAE,kBAAkB;IAE3D,IAAI,iBAAiB,IAAI,SAAS,yBAAyB,EAAE,CAE5D;IAED,IAAI,qBAAqB,IAAI,MAAM,CAElC;IAED,IAAI,4BAA4B,IAAI,MAAM,CAEzC;IAED,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;CAY5B;AAED,qBAAa,iBAAiB;IAI5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAJlC,OAAO,CAAC,YAAY,CAAS;gBAGX,SAAS,EAAE,cAAc,EACzB,gBAAgB,EAAE,wBAAwB;IAO5D,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO;CAezC;AAED,qBAAa,mBAAmB;IAGnB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAF7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;gBAErB,gBAAgB,EAAE,wBAAwB;IAEvE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAU1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK3B"}

package/dist/transport/HttpRequestLifecycle.js

@@ -0,0 +1,87 @@
+const LIFECYCLE_REPORTING_FAILURE_CAPACITY = 32;
+class LifecycleFailureReporter {
+    _onFailure;
+    _reportingFailures = [];
+    _reportingFailureCount = 0;
+    _droppedReportingFailureCount = 0;
+    constructor(_onFailure){
+        this._onFailure = _onFailure;
+    }
+    get reportingFailures() {
+        return [
+            ...this._reportingFailures
+        ];
+    }
+    get reportingFailureCount() {
+        return this._reportingFailureCount;
+    }
+    get droppedReportingFailureCount() {
+        return this._droppedReportingFailureCount;
+    }
+    report(error) {
+        try {
+            this._onFailure(error);
+        } catch (reportingError) {
+            this._reportingFailureCount++;
+            if (this._reportingFailures.length === LIFECYCLE_REPORTING_FAILURE_CAPACITY) {
+                this._reportingFailures.shift();
+                this._droppedReportingFailureCount++;
+            }
+            this._reportingFailures.push({
+                lifecycleError: error,
+                reportingError
+            });
+        }
+    }
+}
+class ResponseFinalizer {
+    _response;
+    _failureReporter;
+    _isFinalized = false;
+    constructor(_response, _failureReporter){
+        this._response = _response;
+        this._failureReporter = _failureReporter;
+        this._response.once('close', ()=>{
+            this._isFinalized = true;
+        });
+    }
+    finalize(writer) {
+        if (this._isFinalized || this._response.destroyed || this._response.writableEnded) {
+            this._isFinalized = true;
+            return false;
+        }
+        this._isFinalized = true;
+        try {
+            writer(this._response);
+        } catch (error) {
+            this._failureReporter.report(error);
+            this._response.destroy();
+        }
+        return true;
+    }
+}
+class AcceptedWorkTracker {
+    _failureReporter;
+    _work = new Set();
+    constructor(_failureReporter){
+        this._failureReporter = _failureReporter;
+    }
+    get size() {
+        return this._work.size;
+    }
+    track(work) {
+        const observed = work.catch((error)=>{
+            this._failureReporter.report(error);
+        });
+        this._work.add(observed);
+        observed.then(()=>{
+            this._work.delete(observed);
+        });
+    }
+    async join() {
+        while(this._work.size > 0)await Promise.all(this._work);
+    }
+}
+export { AcceptedWorkTracker, LIFECYCLE_REPORTING_FAILURE_CAPACITY, LifecycleFailureReporter, ResponseFinalizer };
+
+//# sourceMappingURL=HttpRequestLifecycle.js.map

package/dist/transport/HttpRequestLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport/HttpRequestLifecycle.js","sources":["../../src/transport/HttpRequestLifecycle.ts"],"sourcesContent":["import type { ServerResponse } from 'node:http';\n\ntype ResponseWriter = (response: ServerResponse) => void;\ntype WorkFailureHandler = (error: unknown) => void;\n\nexport type LifecycleReportingFailure = {\n\treadonly lifecycleError: unknown;\n\treadonly reportingError: unknown;\n};\n\n/** Maximum number of reporting failures retained for diagnostics. */\nexport const LIFECYCLE_REPORTING_FAILURE_CAPACITY = 32;\n\nexport class LifecycleFailureReporter {\n\tprivate readonly _reportingFailures: LifecycleReportingFailure[] = [];\n\tprivate _reportingFailureCount = 0;\n\tprivate _droppedReportingFailureCount = 0;\n\n\tconstructor(private readonly _onFailure: WorkFailureHandler) {}\n\n\tget reportingFailures(): readonly LifecycleReportingFailure[] {\n\t\treturn [...this._reportingFailures];\n\t}\n\n\tget reportingFailureCount(): number {\n\t\treturn this._reportingFailureCount;\n\t}\n\n\tget droppedReportingFailureCount(): number {\n\t\treturn this._droppedReportingFailureCount;\n\t}\n\n\treport(error: unknown): void {\n\t\ttry {\n\t\t\tthis._onFailure(error);\n\t\t} catch (reportingError) {\n\t\t\tthis._reportingFailureCount++;\n\t\t\tif (this._reportingFailures.length === LIFECYCLE_REPORTING_FAILURE_CAPACITY) {\n\t\t\t\tthis._reportingFailures.shift();\n\t\t\t\tthis._droppedReportingFailureCount++;\n\t\t\t}\n\t\t\tthis._reportingFailures.push({ lifecycleError: error, reportingError });\n\t\t}\n\t}\n}\n\nexport class ResponseFinalizer {\n\tprivate _isFinalized = false;\n\n\tconstructor(\n\t\tprivate readonly _response: ServerResponse,\n\t\tprivate readonly _failureReporter: LifecycleFailureReporter\n\t) {\n\t\tthis._response.once('close', () => {\n\t\t\tthis._isFinalized = true;\n\t\t});\n\t}\n\n\tfinalize(writer: ResponseWriter): boolean {\n\t\tif (this._isFinalized || this._response.destroyed || this._response.writableEnded) {\n\t\t\tthis._isFinalized = true;\n\t\t\treturn false;\n\t\t}\n\n\t\tthis._isFinalized = true;\n\t\ttry {\n\t\t\twriter(this._response);\n\t\t} catch (error) {\n\t\t\tthis._failureReporter.report(error);\n\t\t\tthis._response.destroy();\n\t\t}\n\t\treturn true;\n\t}\n}\n\nexport class AcceptedWorkTracker {\n\tprivate readonly _work = new Set<Promise<void>>();\n\n\tconstructor(private readonly _failureReporter: LifecycleFailureReporter) {}\n\n\tget size(): number {\n\t\treturn this._work.size;\n\t}\n\n\ttrack(work: Promise<void>): void {\n\t\tconst observed = work.catch((error: unknown) => {\n\t\t\tthis._failureReporter.report(error);\n\t\t});\n\t\tthis._work.add(observed);\n\t\tvoid observed.then(() => {\n\t\t\tthis._work.delete(observed);\n\t\t});\n\t}\n\n\tasync join(): Promise<void> {\n\t\twhile (this._work.size > 0) {\n\t\t\tawait Promise.all(this._work);\n\t\t}\n\t}\n}\n"],"names":["LIFECYCLE_REPORTING_FAILURE_CAPACITY","LifecycleFailureReporter","_onFailure","error","reportingError","ResponseFinalizer","_response","_failureReporter","writer","AcceptedWorkTracker","Set","work","observed","Promise"],"mappings":"AAWO,MAAMA,uCAAuC;AAE7C,MAAMC;;IACK,qBAAkD,EAAE,CAAC;IAC9D,yBAAyB,EAAE;IAC3B,gCAAgC,EAAE;IAE1C,YAA6BC,UAA8B,CAAE;aAAhCA,UAAU,GAAVA;IAAiC;IAE9D,IAAI,oBAA0D;QAC7D,OAAO;eAAI,IAAI,CAAC,kBAAkB;SAAC;IACpC;IAEA,IAAI,wBAAgC;QACnC,OAAO,IAAI,CAAC,sBAAsB;IACnC;IAEA,IAAI,+BAAuC;QAC1C,OAAO,IAAI,CAAC,6BAA6B;IAC1C;IAEA,OAAOC,KAAc,EAAQ;QAC5B,IAAI;YACH,IAAI,CAAC,UAAU,CAACA;QACjB,EAAE,OAAOC,gBAAgB;YACxB,IAAI,CAAC,sBAAsB;YAC3B,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,KAAKJ,sCAAsC;gBAC5E,IAAI,CAAC,kBAAkB,CAAC,KAAK;gBAC7B,IAAI,CAAC,6BAA6B;YACnC;YACA,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC;gBAAE,gBAAgBG;gBAAOC;YAAe;QACtE;IACD;AACD;AAEO,MAAMC;;;IACJ,eAAe,MAAM;IAE7B,YACkBC,SAAyB,EACzBC,gBAA0C,CAC1D;aAFgBD,SAAS,GAATA;aACAC,gBAAgB,GAAhBA;QAEjB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS;YAC5B,IAAI,CAAC,YAAY,GAAG;QACrB;IACD;IAEA,SAASC,MAAsB,EAAW;QACzC,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE;YAClF,IAAI,CAAC,YAAY,GAAG;YACpB,OAAO;QACR;QAEA,IAAI,CAAC,YAAY,GAAG;QACpB,IAAI;YACHA,OAAO,IAAI,CAAC,SAAS;QACtB,EAAE,OAAOL,OAAO;YACf,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAACA;YAC7B,IAAI,CAAC,SAAS,CAAC,OAAO;QACvB;QACA,OAAO;IACR;AACD;AAEO,MAAMM;;IACK,QAAQ,IAAIC,MAAqB;IAElD,YAA6BH,gBAA0C,CAAE;aAA5CA,gBAAgB,GAAhBA;IAA6C;IAE1E,IAAI,OAAe;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI;IACvB;IAEA,MAAMI,IAAmB,EAAQ;QAChC,MAAMC,WAAWD,KAAK,KAAK,CAAC,CAACR;YAC5B,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAACA;QAC9B;QACA,IAAI,CAAC,KAAK,CAAC,GAAG,CAACS;QACVA,SAAS,IAAI,CAAC;YAClB,IAAI,CAAC,KAAK,CAAC,MAAM,CAACA;QACnB;IACD;IAEA,MAAM,OAAsB;QAC3B,MAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,EACxB,MAAMC,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK;IAE9B;AACD"}

package/dist/transport/HttpTransport.d.ts

@@ -0,0 +1,140 @@
+/**
+ * HTTP Transport implementation.
+ *
+ * This transport provides a stateless, REST-like API interface for MCP tool invocations
+ * using standard HTTP request-response patterns.
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpTransport({
+ *   port: 3000,
+ *   host: 'localhost'
+ * });
+ * 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';
+export interface HttpTransportOptions extends TransportOptions {
+    /**
+     * Path for messages endpoint
+     * @default '/messages'
+     */
+    path?: string;
+    metrics?: IMetrics;
+    metricsProvider?: () => 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;
+}
+/**
+ * HTTP Transport for MCP server.
+ *
+ * This transport provides a stateless, REST-like API interface for MCP tool invocations
+ * using standard HTTP request-response patterns.
+ *
+ * @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
+ * - Request body size limits (configurable, default 10MB)
+ * - Request timeout (configurable, default 30s)
+ *
+ * **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`
+ *
+ * **HTTP Status Code Mapping:**
+ * - 200: Success (JSON-RPC response)
+ * - 204: CORS Preflight (empty body)
+ * - 400: Bad Request
+ * - 403: Forbidden (invalid CORS)
+ * - 404: Not Found
+ * - 413: Payload Too Large
+ * - 429: Too Many Requests
+ * - 500: Internal Server Error
+ * - 503: Server Not Ready
+ */
+export declare class HttpTransport extends BaseTransport implements ITransport {
+    get kind(): TransportKind;
+    private _server;
+    private _mcpServer;
+    private _requestTimeout;
+    private _bodySizeLimitEnabled;
+    private _maxBodySize;
+    private _requestCount;
+    private _activeRequests;
+    private _path;
+    private _metrics?;
+    private _metricsProvider;
+    private readonly _lifecycleFailureReporter;
+    private readonly _acceptedWork;
+    private _stopPromise;
+    constructor(options?: HttpTransportOptions);
+    private _requireMcpServer;
+    /**
+     * Get number of active HTTP connections.
+     */
+    get clientCount(): number;
+    /**
+     * Connects MCP server to this transport.
+     */
+    connect(mcpServer: McpServer): Promise<void>;
+    /**
+     * Track an error in metrics.
+     */
+    private _trackError;
+    /**
+     * Route and handle incoming HTTP requests.
+     *
+     * Performs security checks (host, shutdown, rate limit, CORS) then
+     * dispatches to the appropriate endpoint handler.
+     */
+    private _handleRequest;
+    /**
+     * Handle POST to the MCP messages endpoint.
+     *
+     * Reads the request body, validates JSON-RPC format, and delegates
+     * processing to the MCP server.
+     */
+    private _handlePostRequest;
+    /**
+     * Returns number of requests handled.
+     */
+    get requestCount(): number;
+    /**
+     * Stops transport server.
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Create an HTTP transport with given options.
+ *
+ * @param options - Transport configuration
+ * @returns A configured HTTP transport
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpTransport({ port: 3000 });
+ * await transport.connect(server);
+ * ```
+ */
+export declare function createHttpTransport(options?: HttpTransportOptions): HttpTransport;
+//# sourceMappingURL=HttpTransport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HttpTransport.d.ts","sourceRoot":"","sources":["../../src/transport/HttpTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAG3D,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAc3E,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC7D;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IAE/B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAc,SAAQ,aAAc,YAAW,UAAU;IACrE,IAAI,IAAI,IAAI,aAAa,CAExB;IACD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,qBAAqB,CAAU;IACvC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAA2B;IACrE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,YAAY,CAA8B;gBAEtC,OAAO,GAAE,oBAAyB;IAwB9C,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BlD;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;;;;OAKG;YACW,cAAc;IAoE5B;;;;;OAKG;YACW,kBAAkB;IA0FhC;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA0BrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAErF"}