safename 0.1.0

//! Filename validation.

use crate::constants::{DEFAULT_MAX_FILE_LEN, DOT, DOTDOT};
use crate::error::{SafeNameError, SafeNameResult};
use crate::lookup::{BLOCKED_ALWAYS, BLOCKED_FINAL, BLOCKED_INITIAL};

/// Configuration for filename validation.
#[derive(Debug, Clone)]
pub struct FileValidationOptions {
    /// Maximum filename length (default: 255)
    pub max_len: usize,
    /// Allow trailing NUL bytes (default: false)
    ///
    /// When enabled, trailing NUL bytes are trimmed before validation.
    /// The effective filename is everything up to (but not including) the
    /// trailing NUL sequence. Embedded NULs (followed by non-NUL bytes)
    /// are still blocked.
    ///
    /// This is useful for validating fixed-stride null-padded strings
    /// from memory-mapped files or binary formats.
    pub allow_trailing_nul: bool,
}

impl Default for FileValidationOptions {
    fn default() -> Self {
        Self {
            max_len: DEFAULT_MAX_FILE_LEN,
            allow_trailing_nul: false,
        }
    }
}

/// Validates a filename component (what you'd get from `Path::file_name()`).
///
/// This performs a single pass over the bytes, checking position-dependent
/// rules and optionally validating UTF-8.
///
/// Accepts any type that can be referenced as bytes: `&[u8]`, `&str`, `String`,
/// `Vec<u8>`, `Path`, `OsStr`, etc.
///
/// # Errors
///
/// Returns [`SafeNameError`] if the filename violates any validation rule:
/// - [`InvalidLength`](SafeNameError::InvalidLength) if empty or exceeds max length
/// - [`InvalidByte`](SafeNameError::InvalidByte) if contains a blocked byte
///
/// # Example
///
/// ```
/// use safename::{validate_file, SafeNameError};
///
/// assert!(validate_file(b"safe_file.txt").is_ok());
/// assert!(validate_file("safe_file.txt").is_ok());
/// assert_eq!(validate_file(b""), Err(SafeNameError::InvalidLength { len: 0, max: 255 }));
/// assert_eq!(validate_file(b"-rf"), Err(SafeNameError::InvalidByte { index: 0, byte: b'-' }));
/// ```
pub fn validate_file(filename: impl AsRef<[u8]>) -> SafeNameResult<()> {
    validate_file_with_options(filename, &FileValidationOptions::default())
}

/// Validates a filename component with custom options.
///
/// # Errors
///
/// Returns [`SafeNameError`] if the filename violates any validation rule:
/// - [`InvalidLength`](SafeNameError::InvalidLength) if empty or exceeds max length
/// - [`InvalidByte`](SafeNameError::InvalidByte) if contains a blocked byte
pub fn validate_file_with_options(
    filename: impl AsRef<[u8]>,
    options: &FileValidationOptions,
) -> SafeNameResult<()> {
    let original = filename.as_ref();

    // Trim trailing NUL bytes if enabled
    let filename = if options.allow_trailing_nul {
        let end = original.iter().rposition(|&b| b != 0).map_or(0, |i| i + 1);
        &original[..end]
    } else {
        original
    };

    let len = filename.len();

    // Check length bounds (1..=max_len)
    if len == 0 || len > options.max_len {
        return Err(SafeNameError::InvalidLength {
            len,
            max: options.max_len,
        });
    }

    // Special case: "." and ".." are allowed
    if filename == DOT || filename == DOTDOT {
        return Ok(());
    }

    // Single-byte filename: check against both initial and final rules
    if len == 1 {
        let byte = filename[0];
        let byte_index = byte as usize;
        if BLOCKED_ALWAYS[byte_index] || BLOCKED_INITIAL[byte_index] || BLOCKED_FINAL[byte_index] {
            return Err(SafeNameError::InvalidByte { index: 0, byte });
        }

        #[cfg(feature = "require-utf8")]
        if std::str::from_utf8(filename).is_err() {
            return Err(SafeNameError::InvalidByte {
                index: 0,
                byte: filename[0],
            });
        }

        #[cfg(feature = "require-ascii")]
        if byte >= 0x80 {
            return Err(SafeNameError::InvalidByte { index: 0, byte });
        }

        return Ok(());
    }

    // Multi-byte: check each position
    let last_idx = len - 1;
    for (idx, &byte) in filename.iter().enumerate() {
        let byte_index = byte as usize;
        let is_blocked = BLOCKED_ALWAYS[byte_index]
            || (idx == 0 && BLOCKED_INITIAL[byte_index])
            || (idx == last_idx && BLOCKED_FINAL[byte_index]);

        if is_blocked {
            return Err(SafeNameError::InvalidByte { index: idx, byte });
        }

        #[cfg(feature = "require-ascii")]
        if byte >= 0x80 {
            return Err(SafeNameError::InvalidByte { index: idx, byte });
        }
    }

    #[cfg(feature = "require-utf8")]
    {
        if let Err(e) = std::str::from_utf8(filename) {
            return Err(SafeNameError::InvalidByte {
                index: e.valid_up_to(),
                byte: filename[e.valid_up_to()],
            });
        }
    }

    Ok(())
}

