@sschepis/magazine 0.1.0

package/src/components/EventSyncer.js

@@ -0,0 +1,353 @@
+import Logger from './Logger.js';
+
+/**
+ * EventSyncer - Handles blockchain event synchronization logic
+ */
+export default class EventSyncer {
+    constructor(networkManager, eventStore, configManager, retryOperation) {
+        this.networkManager = networkManager;
+        this.eventStore = eventStore;
+        this.configManager = configManager;
+        this.retryOperation = retryOperation;
+        
+        this.logger = new Logger({
+            context: 'EventSyncer',
+            level: configManager.get('logLevel') || 'info'
+        });
+        
+        // Configuration for batch processing
+        this.batchSize = 1000; // Process events in batches of 1000 blocks
+        this.lastSyncTime = 0;
+        
+        this.logger.info('EventSyncer initialized', {
+            batchSize: this.batchSize
+        });
+    }
+
+    // Sync events from the blockchain to the magazine
+    async syncEvents() {
+        if (this._syncing) {
+            this.logger.warn('Sync already in progress, skipping');
+            return 0;
+        }
+        this._setSyncing(true);
+        try {
+        return await this.logger.time('syncEvents', async () => {
+            return this.retryOperation(async () => {
+                // Get the starting block number and latest block number
+                const startBlockNumber = await this.eventStore.getStartBlockNumber();
+                const latestBlockNumber = await this.networkManager.getLatestBlockNumber();
+                
+                if (startBlockNumber > latestBlockNumber) {
+                    this.logger.info('Already up to date', {
+                        startBlockNumber,
+                        latestBlockNumber
+                    });
+                    return;
+                }
+
+                this.logger.info('Starting event synchronization', {
+                    startBlockNumber,
+                    latestBlockNumber,
+                    totalBlocks: latestBlockNumber - startBlockNumber + 1
+                });
+                
+                // Process events in batches to avoid overwhelming the provider
+                let currentStart = startBlockNumber;
+                let totalEventsProcessed = 0;
+                
+                while (currentStart <= latestBlockNumber) {
+                    const currentEnd = Math.min(currentStart + this.batchSize - 1, latestBlockNumber);
+                    
+                    const batchEvents = await this._processBatch(currentStart, currentEnd);
+                    totalEventsProcessed += batchEvents;
+                    currentStart = currentEnd + 1;
+                }
+                
+                // Update the start block number for next sync
+                await this.eventStore.setStartBlockNumber(latestBlockNumber + 1);
+
+                this.lastSyncTime = Date.now();
+
+                this.logger.info('Event synchronization completed', {
+                    totalEventsProcessed,
+                    newStartBlockNumber: latestBlockNumber + 1
+                });
+
+                return totalEventsProcessed;
+            }, 'Event synchronization');
+        });
+        } finally {
+            this._setSyncing(false);
+        }
+    }
+
+    // Process a batch of blocks for events
+    async _processBatch(fromBlock, toBlock) {
+        return this.logger.time('processBatch', async () => {
+            this.logger.debug('Processing batch', { fromBlock, toBlock });
+            
+            const logs = await this.networkManager.getLogs(fromBlock, toBlock);
+            let eventsStored = 0;
+            
+            // Process each log
+            for (const log of logs) {
+                const parsedEvent = this.networkManager.parseLog(log);
+                
+                if (parsedEvent) {
+                    try {
+                        // Store event with unique key to prevent duplicates
+                        const eventKey = this.networkManager.createEventKey(log);
+                        await this.eventStore.storeEvent(
+                            parsedEvent.eventName,
+                            eventKey,
+                            parsedEvent.eventData
+                        );
+                        eventsStored++;
+                        
+                        this.logger.trace('Event stored', {
+                            eventName: parsedEvent.eventName,
+                            eventKey,
+                            blockNumber: log.blockNumber
+                        });
+                    } catch (error) {
+                        this.logger.warn('Failed to store event', {
+                            eventName: parsedEvent.eventName,
+                            blockNumber: log.blockNumber,
+                            transactionHash: log.transactionHash,
+                            error: error.message
+                        });
+                    }
+                }
+            }
+            
+            this.logger.debug('Batch processing completed', {
+                fromBlock,
+                toBlock,
+                logsFound: logs.length,
+                eventsStored
+            });
+            
+            return eventsStored;
+        }, { fromBlock, toBlock });
+    }
+
+    // Sync events from a specific block range
+    async syncEventsFromRange(fromBlock, toBlock) {
+        this.configManager.validateBlockNumber(fromBlock, 'fromBlock');
+        this.configManager.validateBlockNumber(toBlock, 'toBlock');
+
+        if (fromBlock > toBlock) {
+            throw new Error('fromBlock cannot be greater than toBlock');
+        }
+
+        if (this._syncing) {
+            this.logger.warn('Sync already in progress, skipping range sync');
+            return 0;
+        }
+        this._setSyncing(true);
+        try {
+        return await this.logger.time('syncEventsFromRange', async () => {
+            return this.retryOperation(async () => {
+                this.logger.info('Syncing events from specific range', {
+                    fromBlock,
+                    toBlock,
+                    totalBlocks: toBlock - fromBlock + 1
+                });
+                
+                // Process the range in batches
+                let currentStart = fromBlock;
+                let totalEventsProcessed = 0;
+                
+                while (currentStart <= toBlock) {
+                    const currentEnd = Math.min(currentStart + this.batchSize - 1, toBlock);
+                    const batchEvents = await this._processBatch(currentStart, currentEnd);
+                    totalEventsProcessed += batchEvents;
+                    currentStart = currentEnd + 1;
+                }
+                
+                this.lastSyncTime = Date.now();
+
+                this.logger.info('Range synchronization completed', {
+                    fromBlock,
+                    toBlock,
+                    totalEventsProcessed
+                });
+
+                return totalEventsProcessed;
+            }, `Event synchronization for range ${fromBlock}-${toBlock}`);
+        }, { fromBlock, toBlock });
+        } finally {
+            this._setSyncing(false);
+        }
+    }
+
+    // Sync events from a specific transaction
+    async syncEventsFromTransaction(txHash) {
+        if (!txHash || typeof txHash !== 'string') {
+            throw new Error('Transaction hash must be a non-empty string');
+        }
+
+        return this.retryOperation(async () => {
+            const receipt = await this.networkManager.getTransactionReceipt(txHash);
+            if (!receipt) {
+                throw new Error(`Transaction ${txHash} not found`);
+            }
+
+            const contractAddress = this.configManager.get('address').toLowerCase();
+            const relevantLogs = receipt.logs.filter(
+                log => log.address.toLowerCase() === contractAddress
+            );
+
+            for (const log of relevantLogs) {
+                const parsedEvent = this.networkManager.parseLog(log);
+
+                if (parsedEvent) {
+                    const eventKey = this.networkManager.createEventKey(log);
+                    await this.eventStore.storeEvent(
+                        parsedEvent.eventName,
+                        eventKey,
+                        parsedEvent.eventData
+                    );
+                }
+            }
+
+            this.lastSyncTime = Date.now();
+            return relevantLogs.length;
+        }, `Syncing events from transaction ${txHash}`);
+    }
+
+    // Get sync status information
+    async getSyncStatus() {
+        return this.retryOperation(async () => {
+            const startBlockNumber = await this.eventStore.getStartBlockNumber();
+            const latestBlockNumber = await this.networkManager.getLatestBlockNumber();
+            const networkInfo = await this.networkManager.getNetworkInfo();
+            
+            return {
+                nextSyncBlock: startBlockNumber,
+                latestNetworkBlock: latestBlockNumber,
+                blocksBehind: Math.max(0, latestBlockNumber - startBlockNumber + 1),
+                networkInfo,
+                isUpToDate: startBlockNumber > latestBlockNumber
+            };
+        }, 'Getting sync status');
+    }
+
+    // Validate network and contract before syncing
+    async validateBeforeSync() {
+        await this.networkManager.validateNetwork();
+        await this.networkManager.validateContract();
+        return true;
+    }
+
+    // Set batch size for processing (useful for performance tuning)
+    setBatchSize(size) {
+        if (!Number.isInteger(size) || size < 1) {
+            throw new Error('Batch size must be a positive integer');
+        }
+        this.batchSize = size;
+    }
+
+    // Get current batch size
+    getBatchSize() {
+        return this.batchSize;
+    }
+
+    // Reset sync position to a specific block
+    async resetSyncPosition(blockNumber) {
+        this.configManager.validateBlockNumber(blockNumber, 'blockNumber');
+        await this.eventStore.setStartBlockNumber(blockNumber);
+    }
+
+    // Get events count by name
+    async getEventCount(eventName) {
+        const events = await this.eventStore.getEvents(eventName);
+        return events.length;
+    }
+
+    /**
+     * Start real-time event streaming via WebSocket or EventEmitter provider.
+     */
+    startRealtimeSync() {
+        const provider = this.networkManager.getProvider();
+
+        if (!provider || typeof provider.on !== 'function') {
+            throw new Error(
+                'Real-time sync requires a provider that supports event subscriptions ' +
+                '(e.g., WebSocketProvider). The current provider does not have an .on() method.'
+            );
+        }
+
+        if (this._realtimeListener) {
+            this.logger.warn('Real-time sync is already running, call stopRealtimeSync() first');
+            return;
+        }
+
+        const contractAddress = this.configManager.get('address');
+        const filter = { address: contractAddress };
+
+        this.logger.info('Starting real-time event sync', {
+            contractAddress,
+            providerType: provider.constructor.name
+        });
+
+        const listener = async (log) => {
+            try {
+                const parsedEvent = this.networkManager.parseLog(log);
+                if (parsedEvent) {
+                    const eventKey = this.networkManager.createEventKey(log);
+                    await this.eventStore.storeEvent(
+                        parsedEvent.eventName,
+                        eventKey,
+                        parsedEvent.eventData
+                    );
+                    this.logger.debug('Real-time event stored', {
+                        eventName: parsedEvent.eventName,
+                        eventKey,
+                        blockNumber: log.blockNumber
+                    });
+                }
+            } catch (error) {
+                this.logger.warn('Failed to process real-time event', {
+                    blockNumber: log.blockNumber,
+                    error: error.message
+                });
+            }
+        };
+
+        provider.on(filter, listener);
+        this._realtimeListener = listener;
+        this._realtimeFilter = filter;
+        this.logger.info('Real-time event sync started');
+    }
+
+    /**
+     * Stop real-time event streaming and clean up the listener.
+     */
+    stopRealtimeSync() {
+        if (!this._realtimeListener) {
+            this.logger.debug('No real-time sync listener to stop');
+            return;
+        }
+
+        const provider = this.networkManager.getProvider();
+        if (provider && typeof provider.off === 'function') {
+            provider.off(this._realtimeFilter, this._realtimeListener);
+            this.logger.info('Real-time event sync stopped');
+        }
+
+        this._realtimeListener = null;
+        this._realtimeFilter = null;
+    }
+
+    // Check if syncer is busy (for preventing concurrent syncs)
+    isSyncing() {
+        return this._syncing || false;
+    }
+
+    // Set syncing state
+    _setSyncing(state) {
+        this._syncing = state;
+    }
+}

