@sschepis/magazine 0.1.0

package/src/components/DebugUtils.js

@@ -0,0 +1,657 @@
+/**
+ * DebugUtils - Debugging utilities and health check endpoints
+ */
+export default class DebugUtils {
+    constructor(magazine, logger) {
+        this.magazine = magazine;
+        this.logger = logger.child({ context: 'DebugUtils' });
+        this.logger.info('DebugUtils initialized');
+        
+        // Debug mode state
+        this.debugMode = false;
+        
+        // Performance metrics
+        this.metrics = {
+            syncOperations: [],
+            queryOperations: [],
+            storageOperations: [],
+            networkCalls: []
+        };
+        
+        // Log buffer (circular, max 200 entries)
+        this._logBuffer = [];
+        this._logBufferMax = 200;
+
+        // Map to store original methods before instrumentation
+        this._originalMethods = new Map();
+
+        // Verbose error mode flag
+        this._verboseErrors = false;
+
+        // Health check thresholds
+        this.healthThresholds = {
+            syncDelay: 300000, // 5 minutes
+            errorRate: 0.1, // 10%
+            responseTime: 5000, // 5 seconds
+            storageUsage: 0.9 // 90%
+        };
+    }
+
+    /**
+     * Perform comprehensive health check
+     * @returns {Promise<Object>} Health check results
+     */
+    async healthCheck() {
+        const startTime = Date.now();
+        const results = {
+            status: 'healthy',
+            timestamp: new Date().toISOString(),
+            checks: {},
+            issues: []
+        };
+
+        try {
+            // Check network connectivity
+            results.checks.network = await this._checkNetwork();
+            
+            // Check Gun.js database
+            results.checks.database = await this._checkDatabase();
+            
+            // Check sync status
+            results.checks.sync = await this._checkSyncStatus();
+            
+            // Check storage
+            results.checks.storage = await this._checkStorage();
+            
+            // Check performance metrics
+            results.checks.performance = this._checkPerformance();
+            
+            // Determine overall status
+            const issues = [];
+            Object.entries(results.checks).forEach(([check, result]) => {
+                if (result.status !== 'healthy') {
+                    issues.push({
+                        check,
+                        status: result.status,
+                        message: result.message
+                    });
+                }
+            });
+            
+            if (issues.length > 0) {
+                results.status = issues.some(i => i.status === 'critical') ? 'critical' : 'degraded';
+                results.issues = issues;
+            }
+            
+            results.duration = Date.now() - startTime;
+            
+            this.logger.info('Health check completed', {
+                status: results.status,
+                duration: results.duration,
+                issueCount: issues.length
+            });
+            
+            return results;
+            
+        } catch (error) {
+            this.logger.error('Health check failed', { error: error.message });
+            return {
+                status: 'error',
+                timestamp: new Date().toISOString(),
+                error: error.message,
+                duration: Date.now() - startTime
+            };
+        }
+    }
+
+    /**
+     * Get debug information about the current state
+     * @returns {Promise<Object>} Debug information
+     */
+    async getDebugInfo() {
+        const debugInfo = {
+            timestamp: new Date().toISOString(),
+            configuration: this._getConfigInfo(),
+            network: await this._getNetworkInfo(),
+            storage: await this._getStorageInfo(),
+            performance: this._getPerformanceInfo(),
+            logs: this._getRecentLogs()
+        };
+        
+        this.logger.debug('Debug info generated');
+        return debugInfo;
+    }
+
+    /**
+     * Record a metric
+     * @param {string} type - Metric type
+     * @param {Object} data - Metric data
+     */
+    recordMetric(type, data) {
+        const metric = {
+            timestamp: Date.now(),
+            ...data
+        };
+        
+        if (this.metrics[type]) {
+            this.metrics[type].push(metric);
+            
+            // Keep only last 1000 metrics per type
+            if (this.metrics[type].length > 1000) {
+                this.metrics[type] = this.metrics[type].slice(-1000);
+            }
+        }
+    }
+
+    /**
+     * Get performance report
+     * @param {Object} options - Report options
+     * @returns {Object} Performance report
+     */
+    getPerformanceReport(options = {}) {
+        const { 
+            timeRange = 3600000, // Last hour
+            aggregation = 'average'
+        } = options;
+        
+        const now = Date.now();
+        const startTime = now - timeRange;
+        
+        const report = {};
+        
+        Object.entries(this.metrics).forEach(([type, metrics]) => {
+            const recentMetrics = metrics.filter(m => m.timestamp >= startTime);
+            
+            if (recentMetrics.length === 0) {
+                report[type] = { count: 0, average: 0, min: 0, max: 0 };
+                return;
+            }
+            
+            const durations = recentMetrics.map(m => m.duration || 0);
+            const errors = recentMetrics.filter(m => m.error).length;
+            
+            report[type] = {
+                count: recentMetrics.length,
+                errors,
+                errorRate: (errors / recentMetrics.length * 100).toFixed(2) + '%',
+                average: Math.round(durations.reduce((a, b) => a + b, 0) / durations.length),
+                min: Math.min(...durations),
+                max: Math.max(...durations),
+                p95: this._calculatePercentile(durations, 95),
+                p99: this._calculatePercentile(durations, 99)
+            };
+        });
+        
+        return {
+            timeRange: {
+                start: new Date(startTime).toISOString(),
+                end: new Date(now).toISOString(),
+                duration: timeRange
+            },
+            metrics: report
+        };
+    }
+
+    /**
+     * Enable debug mode
+     * @param {Object} options - Debug options
+     */
+    enableDebugMode(options = {}) {
+        const {
+            logLevel = 'debug',
+            captureMetrics = true,
+            verboseErrors = true
+        } = options;
+        
+        // Set log level
+        this.magazine.setLogLevel(logLevel);
+        
+        // Enable metric capture
+        if (captureMetrics) {
+            this._instrumentMethods();
+        }
+        
+        // Enable verbose errors
+        if (verboseErrors) {
+            this._enableVerboseErrors();
+        }
+        
+        this.logger.info('Debug mode enabled', options);
+    }
+
+    /**
+     * Export debug data
+     * @returns {Promise<Object>} Exportable debug data
+     */
+    async exportDebugData() {
+        const data = {
+            version: '1.0.0',
+            exportedAt: new Date().toISOString(),
+            debugInfo: await this.getDebugInfo(),
+            healthCheck: await this.healthCheck(),
+            performanceReport: this.getPerformanceReport(),
+            recentMetrics: {
+                sync: this.metrics.syncOperations.slice(-100),
+                query: this.metrics.queryOperations.slice(-100),
+                storage: this.metrics.storageOperations.slice(-100),
+                network: this.metrics.networkCalls.slice(-100)
+            }
+        };
+        
+        this.logger.info('Debug data exported');
+        return data;
+    }
+
+    /**
+     * Check network connectivity
+     * @private
+     */
+    async _checkNetwork() {
+        try {
+            const startTime = Date.now();
+            const blockNumber = await this.magazine.getLatestBlockNumber();
+            const duration = Date.now() - startTime;
+            
+            return {
+                status: duration < this.healthThresholds.responseTime ? 'healthy' : 'degraded',
+                latestBlock: blockNumber,
+                responseTime: duration,
+                message: `Network response time: ${duration}ms`
+            };
+        } catch (error) {
+            return {
+                status: 'critical',
+                error: error.message,
+                message: 'Network connection failed'
+            };
+        }
+    }
+
+    /**
+     * Check database connectivity
+     * @private
+     */
+    async _checkDatabase() {
+        try {
+            const startTime = Date.now();
+            const gun = this.magazine.eventStore.getGunInstance();
+            
+            // Try to read a test value
+            await new Promise((resolve, reject) => {
+                gun.get('_health_check').put({ 
+                    timestamp: Date.now() 
+                }, (ack) => {
+                    if (ack.err) reject(new Error(ack.err));
+                    else resolve(ack);
+                });
+            });
+            
+            const duration = Date.now() - startTime;
+            
+            return {
+                status: duration < 1000 ? 'healthy' : 'degraded',
+                responseTime: duration,
+                message: `Database response time: ${duration}ms`
+            };
+        } catch (error) {
+            return {
+                status: 'critical',
+                error: error.message,
+                message: 'Database connection failed'
+            };
+        }
+    }
+
+    /**
+     * Check sync status
+     * @private
+     */
+    async _checkSyncStatus() {
+        try {
+            const lastSync = this.magazine.eventSyncer.lastSyncTime || 0;
+            const timeSinceSync = Date.now() - lastSync;
+            
+            if (lastSync === 0) {
+                return {
+                    status: 'warning',
+                    message: 'No sync performed yet'
+                };
+            }
+            
+            return {
+                status: timeSinceSync < this.healthThresholds.syncDelay ? 'healthy' : 'warning',
+                lastSync: new Date(lastSync).toISOString(),
+                timeSinceSync,
+                message: `Last sync: ${Math.round(timeSinceSync / 1000)}s ago`
+            };
+        } catch (error) {
+            return {
+                status: 'error',
+                error: error.message,
+                message: 'Could not check sync status'
+            };
+        }
+    }
+
+    /**
+     * Check storage status
+     * @private
+     */
+    async _checkStorage() {
+        try {
+            const stats = await this.magazine.getCompressionStats();
+            const usage = stats.totalCompressedSize / (100 * 1024 * 1024); // Assume 100MB limit
+            
+            return {
+                status: usage < this.healthThresholds.storageUsage ? 'healthy' : 'warning',
+                usage: `${(usage * 100).toFixed(2)}%`,
+                compressed: stats.totalCompressedSize,
+                saved: stats.spaceSaved,
+                message: `Storage usage: ${(usage * 100).toFixed(2)}%`
+            };
+        } catch (error) {
+            return {
+                status: 'error',
+                error: error.message,
+                message: 'Could not check storage status'
+            };
+        }
+    }
+
+    /**
+     * Check performance metrics
+     * @private
+     */
+    _checkPerformance() {
+        const report = this.getPerformanceReport({ timeRange: 300000 }); // Last 5 minutes
+        let status = 'healthy';
+        const issues = [];
+        
+        Object.entries(report.metrics).forEach(([type, metrics]) => {
+            if (metrics.errorRate && parseFloat(metrics.errorRate) > this.healthThresholds.errorRate * 100) {
+                status = 'degraded';
+                issues.push(`High error rate in ${type}: ${metrics.errorRate}`);
+            }
+            
+            if (metrics.average > this.healthThresholds.responseTime) {
+                status = 'degraded';
+                issues.push(`Slow ${type} operations: ${metrics.average}ms average`);
+            }
+        });
+        
+        return {
+            status,
+            metrics: report.metrics,
+            message: issues.length > 0 ? issues.join(', ') : 'Performance metrics within normal range'
+        };
+    }
+
+    /**
+     * Get configuration info
+     * @private
+     */
+    _getConfigInfo() {
+        const config = this.magazine.configManager.getAll();
+        return {
+            name: config.name,
+            address: config.address,
+            networkId: config.networkId,
+            logLevel: this.magazine.logger.level,
+            compression: {
+                enabled: this.magazine.eventStore.compressionEnabled,
+                strategy: this.magazine.eventStore.compressionStrategy
+            }
+        };
+    }
+
+    /**
+     * Get network info
+     * @private
+     */
+    async _getNetworkInfo() {
+        try {
+            const info = await this.magazine.getNetworkInfo();
+            return {
+                ...info,
+                connected: true
+            };
+        } catch (error) {
+            return {
+                connected: false,
+                error: error.message
+            };
+        }
+    }
+
+    /**
+     * Get storage info
+     * @private
+     */
+    async _getStorageInfo() {
+        try {
+            const compressionStats = await this.magazine.getCompressionStats();
+            const eventCount = (await this.magazine.getAllEvents({ pagination: { page: 1, pageSize: 1 } })).meta.totalItems;
+            
+            return {
+                eventCount,
+                ...compressionStats
+            };
+        } catch (error) {
+            return {
+                error: error.message
+            };
+        }
+    }
+
+    /**
+     * Get performance info
+     * @private
+     */
+    _getPerformanceInfo() {
+        return this.getPerformanceReport({ timeRange: 3600000 }); // Last hour
+    }
+
+    /**
+     * Capture a log entry into the circular buffer
+     * @param {Object} entry - Log entry to capture
+     */
+    captureLog(entry) {
+        this._logBuffer.push(entry);
+        if (this._logBuffer.length > this._logBufferMax) {
+            this._logBuffer.shift();
+        }
+    }
+
+    /**
+     * Get recent logs from the circular buffer
+     * @param {number} [count=50] - Number of recent log entries to return
+     * @returns {Array} Recent log entries
+     * @private
+     */
+    _getRecentLogs(count = 50) {
+        const n = Math.min(count, this._logBuffer.length);
+        return this._logBuffer.slice(-n);
+    }
+
+    /**
+     * Calculate percentile
+     * @private
+     */
+    _calculatePercentile(values, percentile) {
+        if (values.length === 0) return 0;
+        
+        const sorted = [...values].sort((a, b) => a - b);
+        const index = Math.ceil((percentile / 100) * sorted.length) - 1;
+        return sorted[index];
+    }
+
+    /**
+     * Instrument methods for metric collection
+     * @private
+     */
+    _instrumentMethods() {
+        const mag = this.magazine;
+        const methodsToInstrument = [
+            'syncEvents',
+            'getAllEvents',
+            'getEvents',
+            'query',
+            'transformEvent'
+        ];
+
+        for (const methodName of methodsToInstrument) {
+            if (typeof mag[methodName] !== 'function') {
+                this.logger.debug(`Skipping instrumentation for missing method: ${methodName}`);
+                continue;
+            }
+
+            // Skip if already instrumented
+            if (this._originalMethods.has(methodName)) {
+                continue;
+            }
+
+            const original = mag[methodName].bind(mag);
+            this._originalMethods.set(methodName, mag[methodName]);
+
+            const self = this;
+            mag[methodName] = function (...args) {
+                const startTime = Date.now();
+                let metricType;
+                if (methodName === 'syncEvents') {
+                    metricType = 'syncOperations';
+                } else if (methodName === 'getAllEvents' || methodName === 'getEvents' || methodName === 'query') {
+                    metricType = 'queryOperations';
+                } else {
+                    metricType = 'storageOperations';
+                }
+
+                try {
+                    const result = original(...args);
+
+                    // Handle both sync and async results
+                    if (result && typeof result.then === 'function') {
+                        return result.then((value) => {
+                            const duration = Date.now() - startTime;
+                            self.recordMetric(metricType, {
+                                method: methodName,
+                                duration,
+                                success: true
+                            });
+                            self.logger.debug(`${methodName} completed in ${duration}ms`);
+                            return value;
+                        }).catch((error) => {
+                            const duration = Date.now() - startTime;
+                            self.recordMetric(metricType, {
+                                method: methodName,
+                                duration,
+                                success: false,
+                                error: error.message
+                            });
+                            self.logger.debug(`${methodName} failed after ${duration}ms: ${error.message}`);
+                            throw error;
+                        });
+                    }
+
+                    const duration = Date.now() - startTime;
+                    self.recordMetric(metricType, {
+                        method: methodName,
+                        duration,
+                        success: true
+                    });
+                    self.logger.debug(`${methodName} completed in ${duration}ms`);
+                    return result;
+                } catch (error) {
+                    const duration = Date.now() - startTime;
+                    self.recordMetric(metricType, {
+                        method: methodName,
+                        duration,
+                        success: false,
+                        error: error.message
+                    });
+                    self.logger.debug(`${methodName} failed after ${duration}ms: ${error.message}`);
+                    throw error;
+                }
+            };
+        }
+
+        this.logger.debug('Method instrumentation enabled');
+    }
+
+    /**
+     * Enable verbose error logging
+     * @private
+     */
+    _enableVerboseErrors() {
+        this._verboseErrors = true;
+
+        const mag = this.magazine;
+        if (typeof mag.retryOperation === 'function' && !this._originalRetryOperation) {
+            const originalRetry = mag.retryOperation.bind(mag);
+            this._originalRetryOperation = mag.retryOperation;
+            const self = this;
+
+            mag.retryOperation = async function (operation, context, ...rest) {
+                try {
+                    return await originalRetry(operation, context, ...rest);
+                } catch (error) {
+                    if (self._verboseErrors) {
+                        self.logger.error('Verbose error context for retryOperation failure', {
+                            operationContext: context,
+                            errorMessage: error.message,
+                            errorStack: error.stack,
+                            errorName: error.name,
+                            timestamp: new Date().toISOString()
+                        });
+                    }
+                    throw error;
+                }
+            };
+        }
+
+        this.logger.debug('Verbose error logging enabled');
+    }
+
+    /**
+     * Set debug mode on/off
+     * @param {boolean} enabled - Whether to enable debug mode
+     */
+    setDebugMode(enabled) {
+        this.debugMode = !!enabled;
+        this.logger.info(`Debug mode ${enabled ? 'enabled' : 'disabled'}`);
+
+        if (enabled) {
+            this._instrumentMethods();
+            this._enableVerboseErrors();
+
+            // Monkey-patch the logger's _log method to capture entries
+            if (this.logger._log && !this._originalLoggerLog) {
+                this._originalLoggerLog = this.logger._log.bind(this.logger);
+                const self = this;
+                this.logger._log = function (level, message, data) {
+                    const result = self._originalLoggerLog(level, message, data);
+                    self.captureLog({
+                        timestamp: Date.now(),
+                        level,
+                        message,
+                        data
+                    });
+                    return result;
+                };
+            }
+        } else {
+            // Restore logger _log if it was patched
+            if (this._originalLoggerLog) {
+                this.logger._log = this._originalLoggerLog;
+                this._originalLoggerLog = null;
+            }
+        }
+    }
+
+    /**
+     * Check if debug mode is enabled
+     * @returns {boolean} Debug mode status
+     */
+    isDebugMode() {
+        return !!this.debugMode;
+    }
+}