@jagilber-org/index-server 1.19.1

package/dist/dashboard/server/LeaderElection.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * LeaderElection - Manages leader/follower roles for multi-instance MCP servers.
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * Uses a lock file + PID-based election strategy:
+ * - Leader is the instance that successfully acquires the lock file
+ * - On leader death, the surviving instance with the lowest PID promotes
+ * - Heartbeat mechanism keeps leader.lock fresh (stale = dead leader)
+ *
+ * Lock file location: `<stateDir>/leader.lock`
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeaderElection = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const events_1 = require("events");
+const LOCK_FILE = 'leader.lock';
+const DEFAULT_HEARTBEAT_MS = 5000;
+const DEFAULT_STALE_MS = 15000;
+class LeaderElection extends events_1.EventEmitter {
+    stateDir;
+    port;
+    host;
+    heartbeatIntervalMs;
+    staleThresholdMs;
+    _role = 'candidate';
+    heartbeatTimer = null;
+    watchTimer = null;
+    _leaderInfo = null;
+    _stopped = false;
+    constructor(options) {
+        super();
+        this.stateDir = options.stateDir;
+        this.port = options.port;
+        this.host = options.host;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+        this.staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_MS;
+    }
+    get role() { return this._role; }
+    get leaderInfo() { return this._leaderInfo; }
+    get lockFilePath() { return path_1.default.join(this.stateDir, LOCK_FILE); }
+    /**
+     * Attempt to become leader via atomic lock file creation.
+     * Returns true if this instance is now the leader.
+     */
+    tryAcquireLock() {
+        this.ensureStateDir();
+        const lockPath = this.lockFilePath;
+        try {
+            // O_CREAT | O_EXCL = fail if file exists (atomic create)
+            const fd = fs_1.default.openSync(lockPath, fs_1.default.constants.O_CREAT | fs_1.default.constants.O_EXCL | fs_1.default.constants.O_WRONLY);
+            const entry = this.buildLockEntry();
+            fs_1.default.writeSync(fd, JSON.stringify(entry, null, 2));
+            fs_1.default.closeSync(fd);
+            this._role = 'leader';
+            this._leaderInfo = entry;
+            this.emit('promoted', entry);
+            return true;
+        }
+        catch {
+            // Lock file exists — check if holder is alive
+            return this.handleExistingLock();
+        }
+    }
+    /**
+     * Check existing lock file. If holder is dead or stale, try to take over.
+     */
+    handleExistingLock() {
+        const lockPath = this.lockFilePath;
+        let entry;
+        try {
+            const raw = fs_1.default.readFileSync(lockPath, 'utf8');
+            entry = JSON.parse(raw);
+        }
+        catch {
+            // Corrupt lock file — remove and retry
+            try {
+                fs_1.default.unlinkSync(lockPath);
+            }
+            catch { /* ignore */ }
+            return this.tryAcquireLock();
+        }
+        if (!this.isProcessAlive(entry.pid)) {
+            // Leader is dead — remove lock and retry
+            try {
+                fs_1.default.unlinkSync(lockPath);
+            }
+            catch { /* ignore */ }
+            return this.tryAcquireLock();
+        }
+        // Check if heartbeat is stale
+        const heartbeatAge = Date.now() - new Date(entry.heartbeat).getTime();
+        if (heartbeatAge > this.staleThresholdMs) {
+            // Leader heartbeat is stale — assume dead
+            try {
+                fs_1.default.unlinkSync(lockPath);
+            }
+            catch { /* ignore */ }
+            return this.tryAcquireLock();
+        }
+        // Leader is alive and fresh — become follower
+        this._role = 'follower';
+        this._leaderInfo = entry;
+        this.emit('following', entry);
+        return false;
+    }
+    /**
+     * Start the election process and heartbeat/watch timers.
+     */
+    start() {
+        this._stopped = false;
+        const isLeader = this.tryAcquireLock();
+        if (isLeader) {
+            this.startHeartbeat();
+        }
+        else {
+            this.startWatcher();
+        }
+        return this._role;
+    }
+    /**
+     * Stop all timers and release the lock if leader.
+     */
+    stop() {
+        this._stopped = true;
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.watchTimer) {
+            clearInterval(this.watchTimer);
+            this.watchTimer = null;
+        }
+        if (this._role === 'leader') {
+            this.releaseLock();
+        }
+        this._role = 'candidate';
+    }
+    /**
+     * Update the heartbeat timestamp in the lock file (leader only).
+     * Uses atomic write-to-temp-then-rename to prevent corruption if
+     * the process dies mid-write.
+     */
+    updateHeartbeat() {
+        if (this._role !== 'leader')
+            return;
+        const lockPath = this.lockFilePath;
+        const tmpPath = lockPath + '.tmp';
+        try {
+            const entry = this.buildLockEntry();
+            fs_1.default.writeFileSync(tmpPath, JSON.stringify(entry, null, 2), 'utf8');
+            fs_1.default.renameSync(tmpPath, lockPath);
+            this._leaderInfo = entry;
+        }
+        catch {
+            // Clean up temp file on failure
+            try {
+                fs_1.default.unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            // Lost the lock file -- try to re-acquire
+            this.tryAcquireLock();
+        }
+    }
+    /**
+     * Remove the lock file (leader relinquishing).
+     */
+    releaseLock() {
+        try {
+            const lockPath = this.lockFilePath;
+            if (fs_1.default.existsSync(lockPath)) {
+                const raw = fs_1.default.readFileSync(lockPath, 'utf8');
+                const entry = JSON.parse(raw);
+                // Only remove if we own it
+                if (entry.pid === process.pid) {
+                    fs_1.default.unlinkSync(lockPath);
+                }
+            }
+        }
+        catch {
+            // Best-effort
+        }
+    }
+    /**
+     * Check if the current leader is still alive.
+     */
+    isLeaderAlive() {
+        if (this._role === 'leader')
+            return true;
+        if (!this._leaderInfo)
+            return false;
+        return this.isProcessAlive(this._leaderInfo.pid);
+    }
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            if (this._stopped)
+                return;
+            this.updateHeartbeat();
+        }, this.heartbeatIntervalMs);
+    }
+    startWatcher() {
+        this.watchTimer = setInterval(() => {
+            if (this._stopped)
+                return;
+            if (!this.isLeaderAlive() || this.isLeaderStale()) {
+                // Leader is dead or stale — attempt promotion
+                this.emit('leader-lost', this._leaderInfo);
+                const promoted = this.tryAcquireLock();
+                if (promoted) {
+                    if (this.watchTimer) {
+                        clearInterval(this.watchTimer);
+                        this.watchTimer = null;
+                    }
+                    this.startHeartbeat();
+                }
+            }
+        }, this.heartbeatIntervalMs);
+    }
+    isLeaderStale() {
+        try {
+            const raw = fs_1.default.readFileSync(this.lockFilePath, 'utf8');
+            const entry = JSON.parse(raw);
+            const heartbeatTime = new Date(entry.heartbeat).getTime();
+            // Guard against clock drift or invalid timestamps
+            if (isNaN(heartbeatTime))
+                return true;
+            const age = Date.now() - heartbeatTime;
+            // Negative age means clock skew -- treat as fresh to avoid
+            // premature stale detection across machines with clock drift
+            if (age < 0)
+                return false;
+            return age > this.staleThresholdMs;
+        }
+        catch {
+            return true; // Can't read = stale
+        }
+    }
+    buildLockEntry() {
+        const now = new Date().toISOString();
+        return {
+            pid: process.pid,
+            port: this.port,
+            host: this.host,
+            startedAt: this._leaderInfo?.startedAt ?? now,
+            heartbeat: now,
+        };
+    }
+    ensureStateDir() {
+        if (!fs_1.default.existsSync(this.stateDir)) {
+            fs_1.default.mkdirSync(this.stateDir, { recursive: true });
+        }
+    }
+    isProcessAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.LeaderElection = LeaderElection;

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