package/src/components/Logger.js

@@ -0,0 +1,299 @@
+/**
+ * Logger - Structured logging system with configurable levels
+ */
+export default class Logger {
+    constructor(config = {}) {
+        this.level = config.level || 'info';
+        this.context = config.context || 'Magazine';
+        this.enableConsole = config.enableConsole !== false;
+        this.enableFile = config.enableFile || false;
+        this.filePath = config.filePath || './magazine.log';
+
+        // File logging state (lazily initialized)
+        this._fsModule = null;
+        this._fsAvailable = null; // null = not yet checked, true/false after init
+
+        // Log levels with numeric values for comparison
+        this.levels = {
+            error: 0,
+            warn: 1,
+            info: 2,
+            debug: 3,
+            trace: 4
+        };
+
+        this.currentLevelValue = this.levels[this.level.toLowerCase()] || this.levels.info;
+
+        // Initialize file logging if enabled
+        if (this.enableFile) {
+            this._initFileLogging();
+        }
+    }
+
+    // Create a formatted log entry
+    _formatLog(level, message, data = {}) {
+        const timestamp = new Date().toISOString();
+        const logEntry = {
+            timestamp,
+            level: level.toUpperCase(),
+            context: this.context,
+            message,
+            ...data
+        };
+
+        return {
+            formatted: `[${timestamp}] ${level.toUpperCase()} [${this.context}] ${message}${
+                Object.keys(data).length > 0 ? ' ' + JSON.stringify(data, this._getCircularReplacer()) : ''
+            }`,
+            structured: logEntry
+        };
+    }
+
+    // Get a replacer function to handle circular references in JSON.stringify
+    _getCircularReplacer() {
+        const seen = new WeakSet();
+        return (key, value) => {
+            if (typeof value === "object" && value !== null) {
+                if (seen.has(value)) {
+                    return "[Circular]";
+                }
+                seen.add(value);
+            }
+            return value;
+        };
+    }
+
+    // Check if current level allows logging at specified level
+    _shouldLog(level) {
+        const levelValue = this.levels[level.toLowerCase()];
+        return levelValue !== undefined && levelValue <= this.currentLevelValue;
+    }
+
+    // Write log to console
+    _writeToConsole(level, formatted) {
+        if (!this.enableConsole) return;
+        
+        switch (level.toLowerCase()) {
+            case 'error':
+                console.error(formatted);
+                break;
+            case 'warn':
+                console.warn(formatted);
+                break;
+            case 'debug':
+            case 'trace':
+                console.debug(formatted);
+                break;
+            default:
+                console.log(formatted);
+        }
+    }
+
+    // Initialize file system module for file logging
+    _initFileLogging() {
+        if (this._fsAvailable !== null) return; // already initialized
+
+        try {
+            // Use dynamic import to support both Node.js and browser environments.
+            // import() returns a promise, so we kick it off here and store the result
+            // once resolved. File writes before init completes are silently skipped.
+            const fsPromise = import('fs');
+            const pathPromise = import('path');
+
+            Promise.all([fsPromise, pathPromise]).then(([fsModule, pathModule]) => {
+                this._fsModule = fsModule.default || fsModule;
+                this._pathModule = pathModule.default || pathModule;
+                this._fsAvailable = true;
+            }).catch(() => {
+                this._fsAvailable = false;
+            });
+        } catch (_err) {
+            // Static import() not available (older environments) - disable file logging
+            this._fsAvailable = false;
+        }
+    }
+
+    // Write log entry as a JSON line to the configured file
+    _writeToFile(structured) {
+        if (!this.enableFile) return;
+        if (this._fsAvailable === false) return;
+        if (!this._fsModule) return; // fs not yet loaded (async init still pending)
+
+        try {
+            const line = JSON.stringify(structured, this._getCircularReplacer()) + '\n';
+            this._fsModule.appendFileSync(this.filePath, line, 'utf8');
+        } catch (_err) {
+            // File logging failures must not crash the application
+        }
+    }
+
+    // Rotate log file if it exceeds maxSizeBytes. Keeps 1 rotated backup.
+    rotateLogs(maxSizeBytes = 10 * 1024 * 1024) {
+        if (!this._fsModule || this._fsAvailable === false) return;
+
+        try {
+            if (!this._fsModule.existsSync(this.filePath)) return;
+
+            const stats = this._fsModule.statSync(this.filePath);
+            if (stats.size < maxSizeBytes) return;
+
+            const backupPath = this.filePath + '.1';
+
+            // Remove old backup if it exists, then rename current to backup
+            if (this._fsModule.existsSync(backupPath)) {
+                this._fsModule.unlinkSync(backupPath);
+            }
+            this._fsModule.renameSync(this.filePath, backupPath);
+
+            // Start a fresh log file
+            this._fsModule.writeFileSync(this.filePath, '', 'utf8');
+        } catch (_err) {
+            // Rotation failures must not crash the application
+        }
+    }
+
+    // Core logging method
+    _log(level, message, data = {}) {
+        if (!this._shouldLog(level)) return;
+        
+        const { formatted, structured } = this._formatLog(level, message, data);
+        
+        this._writeToConsole(level, formatted);
+        this._writeToFile(structured);
+        
+        return structured;
+    }
+
+    // Logging level methods
+    error(message, data = {}) {
+        return this._log('error', message, data);
+    }
+
+    warn(message, data = {}) {
+        return this._log('warn', message, data);
+    }
+
+    info(message, data = {}) {
+        return this._log('info', message, data);
+    }
+
+    debug(message, data = {}) {
+        return this._log('debug', message, data);
+    }
+
+    trace(message, data = {}) {
+        return this._log('trace', message, data);
+    }
+
+    // Performance logging - measure function execution time
+    async time(operation, fn, context = {}) {
+        const startTime = Date.now();
+        const startMessage = `Starting operation: ${operation}`;
+        
+        this.debug(startMessage, context);
+        
+        try {
+            const result = await fn();
+            const duration = Date.now() - startTime;
+            
+            this.info(`Completed operation: ${operation}`, {
+                ...context,
+                duration: `${duration}ms`,
+                success: true
+            });
+            
+            return result;
+        } catch (error) {
+            const duration = Date.now() - startTime;
+            
+            this.error(`Failed operation: ${operation}`, {
+                ...context,
+                duration: `${duration}ms`,
+                success: false,
+                error: error?.message || error?.toString() || 'Unknown error',
+                stack: error?.stack
+            });
+            
+            throw error;
+        }
+    }
+
+    // Create a child logger with additional context
+    child(additionalContext = {}) {
+        return new Logger({
+            level: this.level,
+            context: this.context,
+            enableConsole: this.enableConsole,
+            enableFile: this.enableFile,
+            filePath: this.filePath,
+            ...additionalContext
+        });
+    }
+
+    // Change log level dynamically
+    setLevel(level) {
+        if (this.levels[level.toLowerCase()] !== undefined) {
+            this.level = level.toLowerCase();
+            this.currentLevelValue = this.levels[this.level];
+            this.info(`Log level changed to: ${level.toUpperCase()}`);
+        } else {
+            this.warn(`Invalid log level: ${level}. Valid levels: ${Object.keys(this.levels).join(', ')}`);
+        }
+    }
+
+    // Get current configuration
+    getConfig() {
+        return {
+            level: this.level,
+            context: this.context,
+            enableConsole: this.enableConsole,
+            enableFile: this.enableFile,
+            filePath: this.filePath
+        };
+    }
+
+    // Log system information
+    logSystemInfo(info = {}) {
+        this.info('System Information', {
+            nodeVersion: process.version,
+            platform: process.platform,
+            arch: process.arch,
+            memoryUsage: process.memoryUsage(),
+            uptime: process.uptime(),
+            ...info
+        });
+    }
+
+    // Log network request/response
+    logNetworkActivity(type, details = {}) {
+        this.debug(`Network ${type}`, {
+            type,
+            timestamp: Date.now(),
+            ...details
+        });
+    }
+
+    // Log blockchain interaction
+    logBlockchainActivity(operation, details = {}) {
+        this.info(`Blockchain: ${operation}`, {
+            operation,
+            timestamp: Date.now(),
+            ...details
+        });
+    }
+
+    // Log Gun.js database activity
+    logDatabaseActivity(operation, details = {}) {
+        this.debug(`Database: ${operation}`, {
+            operation,
+            timestamp: Date.now(),
+            ...details
+        });
+    }
+}
+
+// Export a default logger instance
+export const defaultLogger = new Logger({
+    level: 'info',
+    context: 'Magazine'
+});