1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
//! Pure validation functions for names, references, and hashes.
//!
//! # Architecture
//! This module separates validation logic from data structure construction. By isolating
//! these checks into pure, standalone functions, we adhere to the "fail-fast" principle:
//! inputs are scrutinized before any memory allocation or state mutation occurs.
//!
//! # Design Rationale: Pure Functions vs. Constructors
//! While constructors like [`Hash::from_bytes`](crate::Hash::from_bytes) also perform validation,
//! extracting these checks into standalone functions allows consumers to validate raw,
//! unstructured data (e.g., from network streams or untrusted user input) before deciding
//! how to process it. This avoids partial commits of invalid data and makes the validation
//! logic trivially testable without constructing the full object.
//!
//! # Safety and Performance
//! These functions are entirely pure with no side effects. They operate on borrowed slices
//! (`&str`, `&[u8]`) and perform zero heap allocations. The compiler aggressively inlines
//! these checks when used within constructors, achieving zero-cost abstraction.
//!
//! # Examples
//! *Note: The following examples assume this crate is named `libvctrl_handler`.*
//!
//! ```
//! # use libvctrl_handler::validation::validate_name;
//! # use libvctrl_handler::VctrlError;
//! let valid_name = "feature_branch";
//! assert!(validate_name(valid_name).is_ok());
//!
//! let invalid_name = "";
//! assert!(matches!(validate_name(invalid_name), Err(VctrlError::InvalidName(_))));
//! ```
/// Hash validation utilities.
///
/// # Why this exists
/// Provides standalone validation for byte slices intended to be used as Git object hashes.
/// This ensures that data read from untrusted sources (like network packfiles) is the correct
/// length and format before attempting to construct a [`Hash`](crate::Hash) type, preventing
/// unbound allocations or cryptographic mismatches.
/// Name and reference validation utilities.
///
/// # Why this exists
/// Git has strict rules for naming references (branches, tags) and tree entries.
/// For example, names cannot contain control characters, cannot be empty, and cannot
/// contain certain path components like `..`. This module enforces these rules to prevent
/// filesystem traversal vulnerabilities and repository corruption.
/// Re-export of [`validate_hash_bytes`](hash::validate_hash_bytes) for ergonomic top-level access.
///
/// Validates that a byte slice is the correct length to be a hash.
///
/// # Examples
///
/// ```
/// # use libvctrl_handler::validation::validate_hash_bytes;
/// let valid_hash = [0_u8; 64];
/// assert!(validate_hash_bytes(&valid_hash).is_ok());
/// ```
pub use validate_hash_bytes;
/// Re-exports of name and reference validation utilities.
///
/// Provides ergonomic access to functions that enforce Git naming rules.
///
/// # Examples
///
/// ```
/// # use libvctrl_handler::validation::{validate_name, validate_ref_name, validate_tree_entry_name};
/// assert!(validate_name("valid_name").is_ok());
/// assert!(validate_ref_name("refs/heads/main").is_ok());
/// assert!(validate_tree_entry_name("file.txt").is_ok());
/// ```
pub use ;