@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/src/FlinkLogFactory.ts

@@ -0,0 +1,699 @@
+import Logger from "node-color-log";
+
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+};
+
+/**
+ * Component-specific logger with independent log level control
+ */
+export class ComponentLogger {
+    private componentName: string;
+    private componentLevel: LogLevel | null = null;
+    private namedLogger: any;
+
+    constructor(componentName: string) {
+        this.componentName = componentName;
+        this.namedLogger = Logger.createNamedLogger(componentName);
+    }
+
+    /**
+     * Set log level for this specific component.
+     * Overrides the global log level.
+     */
+    setLevel(level: LogLevel) {
+        this.componentLevel = level;
+    }
+
+    /**
+     * Clear component-specific level and fall back to global level
+     */
+    clearLevel() {
+        this.componentLevel = null;
+    }
+
+    /**
+     * Check if a message should be logged based on component and global levels
+     */
+    private shouldLog(messageLevel: LogLevel): boolean {
+        const effectiveLevel = this.componentLevel ?? FlinkLogFactory.getGlobalLevel();
+        return LOG_LEVELS[messageLevel] >= LOG_LEVELS[effectiveLevel];
+    }
+
+    trace(...args: any[]) {
+        if (this.shouldLog("trace")) {
+            // node-color-log doesn't support trace, use console.log for stdout
+            if (FlinkLogFactory.getShowTimestamps()) {
+                const timestamp = new Date().toISOString();
+                console.log(`${timestamp} [${this.componentName}] [TRACE]`, ...args);
+            } else {
+                console.log(`[${this.componentName}] [TRACE]`, ...args);
+            }
+        }
+    }
+
+    debug(...args: any[]) {
+        if (this.shouldLog("debug")) {
+            this.namedLogger.debug(...args);
+        }
+    }
+
+    info(...args: any[]) {
+        if (this.shouldLog("info")) {
+            this.namedLogger.info(...args);
+        }
+    }
+
+    warn(...args: any[]) {
+        if (this.shouldLog("warn")) {
+            // Use console.warn to write to stderr (Unix/POSIX best practice)
+            if (FlinkLogFactory.getShowTimestamps()) {
+                const timestamp = new Date().toISOString();
+                console.warn(`${timestamp} [${this.componentName}] [WARN]`, ...args);
+            } else {
+                console.warn(`[${this.componentName}] [WARN]`, ...args);
+            }
+        }
+    }
+
+    error(...args: any[]) {
+        if (this.shouldLog("error")) {
+            // Use console.error to write to stderr (Unix/POSIX best practice)
+            if (FlinkLogFactory.getShowTimestamps()) {
+                const timestamp = new Date().toISOString();
+                console.error(`${timestamp} [${this.componentName}] [ERROR]`, ...args);
+            } else {
+                console.error(`[${this.componentName}] [ERROR]`, ...args);
+            }
+        }
+    }
+
+    json(...args: any[]) {
+        if (this.shouldLog("debug")) {
+            for (const o of args) {
+                console.log(JSON.stringify(o, null, 2));
+            }
+        }
+    }
+
+    bgColorLog(color: string, ...args: any[]) {
+        if (this.shouldLog("debug")) {
+            this.namedLogger.bgColorLog(color, ...args);
+        }
+    }
+
+    fontColorLog(color: string, ...args: any[]) {
+        if (this.shouldLog("info")) {
+            this.namedLogger.fontColorLog(color, ...args);
+        }
+    }
+}
+
+/**
+ * Configuration for logging system
+ */
+export interface LoggingConfig {
+    /**
+     * Global log level (default: "info")
+     */
+    global?: LogLevel;
+
+    /**
+     * Show timestamps in log messages (default: true)
+     */
+    showTimestamps?: boolean;
+
+    /**
+     * Component-specific log levels with wildcard support
+     *
+     * Supports:
+     * - Exact match: "flink.ai.openai" → matches only "flink.ai.openai"
+     * - Prefix match: "flink.ai." → matches "flink.ai.openai", "flink.ai.anthropic", etc.
+     * - Single-level wildcard: "flink.ai.*" → matches "flink.ai.openai" but NOT "flink.ai.openai.v4"
+     * - Multi-level wildcard: "flink.ai.**" → matches any depth under "flink.ai"
+     *
+     * @example
+     * {
+     *   "flink.ai.openai": "trace",     // exact match
+     *   "flink.ai.*": "debug",          // single-level wildcard
+     *   "flink.database.**": "warn",    // multi-level wildcard
+     *   "flink.handlers.": "info"       // prefix match (trailing dot)
+     * }
+     */
+    components?: Record<string, LogLevel>;
+
+    /**
+     * @internal
+     * Internal use only - hierarchical configurations parsed from components map
+     */
+    hierarchical?: Array<{
+        prefix: string;
+        level: LogLevel;
+        specificity: number;
+    }>;
+
+    /**
+     * @internal
+     * Internal use only - wildcard configurations parsed from components map
+     */
+    wildcards?: Array<{
+        pattern: string;
+        level: LogLevel;
+        specificity: number;
+    }>;
+}
+
+/**
+ * Factory for creating component-specific loggers with hierarchical level control
+ */
+export class FlinkLogFactory {
+    private static globalLevel: LogLevel = "info";
+    private static loggers: Map<string, ComponentLogger> = new Map();
+    private static initialized = false;
+    private static showTimestamps: boolean = true;
+
+    /**
+     * Store component configurations from environment/config for lazy application
+     */
+    private static componentConfigs: Record<string, LogLevel> = {};
+
+    /**
+     * Hierarchical prefix configurations (Java-style)
+     * Sorted by specificity (most specific first) for efficient matching
+     */
+    private static hierarchicalConfigs: Array<{
+        prefix: string;
+        level: LogLevel;
+        specificity: number;
+    }> = [];
+
+    /**
+     * Wildcard pattern configurations (optional, advanced)
+     * Sorted by specificity (most specific first) for efficient matching
+     */
+    private static wildcardConfigs: Array<{
+        pattern: string;
+        level: LogLevel;
+        specificity: number;
+    }> = [];
+
+    /**
+     * Set the global log level (affects all loggers without component-specific levels)
+     */
+    static setGlobalLevel(level: LogLevel) {
+        FlinkLogFactory.globalLevel = level;
+        // node-color-log doesn't support trace, so use debug as the effective level
+        const effectiveLevel = level === "trace" ? "debug" : level;
+        Logger.setLevel(effectiveLevel);
+    }
+
+    /**
+     * Get the current global log level
+     */
+    static getGlobalLevel(): LogLevel {
+        return FlinkLogFactory.globalLevel;
+    }
+
+    /**
+     * Get all registered loggers (useful for debugging)
+     */
+    static getLoggers(): Map<string, ComponentLogger> {
+        return FlinkLogFactory.loggers;
+    }
+
+    /**
+     * Enable or disable timestamps in log messages
+     */
+    static setShowTimestamps(show: boolean) {
+        FlinkLogFactory.showTimestamps = show;
+    }
+
+    /**
+     * Check if timestamps are enabled
+     */
+    static getShowTimestamps(): boolean {
+        return FlinkLogFactory.showTimestamps;
+    }
+
+    /**
+     * Clear all component-specific log levels (fall back to global)
+     */
+    static resetComponentLevels() {
+        FlinkLogFactory.componentConfigs = {};
+        for (const logger of Array.from(FlinkLogFactory.loggers.values())) {
+            logger.clearLevel();
+        }
+    }
+
+    /**
+     * Clear all hierarchical prefix configurations
+     */
+    static resetHierarchicalLevels() {
+        FlinkLogFactory.hierarchicalConfigs = [];
+    }
+
+    /**
+     * Clear all wildcard pattern configurations
+     */
+    static resetWildcardLevels() {
+        FlinkLogFactory.wildcardConfigs = [];
+    }
+
+    /**
+     * Set log level for a specific component by name (exact match)
+     */
+    static setComponentLevel(componentName: string, level: LogLevel | null) {
+        const normalized = FlinkLogFactory.normalize(componentName);
+
+        if (level === null) {
+            // Remove exact match configuration
+            delete FlinkLogFactory.componentConfigs[normalized];
+            const logger = FlinkLogFactory.loggers.get(normalized);
+            if (logger) {
+                logger.clearLevel();
+            }
+        } else {
+            // Set exact match configuration
+            FlinkLogFactory.componentConfigs[normalized] = level;
+            const logger = FlinkLogFactory.loggers.get(normalized);
+            if (logger) {
+                logger.setLevel(level);
+            }
+        }
+    }
+
+    /**
+     * Set hierarchical prefix-based log level (Java-style)
+     * @param prefix Logger name prefix (e.g., "flink.ai" matches all "flink.ai.*")
+     * @param level Log level to apply
+     *
+     * @example
+     * FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+     * // Now all loggers starting with "flink.ai." will use debug level
+     * // This includes the exact match "flink.ai" AND all children "flink.ai.*"
+     */
+    static setHierarchicalLevel(prefix: string, level: LogLevel) {
+        const normalized = FlinkLogFactory.normalize(prefix);
+        // Ensure prefix ends with dot for consistent matching
+        const prefixWithDot = normalized.endsWith(".") ? normalized : normalized + ".";
+        const specificity = FlinkLogFactory.calculatePrefixSpecificity(normalized);
+
+        // Remove existing config for this prefix if it exists
+        FlinkLogFactory.hierarchicalConfigs = FlinkLogFactory.hierarchicalConfigs.filter(
+            (c) => c.prefix !== prefixWithDot
+        );
+
+        // Add new config
+        FlinkLogFactory.hierarchicalConfigs.push({
+            prefix: prefixWithDot,
+            level,
+            specificity,
+        });
+
+        // Also set exact match for the prefix itself (without trailing dot)
+        // This ensures "flink.ai.openai" matches when using setHierarchicalLevel("flink.ai.openai", "debug")
+        FlinkLogFactory.componentConfigs[normalized] = level;
+
+        // Sort by specificity (most specific first) for efficient matching
+        FlinkLogFactory.hierarchicalConfigs.sort((a, b) => b.specificity - a.specificity);
+    }
+
+    /**
+     * Set wildcard pattern-based log level (advanced)
+     * @param pattern Wildcard pattern (e.g., "flink.ai.*" or "flink.ai.**")
+     * @param level Log level to apply
+     *
+     * @example
+     * FlinkLogFactory.setWildcardLevel("flink.ai.*", "debug");
+     * // Matches flink.ai.openai but NOT flink.ai.openai.v4
+     *
+     * FlinkLogFactory.setWildcardLevel("flink.ai.**", "trace");
+     * // Matches any depth under flink.ai.
+     */
+    static setWildcardLevel(pattern: string, level: LogLevel) {
+        const normalized = FlinkLogFactory.normalize(pattern);
+        const specificity = FlinkLogFactory.calculateWildcardSpecificity(normalized);
+
+        // Remove existing config for this pattern if it exists
+        FlinkLogFactory.wildcardConfigs = FlinkLogFactory.wildcardConfigs.filter(
+            (c) => c.pattern !== normalized
+        );
+
+        // Add new config
+        FlinkLogFactory.wildcardConfigs.push({
+            pattern: normalized,
+            level,
+            specificity,
+        });
+
+        // Sort by specificity (most specific first) for efficient matching
+        FlinkLogFactory.wildcardConfigs.sort((a, b) => b.specificity - a.specificity);
+    }
+
+    /**
+     * Get the effective log level for a component (resolved through hierarchy)
+     * @param componentName Component name to check
+     * @returns Resolved log level or null if only global level applies
+     */
+    static getEffectiveLevel(componentName: string): LogLevel | null {
+        return FlinkLogFactory.resolveComponentLevel(componentName);
+    }
+
+    /**
+     * Initialize logging from environment variables and/or configuration file
+     *
+     * Priority (highest to lowest):
+     * 1. Config file (flink.config.js)
+     * 2. Environment variable (LOG_LEVEL=debug)
+     *
+     * @param fileConfig Optional logging configuration from flink.config.js
+     *
+     * @example Environment Variable
+     * ```bash
+     * LOG_LEVEL=debug pnpm run dev
+     * ```
+     *
+     * @example Config File (flink.config.js)
+     * ```javascript
+     * module.exports = {
+     *   logging: {
+     *     global: "info",
+     *     showTimestamps: true,
+     *     components: {
+     *       "flink.ai.openai": "trace",          // exact match
+     *       "flink.ai.*": "debug",               // single-level wildcard
+     *       "flink.database.**": "warn",         // multi-level wildcard
+     *       "flink.handlers.": "info"            // prefix match
+     *     }
+     *   }
+     * };
+     * ```
+     */
+    static configure(fileConfig?: LoggingConfig) {
+        if (FlinkLogFactory.initialized) {
+            return;
+        }
+
+        // 1. Parse environment variables (lowest priority)
+        const envConfig = FlinkLogFactory.parseEnvironment();
+
+        // 2. Parse file config components map (highest priority)
+        let fileComponentsParsed: {
+            exact: Record<string, LogLevel>;
+            hierarchical: Array<{ prefix: string; level: LogLevel; specificity: number }>;
+            wildcards: Array<{ pattern: string; level: LogLevel; specificity: number }>;
+        } = { exact: {}, hierarchical: [], wildcards: [] };
+        if (fileConfig?.components) {
+            fileComponentsParsed = FlinkLogFactory.parseComponentsMap(fileConfig.components);
+        }
+
+        // 3. Merge configurations
+        const finalConfig = {
+            global: fileConfig?.global || envConfig.global || "info",
+            showTimestamps: fileConfig?.showTimestamps ?? true, // default: true
+            exact: {
+                ...fileComponentsParsed.exact,
+            },
+            hierarchical: [...fileComponentsParsed.hierarchical],
+            wildcards: [...fileComponentsParsed.wildcards],
+        };
+
+        // 4. Apply global level
+        FlinkLogFactory.setGlobalLevel(finalConfig.global);
+
+        // 5. Apply timestamp setting
+        FlinkLogFactory.setShowTimestamps(finalConfig.showTimestamps);
+
+        // 6. Store exact component configs
+        FlinkLogFactory.componentConfigs = finalConfig.exact;
+
+        // 7. Store hierarchical configs (sorted by specificity)
+        FlinkLogFactory.hierarchicalConfigs = finalConfig.hierarchical.sort(
+            (a, b) => b.specificity - a.specificity
+        );
+
+        // 8. Store wildcard configs (sorted by specificity)
+        FlinkLogFactory.wildcardConfigs = finalConfig.wildcards.sort(
+            (a, b) => b.specificity - a.specificity
+        );
+
+        FlinkLogFactory.initialized = true;
+    }
+
+    /**
+     * Parse logging configuration from environment variables
+     * Supports only LOG_LEVEL for global level setting
+     */
+    private static parseEnvironment(): LoggingConfig {
+        const config: LoggingConfig = {};
+
+        if (process.env.LOG_LEVEL) {
+            const level = process.env.LOG_LEVEL.toLowerCase();
+            if (FlinkLogFactory.isValidLogLevel(level)) {
+                config.global = level as LogLevel;
+            }
+        }
+
+        return config;
+    }
+
+    /**
+     * Normalize logger name to lowercase (Java-style convention)
+     * @param name Logger name or pattern
+     * @returns Normalized lowercase name
+     */
+    private static normalize(name: string): string {
+        return name.toLowerCase();
+    }
+
+    /**
+     * Determine if a name should be treated as a hierarchical prefix
+     * @param name Normalized logger name
+     * @returns True if it should be treated as a prefix
+     */
+    private static shouldTreatAsPrefix(name: string): boolean {
+        // Default: if name contains dots, treat as hierarchical prefix
+        // This covers the common case where "flink.ai" should match "flink.ai.*"
+        return name.includes(".");
+    }
+
+    /**
+     * Calculate specificity for prefix matching
+     * More specific prefixes (more segments) have higher specificity
+     * @param prefix Prefix string (may or may not end with dot)
+     * @returns Specificity score (number of segments)
+     */
+    private static calculatePrefixSpecificity(prefix: string): number {
+        // Remove trailing dot if present
+        const normalized = prefix.endsWith(".") ? prefix.slice(0, -1) : prefix;
+        // Count dot-separated segments
+        return normalized.split(".").filter((s) => s.length > 0).length;
+    }
+
+    /**
+     * Calculate specificity for wildcard patterns
+     * More specific patterns (more non-wildcard segments) have higher specificity
+     * For same segment count, * (single-level) is more specific than ** (multi-level)
+     * @param pattern Wildcard pattern
+     * @returns Specificity score (base + decimal for wildcard type)
+     */
+    private static calculateWildcardSpecificity(pattern: string): number {
+        const segments = pattern.split(".");
+        const nonWildcardCount = segments.filter((seg) => seg !== "*" && seg !== "**" && seg.length > 0).length;
+
+        // Base specificity: number of non-wildcard segments
+        let specificity = nonWildcardCount * 10;
+
+        // Add fractional specificity based on wildcard type
+        // * (single-level) = more specific than ** (multi-level)
+        if (pattern.includes("*")) {
+            if (pattern.includes("**")) {
+                specificity += 1; // ** is less specific
+            } else {
+                specificity += 5; // * is more specific
+            }
+        }
+
+        return specificity;
+    }
+
+    /**
+     * Resolve component log level through hierarchical matching
+     * Order of precedence (highest to lowest):
+     * 1. Exact match
+     * 2. Most specific prefix match
+     * 3. Less specific prefix match
+     * 4. Wildcard pattern match
+     * 5. null (falls back to global level)
+     *
+     * @param componentName Component name to resolve
+     * @returns Resolved log level or null
+     */
+    private static resolveComponentLevel(componentName: string): LogLevel | null {
+        const normalized = FlinkLogFactory.normalize(componentName);
+
+        // 1. Try exact match first (O(1) - fastest, highest priority)
+        if (FlinkLogFactory.componentConfigs[normalized]) {
+            return FlinkLogFactory.componentConfigs[normalized];
+        }
+
+        // 2. Try hierarchical prefix matches (O(n) where n = number of prefixes)
+        // Already sorted by specificity (most specific first)
+        for (const config of FlinkLogFactory.hierarchicalConfigs) {
+            if (normalized.startsWith(config.prefix)) {
+                return config.level;
+            }
+        }
+
+        // 3. Try wildcard patterns (O(n) where n = number of patterns)
+        // Already sorted by specificity (most specific first)
+        for (const config of FlinkLogFactory.wildcardConfigs) {
+            if (FlinkLogFactory.matchWildcard(normalized, config.pattern)) {
+                return config.level;
+            }
+        }
+
+        // 4. No match - fall back to global level
+        return null;
+    }
+
+    /**
+     * Simple wildcard matching for logger patterns
+     * Supports:
+     * - * matches single segment (flink.ai.* matches flink.ai.openai)
+     * - ** matches any depth (flink.ai.** matches flink.ai.openai.v4)
+     * - Partial segment match (flink.ai.open* matches flink.ai.openai)
+     *
+     * @param name Logger name to match
+     * @param pattern Wildcard pattern
+     * @returns True if pattern matches
+     */
+    private static matchWildcard(name: string, pattern: string): boolean {
+        // Special handling for ** (multi-level wildcard)
+        // Need to process dots BEFORE replacing **
+
+        // Step 1: Escape dots first (before any other processing)
+        let regexPattern = pattern.replace(/\./g, "\\.");
+
+        // Step 2: Replace ** with placeholder (matches anything including dots)
+        regexPattern = regexPattern.replace(/\*\*/g, "___DOUBLE_STAR___");
+
+        // Step 3: Replace single * with single-segment match (non-dot chars)
+        regexPattern = regexPattern.replace(/\*/g, "[^\\.]+");
+
+        // Step 4: Replace ** placeholder with multi-segment match
+        regexPattern = regexPattern.replace(/___DOUBLE_STAR___/g, ".*");
+
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(name);
+    }
+
+    /**
+     * Parse components map and classify entries into exact, prefix, or wildcard matches
+     * @param components Components map from config
+     * @returns Classified configuration
+     */
+    private static parseComponentsMap(components: Record<string, LogLevel>): {
+        exact: Record<string, LogLevel>;
+        hierarchical: Array<{ prefix: string; level: LogLevel; specificity: number }>;
+        wildcards: Array<{ pattern: string; level: LogLevel; specificity: number }>;
+    } {
+        const exact: Record<string, LogLevel> = {};
+        const hierarchical: Array<{ prefix: string; level: LogLevel; specificity: number }> = [];
+        const wildcards: Array<{ pattern: string; level: LogLevel; specificity: number }> = [];
+
+        for (const [key, level] of Object.entries(components)) {
+            const normalized = FlinkLogFactory.normalize(key);
+
+            if (normalized.includes("*")) {
+                // Wildcard pattern (e.g., "flink.ai.*" or "flink.ai.**")
+                wildcards.push({
+                    pattern: normalized,
+                    level,
+                    specificity: FlinkLogFactory.calculateWildcardSpecificity(normalized),
+                });
+            } else if (normalized.endsWith(".")) {
+                // Prefix match (e.g., "flink.ai.")
+                hierarchical.push({
+                    prefix: normalized,
+                    level,
+                    specificity: FlinkLogFactory.calculatePrefixSpecificity(normalized),
+                });
+            } else if (normalized.includes(".")) {
+                // Ambiguous: could be exact or prefix
+                // Store as BOTH exact and hierarchical
+                exact[normalized] = level;
+                hierarchical.push({
+                    prefix: normalized + ".",
+                    level,
+                    specificity: FlinkLogFactory.calculatePrefixSpecificity(normalized),
+                });
+            } else {
+                // Simple name (no dots) - exact match only
+                exact[normalized] = level;
+            }
+        }
+
+        // Sort by specificity (most specific first)
+        hierarchical.sort((a, b) => b.specificity - a.specificity);
+        wildcards.sort((a, b) => b.specificity - a.specificity);
+
+        return { exact, hierarchical, wildcards };
+    }
+
+    /**
+     * Check if a string is a valid log level
+     */
+    private static isValidLogLevel(level: string): boolean {
+        return ["trace", "debug", "info", "warn", "error"].includes(level);
+    }
+
+    /**
+     * Create or retrieve a component-specific logger
+     * Automatically applies environment/config settings when logger is created
+     * Supports hierarchical prefix matching (Java-style)
+     *
+     * @param componentName Logger name (lowercase dot notation recommended, e.g., "flink.ai.openai")
+     * @returns ComponentLogger instance
+     *
+     * @example
+     * ```typescript
+     * // Java-style hierarchical naming (recommended)
+     * const log = FlinkLogFactory.createLogger("flink.ai.openai");
+     * const dbLog = FlinkLogFactory.createLogger("flink.database.mongodb");
+     *
+     * // Case insensitive - these create the same logger
+     * const log1 = FlinkLogFactory.createLogger("flink.ai.openai");
+     * const log2 = FlinkLogFactory.createLogger("Flink.AI.OpenAI");  // Same instance
+     * ```
+     */
+    static createLogger(componentName: string): ComponentLogger {
+        // Initialize from environment and config file if not already done
+        if (!FlinkLogFactory.initialized) {
+            const { loadFlinkConfig } = require("./utils/loadFlinkConfig");
+            const flinkConfig = loadFlinkConfig();
+            FlinkLogFactory.configure(flinkConfig?.logging);
+        }
+
+        // Normalize to lowercase for consistent lookup
+        const normalized = FlinkLogFactory.normalize(componentName);
+
+        if (!FlinkLogFactory.loggers.has(normalized)) {
+            const logger = new ComponentLogger(normalized);
+            FlinkLogFactory.loggers.set(normalized, logger);
+
+            // Resolve level through hierarchical matching
+            const resolvedLevel = FlinkLogFactory.resolveComponentLevel(normalized);
+            if (resolvedLevel) {
+                logger.setLevel(resolvedLevel);
+            }
+        }
+        return FlinkLogFactory.loggers.get(normalized)!;
+    }
+}