@rbalchii/anchor-engine 4.7.0

package/engine/dist/utils/resource-manager.js

@@ -0,0 +1,235 @@
+/**
+ * Memory Management and Resource Optimization for ECE
+ *
+ * Implements efficient memory usage patterns and resource management
+ * following Standard 062: Inference Worker Stability
+ */
+import * as os from 'os';
+import * as v8 from 'v8';
+import { config } from '../config/index.js';
+/**
+ * Default implementation using real system resources
+ */
+class DefaultSystemResources {
+    getTotalMemory() {
+        return os.totalmem();
+    }
+    getMemoryUsage() {
+        return process.memoryUsage();
+    }
+    getHeapStatistics() {
+        return v8.getHeapStatistics();
+    }
+    getHeapSpaceStatistics() {
+        return v8.getHeapSpaceStatistics();
+    }
+    gc() {
+        if (global.gc) {
+            global.gc();
+        }
+    }
+    hasGc() {
+        return !!global.gc;
+    }
+}
+export class ResourceManager {
+    static instance;
+    limits;
+    lastGCTime = 0;
+    gcCooldown = config.GC_COOLDOWN_MS; // Configurable cooldown between forced GC
+    resources;
+    monitoringInterval = null;
+    constructor(resources) {
+        this.resources = resources || new DefaultSystemResources();
+        // Set default resource limits based on system capabilities
+        const totalMemory = this.resources.getTotalMemory();
+        this.limits = {
+            maxHeapSize: totalMemory * 0.6, // Use up to 60% of total memory
+            memoryThreshold: 0.7, // Optimize when 70% of heap is used
+            maxAtomsInMemory: config.MAX_ATOMS_IN_MEMORY, // Configurable max atoms to keep in memory at once
+            gcThreshold: 0.75 // Force GC when 75% of heap is used
+        };
+    }
+    static getInstance() {
+        if (!ResourceManager.instance) {
+            ResourceManager.instance = new ResourceManager();
+        }
+        return ResourceManager.instance;
+    }
+    /**
+     * Reset the singleton instance (for testing only)
+     */
+    static resetInstance() {
+        // @ts-ignore
+        ResourceManager.instance = undefined;
+    }
+    /**
+     * Create an instance with specific resources (for testing only)
+     */
+    static createInstanceForTesting(resources) {
+        ResourceManager.instance = new ResourceManager(resources);
+        return ResourceManager.instance;
+    }
+    /**
+     * Get current memory statistics
+     */
+    getMemoryStats() {
+        const usage = this.resources.getMemoryUsage();
+        const heapStats = this.resources.getHeapStatistics();
+        const heapSpaces = this.getHeapSpaceInfo();
+        return {
+            rss: usage.rss,
+            heapTotal: usage.heapTotal,
+            heapUsed: usage.heapUsed,
+            external: usage.external,
+            arrayBuffers: usage.arrayBuffers,
+            percentageUsed: (usage.heapUsed / heapStats.heap_size_limit) * 100, // Correct metric relative to V8 limit
+            heapSpaces
+        };
+    }
+    /**
+     * Get detailed heap space information
+     */
+    getHeapSpaceInfo() {
+        try {
+            const spaces = this.resources.getHeapSpaceStatistics();
+            return spaces.map(space => ({
+                name: space.space_name,
+                size: space.space_size,
+                used: space.space_used_size,
+                available: space.space_available_size,
+                physical: space.physical_space_size
+            }));
+        }
+        catch (error) {
+            // If heap space stats are not available, return empty array
+            console.warn('Could not retrieve heap space statistics:', error);
+            return [];
+        }
+    }
+    /**
+     * Check if memory usage is approaching limits
+     */
+    isMemoryCritical() {
+        const stats = this.getMemoryStats();
+        return stats.percentageUsed > this.limits.gcThreshold * 100;
+    }
+    /**
+     * Check if optimization is needed
+     */
+    needsOptimization() {
+        const stats = this.getMemoryStats();
+        return stats.percentageUsed > this.limits.memoryThreshold * 100;
+    }
+    /**
+     * Perform garbage collection if needed and allowed
+     */
+    performGCIfNeeded() {
+        if (!this.needsOptimization()) {
+            return;
+        }
+        const now = Date.now();
+        if (now - this.lastGCTime < this.gcCooldown) {
+            // Still in cooldown period
+            return;
+        }
+        this.performGarbageCollection();
+    }
+    /**
+     * Force garbage collection (requires --expose-gc flag)
+     */
+    performGarbageCollection() {
+        this.lastGCTime = Date.now();
+        try {
+            if (this.resources.hasGc()) {
+                console.log('[ResourceManager] Performing forced garbage collection...');
+                this.resources.gc();
+                console.log('[ResourceManager] Garbage collection completed.');
+            }
+            else {
+                console.warn('[ResourceManager] Garbage collection not available. Run with --expose-gc flag for manual GC.');
+            }
+        }
+        catch (error) {
+            console.error('[ResourceManager] Error during garbage collection:', error);
+        }
+    }
+    /**
+     * Optimize memory usage by clearing caches and releasing unused resources
+     */
+    optimizeMemory() {
+        console.log('[ResourceManager] Starting memory optimization...');
+        // Clear any internal caches (implement as needed)
+        this.clearInternalCaches();
+        // Perform GC if needed
+        this.performGCIfNeeded();
+        // Log memory stats after optimization
+        const stats = this.getMemoryStats();
+        console.log(`[ResourceManager] Memory optimization completed. Heap usage: ${stats.percentageUsed.toFixed(2)}%`);
+    }
+    /**
+     * Clear internal caches to free up memory
+     */
+    clearInternalCaches() {
+        // This is where you would clear any application-specific caches
+        // For example, atom caches, search result caches, etc.
+        console.log('[ResourceManager] Clearing internal caches...');
+        // Example: Clear any cached search results older than 5 minutes
+        // This would be implemented based on your specific caching needs
+        // Example: Clear any temporary data structures
+        // This would be implemented based on your specific needs
+    }
+    /**
+     * Get resource limits
+     */
+    getResourceLimits() {
+        return { ...this.limits };
+    }
+    /**
+     * Update resource limits
+     */
+    updateLimits(newLimits) {
+        this.limits = { ...this.limits, ...newLimits };
+    }
+    /**
+     * Monitor memory usage and trigger optimizations
+     */
+    startMonitoring(intervalMs = config.MONITORING_INTERVAL_MS) {
+        if (this.monitoringInterval !== null) {
+            this.stopMonitoring();
+        }
+        console.log(`[ResourceManager] Starting memory monitoring (interval: ${intervalMs}ms)`);
+        this.monitoringInterval = setInterval(() => {
+            const stats = this.getMemoryStats();
+            if (stats.percentageUsed > this.limits.gcThreshold * 100) {
+                console.log(`[ResourceManager] Memory usage critical: ${stats.percentageUsed.toFixed(2)}%`);
+                this.performGCIfNeeded();
+            }
+            else if (stats.percentageUsed > this.limits.memoryThreshold * 100) {
+                console.log(`[ResourceManager] Memory usage high: ${stats.percentageUsed.toFixed(2)}%`);
+                this.optimizeMemory();
+            }
+            // Log memory stats periodically if in debug mode
+            if (process.env['NODE_ENV'] === 'development' || process.env['DEBUG_MEMORY']) {
+                console.log(`[ResourceManager] RSS: ${(stats.rss / 1024 / 1024).toFixed(2)}MB, Heap: ${stats.percentageUsed.toFixed(2)}%`);
+            }
+        }, intervalMs);
+    }
+    /**
+     * Stop memory monitoring
+     */
+    stopMonitoring() {
+        if (this.monitoringInterval !== null) {
+            clearInterval(this.monitoringInterval);
+            this.monitoringInterval = null;
+            console.log(`[ResourceManager] Stopped memory monitoring`);
+        }
+    }
+}
+// Export singleton instance
+export const resourceManager = ResourceManager.getInstance();
+// Initialize monitoring if enabled
+if (process.env['ECE_MEMORY_MONITORING'] !== 'false') {
+    resourceManager.startMonitoring();
+}
+//# sourceMappingURL=resource-manager.js.map

