@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/dist/utils/performance.js

@@ -0,0 +1,199 @@
+/**
+ * Performance monitoring utilities for PoolBot
+ *
+ * Features:
+ * - Function execution timing with automatic logging
+ * - Memory usage tracking
+ * - Async operation profiling
+ * - Performance markers for critical paths
+ * - Slow operation detection and warnings
+ */
+import { createSubsystemLogger } from "../logging/subsystem.js";
+const perfLog = createSubsystemLogger("perf");
+// Thresholds for slow operation warnings (in ms)
+const SLOW_THRESHOLDS = {
+    default: 100,
+    config: 50,
+    gateway: 200,
+    memory: 500,
+    search: 1000,
+    doctor: 300,
+    completion: 100,
+};
+/**
+ * Active performance markers
+ */
+const activeMarkers = new Map();
+/**
+ * Start a performance marker
+ */
+export function startMarker(name, metadata) {
+    const id = `${name}_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    activeMarkers.set(id, {
+        name,
+        startTime: performance.now(),
+        metadata,
+    });
+    return id;
+}
+/**
+ * End a performance marker and log results
+ */
+export function endMarker(id, options = {}) {
+    const marker = activeMarkers.get(id);
+    if (!marker) {
+        perfLog.warn(`Performance marker not found: ${id}`);
+        return undefined;
+    }
+    activeMarkers.delete(id);
+    const endTime = performance.now();
+    const durationMs = Math.round(endTime - marker.startTime);
+    const threshold = options.threshold ?? SLOW_THRESHOLDS[marker.name] ?? SLOW_THRESHOLDS.default;
+    const slow = durationMs > threshold;
+    const metrics = {
+        operation: marker.name,
+        durationMs,
+        slow,
+        metadata: marker.metadata,
+    };
+    if (options.log ?? true) {
+        if (slow) {
+            perfLog.warn(`Slow operation: ${marker.name} took ${durationMs}ms (threshold: ${threshold}ms)`, marker.metadata);
+        }
+        else {
+            perfLog.debug(`${marker.name}: ${durationMs}ms`, marker.metadata);
+        }
+    }
+    return metrics;
+}
+/**
+ * Time a synchronous function execution
+ */
+export function timeSync(name, fn, options = {}) {
+    const id = startMarker(name, options.metadata);
+    try {
+        return fn();
+    }
+    finally {
+        endMarker(id, { log: options.log, threshold: options.threshold });
+    }
+}
+/**
+ * Time an asynchronous function execution
+ */
+export async function timeAsync(name, fn, options = {}) {
+    const id = startMarker(name, options.metadata);
+    try {
+        return await fn();
+    }
+    finally {
+        endMarker(id, { log: options.log, threshold: options.threshold });
+    }
+}
+/**
+ * Create a performance-monitored version of a function
+ */
+export function withPerformanceTracking(name, fn, options = {}) {
+    return (...args) => {
+        const metadata = options.logArgs ? { args: args.map((a) => String(a)) } : undefined;
+        return timeSync(name, () => fn(...args), { ...options, metadata });
+    };
+}
+/**
+ * Create a performance-monitored version of an async function
+ */
+export function withAsyncPerformanceTracking(name, fn, options = {}) {
+    return async (...args) => {
+        const metadata = options.logArgs ? { args: args.map((a) => String(a)) } : undefined;
+        return timeAsync(name, () => fn(...args), { ...options, metadata });
+    };
+}
+/**
+ * Get current memory usage
+ */
+export function getMemorySnapshot() {
+    const usage = process.memoryUsage();
+    return {
+        timestamp: Date.now(),
+        used: Math.round(usage.heapUsed / 1024 / 1024), // MB
+        total: Math.round(usage.heapTotal / 1024 / 1024), // MB
+        external: Math.round(usage.external / 1024 / 1024), // MB
+        arrayBuffers: Math.round(usage.arrayBuffers / 1024 / 1024), // MB
+    };
+}
+/**
+ * Track memory before and after an operation
+ */
+export async function withMemoryTracking(name, fn, options = {}) {
+    const before = getMemorySnapshot();
+    const startId = startMarker(`${name}_memory`);
+    try {
+        return await fn();
+    }
+    finally {
+        const after = getMemorySnapshot();
+        endMarker(startId, { log: false });
+        const delta = after.used - before.used;
+        const warnThreshold = options.warnThresholdMB ?? 50;
+        if (options.log ?? true) {
+            if (delta > warnThreshold) {
+                perfLog.warn(`High memory usage in ${name}: +${delta}MB (${before.used}MB -> ${after.used}MB)`);
+            }
+            else {
+                perfLog.debug(`${name} memory: ${before.used}MB -> ${after.used}MB (${delta >= 0 ? "+" : ""}${delta}MB)`);
+            }
+        }
+    }
+}
+/**
+ * Get all active markers (for debugging)
+ */
+export function getActiveMarkers() {
+    return Array.from(activeMarkers.values());
+}
+/**
+ * Clear all active markers
+ */
+export function clearAllMarkers() {
+    activeMarkers.clear();
+}
+/**
+ * Create a performance collector for batch operations
+ */
+export function createPerformanceCollector() {
+    const operations = [];
+    return {
+        add: (metrics) => {
+            operations.push(metrics);
+        },
+        getReport: () => {
+            if (operations.length === 0) {
+                return {
+                    operations: [],
+                    summary: {
+                        totalOperations: 0,
+                        slowOperations: 0,
+                        averageDurationMs: 0,
+                        maxDurationMs: 0,
+                        minDurationMs: 0,
+                    },
+                };
+            }
+            const durations = operations.map((o) => o.durationMs);
+            const slowOperations = operations.filter((o) => o.slow).length;
+            return {
+                operations,
+                summary: {
+                    totalOperations: operations.length,
+                    slowOperations,
+                    averageDurationMs: Math.round(durations.reduce((a, b) => a + b, 0) / durations.length),
+                    maxDurationMs: Math.max(...durations),
+                    minDurationMs: Math.min(...durations),
+                },
+            };
+        },
+        clear: () => {
+            operations.length = 0;
+        },
+    };
+}

package/dist/utils/retry.js

@@ -0,0 +1,240 @@
+/**
+ * Retry utilities with exponential backoff and jitter
+ *
+ * Features:
+ * - Exponential backoff with configurable parameters
+ * - Jitter to prevent thundering herd
+ * - Abort signal support for cancellation
+ * - Custom retry predicates (decide which errors to retry)
+ * - OnRetry callback for logging/observability
+ * - Max retry duration support
+ */
+import { createSubsystemLogger } from "../logging/subsystem.js";
+const retryLog = createSubsystemLogger("retry");
+/**
+ * Calculate delay with exponential backoff and optional jitter
+ */
+function calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter) {
+    // Exponential backoff: initialDelay * (multiplier ^ attempt)
+    const exponentialDelay = initialDelayMs * Math.pow(backoffMultiplier, attempt);
+    // Apply jitter: random value between 0.5x and 1.5x of calculated delay
+    if (jitter) {
+        const jitterFactor = 0.5 + Math.random();
+        return Math.min(Math.round(exponentialDelay * jitterFactor), maxDelayMs);
+    }
+    return Math.min(exponentialDelay, maxDelayMs);
+}
+/**
+ * Default retry predicate - retries on network/timeout errors
+ */
+function defaultRetryIf(error) {
+    if (error instanceof Error) {
+        const errorMessage = error.message.toLowerCase();
+        // Network errors
+        if (errorMessage.includes("timeout") ||
+            errorMessage.includes("etimedout") ||
+            errorMessage.includes("enotfound") ||
+            errorMessage.includes("econnrefused") ||
+            errorMessage.includes("econnreset") ||
+            errorMessage.includes("network") ||
+            errorMessage.includes("socket") ||
+            errorMessage.includes("fetch failed") ||
+            errorMessage.includes("abort") ||
+            errorMessage.includes("temporary")) {
+            return true;
+        }
+        // HTTP status codes that indicate retryable errors
+        if (errorMessage.includes("429") || // Too Many Requests
+            errorMessage.includes("503") || // Service Unavailable
+            errorMessage.includes("502") || // Bad Gateway
+            errorMessage.includes("504") // Gateway Timeout
+        ) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Sleep with abort signal support
+ */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("Operation aborted"));
+            return;
+        }
+        const timeout = setTimeout(resolve, ms);
+        if (signal) {
+            signal.addEventListener("abort", () => {
+                clearTimeout(timeout);
+                reject(new Error("Operation aborted"));
+            }, { once: true });
+        }
+    });
+}
+/**
+ * Retry an async operation with exponential backoff
+ */
+export async function retryAsync(operation, options = {}) {
+    const { maxAttempts = 3, initialDelayMs = 100, maxDelayMs = 30000, backoffMultiplier = 2, jitter = true, maxDurationMs, retryIf = defaultRetryIf, onRetry, signal, operationName = "operation", } = options;
+    const startTime = Date.now();
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        // Check max duration
+        if (maxDurationMs !== undefined) {
+            const elapsed = Date.now() - startTime;
+            if (elapsed >= maxDurationMs) {
+                throw new Error(`${operationName} failed: max duration (${maxDurationMs}ms) exceeded after ${attempt} attempts`);
+            }
+        }
+        try {
+            const result = await operation();
+            if (attempt > 0) {
+                retryLog.info(`${operationName} succeeded after ${attempt + 1} attempts`);
+            }
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry this error
+            if (!retryIf(error, attempt)) {
+                retryLog.debug(`${operationName} not retryable: ${error}`);
+                throw error;
+            }
+            // Check if this was the last attempt
+            if (attempt === maxAttempts - 1) {
+                break;
+            }
+            // Calculate delay for next attempt
+            const delayMs = calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter);
+            retryLog.debug(`${operationName} attempt ${attempt + 1} failed, retrying in ${delayMs}ms: ${error}`);
+            // Call onRetry callback
+            onRetry?.(error, attempt + 1, delayMs);
+            // Wait before next attempt
+            await sleep(delayMs, signal);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Retry an async operation and return detailed outcome
+ */
+export async function retryAsyncWithOutcome(operation, options = {}) {
+    const startTime = Date.now();
+    try {
+        const data = await retryAsync(operation, options);
+        return {
+            success: true,
+            data,
+            attempts: 1, // This would need to be tracked properly
+            totalDurationMs: Date.now() - startTime,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error,
+            attempts: options.maxAttempts ?? 3,
+            totalDurationMs: Date.now() - startTime,
+        };
+    }
+}
+/**
+ * Create a retryable version of a function
+ */
+export function withRetry(fn, options = {}) {
+    return async (...args) => {
+        return retryAsync(() => fn(...args), {
+            ...options,
+            operationName: options.operationName ?? fn.name,
+        });
+    };
+}
+/**
+ * Retry configuration presets for common scenarios
+ */
+export const RetryPresets = {
+    /** Fast retry for quick operations (e.g., config reads) */
+    fast: {
+        maxAttempts: 3,
+        initialDelayMs: 50,
+        maxDelayMs: 500,
+        backoffMultiplier: 2,
+    },
+    /** Standard retry for most operations */
+    standard: {
+        maxAttempts: 3,
+        initialDelayMs: 100,
+        maxDelayMs: 5000,
+        backoffMultiplier: 2,
+    },
+    /** Aggressive retry for critical operations */
+    aggressive: {
+        maxAttempts: 5,
+        initialDelayMs: 100,
+        maxDelayMs: 30000,
+        backoffMultiplier: 2,
+    },
+    /** Patient retry for flaky external services */
+    patient: {
+        maxAttempts: 10,
+        initialDelayMs: 1000,
+        maxDelayMs: 60000,
+        backoffMultiplier: 2,
+    },
+    /** No retry - fail fast */
+    none: {
+        maxAttempts: 1,
+    },
+};
+export class CircuitBreaker {
+    options;
+    state = "closed";
+    failures = 0;
+    nextAttempt = 0;
+    halfOpenCalls = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    async execute(operation) {
+        if (this.state === "open") {
+            if (Date.now() < this.nextAttempt) {
+                throw new Error("Circuit breaker is open");
+            }
+            this.state = "half-open";
+            this.halfOpenCalls = 0;
+        }
+        if (this.state === "half-open") {
+            if (this.halfOpenCalls >= this.options.halfOpenMaxCalls) {
+                throw new Error("Circuit breaker is half-open, too many calls");
+            }
+            this.halfOpenCalls++;
+        }
+        try {
+            const result = await operation();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    onSuccess() {
+        if (this.state === "half-open") {
+            this.state = "closed";
+            this.failures = 0;
+            this.halfOpenCalls = 0;
+        }
+    }
+    onFailure() {
+        this.failures++;
+        if (this.failures >= this.options.failureThreshold) {
+            this.state = "open";
+            this.nextAttempt = Date.now() + this.options.resetTimeoutMs;
+        }
+    }
+    getState() {
+        return this.state;
+    }
+}