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}