package/engine/dist/utils/resource-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-manager.js","sourceRoot":"","sources":["../../src/utils/resource-manager.ts"],"names":[],"mappings":"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"}

package/engine/dist/utils/safe-dns.d.ts

@@ -0,0 +1,14 @@
+import dns from 'node:dns';
+/**
+ * Checks if an IP address is private or reserved.
+ * Handles IPv4 and IPv6.
+ *
+ * @param ip - The IP address string
+ * @returns true if the IP is private or reserved, false otherwise.
+ */
+export declare function isPrivateIP(ip: string): boolean;
+/**
+ * Custom DNS lookup function for `got` that prevents resolving to private IP addresses.
+ */
+export declare function safeLookup(hostname: string, options: dns.LookupOptions, callback: (err: NodeJS.ErrnoException | null, address: string | dns.LookupAddress[], family?: number) => void): void;
+//# sourceMappingURL=safe-dns.d.ts.map

package/engine/dist/utils/safe-dns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-dns.d.ts","sourceRoot":"","sources":["../../src/utils/safe-dns.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAmE/C;AAED;;GAEG;AACH,wBAAgB,UAAU,CACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,aAAa,EAC1B,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,GAC9G,IAAI,CA0BN"}

package/engine/dist/utils/safe-dns.js

@@ -0,0 +1,105 @@
+import dns from 'node:dns';
+/**
+ * Checks if an IP address is private or reserved.
+ * Handles IPv4 and IPv6.
+ *
+ * @param ip - The IP address string
+ * @returns true if the IP is private or reserved, false otherwise.
+ */
+export function isPrivateIP(ip) {
+    // IPv6 with embedded IPv4 (e.g., ::ffff:127.0.0.1)
+    if (ip.includes(':') && ip.includes('.')) {
+        const lowerIp = ip.toLowerCase();
+        // IPv4-mapped IPv6 ::ffff:127.0.0.1
+        if (lowerIp.startsWith('::ffff:')) {
+            const ipv4 = lowerIp.substring(7);
+            if (ipv4.includes('.')) {
+                return isPrivateIP(ipv4);
+            }
+        }
+        // Also check for 0:0:0:0:0:ffff:127.0.0.1 style if not normalized
+        // It's likely an embedded IPv4
+        const parts = lowerIp.split(':');
+        const lastPart = parts[parts.length - 1];
+        if (lastPart.includes('.')) {
+            return isPrivateIP(lastPart);
+        }
+    }
+    // IPv4
+    if (ip.includes('.')) {
+        const parts = ip.split('.').map(Number);
+        if (parts.length !== 4)
+            return false;
+        // 127.0.0.0/8 - Loopback
+        if (parts[0] === 127)
+            return true;
+        // 10.0.0.0/8 - Private Network
+        if (parts[0] === 10)
+            return true;
+        // 192.168.0.0/16 - Private Network
+        if (parts[0] === 192 && parts[1] === 168)
+            return true;
+        // 172.16.0.0/12 - Private Network (172.16.x.x - 172.31.x.x)
+        if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
+            return true;
+        // 169.254.0.0/16 - Link-local
+        if (parts[0] === 169 && parts[1] === 254)
+            return true;
+        // 0.0.0.0/8 - Current network (only valid as source address)
+        if (parts[0] === 0)
+            return true;
+        return false;
+    }
+    // IPv6
+    else if (ip.includes(':')) {
+        const lowerIp = ip.toLowerCase();
+        // ::1/128 - Loopback
+        if (lowerIp === '::1' || lowerIp === '0:0:0:0:0:0:0:1')
+            return true;
+        // ::/128 - Unspecified
+        if (lowerIp === '::' || lowerIp === '0:0:0:0:0:0:0:0')
+            return true;
+        // fc00::/7 - Unique Local Address
+        // Check if starts with fc or fd (case insensitive)
+        const firstBlock = lowerIp.split(':')[0];
+        if (firstBlock.length > 0) {
+            const val = parseInt(firstBlock, 16);
+            // fc00::/7 covers fc00 to fdff
+            if (!isNaN(val) && ((val >> 8) & 0xfe) === 0xfc)
+                return true;
+        }
+        // fe80::/10 - Link-local
+        if (lowerIp.startsWith('fe8') || lowerIp.startsWith('fe9') || lowerIp.startsWith('fea') || lowerIp.startsWith('feb'))
+            return true;
+        return false;
+    }
+    return false;
+}
+/**
+ * Custom DNS lookup function for `got` that prevents resolving to private IP addresses.
+ */
+export function safeLookup(hostname, options, callback) {
+    dns.lookup(hostname, options, (err, address, family) => {
+        if (err) {
+            callback(err, address, family);
+            return;
+        }
+        const addressesToCheck = [];
+        if (Array.isArray(address)) {
+            address.forEach(a => addressesToCheck.push(a.address));
+        }
+        else if (typeof address === 'string') {
+            addressesToCheck.push(address);
+        }
+        for (const addr of addressesToCheck) {
+            if (isPrivateIP(addr)) {
+                const error = new Error(`DNS lookup for ${hostname} resolved to a private IP: ${addr}`);
+                error.code = 'ERR_SSRF_PROTECTION';
+                callback(error, address, family);
+                return;
+            }
+        }
+        callback(null, address, family);
+    });
+}
+//# sourceMappingURL=safe-dns.js.map

