TimeTracker/app/utils/file_upload.py

"""
File upload utilities with validation and security.
"""

from typing import Optional, Tuple
from werkzeug.utils import secure_filename
from flask import current_app
import os
from pathlib import Path
from app.constants import MAX_FILE_SIZE, ALLOWED_IMAGE_EXTENSIONS, ALLOWED_DOCUMENT_EXTENSIONS


def validate_file_upload(
    file, allowed_extensions: Optional[set] = None, max_size: int = MAX_FILE_SIZE
) -> Tuple[bool, Optional[str]]:
    """
    Validate a file upload.

    Args:
        file: File object from request
        allowed_extensions: Set of allowed extensions (defaults to all)
        max_size: Maximum file size in bytes

    Returns:
        tuple of (is_valid, error_message)
    """
    if not file or not file.filename:
        return False, "No file provided"

    # Check file size
    file.seek(0, os.SEEK_END)
    file_size = file.tell()
    file.seek(0)

    if file_size > max_size:
        return False, f"File size exceeds maximum of {max_size / (1024*1024):.1f}MB"

    # Check extension
    if allowed_extensions:
        filename = secure_filename(file.filename)
        ext = Path(filename).suffix.lower()
        if ext not in allowed_extensions:
            return False, f"File type not allowed. Allowed types: {', '.join(allowed_extensions)}"

    return True, None


def save_uploaded_file(
    file, upload_folder: str, subfolder: Optional[str] = None, prefix: Optional[str] = None
) -> Optional[str]:
    """
    Save an uploaded file securely.

    Args:
        file: File object from request
        upload_folder: Base upload folder
        subfolder: Optional subfolder (e.g., 'receipts', 'avatars')
        prefix: Optional filename prefix

    Returns:
        Saved file path or None on error
    """
    try:
        # Secure filename
        filename = secure_filename(file.filename)
        if not filename:
            return None

        # Add prefix if provided
        if prefix:
            name, ext = os.path.splitext(filename)
            filename = f"{prefix}_{name}{ext}"

        # Create directory structure
        if subfolder:
            upload_path = os.path.join(upload_folder, subfolder)
        else:
            upload_path = upload_folder

        os.makedirs(upload_path, exist_ok=True)

        # Ensure unique filename
        filepath = os.path.join(upload_path, filename)
        counter = 1
        while os.path.exists(filepath):
            name, ext = os.path.splitext(filename)
            filepath = os.path.join(upload_path, f"{name}_{counter}{ext}")
            counter += 1

        # Save file
        file.save(filepath)

        # Return relative path
        if subfolder:
            return os.path.join(subfolder, os.path.basename(filepath))
        return os.path.basename(filepath)

    except Exception as e:
        current_app.logger.error(f"Error saving uploaded file: {e}")
        return None


def delete_uploaded_file(filepath: str, upload_folder: str) -> bool:
    """
    Delete an uploaded file.

    Args:
        filepath: Relative file path
        upload_folder: Base upload folder

    Returns:
        True if deleted, False otherwise
    """
    try:
        full_path = os.path.join(upload_folder, filepath)
        if os.path.exists(full_path):
            os.remove(full_path)
            return True
        return False
    except Exception as e:
        current_app.logger.error(f"Error deleting file {filepath}: {e}")
        return False


def get_file_info(filepath: str, upload_folder: str) -> Optional[dict]:
    """
    Get information about an uploaded file.

    Args:
        filepath: Relative file path
        upload_folder: Base upload folder

    Returns:
        dict with file info or None
    """
    try:
        full_path = os.path.join(upload_folder, filepath)
        if not os.path.exists(full_path):
            return None

        stat = os.stat(full_path)
        return {
            "path": filepath,
            "size": stat.st_size,
            "modified": stat.st_mtime,
            "extension": Path(filepath).suffix.lower(),
        }
    except Exception as e:
        current_app.logger.error(f"Error getting file info: {e}")
        return None