@juspay/neurolink 3.0.0 → 4.0.0

package/dist/lib/services/websocket/websocket-server.js

@@ -0,0 +1,304 @@
+import { WebSocketServer, WebSocket } from "ws";
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+export class NeuroLinkWebSocketServer extends EventEmitter {
+    wss;
+    connections = new Map();
+    connectionInfo = new Map();
+    rooms = new Map();
+    streamingChannels = new Map();
+    heartbeatInterval;
+    options;
+    constructor(options = {}) {
+        super();
+        this.options = {
+            port: options.port || 8080,
+            maxConnections: options.maxConnections || 1000,
+            heartbeatInterval: options.heartbeatInterval || 30000,
+            enableCompression: options.enableCompression ?? true,
+            enableBackpressure: options.enableBackpressure ?? true,
+            bufferSize: options.bufferSize || 8192,
+            timeoutMs: options.timeoutMs || 30000,
+        };
+        this.wss = new WebSocketServer({
+            port: this.options.port,
+            perMessageDeflate: this.options.enableCompression,
+        });
+        this.setupEventHandlers();
+        this.startHeartbeat();
+    }
+    setupEventHandlers() {
+        this.wss.on("connection", (ws, request) => {
+            this.handleConnection(ws, request);
+        });
+        this.wss.on("error", (error) => {
+            console.error("[WebSocket Server] Error:", error);
+            this.emit("error", error);
+        });
+    }
+    handleConnection(ws, request) {
+        if (this.connections.size >= this.options.maxConnections) {
+            ws.close(1013, "Server at capacity");
+            return;
+        }
+        const connectionId = randomUUID();
+        const userAgent = request.headers["user-agent"];
+        const ipAddress = request.socket.remoteAddress;
+        // Store connection
+        this.connections.set(connectionId, ws);
+        this.connectionInfo.set(connectionId, {
+            id: connectionId,
+            userAgent,
+            ipAddress,
+            connectedAt: Date.now(),
+            lastActivity: Date.now(),
+            rooms: new Set(),
+            subscriptions: new Set(),
+            metadata: {},
+        });
+        // Setup WebSocket event handlers
+        ws.on("message", (data) => {
+            this.handleMessage(connectionId, data);
+        });
+        ws.on("close", () => {
+            this.handleDisconnection(connectionId);
+        });
+        ws.on("error", (error) => {
+            console.error(`[WebSocket] Connection ${connectionId} error:`, error);
+            this.handleDisconnection(connectionId);
+        });
+        // Send connection confirmation
+        this.sendMessage(connectionId, {
+            id: randomUUID(),
+            type: "system",
+            connectionId,
+            timestamp: Date.now(),
+            data: {
+                event: "connected",
+                connectionId,
+                serverInfo: {
+                    version: "3.0.1",
+                    features: ["streaming", "rooms", "tools"],
+                },
+            },
+        });
+        console.log(`[WebSocket] New connection: ${connectionId} (${this.connections.size}/${this.options.maxConnections})`);
+        this.emit("connection", { connectionId, userAgent, ipAddress });
+    }
+    handleMessage(connectionId, data) {
+        try {
+            const message = JSON.parse(data.toString());
+            this.updateLastActivity(connectionId);
+            switch (message.type) {
+                case "heartbeat":
+                    this.handleHeartbeat(connectionId);
+                    break;
+                case "chat":
+                    this.handleChatMessage(connectionId, message);
+                    break;
+                default:
+                    this.emit("message", { connectionId, message });
+            }
+        }
+        catch (error) {
+            console.error(`[WebSocket] Invalid message from ${connectionId}:`, error);
+            this.sendError(connectionId, "Invalid message format");
+        }
+    }
+    handleDisconnection(connectionId) {
+        const connection = this.connectionInfo.get(connectionId);
+        if (!connection) {
+            return;
+        }
+        // Leave all rooms
+        connection.rooms.forEach((roomId) => {
+            this.leaveRoom(connectionId, roomId);
+        });
+        // Close streaming channels
+        this.streamingChannels.forEach((channel, channelId) => {
+            if (channel.connectionId === connectionId) {
+                channel.onClose();
+                this.streamingChannels.delete(channelId);
+            }
+        });
+        // Clean up
+        this.connections.delete(connectionId);
+        this.connectionInfo.delete(connectionId);
+        console.log(`[WebSocket] Disconnected: ${connectionId} (${this.connections.size}/${this.options.maxConnections})`);
+        this.emit("disconnection", { connectionId });
+    }
+    // Room Management
+    joinRoom(connectionId, roomId) {
+        const connection = this.connectionInfo.get(connectionId);
+        if (!connection) {
+            return false;
+        }
+        if (!this.rooms.has(roomId)) {
+            this.rooms.set(roomId, new Set());
+        }
+        this.rooms.get(roomId).add(connectionId);
+        connection.rooms.add(roomId);
+        this.sendMessage(connectionId, {
+            id: randomUUID(),
+            type: "system",
+            connectionId,
+            roomId,
+            timestamp: Date.now(),
+            data: {
+                event: "room_joined",
+                roomId,
+                memberCount: this.rooms.get(roomId).size,
+            },
+        });
+        console.log(`[WebSocket] ${connectionId} joined room ${roomId}`);
+        return true;
+    }
+    leaveRoom(connectionId, roomId) {
+        const connection = this.connectionInfo.get(connectionId);
+        if (!connection) {
+            return false;
+        }
+        const room = this.rooms.get(roomId);
+        if (!room) {
+            return false;
+        }
+        room.delete(connectionId);
+        connection.rooms.delete(roomId);
+        if (room.size === 0) {
+            this.rooms.delete(roomId);
+        }
+        this.sendMessage(connectionId, {
+            id: randomUUID(),
+            type: "system",
+            connectionId,
+            roomId,
+            timestamp: Date.now(),
+            data: {
+                event: "room_left",
+                roomId,
+                memberCount: room.size,
+            },
+        });
+        console.log(`[WebSocket] ${connectionId} left room ${roomId}`);
+        return true;
+    }
+    broadcastToRoom(roomId, message) {
+        const room = this.rooms.get(roomId);
+        if (!room) {
+            return;
+        }
+        room.forEach((connectionId) => {
+            this.sendMessage(connectionId, { ...message, roomId });
+        });
+    }
+    // Streaming Support
+    createStreamingChannel(connectionId, channelId) {
+        const channel = {
+            id: channelId,
+            connectionId,
+            type: "ai-response",
+            status: "open",
+            buffer: {
+                data: [],
+                maxSize: this.options.bufferSize,
+                currentSize: 0,
+                flushThreshold: Math.floor(this.options.bufferSize * 0.8),
+                lastFlush: Date.now(),
+            },
+            onData: (data) => this.handleChannelData(channelId, data),
+            onError: (error) => this.handleChannelError(channelId, error),
+            onClose: () => this.handleChannelClose(channelId),
+        };
+        this.streamingChannels.set(channelId, channel);
+        return channel;
+    }
+    destroyStreamingChannel(channelId) {
+        const channel = this.streamingChannels.get(channelId);
+        if (channel) {
+            channel.status = "closed";
+            channel.onClose();
+            this.streamingChannels.delete(channelId);
+        }
+    }
+    // Helper methods
+    sendMessage(connectionId, message) {
+        const ws = this.connections.get(connectionId);
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            return false;
+        }
+        try {
+            ws.send(JSON.stringify(message));
+            return true;
+        }
+        catch (error) {
+            console.error(`[WebSocket] Failed to send message to ${connectionId}:`, error);
+            return false;
+        }
+    }
+    sendError(connectionId, errorMessage) {
+        this.sendMessage(connectionId, {
+            id: randomUUID(),
+            type: "error",
+            connectionId,
+            timestamp: Date.now(),
+            data: { error: errorMessage },
+        });
+    }
+    updateLastActivity(connectionId) {
+        const connection = this.connectionInfo.get(connectionId);
+        if (connection) {
+            connection.lastActivity = Date.now();
+        }
+    }
+    handleHeartbeat(connectionId) {
+        this.sendMessage(connectionId, {
+            id: randomUUID(),
+            type: "heartbeat",
+            connectionId,
+            timestamp: Date.now(),
+            data: { pong: true },
+        });
+    }
+    handleChatMessage(connectionId, message) {
+        this.emit("chat-message", { connectionId, message });
+    }
+    startHeartbeat() {
+        this.heartbeatInterval = setInterval(() => {
+            this.connections.forEach((ws, connectionId) => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    const connection = this.connectionInfo.get(connectionId);
+                    if (connection &&
+                        Date.now() - connection.lastActivity > this.options.timeoutMs) {
+                        console.log(`[WebSocket] Timeout for connection ${connectionId}`);
+                        ws.terminate();
+                    }
+                }
+            });
+        }, this.options.heartbeatInterval);
+    }
+    // Public getters
+    getConnectionCount() {
+        return this.connections.size;
+    }
+    getRoomCount() {
+        return this.rooms.size;
+    }
+    getActiveChannels() {
+        return this.streamingChannels.size;
+    }
+    close() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+        }
+        this.wss.close();
+    }
+    handleChannelData(channelId, data) {
+        // Implementation for channel data handling
+    }
+    handleChannelError(channelId, error) {
+        console.error(`[Streaming Channel] ${channelId} error:`, error);
+    }
+    handleChannelClose(channelId) {
+        console.log(`[Streaming Channel] ${channelId} closed`);
+    }
+}