package/engine/dist/utils/safe-dns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-dns.js","sourceRoot":"","sources":["../../src/utils/safe-dns.ts"],"names":[],"mappings":"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"}

package/engine/dist/utils/structured-logger.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Structured Logger for Anchor Engine
+ *
+ * Implements standardized, structured logging with metrics collection
+ */
+import winston from 'winston';
+declare const logger: winston.Logger;
+declare class MetricsTracker {
+    private metrics;
+    private startTime;
+    constructor();
+    startTimer(operation: string): () => number;
+    recordMetric(operation: string, duration: number): void;
+    getMetrics(operation: string): {
+        count: number;
+        total: number;
+        min: number;
+        max: number;
+        last: number;
+    } | undefined;
+    getAllMetrics(): Record<string, any>;
+    reset(): void;
+    /**
+     * Prune old metrics to free memory (called during idle cleanup)
+     * Removes metrics older than TTL and enforces maximum size limit
+     */
+    pruneOldMetrics(): void;
+}
+declare const metricsTracker: MetricsTracker;
+export declare const logWithContext: {
+    /**
+     * Log an info message with context and metrics
+     */
+    info: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log a warning with context
+     */
+    warn: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log an error with context
+     */
+    error: (message: string, error?: Error | string, context?: Record<string, any>) => void;
+    /**
+     * Log a debug message with context
+     */
+    debug: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log a silly/verbose message with context
+     */
+    silly: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log a performance metric
+     */
+    performance: (operation: string, duration: number, context?: Record<string, any>) => void;
+    /**
+     * Start a timed operation
+     */
+    startTimer: (operation: string) => () => number;
+    /**
+     * Get current metrics
+     */
+    getMetrics: () => Record<string, any>;
+    /**
+     * Log ingestion event
+     */
+    ingestion: (status: "success" | "partial" | "failed", details: Record<string, any>) => void;
+    /**
+     * Log search event
+     */
+    search: (query: string, resultCount: number, duration: number, context?: Record<string, any>) => void;
+    /**
+     * Log system health event
+     */
+    health: (status: "healthy" | "degraded" | "unhealthy", details: Record<string, any>) => void;
+};
+export { logger, metricsTracker };
+export declare function getFormattedMetrics(): string;
+export declare const StructuredLogger: {
+    /**
+     * Log an info message with context and metrics
+     */
+    info: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log a warning with context
+     */
+    warn: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log an error with context
+     */
+    error: (message: string, error?: Error | string, context?: Record<string, any>) => void;
+    /**
+     * Log a debug message with context
+     */
+    debug: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log a silly/verbose message with context
+     */
+    silly: (message: string, context?: Record<string, any>) => void;
+    /**
+     * Log a performance metric
+     */
+    performance: (operation: string, duration: number, context?: Record<string, any>) => void;
+    /**
+     * Start a timed operation
+     */
+    startTimer: (operation: string) => () => number;
+    /**
+     * Get current metrics
+     */
+    getMetrics: () => Record<string, any>;
+    /**
+     * Log ingestion event
+     */
+    ingestion: (status: "success" | "partial" | "failed", details: Record<string, any>) => void;
+    /**
+     * Log search event
+     */
+    search: (query: string, resultCount: number, duration: number, context?: Record<string, any>) => void;
+    /**
+     * Log system health event
+     */
+    health: (status: "healthy" | "degraded" | "unhealthy", details: Record<string, any>) => void;
+};
+//# sourceMappingURL=structured-logger.d.ts.map

