@pioneer-platform/pioneer-cache 1.0.0

package/src/core/cache-manager.ts

@@ -0,0 +1,293 @@
+/*
+    CacheManager - Orchestrates all cache instances
+
+    Central coordinator for all cache types (balance, price, transaction).
+    Manages cache lifecycle, health monitoring, and worker coordination.
+*/
+
+import { BalanceCache } from '../stores/balance-cache';
+import { PriceCache } from '../stores/price-cache';
+import { TransactionCache } from '../stores/transaction-cache';
+import { RefreshWorker, startUnifiedWorker } from '../workers/refresh-worker';
+import type { BaseCache } from './base-cache';
+import type { HealthCheckResult } from '../types';
+
+const log = require('@pioneer-platform/loggerdog')();
+const TAG = ' | CacheManager | ';
+
+/**
+ * Configuration for CacheManager
+ */
+export interface CacheManagerConfig {
+    redis: any;
+    balanceModule?: any;                   // Optional: if not provided, balance cache won't be initialized
+    markets?: any;                         // Optional: if not provided, price cache won't be initialized
+    enableBalanceCache?: boolean;
+    enablePriceCache?: boolean;
+    enableTransactionCache?: boolean;
+    startWorkers?: boolean;                // Auto-start workers on initialization
+}
+
+/**
+ * CacheManager - Central coordinator for all caches
+ */
+export class CacheManager {
+    private redis: any;
+    private balanceCache?: BalanceCache;
+    private priceCache?: PriceCache;
+    private transactionCache?: TransactionCache;
+    private workers: RefreshWorker[] = [];
+
+    constructor(config: CacheManagerConfig) {
+        this.redis = config.redis;
+
+        // Initialize Balance Cache
+        if (config.enableBalanceCache !== false && config.balanceModule) {
+            this.balanceCache = new BalanceCache(this.redis, config.balanceModule);
+            log.info(TAG, '✅ Balance cache initialized');
+        }
+
+        // Initialize Price Cache
+        if (config.enablePriceCache !== false && config.markets) {
+            this.priceCache = new PriceCache(this.redis, config.markets);
+            log.info(TAG, '✅ Price cache initialized');
+        }
+
+        // Initialize Transaction Cache
+        if (config.enableTransactionCache !== false) {
+            this.transactionCache = new TransactionCache(this.redis);
+            log.info(TAG, '✅ Transaction cache initialized');
+        }
+
+        // Auto-start workers if requested
+        if (config.startWorkers) {
+            setImmediate(() => {
+                this.startWorkers();
+            });
+        }
+
+        log.info(TAG, '✅ CacheManager initialized');
+    }
+
+    /**
+     * Start background refresh workers for all caches
+     */
+    async startWorkers(): Promise<void> {
+        const tag = TAG + 'startWorkers | ';
+
+        try {
+            log.info(tag, 'Starting refresh workers...');
+
+            // Create cache registry for workers
+            const cacheRegistry = new Map<string, BaseCache<any>>();
+
+            if (this.balanceCache) {
+                cacheRegistry.set('balance', this.balanceCache);
+            }
+
+            if (this.priceCache) {
+                cacheRegistry.set('price', this.priceCache);
+            }
+
+            // Start unified worker if we have any caches with queues
+            if (cacheRegistry.size > 0) {
+                const worker = await startUnifiedWorker(
+                    this.redis,
+                    cacheRegistry,
+                    'cache-refresh',                // Unified queue name
+                    {
+                        maxRetries: 3,
+                        retryDelay: 5000,
+                        pollInterval: 100
+                    }
+                );
+
+                this.workers.push(worker);
+                log.info(tag, '✅ Refresh worker started for all caches');
+            }
+
+        } catch (error) {
+            log.error(tag, '❌ Failed to start workers:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Stop all workers gracefully
+     */
+    async stopWorkers(): Promise<void> {
+        const tag = TAG + 'stopWorkers | ';
+
+        try {
+            log.info(tag, 'Stopping all workers...');
+
+            for (const worker of this.workers) {
+                await worker.stop();
+            }
+
+            this.workers = [];
+            log.info(tag, '✅ All workers stopped');
+
+        } catch (error) {
+            log.error(tag, 'Error stopping workers:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Get aggregate health status for all caches
+     * @param forceRefresh - Force refresh stats (bypasses 30s cache)
+     */
+    async getHealth(forceRefresh: boolean = false): Promise<HealthCheckResult & { checks?: any }> {
+        const tag = TAG + 'getHealth | ';
+
+        try {
+            const checks: any = {};
+            const issues: string[] = [];
+            const warnings: string[] = [];
+
+            // Check balance cache
+            if (this.balanceCache) {
+                const balanceHealth = await this.balanceCache.getHealth(forceRefresh);
+                checks.balance = balanceHealth;
+
+                if (balanceHealth.status === 'unhealthy') {
+                    issues.push(...balanceHealth.issues.map(i => `Balance: ${i}`));
+                } else if (balanceHealth.status === 'degraded') {
+                    warnings.push(...balanceHealth.warnings.map(w => `Balance: ${w}`));
+                }
+            }
+
+            // Check price cache
+            if (this.priceCache) {
+                const priceHealth = await this.priceCache.getHealth(forceRefresh);
+                checks.price = priceHealth;
+
+                if (priceHealth.status === 'unhealthy') {
+                    issues.push(...priceHealth.issues.map(i => `Price: ${i}`));
+                } else if (priceHealth.status === 'degraded') {
+                    warnings.push(...priceHealth.warnings.map(w => `Price: ${w}`));
+                }
+            }
+
+            // Check transaction cache (simple stats check)
+            if (this.transactionCache) {
+                const txStats = await this.transactionCache.getStats();
+                checks.transaction = {
+                    status: 'healthy',
+                    stats: txStats
+                };
+            }
+
+            // Check workers
+            for (const worker of this.workers) {
+                const workerStats = await worker.getStats();
+                checks.worker = workerStats;
+
+                if (!workerStats.isRunning) {
+                    issues.push('Refresh worker not running');
+                }
+            }
+
+            // Determine overall status
+            let status: 'healthy' | 'degraded' | 'unhealthy' = 'healthy';
+            if (issues.length > 0) {
+                status = 'unhealthy';
+            } else if (warnings.length > 0) {
+                status = 'degraded';
+            }
+
+            return {
+                status,
+                queueInitialized: this.workers.length > 0,
+                redisConnected: true,
+                stats: {
+                    totalEntries: 0,
+                    staleEntries: 0,
+                    freshEntries: 0,
+                    stalenessRate: '0%'
+                },
+                issues,
+                warnings,
+                timestamp: Date.now(),
+                timestampISO: new Date().toISOString(),
+                checks
+            };
+
+        } catch (error) {
+            log.error(tag, 'Health check failed:', error);
+            return {
+                status: 'unhealthy',
+                queueInitialized: false,
+                redisConnected: false,
+                stats: {
+                    totalEntries: 0,
+                    staleEntries: 0,
+                    freshEntries: 0,
+                    stalenessRate: '0%'
+                },
+                issues: [`Health check error: ${error instanceof Error ? error.message : String(error)}`],
+                warnings: [],
+                timestamp: Date.now(),
+                timestampISO: new Date().toISOString()
+            };
+        }
+    }
+
+    /**
+     * Get all cache instances
+     */
+    getCaches() {
+        return {
+            balance: this.balanceCache,
+            price: this.priceCache,
+            transaction: this.transactionCache
+        };
+    }
+
+    /**
+     * Get specific cache by name
+     */
+    getCache(name: 'balance' | 'price' | 'transaction') {
+        switch (name) {
+            case 'balance':
+                return this.balanceCache;
+            case 'price':
+                return this.priceCache;
+            case 'transaction':
+                return this.transactionCache;
+            default:
+                return undefined;
+        }
+    }
+
+    /**
+     * Clear all caches (use with caution!)
+     */
+    async clearAll(): Promise<{ balance?: number; price?: number; transaction?: number }> {
+        const tag = TAG + 'clearAll | ';
+
+        try {
+            const result: any = {};
+
+            if (this.balanceCache) {
+                result.balance = await this.balanceCache.clearAll();
+            }
+
+            if (this.priceCache) {
+                result.price = await this.priceCache.clearAll();
+            }
+
+            if (this.transactionCache) {
+                result.transaction = await this.transactionCache.clearAll();
+            }
+
+            log.info(tag, 'Cleared all caches:', result);
+            return result;
+
+        } catch (error) {
+            log.error(tag, 'Error clearing caches:', error);
+            throw error;
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/*
+    @pioneer-platform/pioneer-cache
+
+    Unified caching system for Pioneer Platform.
+    Provides stale-while-revalidate caching with TTL, background refresh, and health monitoring.
+*/
+
+// Core exports
+export { BaseCache } from './core/base-cache';
+export { CacheManager } from './core/cache-manager';
+
+// Cache implementations
+export { BalanceCache } from './stores/balance-cache';
+export { PriceCache } from './stores/price-cache';
+export { TransactionCache } from './stores/transaction-cache';
+
+// Worker exports
+export { RefreshWorker, startUnifiedWorker } from './workers/refresh-worker';
+
+// Type exports
+export type {
+    CacheConfig,
+    CachedValue,
+    CacheResult,
+    RefreshJob,
+    HealthCheckResult,
+    CacheStats
+} from './types';
+
+// Data type exports
+export type { BalanceData } from './stores/balance-cache';
+export type { PriceData } from './stores/price-cache';
+
+// Config type export
+export type { CacheManagerConfig } from './core/cache-manager';
+export type { WorkerConfig } from './workers/refresh-worker';

package/src/stores/balance-cache.ts

@@ -0,0 +1,196 @@
+/*
+    BalanceCache - Balance-specific cache implementation
+
+    Extends BaseCache with balance-specific logic.
+    All common logic is inherited from BaseCache.
+*/
+
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+
+const log = require('@pioneer-platform/loggerdog')();
+
+/**
+ * Balance data structure
+ */
+export interface BalanceData {
+    caip: string;
+    pubkey: string;
+    balance: string;
+    priceUsd?: string;
+    valueUsd?: string;
+    symbol?: string;
+    name?: string;
+    networkId?: string;
+}
+
+/**
+ * BalanceCache - Caches blockchain balance data
+ */
+export class BalanceCache extends BaseCache<BalanceData> {
+    private balanceModule: any;
+
+    constructor(redis: any, balanceModule: any, config?: Partial<CacheConfig>) {
+        const defaultConfig: CacheConfig = {
+            name: 'balance',
+            keyPrefix: 'balance_v2:',
+            ttl: 5 * 60 * 1000,                    // 5 minutes
+            staleThreshold: 2 * 60 * 1000,         // 2 minutes
+            enableTTL: true,
+            queueName: 'balance-refresh-v2',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 10000,
+            blockOnMiss: true,                     // Wait for fresh data on first request
+            enableLegacyFallback: true,
+            defaultValue: {
+                caip: '',
+                pubkey: '',
+                balance: '0',
+            },
+            maxConcurrentJobs: 10,
+            apiTimeout: 15000,
+            logCacheHits: false,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+
+        super(redis, { ...defaultConfig, ...config });
+        this.balanceModule = balanceModule;
+    }
+
+    /**
+     * Build Redis key for balance data
+     * Format: balance_v2:caip:pubkey
+     */
+    protected buildKey(params: Record<string, any>): string {
+        const { caip, pubkey } = params;
+        if (!caip || !pubkey) {
+            throw new Error('BalanceCache.buildKey: caip and pubkey required');
+        }
+
+        const normalizedCaip = caip.toLowerCase();
+        // Don't lowercase pubkeys - xpub/ypub/zpub are case-sensitive base58
+        const normalizedPubkey = pubkey;
+
+        return `${this.config.keyPrefix}${normalizedCaip}:${normalizedPubkey}`;
+    }
+
+    /**
+     * Fetch balance from blockchain via balance module
+     */
+    protected async fetchFromSource(params: Record<string, any>): Promise<BalanceData> {
+        const tag = this.TAG + 'fetchFromSource | ';
+
+        try {
+            const { caip, pubkey } = params;
+
+            // Fetch balance using balance module
+            const asset = { caip };
+            const owner = { pubkey };
+            const balanceInfo = await this.balanceModule.getBalance(asset, owner);
+
+            if (!balanceInfo || !balanceInfo.balance) {
+                log.warn(tag, `No balance returned for ${caip}/${pubkey.substring(0, 10)}...`);
+                return {
+                    caip,
+                    pubkey,
+                    balance: '0'
+                };
+            }
+
+            // Get asset metadata
+            const assetData = require('@pioneer-platform/pioneer-discovery').assetData;
+            const { caipToNetworkId } = require('@pioneer-platform/pioneer-caip');
+
+            const assetInfo = assetData[caip.toUpperCase()] || assetData[caip.toLowerCase()] || {};
+            const networkId = caipToNetworkId(caip);
+
+            return {
+                caip,
+                pubkey,
+                balance: balanceInfo.balance,
+                symbol: assetInfo.symbol,
+                name: assetInfo.name,
+                networkId
+            };
+
+        } catch (error) {
+            log.error(tag, 'Error fetching balance:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Try to get balance from legacy cache format
+     */
+    protected async getLegacyCached(params: Record<string, any>): Promise<BalanceData | null> {
+        const tag = this.TAG + 'getLegacyCached | ';
+
+        try {
+            const { caip, pubkey } = params;
+            const { caipToNetworkId } = require('@pioneer-platform/pioneer-caip');
+            const networkId = caipToNetworkId(caip);
+
+            // Try legacy format: cache:balance:pubkey:asset
+            const legacyKey = `cache:balance:${pubkey}:${networkId}`;
+            const legacyData = await this.redis.get(legacyKey);
+
+            if (legacyData) {
+                const parsed = JSON.parse(legacyData);
+                if (parsed.balance !== undefined) {
+                    return {
+                        caip,
+                        pubkey,
+                        balance: typeof parsed.balance === 'string' ? parsed.balance : String(parsed.balance)
+                    };
+                }
+            }
+
+            return null;
+
+        } catch (error) {
+            log.error(tag, 'Error getting legacy cached balance:', error);
+            return null;
+        }
+    }
+
+    /**
+     * Get balance for a specific asset and pubkey
+     * Convenience method that wraps base get()
+     */
+    async getBalance(caip: string, pubkey: string, waitForFresh?: boolean): Promise<BalanceData> {
+        const result = await this.get({ caip, pubkey }, waitForFresh);
+        return result.value || this.config.defaultValue;
+    }
+
+    /**
+     * Get balances for multiple assets (batch operation)
+     */
+    async getBatchBalances(items: Array<{ caip: string; pubkey: string }>, waitForFresh?: boolean): Promise<BalanceData[]> {
+        const tag = this.TAG + 'getBatchBalances | ';
+        const startTime = Date.now();
+
+        try {
+            log.info(tag, `Batch request for ${items.length} balances`);
+
+            // Get all balances in parallel
+            const promises = items.map(item => this.getBalance(item.caip, item.pubkey, waitForFresh));
+            const results = await Promise.all(promises);
+
+            const responseTime = Date.now() - startTime;
+            log.info(tag, `Batch completed: ${results.length} balances in ${responseTime}ms (${(responseTime / results.length).toFixed(1)}ms avg)`);
+
+            return results;
+
+        } catch (error) {
+            log.error(tag, 'Error in batch balance request:', error);
+            // Return defaults for all items
+            return items.map(item => ({
+                caip: item.caip,
+                pubkey: item.pubkey,
+                balance: '0'
+            }));
+        }
+    }
+}