mcp_host/

utils.rs

//! Utility functions for file handling, path security, and encoding
//!
//! Provides common utilities needed by MCP servers: file collection with
//! gitignore support, path security validation, byte offset conversion,
//! and base64 encoding for pagination cursors.

use std::path::{Path, PathBuf};

/// Collect files recursively from a path, respecting .gitignore
///
/// Uses `ignore` crate to respect:
/// - `.gitignore` files
/// - `.git/info/exclude`
/// - Global git ignore configuration
///
/// # Arguments
///
/// * `path` - File or directory to collect from
///
/// # Returns
///
/// Vector of file paths (directories are excluded)
///
/// # Example
///
/// ```rust,ignore
/// let files = collect_files(Path::new("src"));
/// for file in files {
///     println!("Found: {:?}", file);
/// }
/// ```
pub fn collect_files(path: &Path) -> Vec<PathBuf> {
    use ignore::WalkBuilder;

    let mut files = Vec::new();
    if path.is_file() {
        files.push(path.to_path_buf());
    } else if path.is_dir() {
        let walker = WalkBuilder::new(path)
            .standard_filters(true) // enables .gitignore, .git/info/exclude, global config
            .build();

        for result in walker.flatten() {
            if result.file_type().is_some_and(|ft| ft.is_file()) {
                files.push(result.path().to_path_buf());
            }
        }
    }
    files
}

/// Convert byte offset to line and column numbers
///
/// Useful for converting byte-based spans from parsers to human-readable
/// line/column positions.
///
/// # Arguments
///
/// * `src` - Source text
/// * `byte_idx` - Byte offset into source
///
/// # Returns
///
/// Tuple of (line, column), both 1-indexed
///
/// # Example
///
/// ```rust
/// use mcp_host::utils::byte_to_line_col;
///
/// let src = "hello\nworld";
/// let (line, col) = byte_to_line_col(src, 6);
/// assert_eq!((line, col), (2, 1)); // First char of "world"
/// ```
pub fn byte_to_line_col(src: &str, byte_idx: usize) -> (usize, usize) {
    let mut line = 1;
    let mut col = 1;
    for (i, ch) in src.char_indices() {
        if i == byte_idx {
            return (line, col);
        }
        if ch == '\n' {
            line += 1;
            col = 1;
        } else {
            col += 1;
        }
    }
    (line, col)
}

/// Check if a path is within a base directory (security boundary)
///
/// Prevents path traversal attacks by ensuring paths don't escape the
/// base directory using `..` or absolute paths.
///
/// # Arguments
///
/// * `path` - Path to validate
/// * `base_dir` - Base directory (security boundary)
///
/// # Returns
///
/// `true` if path is within base_dir, `false` otherwise
///
/// # Security
///
/// This function prevents:
/// - Absolute paths outside base_dir
/// - Relative paths with `..` that escape base_dir
/// - Symlink escapes (via canonicalization)
///
/// # Example
///
/// ```rust,ignore
/// let cwd = std::env::current_dir()?;
/// assert!(is_safe_path(Path::new("foo/bar.txt"), &cwd));
/// assert!(!is_safe_path(Path::new("../etc/passwd"), &cwd));
/// ```
pub fn is_safe_path(path: &Path, base_dir: &Path) -> bool {
    let resolved = if path.is_absolute() {
        path.to_path_buf()
    } else {
        base_dir.join(path)
    };

    // Try canonicalize first (handles symlinks and ..)
    if let (Ok(resolved_canon), Ok(base_canon)) = (resolved.canonicalize(), base_dir.canonicalize())
    {
        return resolved_canon.starts_with(&base_canon);
    }

    // For non-existent paths, do basic check:
    // - Absolute paths outside base are rejected
    // - Relative paths with .. that escape are rejected
    if path.is_absolute() {
        if let Ok(base_canon) = base_dir.canonicalize() {
            return resolved.starts_with(&base_canon);
        }
        return false;
    }

    // Relative path - check it doesn't start with .. that would escape
    let mut depth: i32 = 0;
    for component in path.components() {
        match component {
            std::path::Component::ParentDir => depth -= 1,
            std::path::Component::Normal(_) => depth += 1,
            _ => {}
        }
        if depth < 0 {
            return false; // Escapes base with ..
        }
    }
    true // Relative path stays within base
}

