Oracle Integration Patterns

// Naive Pattern - DON'T DO THIS
async function getAssetPrice(asset) {
    const oracleAccount = 'rOracleAccount...';
    const priceData = await xrplClient.getAccountObjects({
        account: oracleAccount,
        type: 'OracleObject',
        oracle_document_id: asset
    });
    
    return parseOraclePrice(priceData);
}

// Called frequently throughout the application
const btcPrice = await getAssetPrice('BTC');
const ethPrice = await getAssetPrice('ETH');

class CachedOracleConsumer {
    constructor(xrplClient, cacheConfig) {
        this.client = xrplClient;
        this.cache = new Map();
        this.cacheConfig = cacheConfig;
        this.requestMetrics = new Map();
    }
    
    async getOracleData(oracleId, dataKey, freshnessWindow = 30000) {
        const cacheKey = `${oracleId}:${dataKey}`;
        const cached = this.cache.get(cacheKey);
        
        // Return cached data if within freshness window
        if (cached && (Date.now() - cached.timestamp) < freshnessWindow) {
            this.recordMetric(cacheKey, 'cache_hit');
            return cached.data;
        }
        
        try {
            // Fetch fresh data from oracle
            const freshData = await this.fetchOracleData(oracleId, dataKey);
            
            // Update cache
            this.cache.set(cacheKey, {
                data: freshData,
                timestamp: Date.now()
            });
            
            this.recordMetric(cacheKey, 'cache_miss');
            return freshData;
            
        } catch (error) {
            // Return stale data if available and error is recoverable
            if (cached && this.isRecoverableError(error)) {
                this.recordMetric(cacheKey, 'stale_fallback');
                return cached.data;
            }
            throw error;
        }
    }
}

class OracleCircuitBreaker {
    constructor(config = {}) {
        this.failureThreshold = config.failureThreshold || 5;
        this.recoveryTimeout = config.recoveryTimeout || 60000;
        this.requestTimeout = config.requestTimeout || 10000;
        
        this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
        this.failureCount = 0;
        this.lastFailureTime = null;
        this.successCount = 0;
    }
    
    async executeWithCircuitBreaker(oracleFunction) {
        if (this.state === 'OPEN') {
            if (Date.now() - this.lastFailureTime > this.recoveryTimeout) {
                this.state = 'HALF_OPEN';
                this.successCount = 0;
            } else {
                throw new Error('Circuit breaker is OPEN - oracle unavailable');
            }
        }
        
        try {
            const result = await Promise.race([
                oracleFunction(),
                new Promise((_, reject) => 
                    setTimeout(() => reject(new Error('Oracle timeout')), 
                    this.requestTimeout)
                )
            ]);
            
            this.onSuccess();
            return result;
            
        } catch (error) {
            this.onFailure();
            throw error;
        }
    }
    
    onSuccess() {
        if (this.state === 'HALF_OPEN') {
            this.successCount++;
            if (this.successCount >= 3) {
                this.state = 'CLOSED';
                this.failureCount = 0;
            }
        } else {
            this.failureCount = Math.max(0, this.failureCount - 1);
        }
    }
    
    onFailure() {
        this.failureCount++;
        this.lastFailureTime = Date.now();
        
        if (this.failureCount >= this.failureThreshold) {
            this.state = 'OPEN';
        }
    }
}

class MultiTierOracleCache {
    constructor(config) {
        // L1: In-memory cache for ultra-fast access
        this.l1Cache = new LRUCache({ max: 1000, ttl: 30000 });
        
        // L2: Redis cache for shared access across instances
        this.l2Cache = new Redis(config.redis);
        
        // L3: Database cache for persistence across restarts
        this.l3Cache = config.database;
        
        this.metrics = new MetricsCollector();
    }
    