@@ -0,0 +1,200 @@
+/**
+ * MetricsCollector — coordinator class (Phase 1–4 Dashboard Foundation).
+ *
+ * Owns all mutable metrics state and delegates:
+ *  - pure math to metricsAggregation.ts
+ *  - output serialisation to metricsSerializer.ts
+ */
+import { BufferRingStats } from '../../utils/BufferRing.js';
+export type { ToolMetrics, ServerMetrics, ConnectionMetrics, MetricsSnapshot, MetricsTimeSeriesEntry, ToolCallEvent, MetricsBufferConfig, ChartDataPoint, ToolUsageChartData, PerformanceChartData, RealtimeMetrics, RealtimeStreamingData, SystemHealth, EnhancedPerformanceMetrics, StreamingStats, ActivityEvent, AdvancedAnalytics, HourlyStats, ToolUsageStats, ErrorAnalysis, PerformanceTrend, PredictionData, Anomaly, Alert, MetricsCollectorOptions, ResourceSample, } from './metricsAggregation.js';
+import { type ToolMetrics, type MetricsSnapshot, type MetricsTimeSeriesEntry, type ToolCallEvent, type RealtimeMetrics, type RealtimeStreamingData, type SystemHealth, type EnhancedPerformanceMetrics, type AdvancedAnalytics, type Alert, type MetricsCollectorOptions, type ResourceSample } from './metricsAggregation.js';
+import type { ToolUsageChartData, PerformanceChartData, ToolUsageStats } from './metricsAggregation.js';
+export declare class MetricsCollector {
+    private tools;
+    private resourceSamples;
+    private lastCpuUsageSample;
+    private lastCpuSampleTime;
+    private snapshots;
+    private connections;
+    private disconnectedCount;
+    private totalSessionTime;
+    private sessionStartTimes;
+    private startTime;
+    private options;
+    private collectTimer?;
+    private lastCpuUsage?;
+    private recentAlerts;
+    private activeConnections;
+    private recentCallTimestamps;
+    private static readonly MAX_RECENT_CALLS;
+    private static readonly MAX_MEMORY_SNAPSHOTS;
+    private static readonly MAX_TOOL_METRICS;
+    private fileStorage;
+    private useFileStorage;
+    private historicalSnapshots;
+    private toolCallEvents;
+    private _lastToolPersist;
+    private _pendingToolPersist;
+    private performanceMetrics;
+    private bufferConfig;
+    private appendMode;
+    private appendLogPath;
+    private pendingAppendEvents;
+    private lastAppendFlush;
+    private lastAppendCompact;
+    private appendChunkSize;
+    private appendFlushMs;
+    private appendCompactMs;
+    constructor(options?: MetricsCollectorOptions);
+    /**
+     * Record a tool call event
+     */
+    recordToolCall(toolName: string, success: boolean, responseTimeMs: number, errorType?: string, clientId?: string): void;
+    /** Flush tool call events (append or snapshot) */
+    private flushToolCallEvents;
+    /**
+     * Record client connection
+     */
+    recordConnection(clientId: string): void;
+    /**
+     * Record client disconnection
+     */
+    recordDisconnection(clientId: string): void;
+    /**
+     * Get current metrics snapshot
+     */
+    getCurrentSnapshot(): MetricsSnapshot;
+    /**
+     * Get historical snapshots (from memory for recent, or from files for historical)
+     */
+    getSnapshots(count?: number): MetricsSnapshot[];
+    /**
+     * Get snapshots from file storage (for historical analysis)
+     */
+    getHistoricalSnapshots(count?: number): Promise<MetricsSnapshot[]>;
+    /**
+     * Get snapshots within a specific time range from files
+     */
+    getSnapshotsInRange(startTime: number, endTime: number): Promise<MetricsSnapshot[]>;
+    /**
+     * Get file storage statistics
+     */
+    getStorageStats(): Promise<{
+        fileCount: number;
+        totalSizeKB: number;
+        oldestTimestamp?: number;
+        newestTimestamp?: number;
+        memorySnapshots: number;
+    }>;
+    /**
+     * Get tool-specific metrics
+     */
+    getToolMetrics(toolName?: string): {
+        [toolName: string]: ToolMetrics;
+    } | ToolMetrics | null;
+    /**
+     * Clear all metrics data (memory and files)
+     */
+    clearMetrics(): Promise<void>;
+    /**
+     * Clear only memory data (keep files)
+     */
+    clearMemoryMetrics(): void;
+    /**
+     * Stop metrics collection
+     */
+    stop(): void;
+    private startCollection;
+    private takeSnapshot;
+    private getVersion;
+    getRealtimeMetrics(): RealtimeMetrics;
+    getToolUsageChartData(minutes?: number): ToolUsageChartData[];
+    getPerformanceChartData(minutes?: number): PerformanceChartData;
+    getTimeRangeMetrics(range: '1h' | '6h' | '24h' | '7d' | '30d'): MetricsSnapshot[];
+    getRealtimeStreamingData(): RealtimeStreamingData;
+    getSystemHealth(): SystemHealth;
+    getDetailedPerformanceMetrics(): EnhancedPerformanceMetrics;
+    getAdvancedAnalytics(timeRange?: string): AdvancedAnalytics;
+    /**
+     * Generate real-time alert
+     */
+    generateRealTimeAlert(type: string, severity: string, message: string, value: number, threshold: number): Alert;
+    /**
+     * Get active alerts
+     */
+    getActiveAlerts(): Alert[];
+    /**
+     * Resolve alert by ID
+     */
+    resolveAlert(alertId: string): boolean;
+    private sampleResources;
+    getResourceHistory(limit?: number): {
+        samples: ResourceSample[];
+        trend?: {
+            cpuSlope: number;
+            memSlope: number;
+        };
+    };
+    /** Remove stale / low-activity tool entries to prevent unbounded map growth. */
+    private cleanupOldToolMetrics;
+    /**
+     * Get historical metrics data for charting
+     */
+    getHistoricalMetrics(minutes?: number): MetricsTimeSeriesEntry[];
+    /**
+     * Get recent tool call events for analysis
+     */
+    getRecentToolCallEvents(minutes?: number): ToolCallEvent[];
+    /**
+     * Get performance metrics time series for dashboard charts (BufferRing-enhanced)
+     */
+    getPerformanceTimeSeriesData(minutes?: number): PerformanceChartData;
+    /**
+     * Get tool usage analytics from historical data
+     */
+    getToolUsageAnalytics(minutes?: number): ToolUsageStats[];
+    /**
+     * Get BufferRing statistics for monitoring
+     */
+    getBufferRingStats(): {
+        historicalSnapshots: BufferRingStats;
+        toolCallEvents: BufferRingStats;
+        performanceMetrics: BufferRingStats;
+    };
+    /**
+     * Export metrics data for backup/analysis
+     */
+    exportMetricsData(options?: {
+        includeHistorical?: boolean;
+        includeEvents?: boolean;
+        includePerformance?: boolean;
+    }): {
+        timestamp: number;
+        currentSnapshot: MetricsSnapshot;
+        bufferStats: {
+            historicalSnapshots: BufferRingStats;
+            toolCallEvents: BufferRingStats;
+            performanceMetrics: BufferRingStats;
+        };
+        historicalSnapshots?: MetricsTimeSeriesEntry[];
+        toolCallEvents?: ToolCallEvent[];
+        performanceMetrics?: Array<{
+            timestamp: number;
+            responseTime: number;
+            throughput: number;
+            errorRate: number;
+        }>;
+    };
+    /**
+     * Clear all BufferRing data (for maintenance)
+     */
+    clearBufferedData(): void;
+}
+/**
+ * Get or create the global metrics collector instance
+ */
+export declare function getMetricsCollector(): MetricsCollector;
+/**
+ * Set a custom metrics collector instance (useful for testing)
+ */
+export declare function setMetricsCollector(collector: MetricsCollector | null): void;