package/dist/lib/telemetry/index.d.ts

@@ -0,0 +1,15 @@
+export { TelemetryService, type HealthMetrics } from "./telemetry-service.js";
+/**
+ * Initialize telemetry for NeuroLink
+ * OPTIONAL - Only works when NEUROLINK_TELEMETRY_ENABLED=true
+ */
+export declare function initializeTelemetry(): Promise<import("./telemetry-service.js").TelemetryService>;
+/**
+ * Get telemetry status
+ */
+export declare function getTelemetryStatus(): Promise<{
+    enabled: boolean;
+    endpoint?: string;
+    service?: string;
+    version?: string;
+}>;

package/dist/lib/telemetry/index.js

@@ -0,0 +1,22 @@
+// Optional Telemetry Infrastructure (Phase 2)
+export { TelemetryService } from "./telemetry-service.js";
+/**
+ * Initialize telemetry for NeuroLink
+ * OPTIONAL - Only works when NEUROLINK_TELEMETRY_ENABLED=true
+ */
+export async function initializeTelemetry() {
+    const { TelemetryService } = await import("./telemetry-service.js");
+    const telemetry = TelemetryService.getInstance();
+    if (telemetry.isEnabled()) {
+        await telemetry.initialize();
+        console.log("[NeuroLink] Telemetry initialized");
+    }
+    return telemetry;
+}
+/**
+ * Get telemetry status
+ */
+export async function getTelemetryStatus() {
+    const { TelemetryService } = await import("./telemetry-service.js");
+    return TelemetryService.getInstance().getStatus();
+}