    async get(key, freshnessWindow) {
        // Try L1 cache first
        const l1Result = this.l1Cache.get(key);
        if (l1Result && this.isFresh(l1Result, freshnessWindow)) {
            this.metrics.increment('cache.l1.hit');
            return l1Result.data;
        }
        
        // Try L2 cache
        const l2Result = await this.l2Cache.get(key);
        if (l2Result) {
            const parsed = JSON.parse(l2Result);
            if (this.isFresh(parsed, freshnessWindow)) {
                // Populate L1 cache
                this.l1Cache.set(key, parsed);
                this.metrics.increment('cache.l2.hit');
                return parsed.data;
            }
        }
        
        // Try L3 cache for fallback data
        const l3Result = await this.l3Cache.findOne({ key });
        if (l3Result && this.isAcceptableForFallback(l3Result, freshnessWindow)) {
            this.metrics.increment('cache.l3.hit');
            return l3Result.data;
        }
        
        this.metrics.increment('cache.miss');
        return null;
    }
    
    async set(key, data) {
        const cacheEntry = {
            data,
            timestamp: Date.now(),
            version: this.generateVersion()
        };
        
        // Write to all cache levels
        this.l1Cache.set(key, cacheEntry);
        await this.l2Cache.setex(key, 3600, JSON.stringify(cacheEntry));
        await this.l3Cache.upsert({ key }, cacheEntry);
    }
}

class IntelligentCacheWarmer {
    constructor(oracleConsumer, scheduler) {
        this.consumer = oracleConsumer;
        this.scheduler = scheduler;
        this.usagePatterns = new Map();
        this.warmingQueue = new PriorityQueue();
    }
    
    // Learn from usage patterns to predict future needs
    recordUsage(dataKey, context) {
        const pattern = this.usagePatterns.get(dataKey) || {
            frequency: 0,
            lastAccess: 0,
            contexts: new Set(),
            timeDistribution: []
        };
        
        pattern.frequency++;
        pattern.lastAccess = Date.now();
        pattern.contexts.add(context);
        pattern.timeDistribution.push(new Date().getHours());
        
        this.usagePatterns.set(dataKey, pattern);
        
        // Schedule warming based on predicted next access
        this.scheduleWarming(dataKey, pattern);
    }
    
    scheduleWarming(dataKey, pattern) {
        // Predict next access time based on historical patterns
        const avgInterval = this.calculateAverageInterval(pattern.timeDistribution);
        const nextWarmingTime = Date.now() + (avgInterval * 0.8); // Warm 20% early
        
        this.warmingQueue.enqueue({
            dataKey,
            scheduledTime: nextWarmingTime,
            priority: pattern.frequency
        });
    }
    
    async executeWarming() {
        while (!this.warmingQueue.isEmpty()) {
            const item = this.warmingQueue.peek();
            
            if (item.scheduledTime > Date.now()) {
                break; // Wait for scheduled time
            }
            
            this.warmingQueue.dequeue();
            
            try {
                // Warm cache by fetching fresh data
                await this.consumer.getOracleData(
                    item.dataKey.oracleId,
                    item.dataKey.key,
                    0 // Force fresh fetch
                );
                
                this.metrics.increment('cache.warming.success');
            } catch (error) {
                this.metrics.increment('cache.warming.failure');
                // Reschedule with backoff
                this.scheduleWarming(item.dataKey, { frequency: 1 });
            }
        }
    }
}

class CostAwareCachePolicy {
    constructor(costModel) {
        this.costModel = costModel;
        this.budgetManager = new OracleBudgetManager();
    }
    
    calculateOptimalCacheTTL(dataKey, usagePattern) {
        const oracleCost = this.costModel.getQueryCost(dataKey);
        const stalnessCost = this.costModel.getStalnessCost(dataKey);
        const queryFrequency = usagePattern.frequency;
        
        // Minimize total cost = oracle_cost + staleness_cost
        // Oracle cost decreases with longer TTL (fewer queries)
        // Staleness cost increases with longer TTL (more stale data)
        
        const optimalTTL = this.findCostMinimizingTTL(
            oracleCost,
            stalnessCost,
            queryFrequency
        );
        
        return Math.max(optimalTTL, this.costModel.getMinimumTTL(dataKey));
    }
    
    shouldRefreshCache(dataKey, cacheAge, currentBudget) {
        const refreshCost = this.costModel.getQueryCost(dataKey);
        const stalnessPenalty = this.costModel.getStalnessPenalty(dataKey, cacheAge);
        
        // Refresh if staleness penalty exceeds refresh cost
        // and we have sufficient budget
        return stalnessPenalty > refreshCost && 
               currentBudget >= refreshCost;
    }
    
