@jagilber-org/index-server 1.22.0

package/dist/dashboard/server/WebSocketManager.js

@@ -0,0 +1,448 @@
+"use strict";
+/**
+ * WebSocketManager - Phase 1 Dashboard Foundation
+ *
+ * Manages WebSocket connections for real-time dashboard updates.
+ * Provides bidirectional communication between dashboard clients and server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketManager = void 0;
+exports.getWebSocketManager = getWebSocketManager;
+exports.setWebSocketManager = setWebSocketManager;
+const ws_1 = require("ws");
+const crypto_1 = require("crypto");
+const MetricsCollector_js_1 = require("./MetricsCollector.js");
+const SessionPersistenceManager_1 = require("./SessionPersistenceManager");
+const runtimeConfig_js_1 = require("../../config/runtimeConfig.js");
+const logger_js_1 = require("../../services/logger.js");
+const adminAuth_js_1 = require("./routes/adminAuth.js");
+class WebSocketManager {
+    wss = null;
+    clients = new Set();
+    options;
+    pingTimer;
+    persistenceManager;
+    constructor(options = {}) {
+        this.options = {
+            path: options.path ?? '/ws',
+            maxConnections: options.maxConnections ?? 100,
+            pingInterval: options.pingInterval ?? 30000, // 30 seconds
+            pongTimeout: options.pongTimeout ?? 5000, // 5 seconds
+        };
+        // Initialize session persistence manager
+        this.persistenceManager = new SessionPersistenceManager_1.SessionPersistenceManager();
+    }
+    /**
+     * Initialize WebSocket server
+     */
+    initialize(server) {
+        this.wss = new ws_1.WebSocketServer({
+            server,
+            path: this.options.path,
+            verifyClient: (info, callback) => {
+                const adminKey = (0, runtimeConfig_js_1.getRuntimeConfig)().dashboard.http.adminApiKey;
+                if (!adminKey) {
+                    const addr = info.req.socket.remoteAddress || '';
+                    callback((0, adminAuth_js_1.isLoopbackHost)(addr), 403, 'WebSocket access restricted to localhost');
+                    return;
+                }
+                const url = new URL(info.req.url || '', 'http://localhost');
+                const token = url.searchParams.get('token') || '';
+                const authHeader = info.req.headers['authorization'] || '';
+                const bearerToken = authHeader.replace(/^Bearer\s+/i, '');
+                callback((0, adminAuth_js_1.constantTimeKeyMatch)(token, adminKey) || (0, adminAuth_js_1.constantTimeKeyMatch)(bearerToken, adminKey), 401, 'WebSocket authentication required');
+            },
+        });
+        this.wss.on('connection', (ws) => {
+            this.handleConnection(ws);
+        });
+        this.wss.on('error', (error) => {
+            (0, logger_js_1.logError)('[WebSocketManager] Server error', error);
+        });
+        // Start ping/pong heartbeat
+        this.startHeartbeat();
+        (0, logger_js_1.logInfo)(`[WebSocketManager] Server initialized on path ${this.options.path}`);
+    }
+    /**
+     * Broadcast message to all connected clients
+     */
+    broadcast(message) {
+        if (this.clients.size === 0)
+            return;
+        const payload = JSON.stringify(message);
+        const deadClients = [];
+        this.clients.forEach((ws) => {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                try {
+                    ws.send(payload);
+                }
+                catch (error) {
+                    (0, logger_js_1.logError)('[WebSocketManager] Send error', error);
+                    deadClients.push(ws);
+                }
+            }
+            else {
+                deadClients.push(ws);
+            }
+        });
+        // Clean up dead connections
+        deadClients.forEach((ws) => {
+            this.clients.delete(ws);
+        });
+    }
+    /**
+     * Send message to specific client
+     */
+    sendToClient(client, message) {
+        if (client.readyState === ws_1.WebSocket.OPEN) {
+            try {
+                client.send(JSON.stringify(message));
+            }
+            catch (error) {
+                (0, logger_js_1.logError)('[WebSocketManager] Send to client error', error);
+                this.clients.delete(client);
+            }
+        }
+    }
+    /**
+     * Get connected client count
+     */
+    getClientCount() {
+        return this.clients.size;
+    }
+    /**
+     * Get all connected clients
+     */
+    getClients() {
+        return Array.from(this.clients);
+    }
+    /**
+     * Close all connections and cleanup
+     */
+    close() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = undefined;
+        }
+        this.clients.forEach((ws) => {
+            try {
+                ws.close(1000, 'Server shutting down');
+            }
+            catch (error) {
+                (0, logger_js_1.logError)('[WebSocketManager] Close error', error);
+            }
+        });
+        this.clients.clear();
+        if (this.wss) {
+            this.wss.close();
+            this.wss = null;
+        }
+        (0, logger_js_1.logInfo)('[WebSocketManager] Server closed');
+    }
+    handleConnection(ws) {
+        // Add to client set
+        this.clients.add(ws);
+        // Assign client identity & timestamps
+        try {
+            ws.clientId = this.safeGenerateClientId();
+        }
+        catch {
+            // Fallback simple id
+            ws.clientId = `client-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+        }
+        ws.connectedAt = Date.now();
+        ws.lastActivity = Date.now();
+        // Extract client info from request if available
+        try {
+            const request = ws._socket?.remoteAddress;
+            if (request) {
+                ws.ipAddress = request;
+            }
+            // Note: User-Agent would come from upgrade request headers if needed
+        }
+        catch {
+            // Ignore if not available
+        }
+        // Record connection in metrics
+        try {
+            (0, MetricsCollector_js_1.getMetricsCollector)().recordConnection(ws.clientId);
+        }
+        catch (err) {
+            (0, logger_js_1.logError)('[WebSocketManager] metrics recordConnection failed', err);
+        }
+        // Persist connection state
+        this.persistConnectionState().catch((error) => {
+            (0, logger_js_1.logError)('[WebSocketManager] Failed to persist WebSocket connection state', error);
+        });
+        // Broadcast connection event
+        this.broadcast({
+            type: 'client_connect',
+            timestamp: Date.now(),
+            data: { clientId: ws.clientId, timestamp: ws.connectedAt }
+        });
+        // Setup client event handlers
+        ws.on('message', (data) => {
+            try {
+                // Update activity timestamp
+                ws.lastActivity = Date.now();
+                const message = JSON.parse(data.toString());
+                this.handleClientMessage(ws, message);
+            }
+            catch (error) {
+                (0, logger_js_1.logError)('[WebSocketManager] Invalid message format', error);
+                this.sendError(ws, 'Invalid message format');
+            }
+        });
+        ws.on('close', (code, reason) => {
+            this.clients.delete(ws);
+            const disconnectTs = Date.now();
+            const duration = ws.connectedAt ? disconnectTs - ws.connectedAt : 0;
+            (0, logger_js_1.logInfo)('[WebSocketManager] Client disconnected', { code, reason: reason.toString(), id: ws.clientId, durationMs: duration, totalClients: this.clients.size });
+            if (ws.clientId) {
+                try {
+                    (0, MetricsCollector_js_1.getMetricsCollector)().recordDisconnection(ws.clientId);
+                }
+                catch (err) {
+                    (0, logger_js_1.logError)('[WebSocketManager] metrics recordDisconnection failed', err);
+                }
+                this.broadcast({
+                    type: 'client_disconnect',
+                    timestamp: disconnectTs,
+                    data: { clientId: ws.clientId, timestamp: disconnectTs, duration }
+                });
+            }
+            // Persist connection state after disconnect
+            this.persistConnectionState().catch((error) => {
+                (0, logger_js_1.logError)('[WebSocketManager] Failed to persist WebSocket state after disconnect', error);
+            });
+            // Push fresh metrics snapshot after disconnect
+            this.broadcastMetricsSnapshot();
+        });
+        ws.on('error', (error) => {
+            this.clients.delete(ws);
+            (0, logger_js_1.logError)(`[WebSocketManager] Client error (${ws.clientId})`, error);
+        });
+        ws.on('pong', () => {
+            // Mark as alive (handled by ping/pong mechanism)
+            ws.isAlive = true;
+        });
+        // Send welcome message
+        this.sendToClient(ws, {
+            type: 'welcome',
+            timestamp: Date.now(),
+            data: {
+                message: 'Connected to Index Server Dashboard',
+                version: '1.0.0',
+                features: ['real-time-metrics', 'tool-monitoring', 'admin-controls'],
+            },
+        });
+        (0, logger_js_1.logInfo)('[WebSocketManager] Client connected', { totalClients: this.clients.size });
+        // Send immediate metrics snapshot to the new client
+        this.sendCurrentMetrics(ws);
+        // And broadcast updated snapshot to all clients (active connection count changed)
+        this.broadcastMetricsSnapshot();
+    }
+    handleClientMessage(client, message) {
+        try {
+            switch (message.type) {
+                case 'ping':
+                    this.sendToClient(client, {
+                        type: 'pong',
+                        timestamp: Date.now(),
+                        data: message.data,
+                    });
+                    break;
+                case 'subscribe': {
+                    // Future: Handle subscription to specific events
+                    const events = message.data?.events || ['all'];
+                    this.sendToClient(client, {
+                        type: 'subscribed',
+                        timestamp: Date.now(),
+                        data: { events },
+                    });
+                    break;
+                }
+                case 'get_metrics':
+                    this.sendCurrentMetrics(client);
+                    break;
+                default:
+                    (0, logger_js_1.logWarn)('[WebSocketManager] Unknown message type', message.type);
+                    this.sendError(client, `Unknown message type: ${message.type}`);
+            }
+        }
+        catch (error) {
+            (0, logger_js_1.logError)('[WebSocketManager] Message handling error', error);
+            this.sendError(client, 'Message handling error');
+        }
+    }
+    sendError(client, message) {
+        this.sendToClient(client, {
+            type: 'error',
+            timestamp: Date.now(),
+            data: {
+                message,
+                severity: 'medium',
+            },
+        });
+    }
+    startHeartbeat() {
+        this.pingTimer = setInterval(() => {
+            this.clients.forEach((ws) => {
+                if (ws.isAlive === false) {
+                    // Client didn't respond to ping, terminate
+                    ws.terminate();
+                    this.clients.delete(ws);
+                    if (ws.clientId) {
+                        try {
+                            (0, MetricsCollector_js_1.getMetricsCollector)().recordDisconnection(ws.clientId);
+                        }
+                        catch (err) {
+                            (0, logger_js_1.logError)('[WebSocketManager] heartbeat disconnect metrics error', err);
+                        }
+                        this.broadcast({
+                            type: 'client_disconnect',
+                            timestamp: Date.now(),
+                            data: { clientId: ws.clientId, timestamp: Date.now(), duration: ws.connectedAt ? Date.now() - ws.connectedAt : 0 }
+                        });
+                        this.broadcastMetricsSnapshot();
+                    }
+                    return;
+                }
+                // Mark as potentially dead until pong received
+                ws.isAlive = false;
+                try {
+                    ws.ping();
+                }
+                catch (error) {
+                    (0, logger_js_1.logError)('[WebSocketManager] Ping error', error);
+                    this.clients.delete(ws);
+                }
+            });
+        }, this.options.pingInterval);
+    }
+    /** Generate a UUID using crypto.randomUUID if available */
+    safeGenerateClientId() {
+        if (typeof crypto_1.randomUUID === 'function')
+            return (0, crypto_1.randomUUID)();
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        return 'client-' + Math.random().toString(36).slice(2);
+    }
+    /** Send current metrics snapshot to a specific client */
+    sendCurrentMetrics(client) {
+        try {
+            const snapshot = (0, MetricsCollector_js_1.getMetricsCollector)().getCurrentSnapshot();
+            this.sendToClient(client, {
+                type: 'metrics_update',
+                timestamp: Date.now(),
+                data: snapshot,
+            });
+        }
+        catch (err) {
+            (0, logger_js_1.logError)('[WebSocketManager] Failed to send metrics snapshot', err);
+        }
+    }
+    /** Broadcast fresh metrics snapshot to all clients */
+    broadcastMetricsSnapshot() {
+        try {
+            const snapshot = (0, MetricsCollector_js_1.getMetricsCollector)().getCurrentSnapshot();
+            this.broadcast({
+                type: 'metrics_update',
+                timestamp: Date.now(),
+                data: snapshot,
+            });
+        }
+        catch (err) {
+            (0, logger_js_1.logError)('[WebSocketManager] Failed to broadcast metrics snapshot', err);
+        }
+    }
+    /**
+     * Return lightweight summaries of active websocket connections with real IDs and durations.
+     * Exposed via /api/admin/connections for dashboard consumption.
+     */
+    getActiveConnectionSummaries() {
+        const now = Date.now();
+        return this.getClients().map(c => ({
+            id: c.clientId || 'unknown',
+            connectedAt: c.connectedAt || now,
+            durationMs: c.connectedAt ? now - c.connectedAt : 0
+        }));
+    }
+    /**
+     * Persist current WebSocket connection state to disk
+     */
+    async persistConnectionState() {
+        try {
+            // Convert current connections to persistable format
+            const webSocketConnections = this.getClients().map(client => ({
+                id: client.clientId || 'unknown',
+                clientId: client.clientId || 'unknown',
+                connectedAt: client.connectedAt ? new Date(client.connectedAt).toISOString() : new Date().toISOString(),
+                lastActivity: client.lastActivity ? new Date(client.lastActivity).toISOString() : new Date().toISOString(),
+                ipAddress: client.ipAddress,
+                userAgent: client.userAgent,
+                isActive: client.readyState === ws_1.WebSocket.OPEN,
+                persistedAt: new Date().toISOString(),
+                version: 1
+            }));
+            // Get existing data and update connections
+            const existingData = await this.persistenceManager.loadData();
+            const persistedData = {
+                adminSessions: existingData?.adminSessions || [],
+                webSocketConnections,
+                sessionHistory: existingData?.sessionHistory || [],
+                metadata: {
+                    lastPersisted: new Date().toISOString(),
+                    version: 1,
+                    totalSessions: existingData?.adminSessions?.length || 0,
+                    totalConnections: webSocketConnections.length,
+                    totalHistoryEntries: existingData?.sessionHistory?.length || 0,
+                    checksums: {
+                        sessions: '',
+                        connections: '',
+                        history: ''
+                    }
+                }
+            };
+            await this.persistenceManager.persistData(persistedData);
+        }
+        catch (error) {
+            (0, logger_js_1.logError)('[WebSocketManager] Failed to persist WebSocket connection state', error);
+            // Don't throw - continue operation
+        }
+    }
+    /**
+     * Update connection activity timestamp
+     */
+    updateConnectionActivity(clientId) {
+        const client = Array.from(this.clients).find(c => c.clientId === clientId);
+        if (client) {
+            client.lastActivity = Date.now();
+            // Persist activity update (but don't await to avoid blocking)
+            this.persistConnectionState().catch((error) => {
+                (0, logger_js_1.logError)('[WebSocketManager] Failed to persist connection activity update', error);
+            });
+            return true;
+        }
+        return false;
+    }
+}
+exports.WebSocketManager = WebSocketManager;
+// Global singleton instance
+let globalWebSocketManager = null;
+/**
+ * Get or create the global WebSocket manager instance
+ */
+function getWebSocketManager() {
+    if (!globalWebSocketManager) {
+        globalWebSocketManager = new WebSocketManager();
+    }
+    return globalWebSocketManager;
+}
+/**
+ * Set a custom WebSocket manager instance (useful for testing)
+ */
+function setWebSocketManager(manager) {
+    globalWebSocketManager = manager;
+}

package/dist/dashboard/server/httpLifecycle.d.ts

@@ -0,0 +1,17 @@
+/**
+ * httpLifecycle — HTTP/HTTPS server creation, port binding, and graceful shutdown.
+ * Extracted from DashboardServer.ts to keep the coordinator within line limits.
+ */
+import { Express } from 'express';
+import { Server as HttpServer } from 'http';
+export interface TlsOptions {
+    cert: string;
+    key: string;
+    ca?: string;
+}
+/** Creates an HTTP or HTTPS server wrapping the given Express app. */
+export declare function buildHttpServer(app: Express, tls?: TlsOptions): HttpServer;
+/** Wraps `server.listen` in a promise; rejects on EADDRINUSE or any other error. */
+export declare function bindToPort(server: HttpServer, port: number, host: string): Promise<void>;
+/** Wraps `server.close` in a promise for graceful shutdown. */
+export declare function closeHttpServer(server: HttpServer): Promise<void>;

package/dist/dashboard/server/httpLifecycle.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * httpLifecycle — HTTP/HTTPS server creation, port binding, and graceful shutdown.
+ * Extracted from DashboardServer.ts to keep the coordinator within line limits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHttpServer = buildHttpServer;
+exports.bindToPort = bindToPort;
+exports.closeHttpServer = closeHttpServer;
+const http_1 = require("http");
+const https_1 = require("https");
+const logger_js_1 = require("../../services/logger.js");
+/** Creates an HTTP or HTTPS server wrapping the given Express app. */
+function buildHttpServer(app, tls) {
+    if (tls) {
+        return (0, https_1.createServer)({ cert: tls.cert, key: tls.key, ca: tls.ca }, app);
+    }
+    return (0, http_1.createServer)(app);
+}
+/** Wraps `server.listen` in a promise; rejects on EADDRINUSE or any other error. */
+function bindToPort(server, port, host) {
+    return new Promise((resolve, reject) => {
+        server.listen(port, host, () => resolve());
+        server.on('error', reject);
+    });
+}
+/** Wraps `server.close` in a promise for graceful shutdown. */
+function closeHttpServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => {
+            (0, logger_js_1.logInfo)('[httpLifecycle] Server stopped');
+            resolve();
+        });
+    });
+}

package/dist/dashboard/server/legacyDashboardHtml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * legacyDashboardHtml - generates the v1 legacy dashboard HTML page.
+ * Extracted from DashboardServer.ts to keep the coordinator within line limits.
+ * CSS lives in legacyDashboardStyles.ts to stay within per-file line limits.
+ */
+import { MetricsSnapshot } from "./MetricsCollector.js";
+export declare function stripGraphTab(html: string): string;
+export declare function formatUptime(ms: number): string;
+export declare function generateDashboardHtml(nonce: string, snapshot: MetricsSnapshot, webSocketUrl: string | null): string;