/// Checks if a filename is safe according to all enabled validation rules.
///
/// Accepts any type that can be referenced as bytes: `&[u8]`, `&str`, `String`,
/// `Vec<u8>`, etc.
///
/// # Returns
///
/// * `true` if the filename passes all validation checks
/// * `false` if the filename violates any rule
///
/// # Example
///
/// ```
/// use safename::is_file_safe;
///
/// assert!(is_file_safe("normal_file.txt"));
/// assert!(is_file_safe(b"normal_file.txt"));
/// assert!(!is_file_safe("-dangerous"));
/// assert!(!is_file_safe(""));
/// ```
pub fn is_file_safe(filename: impl AsRef<[u8]>) -> bool {
    validate_file(filename).is_ok()
}

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

    #[test]
    fn test_valid_filenames() {
        assert!(is_file_safe("file.txt"));
        assert!(is_file_safe("my_document.pdf"));
        assert!(is_file_safe("image-001.png"));
        assert!(is_file_safe("CamelCase"));
        assert!(is_file_safe("file.with.dots"));
        #[cfg(not(feature = "require-ascii"))]
        assert!(is_file_safe("unicode_αβγ.txt"));
        assert!(is_file_safe(".hidden"));
        assert!(is_file_safe("..dotdot"));
    }

    #[test]
    fn test_special_dotfiles() {
        assert!(is_file_safe("."));
        assert!(is_file_safe(".."));
    }

    #[test]
    fn test_empty_filename() {
        assert_eq!(
            validate_file(b""),
            Err(SafeNameError::InvalidLength { len: 0, max: 255 })
        );
        assert!(!is_file_safe(""));
    }

    #[test]
    fn test_too_long() {
        let long_name = [b'a'; 300];
        assert_eq!(
            validate_file(long_name),
            Err(SafeNameError::InvalidLength { len: 300, max: 255 })
        );

        let max_name = [b'a'; 255];
        assert!(validate_file(max_name).is_ok());
    }

    #[test]
    fn test_control_characters() {
        assert_eq!(
            validate_file(b"file\x00name"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: 0x00
            })
        );
        assert_eq!(
            validate_file(b"file\nname"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: 0x0A
            })
        );
        assert_eq!(
            validate_file(b"file\tname"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: 0x09
            })
        );
        assert_eq!(
            validate_file(b"file\x7Fname"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: 0x7F
            })
        );
    }

    #[test]
    fn test_forward_slash_blocked() {
        // Forward slash is the path separator and cannot appear in filenames
        assert_eq!(
            validate_file(b"foo/bar"),
            Err(SafeNameError::InvalidByte {
                index: 3,
                byte: b'/'
            })
        );
        assert_eq!(
            validate_file(b"/leading"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: b'/'
            })
        );
    }

    #[test]
    fn test_leading_dash() {
        assert_eq!(
            validate_file(b"-rf"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: b'-'
            })
        );
        assert_eq!(
            validate_file(b"--help"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: b'-'
            })
        );
        assert!(is_file_safe("file-name"));
    }

    #[test]
    fn test_leading_tilde() {
        assert_eq!(
            validate_file(b"~user"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: b'~'
            })
        );
        assert!(is_file_safe("file~backup"));
    }

    #[test]
    fn test_leading_space() {
        assert_eq!(
            validate_file(b" file"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: b' '
            })
        );
    }

    #[test]
    fn test_trailing_space() {
        assert_eq!(
            validate_file(b"file "),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: b' '
            })
        );
        #[cfg(not(feature = "block-space"))]
        assert!(is_file_safe("file name"));
        #[cfg(feature = "block-space")]
        assert!(!is_file_safe("file name"));
    }

    #[test]
    fn test_single_char() {
        assert!(validate_file(b" ").is_err());
        assert!(validate_file(b"-").is_err());
        assert!(validate_file(b"a").is_ok());
    }

    #[test]
    fn test_0xff() {
        assert_eq!(
            validate_file(b"file\xFFname"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: 0xFF
            })
        );
    }

    #[test]
    #[cfg(feature = "block-colon")]
    fn test_colon_blocked() {
        assert_eq!(
            validate_file(b"file:name"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: b':'
            })
        );
    }

    #[test]
    #[cfg(not(feature = "block-colon"))]
    fn test_colon_allowed() {
        assert!(is_file_safe("file:name"));
    }

    #[test]
    #[cfg(feature = "block-backslash")]
    fn test_backslash_blocked() {
        assert_eq!(
            validate_file(b"file\\name"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: b'\\'
            })
        );
    }

    #[test]
    #[cfg(not(feature = "block-backslash"))]
    fn test_backslash_allowed() {
        assert!(is_file_safe("file\\name"));
    }

    #[test]
    #[cfg(feature = "require-utf8")]
    fn test_invalid_utf8() {
        assert_eq!(
            validate_file(b"file\x80name"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: 0x80
            })
        );
        assert!(is_file_safe("valid_utf8_αβγ"));
    }

    #[test]
    #[cfg(feature = "require-ascii")]
    fn test_non_ascii_rejected() {
        // High bytes (>= 0x80) are rejected
        assert_eq!(
            validate_file(b"file\x80name"),
            Err(SafeNameError::InvalidByte {
                index: 4,
                byte: 0x80
            })
        );
        assert_eq!(
            validate_file(b"\xFFstart"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: 0xFF
            })
        );
        // Valid UTF-8 non-ASCII is also rejected
        assert!(!is_file_safe("unicode_αβγ.txt"));
        // Pure ASCII is fine
        assert!(is_file_safe("ascii_only.txt"));
    }

    #[test]
    fn test_asref_accepts_various_types() {
        // &str
        assert!(is_file_safe("file.txt"));
        // &[u8]
        assert!(is_file_safe(b"file.txt"));
        // String
        assert!(is_file_safe(String::from("file.txt")));
        // Vec<u8>
        assert!(is_file_safe(vec![b'f', b'i', b'l', b'e']));
    }

    #[test]
    fn test_trailing_nul_disabled_by_default() {
        // NUL is blocked by default
        assert!(validate_file(b"file\x00").is_err());
    }

    #[test]
    #[cfg(feature = "require-utf8")]
    fn test_single_byte_non_ascii_utf8_error() {
        // A single non-ASCII byte is invalid UTF-8
        assert_eq!(
            validate_file(b"\x80"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: 0x80
            })
        );
        assert_eq!(
            validate_file(b"\xFF"),
            Err(SafeNameError::InvalidByte {
                index: 0,
                byte: 0xFF
            })
        );
    }

    // Property-based tests
    proptest! {
        /// Filenames exceeding max length are rejected
        #[test]
        fn prop_length_limit_enforced(len in 256usize..512) {
            let input = vec![b'a'; len];
            prop_assert!(validate_file(&input).is_err(), "Length {} not rejected", len);
        }

        /// ASCII alphanumeric filenames are always valid
        #[test]
        fn prop_alphanumeric_always_valid(input in "[a-zA-Z0-9]{1,100}") {
            prop_assert!(validate_file(input.as_bytes()).is_ok(), "Rejected: {:?}", input);
        }

        /// Control characters (0x00-0x1F) are always blocked
        #[test]
        fn prop_control_chars_blocked(
            prefix in "[a-z]{1,5}",
            ctrl in 0u8..=0x1F,
            suffix in "[a-z]{1,5}"
        ) {
            let mut input = prefix.into_bytes();
            input.push(ctrl);
            input.extend_from_slice(suffix.as_bytes());
            prop_assert!(validate_file(&input).is_err(), "Control char 0x{:02X} not blocked", ctrl);
        }

        /// Dash/tilde in middle positions are allowed
        #[test]
        fn prop_middle_position_allowed(
            prefix in "[a-z]{1,5}",
            ch in prop_oneof![Just('-'), Just('~')],
            suffix in "[a-z]{1,5}"
        ) {
            let input = format!("{}{}{}", prefix, ch, suffix);
            prop_assert!(validate_file(input.as_bytes()).is_ok(), "Rejected: {:?}", input);
        }

        /// Leading dash/tilde/space are blocked
        #[test]
        fn prop_leading_blocked(
            ch in prop_oneof![Just('-'), Just('~'), Just(' ')],
            suffix in "[a-z]{1,10}"
        ) {
            let input = format!("{}{}", ch, suffix);
            prop_assert!(validate_file(input.as_bytes()).is_err(), "Not blocked: {:?}", input);
        }

        /// Trailing space is blocked
        #[test]
        fn prop_trailing_space_blocked(prefix in "[a-z]{1,10}") {
            let input = format!("{} ", prefix);
            prop_assert!(validate_file(input.as_bytes()).is_err(), "Not blocked: {:?}", input);
        }

        /// Trailing NULs are trimmed when allow_trailing_nul is enabled
        #[test]
        fn prop_trailing_nuls_trimmed(nul_count in 1usize..100) {
            let opts = FileValidationOptions {
                allow_trailing_nul: true,
                ..Default::default()
            };
            let mut filename = b"file".to_vec();
            filename.extend(vec![0u8; nul_count]);
            prop_assert!(
                validate_file_with_options(&filename, &opts).is_ok(),
                "Filename with {} trailing NULs rejected", nul_count
            );
        }

        /// Only-NUL filenames are empty after trimming
        #[test]
        fn prop_only_nuls_empty(nul_count in 1usize..100) {
            let opts = FileValidationOptions {
                allow_trailing_nul: true,
                ..Default::default()
            };
            let filename = vec![0u8; nul_count];
            prop_assert!(
                validate_file_with_options(&filename, &opts).is_err(),
                "Filename with only {} NULs should be empty error", nul_count
            );
        }

        /// Embedded NULs still blocked even with allow_trailing_nul
        #[test]
        fn prop_embedded_nul_blocked(
            prefix in "[a-z]{1,5}",
            suffix in "[a-z]{1,5}",
            trailing_nuls in 0usize..10
        ) {
            let opts = FileValidationOptions {
                allow_trailing_nul: true,
                ..Default::default()
            };
            let mut filename = prefix.into_bytes();
            filename.push(0);
            filename.extend_from_slice(suffix.as_bytes());
            filename.extend(vec![0u8; trailing_nuls]);
            prop_assert!(
                validate_file_with_options(&filename, &opts).is_err(),
                "Embedded NUL not blocked: {:?}", filename
            );
        }
    }
}