package/dist/lib/telemetry/telemetry-service.d.ts

@@ -0,0 +1,47 @@
+export interface HealthMetrics {
+    timestamp: number;
+    memoryUsage: NodeJS.MemoryUsage;
+    uptime: number;
+    activeConnections: number;
+    errorRate: number;
+    averageResponseTime: number;
+}
+export declare class TelemetryService {
+    private static instance;
+    private sdk?;
+    private enabled;
+    private meter?;
+    private tracer?;
+    private aiRequestCounter?;
+    private aiRequestDuration?;
+    private aiTokensUsed?;
+    private aiProviderErrors?;
+    private mcpToolCalls?;
+    private connectionCounter?;
+    private responseTimeHistogram?;
+    private constructor();
+    static getInstance(): TelemetryService;
+    private isTelemetryEnabled;
+    private initializeTelemetry;
+    private initializeMetrics;
+    initialize(): Promise<void>;
+    traceAIRequest<T>(provider: string, operation: () => Promise<T>): Promise<T>;
+    recordAIRequest(provider: string, model: string, tokens: number, duration: number): void;
+    recordAIError(provider: string, error: Error): void;
+    recordMCPToolCall(toolName: string, duration: number, success: boolean): void;
+    recordConnection(type: "websocket" | "sse" | "http"): void;
+    recordResponseTime(endpoint: string, method: string, duration: number): void;
+    recordCustomMetric(name: string, value: number, labels?: Record<string, string>): void;
+    recordCustomHistogram(name: string, value: number, labels?: Record<string, string>): void;
+    getHealthMetrics(): Promise<HealthMetrics>;
+    isEnabled(): boolean;
+    getStatus(): {
+        enabled: boolean;
+        endpoint?: string;
+        service?: string;
+        version?: string;
+    };
+    private getDurationBucket;
+    private getStatusBucket;
+    shutdown(): Promise<void>;
+}