    prioritizeRefreshes(pendingRefreshes, availableBudget) {
        // Sort by value per cost ratio
        return pendingRefreshes
            .map(item => ({
                ...item,
                valuePerCost: this.calculateValuePerCost(item)
            }))
            .sort((a, b) => b.valuePerCost - a.valuePerCost)
            .filter(item => item.cost <= availableBudget);
    }
}

class OracleFallbackManager {
    constructor(config) {
        this.primaryOracles = config.primaryOracles;
        this.backupOracles = config.backupOracles;
        this.staticFallbacks = config.staticFallbacks;
        this.degradedModeConfig = config.degradedMode;
        
        this.healthMonitor = new OracleHealthMonitor();
        this.failoverLog = [];
    }
    
    async getDataWithFallback(dataRequest) {
        const fallbackChain = this.buildFallbackChain(dataRequest);
        
        for (const fallback of fallbackChain) {
            try {
                const result = await this.executeWithTimeout(
                    () => fallback.execute(dataRequest),
                    fallback.timeout
                );
                
                // Record successful fallback level
                this.recordFallbackSuccess(dataRequest, fallback.level);
                
                return {
                    data: result,
                    source: fallback.source,
                    confidence: fallback.confidence,
                    staleness: fallback.staleness
                };
                
            } catch (error) {
                this.recordFallbackFailure(dataRequest, fallback.level, error);
                
                // Continue to next fallback level
                if (fallback.level === 'CRITICAL') {
                    // Log critical fallback failure
                    this.alertCriticalFailure(dataRequest, error);
                }
            }
        }
        
        // All fallbacks failed
        throw new OracleFailureError('All oracle fallbacks exhausted', {
            dataRequest,
            fallbackChain: fallbackChain.map(f => f.level),
            lastErrors: this.getRecentErrors(dataRequest)
        });
    }

class OracleHealthMonitor {
    constructor(config) {
        this.oracles = new Map();
        this.healthChecks = config.healthChecks;
        this.alertThresholds = config.alertThresholds;
        this.metrics = new MetricsCollector();
        
        // Start continuous monitoring
        this.startHealthChecks();
    }
    
    async checkOracleHealth(oracleId) {
        const oracle = this.oracles.get(oracleId);
        const healthMetrics = {
            availability: 0,
            latency: Infinity,
            dataFreshness: Infinity,
            errorRate: 1,
            costEfficiency: 0,
            timestamp: Date.now()
        };
        
        try {
            // Test availability with lightweight query
            const startTime = Date.now();
            await this.pingOracle(oracleId);
            healthMetrics.latency = Date.now() - startTime;
            healthMetrics.availability = 1;
            
            // Check data freshness
            const sampleData = await this.getSampleData(oracleId);
            healthMetrics.dataFreshness = Date.now() - sampleData.timestamp;
            
            // Calculate error rate from recent history
            const recentErrors = this.getRecentErrors(oracleId, 300000); // 5 minutes
            const totalRequests = this.getTotalRequests(oracleId, 300000);
            healthMetrics.errorRate = recentErrors / Math.max(totalRequests, 1);
            
            // Assess cost efficiency
            healthMetrics.costEfficiency = this.calculateCostEfficiency(oracleId);
            
        } catch (error) {
            this.recordHealthCheckError(oracleId, error);
            healthMetrics.availability = 0;
        }
        
        // Update oracle health record
        oracle.healthHistory.push(healthMetrics);
        oracle.currentHealth = healthMetrics;
        
        // Check alert thresholds
        this.checkAlertThresholds(oracleId, healthMetrics);
        
        return healthMetrics;
    }

class GracefulDegradationManager {
    constructor(config) {
        this.degradationPolicies = config.policies;
        this.featureFlags = new FeatureFlagManager();
        this.userNotifications = new NotificationManager();
    }
    