package/engine/dist/utils/structured-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.d.ts","sourceRoot":"","sources":["../../src/utils/structured-logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,OAAO,MAAM,SAAS,CAAC;AA+E9B,QAAA,MAAM,MAAM,gBAmDV,CAAC;AAGH,cAAM,cAAc;IAClB,OAAO,CAAC,OAAO,CAAwF;IACvG,OAAO,CAAC,SAAS,CAAS;;IAO1B,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,MAAM;IAU3C,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAavD,UAAU,CAAC,SAAS,EAAE,MAAM;eA/BU,MAAM;eAAS,MAAM;aAAO,MAAM;aAAO,MAAM;cAAQ,MAAM;;IAmCnG,aAAa;IAmBb,KAAK;IAIL;;;OAGG;IACH,eAAe,IAAI,IAAI;CA6BxB;AAGD,QAAA,MAAM,cAAc,gBAAuB,CAAC;AAG5C,eAAO,MAAM,cAAc;IACzB;;OAEG;oBACa,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAcrD;;OAEG;oBACa,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAQrD;;OAEG;qBACc,MAAM,UAAU,KAAK,GAAG,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAS9E;;OAEG;qBACc,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAQtD;;OAEG;qBACc,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAQtD;;OAEG;6BACsB,MAAM,YAAY,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAahF;;OAEG;4BACqB,MAAM,WA3KO,MAAM;IA+K3C;;OAEG;;IAKH;;OAEG;wBACiB,SAAS,GAAG,SAAS,GAAG,QAAQ,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAiBlF;;OAEG;oBACa,MAAM,eAAe,MAAM,YAAY,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAgB5F;;OAEG;qBACc,SAAS,GAAG,UAAU,GAAG,WAAW,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CASpF,CAAC;AAGF,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;AAGlC,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AAGD,eAAO,MAAM,gBAAgB;IA3J3B;;OAEG;oBACa,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAcrD;;OAEG;oBACa,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAQrD;;OAEG;qBACc,MAAM,UAAU,KAAK,GAAG,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAS9E;;OAEG;qBACc,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAQtD;;OAEG;qBACc,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAQtD;;OAEG;6BACsB,MAAM,YAAY,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAahF;;OAEG;4BACqB,MAAM,WA3KO,MAAM;IA+K3C;;OAEG;;IAKH;;OAEG;wBACiB,SAAS,GAAG,SAAS,GAAG,QAAQ,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAiBlF;;OAEG;oBACa,MAAM,eAAe,MAAM,YAAY,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAgB5F;;OAEG;qBACc,SAAS,GAAG,UAAU,GAAG,WAAW,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAqBvC,CAAC"}