/// Base64 encode bytes
///
/// Useful for creating pagination cursors or encoding binary data
/// for JSON transmission.
///
/// # Arguments
///
/// * `data` - Bytes to encode
///
/// # Returns
///
/// Base64-encoded string
pub fn base64_encode(data: &[u8]) -> String {
    use base64::{engine::general_purpose::STANDARD, Engine};
    STANDARD.encode(data)
}

/// Base64 decode string
///
/// Decodes base64-encoded data. Returns empty vector on invalid input.
///
/// # Arguments
///
/// * `s` - Base64-encoded string
///
/// # Returns
///
/// Decoded bytes, or empty vector if invalid
pub fn base64_decode(s: &str) -> Vec<u8> {
    use base64::{engine::general_purpose::STANDARD, Engine};
    STANDARD.decode(s).unwrap_or_default()
}

// ============================================================================
// Pagination Utilities
// ============================================================================

/// Default page size for list operations
pub const DEFAULT_PAGE_SIZE: usize = 100;

/// Result of a paginated list operation
#[derive(Debug, Clone)]
pub struct PaginatedResult<T> {
    /// Items in the current page
    pub items: Vec<T>,
    /// Cursor for the next page, if more items exist
    pub next_cursor: Option<String>,
}

impl<T> PaginatedResult<T> {
    /// Create a new paginated result
    pub fn new(items: Vec<T>, next_cursor: Option<String>) -> Self {
        Self { items, next_cursor }
    }

    /// Create an empty result
    pub fn empty() -> Self {
        Self {
            items: Vec::new(),
            next_cursor: None,
        }
    }
}

/// Encode a pagination cursor
///
/// Creates an opaque base64-encoded cursor from an offset.
/// The cursor format is implementation-specific and clients
/// should treat it as opaque.
pub fn encode_cursor(offset: usize) -> String {
    base64_encode(offset.to_string().as_bytes())
}

/// Decode a pagination cursor
///
/// Decodes an opaque cursor back to an offset.
/// Returns None for invalid cursors.
pub fn decode_cursor(cursor: &str) -> Option<usize> {
    let bytes = base64_decode(cursor);
    let s = String::from_utf8(bytes).ok()?;
    s.parse().ok()
}

/// Paginate a list of items
///
/// Generic pagination helper that works with any list of items.
/// Uses offset-based pagination with opaque cursors.
///
/// # Arguments
///
/// * `items` - Full list of items to paginate
/// * `cursor` - Optional cursor from previous page
/// * `page_size` - Maximum items per page
///
/// # Returns
///
/// PaginatedResult with the current page and optional next cursor
pub fn paginate<T: Clone>(
    items: &[T],
    cursor: Option<&str>,
    page_size: usize,
) -> PaginatedResult<T> {
    if items.is_empty() {
        return PaginatedResult::empty();
    }

    // Decode cursor to get starting offset
    let start = cursor.and_then(decode_cursor).unwrap_or(0).min(items.len());

    let end = (start + page_size).min(items.len());
    let page_items: Vec<T> = items[start..end].to_vec();

    // Generate next cursor if there are more items
    let next_cursor = if end < items.len() {
        Some(encode_cursor(end))
    } else {
        None
    };

    PaginatedResult::new(page_items, next_cursor)
}

#[cfg(test)]
mod tests {
    use super::*;

    // ========== is_safe_path tests ==========

    #[test]
    fn test_is_safe_path_relative() {
        let base = std::env::current_dir().unwrap();
        assert!(is_safe_path(Path::new("foo"), &base));
        assert!(is_safe_path(Path::new("foo/bar"), &base));
        assert!(is_safe_path(Path::new("./foo"), &base));
    }

    #[test]
    fn test_is_safe_path_parent_escape() {
        let base = std::env::current_dir().unwrap();
        assert!(!is_safe_path(Path::new("../foo"), &base));
        assert!(!is_safe_path(Path::new("foo/../../bar"), &base));
        assert!(!is_safe_path(Path::new(".."), &base));
    }

    #[test]
    fn test_is_safe_path_absolute_outside() {
        let base = std::env::current_dir().unwrap();
        assert!(!is_safe_path(Path::new("/tmp"), &base));
        assert!(!is_safe_path(Path::new("/etc/passwd"), &base));
        assert!(!is_safe_path(Path::new("/home"), &base));
    }

    // ========== Base64 encoding tests ==========