    async handleOracleFailure(failureContext) {
        const policy = this.selectDegradationPolicy(failureContext);
        
        switch (policy.strategy) {
            case 'DISABLE_FEATURE':
                return this.disableAffectedFeatures(failureContext);
                
            case 'STATIC_FALLBACK':
                return this.enableStaticFallback(failureContext);
                
            case 'REDUCED_FUNCTIONALITY':
                return this.reduceFeatureFunctionality(failureContext);
                
            case 'USER_NOTIFICATION':
                return this.notifyUsersOfLimitations(failureContext);
                
            default:
                throw new Error(`Unknown degradation strategy: ${policy.strategy}`);
        }
    }

class OracleUsageAnalyzer {
    constructor(metricsCollector) {
        this.metrics = metricsCollector;
        this.usagePatterns = new Map();
        this.costModel = new OracleCostModel();
    }
    
    analyzeUsagePatterns(timeWindow = 86400000) { // 24 hours
        const usage = this.metrics.getUsageData(timeWindow);
        const analysis = {
            totalQueries: 0,
            totalCost: 0,
            queryDistribution: new Map(),
            temporalPatterns: new Map(),
            inefficiencies: []
        };
        
        for (const query of usage.queries) {
            analysis.totalQueries++;
            analysis.totalCost += this.costModel.calculateQueryCost(query);
            
            // Track query distribution
            const key = `${query.oracleId}:${query.dataKey}`;
            const count = analysis.queryDistribution.get(key) || 0;
            analysis.queryDistribution.set(key, count + 1);
            
            // Track temporal patterns
            const hour = new Date(query.timestamp).getHours();
            const hourlyCount = analysis.temporalPatterns.get(hour) || 0;
            analysis.temporalPatterns.set(hour, hourlyCount + 1);
        }
        
        // Identify inefficiencies
        this.identifyInefficiencies(analysis, usage);
        
        return analysis;
    }

class IntelligentBatchingManager {
    constructor(config) {
        this.batchWindows = config.batchWindows;
        this.maxBatchSize = config.maxBatchSize || 10;
        this.pendingRequests = new Map();
        this.batchTimers = new Map();
    }
    
    async requestOracleData(oracleId, dataKey, options = {}) {
        const requestId = this.generateRequestId();
        const batchKey = `${oracleId}:${options.batchGroup || 'default'}`;
        
        // Add request to pending batch
        if (!this.pendingRequests.has(batchKey)) {
            this.pendingRequests.set(batchKey, []);
        }
        
        const batch = this.pendingRequests.get(batchKey);
        const request = {
            id: requestId,
            oracleId,
            dataKey,
            options,
            timestamp: Date.now(),
            resolve: null,
            reject: null
        };
        
        // Create promise for this request
        const promise = new Promise((resolve, reject) => {
            request.resolve = resolve;
            request.reject = reject;
        });
        
        batch.push(request);
        
        // Schedule batch execution
        this.scheduleBatchExecution(batchKey, options);
        
        return promise;
    }

class DynamicCostManager {
    constructor(config) {
        this.dailyBudget = config.dailyBudget;
        this.criticalDataBudget = config.criticalDataBudget;
        this.currentSpend = 0;
        this.spendHistory = [];
        this.costPredictionModel = new CostPredictionModel();
    }
    
    async shouldExecuteQuery(queryRequest) {
        const estimatedCost = this.estimateQueryCost(queryRequest);
        const currentBudgetStatus = this.getBudgetStatus();
        
        // Always allow critical data within critical budget
        if (queryRequest.criticality === 'CRITICAL' && 
            currentBudgetStatus.criticalSpend + estimatedCost <= this.criticalDataBudget) {
            return { approved: true, reason: 'CRITICAL_DATA' };
        }
        
        // Check total budget availability
        if (currentBudgetStatus.totalSpend + estimatedCost > this.dailyBudget) {
            // Predict if budget will be exceeded
            const prediction = this.costPredictionModel.predictDailySpend(
                currentBudgetStatus,
                this.getTimeRemainingInDay()
            );
            
            if (prediction.estimatedTotal > this.dailyBudget * 1.1) { // 10% buffer
                return { 
                    approved: false, 
                    reason: 'BUDGET_EXCEEDED',
                    alternatives: this.suggestAlternatives(queryRequest)
                };
            }
        }
        
        return { approved: true, reason: 'WITHIN_BUDGET' };
    }

class OracleMockingFramework {
    constructor(config) {
        this.mockOracles = new Map();
        this.behaviorProfiles = config.behaviorProfiles;
        this.networkSimulator = new NetworkSimulator();
        this.costTracker = new MockCostTracker();
    }
    