package/dist/lib/telemetry/telemetry-service.js

@@ -0,0 +1,259 @@
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { metrics, trace } from "@opentelemetry/api";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { Resource } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
+export class TelemetryService {
+    static instance;
+    sdk;
+    enabled = false;
+    meter;
+    tracer;
+    // Optional Metrics (only created when enabled)
+    aiRequestCounter;
+    aiRequestDuration;
+    aiTokensUsed;
+    aiProviderErrors;
+    mcpToolCalls;
+    connectionCounter;
+    responseTimeHistogram;
+    constructor() {
+        // Check if telemetry is enabled
+        this.enabled = this.isTelemetryEnabled();
+        if (this.enabled) {
+            this.initializeTelemetry();
+        }
+        else {
+            console.log("[Telemetry] Disabled - set NEUROLINK_TELEMETRY_ENABLED=true or configure OTEL_EXPORTER_OTLP_ENDPOINT to enable");
+        }
+    }
+    static getInstance() {
+        if (!TelemetryService.instance) {
+            TelemetryService.instance = new TelemetryService();
+        }
+        return TelemetryService.instance;
+    }
+    isTelemetryEnabled() {
+        return (process.env.NEUROLINK_TELEMETRY_ENABLED === "true" ||
+            process.env.OTEL_EXPORTER_OTLP_ENDPOINT !== undefined);
+    }
+    initializeTelemetry() {
+        try {
+            const resource = new Resource({
+                [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
+                [ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || "3.0.1",
+            });
+            this.sdk = new NodeSDK({
+                resource,
+                traceExporter: new OTLPTraceExporter({
+                    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
+                        `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
+                }),
+                // Note: Metric reader configured separately
+                instrumentations: [getNodeAutoInstrumentations()],
+            });
+            this.meter = metrics.getMeter("neurolink-ai");
+            this.tracer = trace.getTracer("neurolink-ai");
+            this.initializeMetrics();
+            console.log("[Telemetry] Initialized with endpoint:", process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+        }
+        catch (error) {
+            console.error("[Telemetry] Failed to initialize:", error);
+            this.enabled = false;
+        }
+    }
+    initializeMetrics() {
+        if (!this.enabled || !this.meter) {
+            return;
+        }
+        this.aiRequestCounter = this.meter.createCounter("ai_requests_total", {
+            description: "Total number of AI requests",
+        });
+        this.aiRequestDuration = this.meter.createHistogram("ai_request_duration_ms", {
+            description: "AI request duration in milliseconds",
+        });
+        this.aiTokensUsed = this.meter.createCounter("ai_tokens_used_total", {
+            description: "Total number of AI tokens used",
+        });
+        this.aiProviderErrors = this.meter.createCounter("ai_provider_errors_total", {
+            description: "Total number of AI provider errors",
+        });
+        this.mcpToolCalls = this.meter.createCounter("mcp_tool_calls_total", {
+            description: "Total number of MCP tool calls",
+        });
+        this.connectionCounter = this.meter.createCounter("connections_total", {
+            description: "Total number of connections",
+        });
+        this.responseTimeHistogram = this.meter.createHistogram("response_time_ms", {
+            description: "Response time in milliseconds",
+        });
+    }
+    async initialize() {
+        if (!this.enabled) {
+            return;
+        }
+        try {
+            await this.sdk?.start();
+            console.log("[Telemetry] SDK started successfully");
+        }
+        catch (error) {
+            console.error("[Telemetry] Failed to start SDK:", error);
+            this.enabled = false;
+        }
+    }
+    // AI Operation Tracing (NO-OP when disabled)
+    async traceAIRequest(provider, operation) {
+        if (!this.enabled || !this.tracer) {
+            return await operation(); // Direct execution when disabled
+        }
+        const span = this.tracer.startSpan(`ai.${provider}.generate_text`, {
+            attributes: {
+                "ai.provider": provider,
+                "ai.operation": "generate_text",
+            },
+        });
+        try {
+            const result = await operation();
+            span.setStatus({ code: 1 }); // OK
+            return result;
+        }
+        catch (error) {
+            span.setStatus({
+                code: 2,
+                message: error instanceof Error ? error.message : "Unknown error",
+            }); // ERROR
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    }
+    // Metrics Recording (NO-OP when disabled)
+    recordAIRequest(provider, model, tokens, duration) {
+        if (!this.enabled || !this.aiRequestCounter) {
+            return;
+        }
+        const labels = { provider, model };
+        this.aiRequestCounter.add(1, labels);
+        this.aiRequestDuration?.record(duration, labels);
+        this.aiTokensUsed?.add(tokens, labels);
+    }
+    recordAIError(provider, error) {
+        if (!this.enabled || !this.aiProviderErrors) {
+            return;
+        }
+        this.aiProviderErrors.add(1, {
+            provider,
+            error: error.name,
+            message: error.message.substring(0, 100), // Limit message length
+        });
+    }
+    recordMCPToolCall(toolName, duration, success) {
+        if (!this.enabled || !this.mcpToolCalls) {
+            return;
+        }
+        this.mcpToolCalls.add(1, {
+            tool: toolName,
+            success: success.toString(),
+            duration_bucket: this.getDurationBucket(duration),
+        });
+    }
+    recordConnection(type) {
+        if (!this.enabled || !this.connectionCounter) {
+            return;
+        }
+        this.connectionCounter.add(1, { connection_type: type });
+    }
+    recordResponseTime(endpoint, method, duration) {
+        if (!this.enabled || !this.responseTimeHistogram) {
+            return;
+        }
+        this.responseTimeHistogram.record(duration, {
+            endpoint,
+            method,
+            status_bucket: this.getStatusBucket(duration),
+        });
+    }
+    // Custom Metrics
+    recordCustomMetric(name, value, labels) {
+        if (!this.enabled || !this.meter) {
+            return;
+        }
+        const counter = this.meter.createCounter(`custom_${name}`, {
+            description: `Custom metric: ${name}`,
+        });
+        counter.add(value, labels || {});
+    }
+    recordCustomHistogram(name, value, labels) {
+        if (!this.enabled || !this.meter) {
+            return;
+        }
+        const histogram = this.meter.createHistogram(`custom_${name}_histogram`, {
+            description: `Custom histogram: ${name}`,
+        });
+        histogram.record(value, labels || {});
+    }
+    // Health Checks
+    async getHealthMetrics() {
+        const memoryUsage = process.memoryUsage();
+        return {
+            timestamp: Date.now(),
+            memoryUsage,
+            uptime: process.uptime(),
+            activeConnections: 0, // Would need to be provided by calling code
+            errorRate: 0, // Would need to be calculated from metrics
+            averageResponseTime: 0, // Would need to be calculated from metrics
+        };
+    }
+    // Telemetry Status
+    isEnabled() {
+        return this.enabled;
+    }
+    getStatus() {
+        return {
+            enabled: this.enabled,
+            endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+            service: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
+            version: process.env.OTEL_SERVICE_VERSION || "3.0.1",
+        };
+    }
+    // Helper methods
+    getDurationBucket(duration) {
+        if (duration < 100) {
+            return "fast";
+        }
+        if (duration < 500) {
+            return "medium";
+        }
+        if (duration < 1000) {
+            return "slow";
+        }
+        return "very_slow";
+    }
+    getStatusBucket(duration) {
+        if (duration < 200) {
+            return "excellent";
+        }
+        if (duration < 500) {
+            return "good";
+        }
+        if (duration < 1000) {
+            return "acceptable";
+        }
+        return "poor";
+    }
+    // Cleanup
+    async shutdown() {
+        if (this.enabled && this.sdk) {
+            try {
+                await this.sdk.shutdown();
+                console.log("[Telemetry] SDK shutdown completed");
+            }
+            catch (error) {
+                console.error("[Telemetry] Error during shutdown:", error);
+            }
+        }
+    }
+}