    #[test]
    fn test_base64_roundtrip() {
        let original = "42";
        let encoded = base64_encode(original.as_bytes());
        let decoded = String::from_utf8(base64_decode(&encoded)).unwrap();
        assert_eq!(original, decoded);
    }

    #[test]
    fn test_base64_offset_encoding() {
        let offsets = [0, 10, 100, 12345];
        for offset in offsets {
            let encoded = base64_encode(offset.to_string().as_bytes());
            let decoded: usize = String::from_utf8(base64_decode(&encoded))
                .unwrap()
                .parse()
                .unwrap();
            assert_eq!(offset, decoded);
        }
    }

    #[test]
    fn test_base64_invalid_input() {
        // Invalid base64 should return empty vec
        let result = base64_decode("!!!invalid!!!");
        assert!(result.is_empty());
    }

    // ========== byte_to_line_col tests ==========

    #[test]
    fn test_byte_to_line_col_start() {
        let src = "hello\nworld\n";
        let (line, col) = byte_to_line_col(src, 0);
        assert_eq!((line, col), (1, 1));
    }

    #[test]
    fn test_byte_to_line_col_middle_first_line() {
        let src = "hello\nworld\n";
        let (line, col) = byte_to_line_col(src, 2);
        assert_eq!((line, col), (1, 3)); // 'l' at position 2
    }

    #[test]
    fn test_byte_to_line_col_second_line() {
        let src = "hello\nworld\n";
        let (line, col) = byte_to_line_col(src, 6);
        assert_eq!((line, col), (2, 1)); // 'w' at start of line 2
    }

    #[test]
    fn test_byte_to_line_col_end() {
        let src = "hello\nworld\n";
        let (line, col) = byte_to_line_col(src, 11);
        assert_eq!((line, col), (2, 6)); // newline at end of 'world'
    }

    #[test]
    fn test_byte_to_line_col_beyond_end() {
        let src = "hi";
        let (line, col) = byte_to_line_col(src, 100);
        // Should return last position
        assert_eq!((line, col), (1, 3));
    }

    // ========== pagination tests ==========

    #[test]
    fn test_encode_decode_cursor() {
        let cursor = encode_cursor(42);
        assert_eq!(decode_cursor(&cursor), Some(42));
    }

    #[test]
    fn test_decode_invalid_cursor() {
        assert_eq!(decode_cursor("invalid"), None);
        assert_eq!(decode_cursor("!!!"), None);
    }

    #[test]
    fn test_paginate_empty() {
        let items: Vec<i32> = vec![];
        let result = paginate(&items, None, 10);
        assert!(result.items.is_empty());
        assert!(result.next_cursor.is_none());
    }

    #[test]
    fn test_paginate_no_cursor_within_limit() {
        let items: Vec<i32> = vec![1, 2, 3, 4, 5];
        let result = paginate(&items, None, 10);
        assert_eq!(result.items, vec![1, 2, 3, 4, 5]);
        assert!(result.next_cursor.is_none());
    }

    #[test]
    fn test_paginate_no_cursor_exceeds_limit() {
        let items: Vec<i32> = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
        let result = paginate(&items, None, 3);
        assert_eq!(result.items, vec![1, 2, 3]);
        assert!(result.next_cursor.is_some());
    }

    #[test]
    fn test_paginate_with_cursor() {
        let items: Vec<i32> = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

        // First page
        let result1 = paginate(&items, None, 3);
        assert_eq!(result1.items, vec![1, 2, 3]);

        // Second page
        let result2 = paginate(&items, result1.next_cursor.as_deref(), 3);
        assert_eq!(result2.items, vec![4, 5, 6]);

        // Third page
        let result3 = paginate(&items, result2.next_cursor.as_deref(), 3);
        assert_eq!(result3.items, vec![7, 8, 9]);

        // Last page
        let result4 = paginate(&items, result3.next_cursor.as_deref(), 3);
        assert_eq!(result4.items, vec![10]);
        assert!(result4.next_cursor.is_none());
    }

    #[test]
    fn test_paginate_invalid_cursor() {
        let items: Vec<i32> = vec![1, 2, 3, 4, 5];
        // Invalid cursor should start from beginning
        let result = paginate(&items, Some("invalid"), 10);
        assert_eq!(result.items, vec![1, 2, 3, 4, 5]);
    }
}