    createMockOracle(oracleId, profile = 'default') {
        const behavior = this.behaviorProfiles[profile];
        const mock = {
            id: oracleId,
            behavior: behavior,
            state: 'HEALTHY',
            data: new Map(),
            requestHistory: [],
            metrics: {
                totalRequests: 0,
                successfulRequests: 0,
                averageLatency: 0,
                totalCost: 0
            }
        };
        
        this.mockOracles.set(oracleId, mock);
        return mock;
    }
    
    async simulateOracleQuery(oracleId, dataKey, options = {}) {
        const mock = this.mockOracles.get(oracleId);
        if (!mock) {
            throw new Error(`Mock oracle ${oracleId} not found`);
        }
        
        // Record request
        const request = {
            timestamp: Date.now(),
            dataKey,
            options
        };
        mock.requestHistory.push(request);
        mock.metrics.totalRequests++;
        
        // Simulate network latency
        const latency = this.networkSimulator.simulateLatency(mock.behavior.latency);
        await this.delay(latency);
        
        // Simulate failures based on behavior profile
        if (Math.random() < mock.behavior.failureRate) {
            const error = this.generateRealisticError(mock.behavior);
            throw error;
        }
        
        // Simulate cost
        const cost = this.costTracker.calculateCost(oracleId, dataKey);
        mock.metrics.totalCost += cost;
        
        // Generate realistic data
        const data = this.generateRealisticData(dataKey, mock.behavior);
        mock.data.set(dataKey, data);
        
        mock.metrics.successfulRequests++;
        mock.metrics.averageLatency = this.updateAverageLatency(
            mock.metrics.averageLatency,
            latency,
            mock.metrics.successfulRequests
        );
        
        return data;
    }

class OracleIntegrationTestSuite {
    constructor(testConfig) {
        this.mockFramework = new OracleMockingFramework(testConfig.mocking);
        this.testApplication = new TestApplication(testConfig.application);
        this.scenarios = testConfig.scenarios;
    }
    
    async testCachingEffectiveness() {
        // Setup scenario with high-frequency queries
        const oracleId = 'test-price-oracle';
        this.mockFramework.createMockOracle(oracleId, 'stable');
        
        const startTime = Date.now();
        const queryCount = 100;
        const dataKey = 'BTC-USD';
        
        // Execute queries and measure performance
        for (let i = 0; i < queryCount; i++) {
            await this.testApplication.getOracleData(oracleId, dataKey);
            await this.delay(100); // 100ms between queries
        }
        
        const totalTime = Date.now() - startTime;
        const mock = this.mockFramework.mockOracles.get(oracleId);
        
        // Verify caching effectiveness
        const cacheHitRate = 1 - (mock.metrics.totalRequests / queryCount);
        assert(cacheHitRate > 0.8, 'Cache hit rate should exceed 80%');
        
        const avgLatencyPerQuery = totalTime / queryCount;
        assert(avgLatencyPerQuery < 50, 'Average latency should be under 50ms with caching');
        
        return {
            cacheHitRate,
            avgLatencyPerQuery,
            totalOracleRequests: mock.metrics.totalRequests,
            totalCost: mock.metrics.totalCost
        };
    }

class OracleLoadTestFramework {
    constructor(config) {
        this.loadGenerators = [];
        this.metricsCollector = new MetricsCollector();
        this.testDuration = config.testDuration;
        this.concurrencyLevels = config.concurrencyLevels;
    }
    
    async runLoadTest(testProfile) {
        const results = {
            profile: testProfile.name,
            duration: this.testDuration,
            metrics: new Map(),
            performanceBreakdown: {}
        };
        
        for (const concurrency of this.concurrencyLevels) {
            console.log(`Testing with ${concurrency} concurrent users...`);
            
            const concurrencyResult = await this.testConcurrencyLevel(
                testProfile,
                concurrency
            );
            
            results.metrics.set(concurrency, concurrencyResult);
            
            // Check if system breaks down at this concurrency level
            if (concurrencyResult.errorRate > 0.1) { // 10% error threshold
                results.maxSustainableConcurrency = concurrency - 1;
                break;
            }
        }
        
        return results;
    }