mlx-stack 0.1.0__py3-none-any.whl

mlx_stack/core/log_rotation.py

@@ -0,0 +1,231 @@
+"""Log rotation infrastructure for mlx-stack.
+
+Implements copytruncate-based rotation for service log files in
+~/.mlx-stack/logs/. The rotation strategy copies the log file to an
+archive, compresses it with gzip, then truncates the original in-place
+so that the writing process's file descriptor remains valid.
+
+Archive naming uses sequential numbering:
+  <name>.log.1.gz = most recent rotation
+  <name>.log.2.gz = second most recent
+  ...
+  <name>.log.N.gz = oldest retained rotation
+
+Archives beyond max_files are deleted.
+"""
+
+from __future__ import annotations
+
+import gzip
+import logging
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class LogRotationError(Exception):
+    """Raised when a log rotation operation fails."""
+
+
+def rotate_log(
+    log_path: Path,
+    max_size_mb: int = 50,
+    max_files: int = 5,
+) -> bool:
+    """Rotate a log file using the copytruncate strategy.
+
+    If the log file exceeds ``max_size_mb``, this function:
+    1. Shifts existing archives up by one number (.1.gz → .2.gz, etc.)
+    2. Copies the current log to ``<name>.log.1.gz`` (gzip compressed)
+    3. Truncates the original log file in-place (preserving the FD)
+    4. Deletes archives numbered higher than ``max_files``
+
+    Args:
+        log_path: Path to the log file to rotate.
+        max_size_mb: Maximum log file size in megabytes before rotation.
+        max_files: Maximum number of rotated archive files to retain.
+
+    Returns:
+        True if rotation was performed, False if skipped (file missing,
+        empty, or below threshold).
+
+    Raises:
+        LogRotationError: If a permission error or I/O error prevents
+            rotation.
+    """
+    # Edge case: missing file — silently skip
+    if not log_path.exists():
+        return False
+
+    # Edge case: empty file — skip
+    try:
+        file_size = log_path.stat().st_size
+    except OSError:
+        return False
+
+    if file_size == 0:
+        return False
+
+    # Edge case: below threshold — skip
+    threshold_bytes = max_size_mb * 1024 * 1024
+    if file_size < threshold_bytes:
+        return False
+
+    try:
+        _perform_rotation(log_path, max_files)
+    except PermissionError as exc:
+        msg = f"Permission denied during log rotation of {log_path}: {exc}"
+        raise LogRotationError(msg) from None
+    except OSError as exc:
+        msg = f"I/O error during log rotation of {log_path}: {exc}"
+        raise LogRotationError(msg) from None
+
+    return True
+
+
+def _perform_rotation(log_path: Path, max_files: int) -> None:
+    """Execute the actual rotation steps.
+
+    This is separated from ``rotate_log`` to keep the edge-case
+    handling clean.
+
+    Args:
+        log_path: Path to the log file.
+        max_files: Maximum number of archive files to keep.
+    """
+    base = log_path.parent
+    stem = log_path.name  # e.g. "fast.log"
+
+    # Step 1: Delete archives beyond max_files (they'll shift up by 1)
+    # After shifting, the old .max_files.gz becomes .(max_files+1).gz
+    # so we need to delete .max_files.gz before shifting
+    _delete_excess_archives(base, stem, max_files)
+
+    # Step 2: Shift existing archives up by one number
+    _shift_archives(base, stem, max_files)
+
+    # Step 3: Copy current log to temporary file, compress to .1.gz
+    archive_path = base / f"{stem}.1.gz"
+    _copy_and_compress(log_path, archive_path)
+
+    # Step 4: Truncate the original log file in-place
+    _truncate_file(log_path)
+
+
+def _archive_path_for(base: Path, stem: str, number: int) -> Path:
+    """Return the path for archive number N.
+
+    Args:
+        base: Parent directory.
+        stem: Log file name (e.g. "fast.log").
+        number: Archive number (1 = most recent).
+
+    Returns:
+        Path like ``base/fast.log.1.gz``.
+    """
+    return base / f"{stem}.{number}.gz"
+
+
+def _delete_excess_archives(base: Path, stem: str, max_files: int) -> None:
+    """Delete archives numbered higher than max_files.
+
+    After the upcoming shift, what is currently archive N will become
+    archive N+1. So we need to remove the current max_files archive
+    (which would become max_files+1 after shifting) and any existing
+    archives beyond max_files.
+
+    Scans the logs directory for ALL matching archive files using a glob
+    pattern (``<stem>.*.gz``) instead of stopping at the first missing
+    sequential index. Archives are sorted by modification time; the
+    oldest are deleted until the count is at or below ``max_files - 1``
+    (leaving room for the new rotation).
+
+    Args:
+        base: Parent directory.
+        stem: Log file name.
+        max_files: Maximum archives to keep.
+    """
+    import re
+
+    pattern = re.compile(rf"^{re.escape(stem)}\.(\d+)\.gz$")
+    archives: list[Path] = []
+
+    for path in base.iterdir():
+        if pattern.match(path.name) and path.is_file():
+            archives.append(path)
+
+    # We need room for the new archive that will become .1.gz after
+    # shifting, so keep at most max_files - 1 existing archives.
+    if len(archives) < max_files:
+        return
+
+    # Sort by modification time, oldest first
+    archives.sort(key=lambda p: p.stat().st_mtime)
+
+    # Delete oldest until we have at most max_files - 1
+    excess = len(archives) - (max_files - 1)
+    for path in archives[:excess]:
+        path.unlink()
+
+
+def _shift_archives(base: Path, stem: str, max_files: int) -> None:
+    """Shift existing archives up by one number.
+
+    Moves .N.gz → .(N+1).gz, starting from the highest existing
+    number down to 1, to avoid overwriting.
+
+    Args:
+        base: Parent directory.
+        stem: Log file name.
+        max_files: Maximum archives (used as upper bound for search).
+    """
+    # Find the highest existing archive number (up to max_files - 1,
+    # since max_files was already deleted)
+    highest = 0
+    for i in range(1, max_files):
+        if _archive_path_for(base, stem, i).exists():
+            highest = i
+
+    # Shift from highest down to 1
+    for i in range(highest, 0, -1):
+        src = _archive_path_for(base, stem, i)
+        dst = _archive_path_for(base, stem, i + 1)
+        if src.exists():
+            src.rename(dst)
+
+
+def _copy_and_compress(src: Path, dst_gz: Path) -> None:
+    """Copy a file and compress it to a gzip archive.
+
+    Uses shutil.copy2 to copy to a temporary file, then compresses
+    the temporary file to the target gzip path.
+
+    Args:
+        src: Source log file path.
+        dst_gz: Destination gzip archive path.
+    """
+    # Create a temporary uncompressed copy
+    tmp_path = dst_gz.parent / f"{dst_gz.name}.tmp"
+    try:
+        shutil.copy2(str(src), str(tmp_path))
+
+        # Compress the copy
+        with open(tmp_path, "rb") as f_in:
+            with gzip.open(str(dst_gz), "wb") as f_out:
+                shutil.copyfileobj(f_in, f_out)
+    finally:
+        # Clean up temporary file
+        if tmp_path.exists():
+            tmp_path.unlink()
+
+
+def _truncate_file(path: Path) -> None:
+    """Truncate a file in-place, preserving the path.
+
+    Uses ``open(path, "w").close()`` to truncate to zero bytes.
+
+    Args:
+        path: Path to the file to truncate.
+    """
+    open(path, "w").close()  # noqa: SIM115

