firewalla-mcp-server/dist/utils/geographic-enrichment-pipeline.d.ts

Model Context Protocol (MCP) server for Firewalla MSP API - Provides real-time network monitoring, security analysis, and firewall management through 28 specialized tools compatible with any MCP client

/**
 * Geographic Enrichment Pipeline
 *
 * Implements a high-performance, fault-tolerant pipeline for enriching data with
 * geographic information. Features multiple fallback providers, performance
 * monitoring, and success rate tracking to guarantee ≥95% enrichment success
 * with ≤3ms latency impact.
 *
 * Architecture:
 * - Multi-tier fallback strategy (primary → secondary → tertiary → default)
 * - Batch processing for efficiency
 * - Performance budgeting with early termination
 * - Comprehensive monitoring and metrics
 * - Feature flag integration for safe rollout
 */
import type { GeographicData } from '../types.js';
import { type GeographicCache } from './geographic.js';
/**
 * Geographic enrichment statistics (simplified)
 */
export interface EnrichmentStats {
    totalRequests: number;
    successfulRequests: number;
    successRate: number;
}
/**
 * Geographic enrichment result with metadata
 */
export interface EnrichmentResult {
    data: GeographicData | null;
    source: 'cache' | 'primary' | 'secondary' | 'tertiary' | 'default' | 'failed';
    latencyMs: number;
    success: boolean;
}
/**
 * Batch enrichment request
 */
export interface BatchEnrichmentRequest {
    ip: string;
    fieldPath: string;
}
/**
 * Geographic Enrichment Pipeline
 *
 * High-performance pipeline that guarantees geographic data enrichment with
 * comprehensive fallback strategies and performance monitoring.
 */
export declare class GeographicEnrichmentPipeline {
    private stats;
    private geoCache;
    private performanceBudgetMs;
    private successTarget;
    constructor(geoCache: GeographicCache);
    /**
     * Enrich a single IP address with geographic data
     */
    enrichIP(ip: string): Promise<EnrichmentResult>;
    /**
     * Batch enrich multiple IPs for efficiency
     */
    enrichBatch(requests: BatchEnrichmentRequest[]): Promise<Map<string, EnrichmentResult>>;
    /**
     * Enrich an object with geographic data based on IP fields
     */
    enrichObject<T extends Record<string, any>>(obj: T, ipFields?: string[]): Promise<T>;
    /**
     * Try primary geographic provider (geoip-lite)
     */
    private tryPrimaryProvider;
    /**
     * Try secondary provider (IP range mapping)
     */
    private trySecondaryProvider;
    /**
     * Try tertiary provider (country-based defaults using first octet)
     */
    private tryTertiaryProvider;
    /**
     * Create enrichment result with performance tracking
     */
    private createResult;
    /**
     * Update basic statistics
     */
    private updateStats;
    /**
     * Get nested object value by path
     */
    private getNestedValue;
    /**
     * Set nested object value by path
     */
    private setNestedValue;
    /**
     * Get current enrichment statistics
     */
    getStats(): EnrichmentStats;
    /**
     * Reset statistics (for testing or monitoring reset)
     */
    resetStats(): void;
    /**
     * Check if pipeline is meeting success rate target
     */
    isPerformingWell(): boolean;
}
/**
 * Get or create the global geographic enrichment pipeline
 */
export declare function getGlobalEnrichmentPipeline(geoCache: GeographicCache): GeographicEnrichmentPipeline;
/**
 * Convenience function for enriching objects with geographic data
 */
export declare function enrichWithGeographicData<T extends Record<string, any>>(obj: T, geoCache: GeographicCache, ipFields?: string[]): Promise<T>;
/**
 * Convenience function for batch enriching arrays of objects
 */
export declare function enrichArrayWithGeographicData<T extends Record<string, any>>(objects: T[], geoCache: GeographicCache, ipFields?: string[]): Promise<T[]>;
//# sourceMappingURL=geographic-enrichment-pipeline.d.ts.map