ailloli_ui_fs/
metadata.rs

1//! Provider-neutral file kinds and metadata snapshots.
2
3use std::time::SystemTime;
4
5/// Primary filesystem entry kind, before following a symlink.
6///
7/// # Examples
8///
9/// ```
10/// use ailloli_ui_fs::FileKind;
11/// assert_ne!(FileKind::Symlink, FileKind::Directory);
12/// ```
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
14pub enum FileKind {
15    /// Regular file or provider-equivalent byte object.
16    File,
17    /// Directory/container that can be listed.
18    Directory,
19    /// Symbolic link; target kind is separately reported by [`FileMetadata`].
20    Symlink,
21    /// Provider entry not represented by the other portable kinds.
22    Other,
23}
24
25/// Metadata snapshot returned by a provider.
26///
27/// Time fields may be absent when unknown or unsupported. No relationship is
28/// enforced between `kind`, `symlink_target_kind`, length, or timestamps, and
29/// derived deserialization preserves provider values verbatim.
30///
31/// # Examples
32///
33/// ```
34/// use ailloli_ui_fs::{FileKind, FileMetadata};
35/// let metadata = FileMetadata::new(FileKind::File);
36/// assert_eq!(metadata.len, 0);
37/// assert_eq!(metadata.modified, None);
38/// ```
39#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
40pub struct FileMetadata {
41    /// Kind of the entry itself; a symlink remains [`FileKind::Symlink`].
42    pub kind: FileKind,
43    /// Target kind for a resolved symlink, or `None` when absent, broken, or unknown.
44    #[serde(default)]
45    pub symlink_target_kind: Option<FileKind>,
46    /// Provider-reported byte length; directory semantics are provider-defined.
47    pub len: u64,
48    /// `true` when the provider reports the entry as read-only.
49    pub readonly: bool,
50    /// Last modification time, or `None` when unavailable.
51    pub modified: Option<SystemTime>,
52    /// Creation/birth time, or `None` when unavailable.
53    pub created: Option<SystemTime>,
54}
55
56impl FileMetadata {
57    /// Creates a zero-length, writable snapshot with no target kind or times.
58    ///
59    /// # Examples
60    ///
61    /// ```
62    /// use ailloli_ui_fs::{FileKind, FileMetadata};
63    /// let metadata = FileMetadata::new(FileKind::Directory);
64    /// assert!(!metadata.readonly);
65    /// assert_eq!(metadata.symlink_target_kind, None);
66    /// ```
67    pub fn new(kind: FileKind) -> Self {
68        Self {
69            kind,
70            symlink_target_kind: None,
71            len: 0,
72            readonly: false,
73            modified: None,
74            created: None,
75        }
76    }
77
78    /// Returns whether the entry itself is a symlink, regardless of target kind.
79    ///
80    /// # Examples
81    ///
82    /// ```
83    /// use ailloli_ui_fs::{FileKind, FileMetadata};
84    /// assert!(FileMetadata::new(FileKind::Symlink).is_symlink());
85    /// ```
86    pub fn is_symlink(&self) -> bool {
87        self.kind == FileKind::Symlink
88    }
89
90    /// Returns whether the entry is a directory or a symlink to a directory.
91    ///
92    /// A broken/unknown symlink (`symlink_target_kind == None`) returns `false`.
93    ///
94    /// # Examples
95    ///
96    /// ```
97    /// use ailloli_ui_fs::{FileKind, FileMetadata};
98    /// let mut link = FileMetadata::new(FileKind::Symlink);
99    /// link.symlink_target_kind = Some(FileKind::Directory);
100    /// assert!(link.is_directory_like());
101    /// ```
102    pub fn is_directory_like(&self) -> bool {
103        self.kind == FileKind::Directory
104            || matches!(self.symlink_target_kind, Some(FileKind::Directory))
105    }
106
107    /// Returns whether the entry is a file or a symlink to a file.
108    ///
109    /// [`FileKind::Other`] and symlinks with unknown targets return `false`.
110    ///
111    /// # Examples
112    ///
113    /// ```
114    /// use ailloli_ui_fs::{FileKind, FileMetadata};
115    /// assert!(FileMetadata::new(FileKind::File).is_file_like());
116    /// assert!(!FileMetadata::new(FileKind::Other).is_file_like());
117    /// ```
118    pub fn is_file_like(&self) -> bool {
119        self.kind == FileKind::File || matches!(self.symlink_target_kind, Some(FileKind::File))
120    }
121}
122
123#[cfg(test)]
124mod tests {
125    //! Covers symlink identity/target separation and backward-compatible serde defaults.
126
127    use super::*;
128
129    #[test]
130    fn metadata_helpers_keep_symlink_identity_and_target_kind_separate() {
131        let mut metadata = FileMetadata::new(FileKind::Symlink);
132        metadata.symlink_target_kind = Some(FileKind::Directory);
133
134        assert!(metadata.is_symlink());
135        assert!(metadata.is_directory_like());
136        assert!(!metadata.is_file_like());
137        assert_eq!(metadata.kind, FileKind::Symlink);
138    }
139
140    #[test]
141    fn broken_symlink_is_not_directory_like_or_file_like() {
142        let metadata = FileMetadata::new(FileKind::Symlink);
143
144        assert!(metadata.is_symlink());
145        assert!(!metadata.is_directory_like());
146        assert!(!metadata.is_file_like());
147    }
148
149    #[test]
150    fn missing_symlink_target_kind_deserializes_as_none() {
151        let json = r#"{
152            "kind": "Symlink",
153            "len": 0,
154            "readonly": false,
155            "modified": null,
156            "created": null
157        }"#;
158
159        let metadata: FileMetadata = serde_json::from_str(json).expect("metadata");
160
161        assert_eq!(metadata.kind, FileKind::Symlink);
162        assert_eq!(metadata.symlink_target_kind, None);
163    }
164}