mlx_stack/core/log_viewer.py

@@ -0,0 +1,386 @@
+"""Log viewing and management module for mlx-stack.
+
+Provides core functionality for viewing, following, listing, and rotating
+service log files in ~/.mlx-stack/logs/. Supports tail-style viewing,
+real-time following with truncation detection, log listing with metadata,
+on-demand rotation, and archived log viewing.
+"""
+
+from __future__ import annotations
+
+import gzip
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mlx_stack.core.config import get_value
+from mlx_stack.core.log_rotation import LogRotationError, rotate_log
+from mlx_stack.core.paths import get_logs_dir
+
+# --------------------------------------------------------------------------- #
+# Constants
+# --------------------------------------------------------------------------- #
+
+# Polling interval for --follow mode (seconds)
+FOLLOW_POLL_INTERVAL = 0.5
+
+# Default number of lines for --tail
+DEFAULT_TAIL_LINES = 50
+
+# --------------------------------------------------------------------------- #
+# Data classes
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class LogFileInfo:
+    """Metadata about a log file."""
+
+    name: str
+    service: str
+    size_bytes: int
+    modified: datetime
+    is_archive: bool = False
+
+    @property
+    def size_display(self) -> str:
+        """Return human-readable file size."""
+        if self.size_bytes < 1024:
+            return f"{self.size_bytes} B"
+        elif self.size_bytes < 1024 * 1024:
+            return f"{self.size_bytes / 1024:.1f} KB"
+        elif self.size_bytes < 1024 * 1024 * 1024:
+            return f"{self.size_bytes / (1024 * 1024):.1f} MB"
+        else:
+            return f"{self.size_bytes / (1024 * 1024 * 1024):.1f} GB"
+
+    @property
+    def modified_display(self) -> str:
+        """Return human-readable modification time."""
+        return self.modified.strftime("%Y-%m-%d %H:%M:%S")
+
+
+@dataclass
+class RotationResult:
+    """Result of a rotation operation."""
+
+    service: str
+    rotated: bool
+    error: str | None = None
+
+
+# --------------------------------------------------------------------------- #
+# Log listing
+# --------------------------------------------------------------------------- #
+
+
+def list_log_files() -> list[LogFileInfo]:
+    """List all log files in the logs directory.
+
+    Returns current log files (*.log) sorted alphabetically. Does not
+    include archived .gz files.
+
+    Returns:
+        List of LogFileInfo objects for each log file found.
+    """
+    logs_dir = get_logs_dir()
+    if not logs_dir.exists():
+        return []
+
+    results: list[LogFileInfo] = []
+    for path in sorted(logs_dir.iterdir()):
+        if path.suffix == ".log" and path.is_file():
+            # Extract service name: "fast.log" -> "fast"
+            service = path.stem
+            try:
+                stat = path.stat()
+                info = LogFileInfo(
+                    name=path.name,
+                    service=service,
+                    size_bytes=stat.st_size,
+                    modified=datetime.fromtimestamp(
+                        stat.st_mtime, tz=timezone.utc
+                    ),
+                )
+                results.append(info)
+            except OSError:
+                continue
+
+    return results
+
+
+def get_log_path(service: str) -> Path | None:
+    """Get the path to a service's log file.
+
+    Args:
+        service: The service name (e.g. "fast", "litellm").
+
+    Returns:
+        Path to the log file, or None if it doesn't exist.
+    """
+    logs_dir = get_logs_dir()
+    log_path = logs_dir / f"{service}.log"
+    if log_path.exists() and log_path.is_file():
+        return log_path
+    return None
+
+
+def get_available_services() -> list[str]:
+    """Get list of services that have log files.
+
+    Returns:
+        Sorted list of service names with existing log files.
+    """
+    return [info.service for info in list_log_files()]
+
+
+# --------------------------------------------------------------------------- #
+# Log viewing
+# --------------------------------------------------------------------------- #
+
+
+def read_log_tail(log_path: Path, num_lines: int = DEFAULT_TAIL_LINES) -> str:
+    """Read the last N lines from a log file.
+
+    Args:
+        log_path: Path to the log file.
+        num_lines: Number of lines to return from the end.
+
+    Returns:
+        String containing the last N lines of the file.
+    """
+    try:
+        content = log_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+    if not content:
+        return ""
+
+    lines = content.splitlines()
+    tail_lines = lines[-num_lines:] if len(lines) > num_lines else lines
+    return "\n".join(tail_lines)
+
+
+def read_log_full(log_path: Path) -> str:
+    """Read the full content of a log file.
+
+    Args:
+        log_path: Path to the log file.
+
+    Returns:
+        Full file content as a string.
+    """
+    try:
+        return log_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+# --------------------------------------------------------------------------- #
+# Log following
+# --------------------------------------------------------------------------- #
+
+
+def follow_log(
+    log_path: Path,
+    num_lines: int = DEFAULT_TAIL_LINES,
+    output_callback: Callable[[str], None] | None = None,
+) -> None:
+    """Follow a log file, printing new content as it appears.
+
+    Implements tail -f behavior using polling. Checks file size every
+    FOLLOW_POLL_INTERVAL seconds, reads new content when size increases.
+    Detects file truncation (size decrease) and resets read position.
+
+    This function blocks until interrupted. Ctrl-C is handled cleanly
+    (no traceback, exit 0).
+
+    Args:
+        log_path: Path to the log file to follow.
+        num_lines: Number of initial lines to show.
+        output_callback: Optional callable for writing output. If None,
+            uses print(). Signature: callback(text: str) -> None.
+    """
+    write = output_callback or print
+
+    # Show initial tail
+    initial = read_log_tail(log_path, num_lines)
+    if initial:
+        write(initial)
+
+    # Start following from current end of file
+    try:
+        position = log_path.stat().st_size
+    except OSError:
+        position = 0
+
+    try:
+        while True:
+            time.sleep(FOLLOW_POLL_INTERVAL)
+
+            try:
+                current_size = log_path.stat().st_size
+            except OSError:
+                # File may have been removed temporarily
+                continue
+
+            # Detect truncation (copytruncate rotation)
+            if current_size < position:
+                position = 0
+
+            if current_size > position:
+                try:
+                    with open(log_path, "r", encoding="utf-8", errors="replace") as f:
+                        f.seek(position)
+                        new_content = f.read()
+                        if new_content:
+                            # Strip trailing newline to avoid double-spacing
+                            text = new_content.rstrip("\n")
+                            if text:
+                                write(text)
+                        position = f.tell()
+                except OSError:
+                    continue
+
+    except KeyboardInterrupt:
+        # Clean exit on Ctrl-C — no traceback
+        pass
+
+
+# --------------------------------------------------------------------------- #
+# Archived log viewing
+# --------------------------------------------------------------------------- #
+
+
+def _get_archives_for_service(service: str) -> list[Path]:
+    """Get archived log files for a service, sorted oldest first.
+
+    Archives are named like ``<service>.log.N.gz`` where N=1 is the most
+    recent. We return them sorted with the highest N first (oldest first)
+    for chronological display.
+
+    Args:
+        service: The service name.
+
+    Returns:
+        List of archive paths, sorted oldest first.
+    """
+    logs_dir = get_logs_dir()
+    if not logs_dir.exists():
+        return []
+
+    pattern = re.compile(rf"^{re.escape(service)}\.log\.(\d+)\.gz$")
+    archives: list[tuple[int, Path]] = []
+
+    for path in logs_dir.iterdir():
+        match = pattern.match(path.name)
+        if match and path.is_file():
+            num = int(match.group(1))
+            archives.append((num, path))
+
+    # Sort by number descending (highest number = oldest)
+    archives.sort(key=lambda x: x[0], reverse=True)
+    return [path for _, path in archives]
+
+
+def read_archive(archive_path: Path) -> str:
+    """Read and decompress a gzip archive.
+
+    Args:
+        archive_path: Path to the .gz archive file.
+
+    Returns:
+        Decompressed content as a string.
+    """
+    try:
+        with gzip.open(str(archive_path), "rb") as f:
+            return f.read().decode("utf-8", errors="replace")
+    except (OSError, gzip.BadGzipFile):
+        return f"[Error reading archive: {archive_path.name}]\n"
+
+
+def read_all_logs(service: str) -> str:
+    """Read all logs for a service: archives + current, chronologically.
+
+    Archives are shown oldest first, then the current log file.
+
+    Args:
+        service: The service name.
+
+    Returns:
+        Combined content from all archives and the current log.
+    """
+    parts: list[str] = []
+
+    # Read archives oldest first
+    archives = _get_archives_for_service(service)
+    for archive_path in archives:
+        content = read_archive(archive_path)
+        if content:
+            parts.append(f"--- Archive: {archive_path.name} ---")
+            parts.append(content.rstrip("\n"))
+
+    # Read current log
+    log_path = get_log_path(service)
+    if log_path is not None:
+        current = read_log_full(log_path)
+        if current:
+            parts.append(f"--- Current: {log_path.name} ---")
+            parts.append(current.rstrip("\n"))
+
+    return "\n".join(parts) if parts else ""
+
+
+# --------------------------------------------------------------------------- #
+# On-demand rotation
+# --------------------------------------------------------------------------- #
+
+
+def rotate_service_log(service: str) -> RotationResult:
+    """Rotate a single service's log file.
+
+    Uses configured max_size_mb and max_files from the config module.
+
+    Args:
+        service: The service name.
+
+    Returns:
+        RotationResult indicating whether rotation was performed.
+    """
+    log_path = get_log_path(service)
+    if log_path is None:
+        return RotationResult(
+            service=service,
+            rotated=False,
+            error=f"No log file found for service '{service}'",
+        )
+
+    max_size_mb = get_value("log-max-size-mb")
+    max_files = get_value("log-max-files")
+
+    try:
+        rotated = rotate_log(log_path, max_size_mb=max_size_mb, max_files=max_files)
+        return RotationResult(service=service, rotated=rotated)
+    except LogRotationError as exc:
+        return RotationResult(service=service, rotated=False, error=str(exc))
+
+
+def rotate_all_logs() -> list[RotationResult]:
+    """Rotate all eligible service log files.
+
+    Returns:
+        List of RotationResult objects, one per service.
+    """
+    services = get_available_services()
+    if not services:
+        return []
+
+    results: list[RotationResult] = []
+    for service in services:
+        result = rotate_service_log(service)
+        results.append(result)
+    return results