utils.py

"""
Utility functions for Linux Incident Time Machine.
"""
import logging
import sys
import threading
from collections import OrderedDict
from pathlib import Path
from typing import Optional
import pwd


def setup_logging(
    log_level: str = "INFO",
    log_file: Optional[Path] = None,
    quiet: bool = False
) -> logging.Logger:
    """
    Setup professional logging configuration.
    
    Args:
        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
        log_file: Optional file path for log output
        quiet: If True, only log warnings and errors
        
    Returns:
        Configured logger instance
    """
    level = logging.WARNING if quiet else getattr(logging, log_level.upper(), logging.INFO)
    
    handlers = [logging.StreamHandler(sys.stderr)]
    if log_file:
        handlers.append(logging.FileHandler(log_file))
    
    logging.basicConfig(
        level=level,
        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
        datefmt='%Y-%m-%d %H:%M:%S',
        handlers=handlers
    )
    
    return logging.getLogger(__name__)


class UserResolver:
    """Resolve UID to username with thread-safe LRU cache."""
    _cache: OrderedDict[int, Optional[str]] = OrderedDict()
    _max_cache_size: int = 10000
    _lock = threading.Lock()
    
    @classmethod
    def resolve(cls, uid: int) -> Optional[str]:
        """
        Resolve UID to username with thread-safe LRU cache.
        
        Args:
            uid: User ID to resolve
            
        Returns:
            Username or None if not found
        """
        # Check cache first (thread-safe)
        with cls._lock:
            if uid in cls._cache:
                # Move to end (most recently used)
                cls._cache.move_to_end(uid)
                return cls._cache[uid]
        
        # Resolve UID (outside lock to avoid blocking)
        try:
            user_info = pwd.getpwuid(uid)
            username = user_info.pw_name
        except KeyError:
            username = None
        except Exception:
            # Fallback if pwd module is not available or fails
            username = None
        
        # Update cache (thread-safe)
        with cls._lock:
            # Check again in case another thread added it
            if uid in cls._cache:
                cls._cache.move_to_end(uid)
                return cls._cache[uid]
            
            # Check cache size and evict if needed
            if len(cls._cache) >= cls._max_cache_size:
                # Remove oldest entry (LRU eviction)
                cls._cache.popitem(last=False)
            
            # Add to cache
            cls._cache[uid] = username
            cls._cache.move_to_end(uid)
        
        return username
    
    @classmethod
    def clear_cache(cls):
        """Clear the username cache (thread-safe)."""
        with cls._lock:
            cls._cache.clear()
    
    @classmethod
    def get_cache_size(cls) -> int:
        """Get current cache size (thread-safe)."""
        with cls._lock:
            return len(cls._cache)


def validate_audit_log_file(filepath: Path, max_size_mb: int = 1000) -> None:
    """
    Validate audit log file before processing.
    
    Args:
        filepath: Path to audit log file
        max_size_mb: Maximum file size in MB
        
    Raises:
        FileNotFoundError: If file doesn't exist
        ValueError: If file is empty or too large
    """
    if not filepath.exists():
        raise FileNotFoundError(f"Audit log file not found: {filepath}")
    
    file_size = filepath.stat().st_size
    
    if file_size == 0:
        raise ValueError(f"Audit log file is empty: {filepath}")
    
    size_mb = file_size / (1024 * 1024)
    if size_mb > max_size_mb:
        raise ValueError(
            f"Audit log file too large ({size_mb:.1f}MB > {max_size_mb}MB): {filepath}"
        )