dovenest

dovenest/server/src/fs.rs
fs.rs
⎇
Raw
1//! Safe filesystem access: every operation resolves
2//! `<server-root>/<user-root>/<requested-path>`, canonicalizes it and verifies
3//! the result is still inside the user's root (blocks `..` and symlink escapes).
4
5use std::io::Read;
6use std::path::{Component, Path, PathBuf};
7use std::time::UNIX_EPOCH;
8
9use chrono::DateTime;
10
11use api_types::{Entry, FileKind};
12
13use crate::error::ApiError;
14
15#[derive(Debug, thiserror::Error)]
16pub enum FsError {
17 #[error("folder not found")]
18 NotFound,
19 #[error("not a folder")]
20 NotADirectory,
21 #[error("access denied")]
22 Forbidden,
23 #[error("the configured folder no longer exists")]
24 RootMissing,
25 #[error("already exists")]
26 Conflict,
27 #[error("{0}")]
28 Invalid(String),
29}
30
31impl From<FsError> for ApiError {
32 fn from(e: FsError) -> Self {
33 use axum::http::StatusCode as S;
34 match &e {
35 FsError::NotFound => {
36 ApiError::localized(S::NOT_FOUND, e.to_string(), "err_fs_not_found")
37 }
38 FsError::NotADirectory => {
39 ApiError::localized(S::BAD_REQUEST, e.to_string(), "err_fs_not_a_dir")
40 }
41 FsError::Forbidden => {
42 ApiError::localized(S::FORBIDDEN, e.to_string(), "err_fs_forbidden")
43 }
44 FsError::RootMissing => {
45 ApiError::localized(S::NOT_FOUND, e.to_string(), "err_fs_root_missing")
46 }
47 FsError::Conflict => ApiError::localized(S::CONFLICT, e.to_string(), "err_fs_conflict"),
48 // Dynamic message (e.g. an invalid name), not a fixed string.
49 FsError::Invalid(_) => ApiError::new(S::BAD_REQUEST, e.to_string()),
50 }
51 }
52}
53
54/// Resolve a user root (path relative to the server root) to a canonical
55/// absolute path, verified to be inside the server root.
56pub fn resolve_root(server_root: &Path, root_rel: &str) -> Result<PathBuf, FsError> {
57 let candidate = server_root.join(root_rel);
58 let canonical = candidate.canonicalize().map_err(|_| FsError::RootMissing)?;
59 ensure_within(server_root, &canonical)?;
60 if !canonical.is_dir() {
61 return Err(FsError::RootMissing);
62 }
63 Ok(canonical)
64}
65
66/// Resolve a requested path (relative to a user root) safely.
67pub fn resolve_path(server_root: &Path, root_rel: &str, req_rel: &str) -> Result<PathBuf, FsError> {
68 let root_abs = resolve_root(server_root, root_rel)?;
69 let req = Path::new(req_rel);
70 for c in req.components() {
71 if matches!(c, Component::ParentDir) {
72 return Err(FsError::Forbidden);
73 }
74 }
75 let full = root_abs.join(req);
76 let full = full.canonicalize().map_err(|e| match e.kind() {
77 std::io::ErrorKind::NotFound => FsError::NotFound,
78 _ => FsError::Forbidden,
79 })?;
80 ensure_within(&root_abs, &full)?;
81 Ok(full)
82}
83
84/// Resolve a share target that is a single file (relative to the server root).
85/// Unlike [`resolve_path`], the target itself is the file — there is no
86/// directory root beneath it.
87pub fn resolve_file(server_root: &Path, rel: &str) -> Result<PathBuf, FsError> {
88 let full = server_root.join(rel);
89 let full = full.canonicalize().map_err(|e| match e.kind() {
90 std::io::ErrorKind::NotFound => FsError::NotFound,
91 _ => FsError::Forbidden,
92 })?;
93 ensure_within(server_root, &full)?;
94 Ok(full)
95}
96
97fn ensure_within(base: &Path, p: &Path) -> Result<(), FsError> {
98 if p == base || p.starts_with(base) {
99 Ok(())
100 } else {
101 Err(FsError::Forbidden)
102 }
103}
104
105/// List a directory (blocking — call via spawn_blocking). The `bool` is true
106/// when the listing was cut to [`api_types::MAX_LIST_ENTRIES`].
107pub fn list_dir(dir: &Path) -> Result<(Vec<Entry>, bool), FsError> {
108 let rd = std::fs::read_dir(dir).map_err(|e| match e.kind() {
109 std::io::ErrorKind::NotFound => FsError::NotFound,
110 std::io::ErrorKind::NotADirectory => FsError::NotADirectory,
111 _ => FsError::Forbidden,
112 })?;
113
114 // Pass 1: names only. Walking the directory stream is inherently
115 // sequential, but it is also the only part that has to be: every field
116 // below comes from a per-entry syscall, which pass 2 can do in parallel.
117 // The values here are the fallbacks used when that syscall fails.
118 let mut rows: Vec<(Entry, PathBuf)> = Vec::new();
119 for e in rd.flatten() {
120 let entry = Entry {
121 name: e.file_name().to_string_lossy().into_owned(),
122 is_dir: false,
123 size: 0,
124 mtime: EPOCH_MTIME.to_string(),
125 kind: FileKind::Binary,
126 };
127 rows.push((entry, e.path()));
128 }
129
130 // Pass 2: metadata, which the sort needs (folders first).
131 describe_rows(&mut rows, fill_meta);
132
133 // Folders first, then case-insensitive name. Sorting after pass 2 means
134 // the parallel fan-out cannot affect the order.
135 rows.sort_by_cached_key(|(e, _)| (!e.is_dir, e.name.to_lowercase(), e.name.clone()));
136
137 // Cut over-long listings here, so the sniff below never sees the tail.
138 // The client cannot render that many rows anyway.
139 let truncated = rows.len() > api_types::MAX_LIST_ENTRIES;
140 rows.truncate(api_types::MAX_LIST_ENTRIES);
141
142 // Pass 3: the content sniff, the expensive per-entry syscall.
143 describe_rows(&mut rows, fill_kind);
144
145 Ok((rows.into_iter().map(|(e, _)| e).collect(), truncated))
146}
147
148// ---------------------------------------------------------------------------
149// Content sniffing
150// ---------------------------------------------------------------------------
151
152/// How many leading bytes we read to classify a file. Every magic number
153/// `infer` knows lives in the first few dozen bytes; 256 also gives the
154/// text/binary heuristic enough to work with. Measured at ~4.6 µs per file,
155/// against ~1.4 µs for the `metadata` call in the same pass.
156const SNIFF_BYTES: usize = 256;
157
158/// Entries per thread, and the point below which parallelism is not worth it.
159/// Measured on a 22-core machine: at 50 entries fan-out is a wash (thread
160/// spawn costs about as much as the work), at 200 it is already 2x.
161const SNIFF_CHUNK: usize = 256;
162
163/// Process-wide ceiling on threads spawned for sniffing, so many concurrent
164/// listings of large directories cannot multiply into a thread explosion.
165/// One listing alone can use the whole budget; the next one degrades to fewer
166/// threads, and eventually to serial, instead of queueing.
167static SNIFF_BUDGET: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
168
169fn sniff_budget_total() -> usize {
170 static TOTAL: std::sync::LazyLock<usize> = std::sync::LazyLock::new(|| {
171 std::thread::available_parallelism()
172 .map(|n| n.get())
173 .unwrap_or(1)
174 });
175 *TOTAL
176}
177
178/// Claimed helper threads, returned to [`SNIFF_BUDGET`] on drop.
179struct SniffPermit(usize);
180
181impl SniffPermit {
182 /// Claim up to `want` helper threads, or fewer when the budget is thin.
183 fn claim(want: usize) -> Self {
184 use std::sync::atomic::Ordering;
185 let total = sniff_budget_total();
186 let mut granted = 0;
187 let _ = SNIFF_BUDGET.fetch_update(Ordering::AcqRel, Ordering::Acquire, |in_flight| {
188 granted = want.min(total.saturating_sub(in_flight));
189 (granted > 0).then_some(in_flight + granted)
190 });
191 Self(granted)
192 }
193}
194
195impl Drop for SniffPermit {
196 fn drop(&mut self) {
197 if self.0 > 0 {
198 SNIFF_BUDGET.fetch_sub(self.0, std::sync::atomic::Ordering::AcqRel);
199 }
200 }
201}
202
203/// Metadata for one row. Follows symlinks; a broken link keeps the caller's
204/// fallbacks and so shows up as an empty file.
205fn fill_meta(entry: &mut Entry, path: &Path) {
206 if let Ok(m) = std::fs::metadata(path) {
207 entry.is_dir = m.is_dir();
208 entry.size = m.len();
209 entry.mtime = mtime_str(&m);
210 }
211}
212
213/// The content sniff for one row. Needs `is_dir`, so it runs after
214/// [`fill_meta`].
215fn fill_kind(entry: &mut Entry, path: &Path) {
216 entry.kind = detect_kind(path, entry.is_dir);
217}
218
219/// Apply `one` to each row, fanning the work out across threads for big
220/// directories.
221///
222/// The calling thread takes a chunk too, so `n` helper threads process `n + 1`
223/// chunks and a zero-thread grant is simply the serial path.
224fn describe_rows(rows: &mut [(Entry, PathBuf)], one: fn(&mut Entry, &Path)) {
225 fn describe(rows: &mut [(Entry, PathBuf)], one: fn(&mut Entry, &Path)) {
226 for (entry, path) in rows {
227 one(entry, path);
228 }
229 }
230
231 if rows.len() < SNIFF_CHUNK {
232 describe(rows, one);
233 return;
234 }
235 // One chunk per helper thread plus one for this thread.
236 let want = rows.len().div_ceil(SNIFF_CHUNK).saturating_sub(1);
237 let permit = SniffPermit::claim(want);
238 if permit.0 == 0 {
239 describe(rows, one);
240 return;
241 }
242 let chunk = rows.len().div_ceil(permit.0 + 1);
243 std::thread::scope(|s| {
244 let mut rest = rows;
245 // Hand every chunk but the last to a helper thread.
246 while rest.len() > chunk {
247 let (head, tail) = rest.split_at_mut(chunk);
248 s.spawn(move || describe(head, one));
249 rest = tail;
250 }
251 describe(rest, one);
252 });
253}
254
255/// Classify a directory entry by reading its first [`SNIFF_BYTES`] bytes.
256///
257/// Blocking — called from `list_dir` (itself under `spawn_blocking`), on
258/// several threads at once for large directories. An unreadable file is
259/// reported as [`FileKind::Binary`] rather than failing the whole listing.
260///
261// ponytail: one open() per entry, fanned out but not cached. Measured warm on
262// 22 cores: 5000 entries take 29 ms serially and 6.9 ms across threads. The
263// remaining ceiling is a cold cache or a network filesystem (NFS/SMB), where
264// each entry costs a round trip. If that shows up: cache by (dev, ino, mtime),
265// or skip the sniff for zero-byte files.
266pub fn detect_kind(path: &Path, is_dir: bool) -> FileKind {
267 if is_dir {
268 return FileKind::Dir;
269 }
270 let mut head = [0u8; SNIFF_BYTES];
271 // A read error is *not* the same as an empty file: an empty file is text
272 // (it opens in the editor), an unreadable one gets no viewer offered.
273 match std::fs::File::open(path).and_then(|mut f| f.read(&mut head)) {
274 Ok(n) => kind_from_bytes(&head[..n], path),
275 Err(_) => FileKind::Binary,
276 }
277}
278
279/// The pure half of [`detect_kind`], so it can be unit-tested without a disk.
280///
281/// `path` is consulted only for the SVG case: SVG is XML text with no magic
282/// number, but browsers render it as an image, so the extension is the only
283/// thing that can tell us to offer an image preview.
284fn kind_from_bytes(head: &[u8], path: &Path) -> FileKind {
285 if let Some(t) = infer::get(head) {
286 // PDF is filed under `Archive` by `infer`, so match the MIME first.
287 if t.mime_type() == "application/pdf" {
288 return FileKind::Pdf;
289 }
290 return match t.matcher_type() {
291 infer::MatcherType::Image => FileKind::Image,
292 infer::MatcherType::Video => FileKind::Video,
293 infer::MatcherType::Audio => FileKind::Audio,
294 infer::MatcherType::Archive => FileKind::Archive,
295 infer::MatcherType::Text => FileKind::Text,
296 // App / Book / Font / Doc / Custom: recognized, but nothing we
297 // can show in the browser.
298 _ => FileKind::Binary,
299 };
300 }
301 if !looks_like_text(head) {
302 return FileKind::Binary;
303 }
304 let ext = path
305 .extension()
306 .map(|e| e.to_string_lossy().to_lowercase())
307 .unwrap_or_default();
308 if ext == "svg" {
309 FileKind::Image
310 } else {
311 FileKind::Text
312 }
313}
314
315/// Text heuristic for the files `infer` has no signature for (plain text,
316/// source code, most config formats): no NUL byte, and the head decodes as
317/// UTF-8 once a truncated trailing character is discounted.
318///
319/// An empty file counts as text — it opens in the editor, which is what you
320/// want for a file you just created.
321fn looks_like_text(head: &[u8]) -> bool {
322 if head.contains(&0) {
323 return false;
324 }
325 match std::str::from_utf8(head) {
326 Ok(_) => true,
327 // A multi-byte character cut in half by the read boundary is fine;
328 // anything else is not text. `error_len() == None` means "unexpected
329 // end of input", i.e. truncation.
330 Err(e) => e.error_len().is_none() && e.valid_up_to() + 4 > head.len(),
331 }
332}
333
334/// Reported when a file's modification time is unavailable or unrepresentable.
335const EPOCH_MTIME: &str = "1970-01-01T00:00:00Z";
336
337/// A file's modification time in whole unix seconds, or `None` when the
338/// platform cannot report one. The single place that converts a `SystemTime`.
339pub fn mtime_secs(m: &std::fs::Metadata) -> Option<i64> {
340 m.modified()
341 .ok()
342 .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
343 .map(|d| d.as_secs() as i64)
344}
345
346fn mtime_str(m: &std::fs::Metadata) -> String {
347 let dt: Option<DateTime<chrono::Utc>> =
348 mtime_secs(m).and_then(|s| DateTime::from_timestamp(s, 0));
349 dt.map(|d| d.to_rfc3339_opts(chrono::SecondsFormat::Secs, true))
350 .unwrap_or_else(|| EPOCH_MTIME.to_string())
351}
352
353// ---------------------------------------------------------------------------
354// Mutations (milestone 3): mkdir, rename, remove, move, copy, upload
355// ---------------------------------------------------------------------------
356
357/// Resolve a directory that must exist (relative to a user root). Used as the
358/// base for operations that target the *parent* of the item.
359pub fn resolve_dir(server_root: &Path, root_rel: &str, req_rel: &str) -> Result<PathBuf, FsError> {
360 let full = resolve_path(server_root, root_rel, req_rel)?;
361 if !full.is_dir() {
362 return Err(FsError::NotADirectory);
363 }
364 Ok(full)
365}
366
367/// Validate a new single-component name (for rename / new folder).
368fn validate_component(name: &str) -> Result<(), FsError> {
369 let p = Path::new(name);
370 if name.is_empty()
371 || p.components().count() != 1
372 || name == "."
373 || name == ".."
374 || name.contains(['/', '\\', '\0'])
375 {
376 return Err(FsError::Invalid("invalid name".to_string()));
377 }
378 Ok(())
379}
380
381/// Create a directory (and any missing parents) inside a user root.
382pub fn mkdir(server_root: &Path, root_rel: &str, req_rel: &str) -> Result<(), FsError> {
383 let full = resolve_path_or_new(server_root, root_rel, req_rel)?;
384 if full.exists() {
385 return Err(FsError::Conflict);
386 }
387 std::fs::create_dir_all(&full).map_err(|e| io_err(e, &full))?;
388 Ok(())
389}
390
391/// Create an empty file. The parent must exist; the file must not.
392pub fn create_file(server_root: &Path, root_rel: &str, req_rel: &str) -> Result<(), FsError> {
393 let full = resolve_path_or_new(server_root, root_rel, req_rel)?;
394 // create_new = O_EXCL: fails on an existing path, does not follow a symlink.
395 std::fs::File::create_new(&full).map_err(|e| match e.kind() {
396 std::io::ErrorKind::AlreadyExists => FsError::Conflict,
397 _ => io_err(e, &full),
398 })?;
399 Ok(())
400}
401
402/// Resolve a path that does not need to exist yet, but whose *parent* must.
403fn resolve_path_or_new(
404 server_root: &Path,
405 root_rel: &str,
406 req_rel: &str,
407) -> Result<PathBuf, FsError> {
408 let root_abs = resolve_root(server_root, root_rel)?;
409 let req = Path::new(req_rel);
410 for c in req.components() {
411 if matches!(c, Component::ParentDir) {
412 return Err(FsError::Forbidden);
413 }
414 }
415 let full = root_abs.join(req);
416 // The parent must exist and stay inside the root.
417 let parent = full
418 .parent()
419 .filter(|p| !p.as_os_str().is_empty())
420 .ok_or_else(|| FsError::Invalid("invalid path".to_string()))?;
421 let parent = parent.canonicalize().map_err(|e| io_err(e, parent))?;
422 ensure_within(&root_abs, &parent)?;
423 Ok(full)
424}
425
426/// Rename (or move within the same directory) an item.
427/// Returns the path the item was renamed *away from*, so the caller can
428/// revoke anything (a share) that still names it.
429pub fn rename_item(
430 server_root: &Path,
431 root_rel: &str,
432 req_rel: &str,
433 new_name: &str,
434 overwrite: bool,
435) -> Result<PathBuf, FsError> {
436 validate_component(new_name)?;
437 let from = resolve_path(server_root, root_rel, req_rel)?;
438 let parent = from
439 .parent()
440 .ok_or_else(|| FsError::Invalid("invalid path".to_string()))?;
441 let to = parent.join(new_name);
442 // Renaming onto itself is a no-op (the overwrite path below would
443 // delete the file before the rename). Nothing was vacated.
444 if to == from {
445 return Ok(to);
446 }
447 // `rename` replaces a file target atomically; no remove-then-rename gap.
448 if to.exists() && (!overwrite || to.is_dir() || from.is_dir()) {
449 return Err(FsError::Conflict);
450 }
451 std::fs::rename(&from, &to).map_err(|e| io_err(e, &to))?;
452 Ok(from)
453}
454
455/// Delete a file or a directory tree. Returns whether it was a directory, and
456/// the path that is now gone (so the caller can revoke shares naming it).
457pub fn remove_item(
458 server_root: &Path,
459 root_rel: &str,
460 req_rel: &str,
461) -> Result<(bool, PathBuf), FsError> {
462 let full = resolve_path(server_root, root_rel, req_rel)?;
463 let is_dir = full.is_dir();
464 if is_dir {
465 std::fs::remove_dir_all(&full).map_err(|e| io_err(e, &full))?;
466 } else {
467 std::fs::remove_file(&full).map_err(|e| io_err(e, &full))?;
468 }
469 Ok((is_dir, full))
470}
471
472/// Overwrite an existing file's contents (the editor's save path).
473///
474/// The file must already exist and be a regular file. If `expected_mtime`
475/// (whole unix seconds) is provided and differs from the file's current mtime,
476/// the file changed on disk since it was read → `Conflict` (409). Returns the
477/// file's new mtime (unix seconds) after a successful write.
478pub fn save_file(
479 server_root: &Path,
480 root_rel: &str,
481 req_rel: &str,
482 content: &[u8],
483 expected_mtime: Option<i64>,
484) -> Result<i64, FsError> {
485 let full = resolve_path(server_root, root_rel, req_rel)?; // must exist
486 write_checked(&full, content, expected_mtime)
487}
488
489/// The share-aware variant of [`save_file`]: for a *file* share the root is
490/// the file itself, so `target` (relative to `server_root`) points at the
491/// file — there is no directory root beneath it.
492pub fn save_file_at(
493 server_root: &Path,
494 target: &str,
495 content: &[u8],
496 expected_mtime: Option<i64>,
497) -> Result<i64, FsError> {
498 let full = resolve_file(server_root, target)?; // must exist
499 write_checked(&full, content, expected_mtime)
500}
501
502fn write_checked(full: &Path, content: &[u8], expected_mtime: Option<i64>) -> Result<i64, FsError> {
503 let meta = std::fs::metadata(full).map_err(|_| FsError::NotFound)?;
504 if meta.is_dir() {
505 return Err(FsError::NotADirectory);
506 }
507 if let Some(expected) = expected_mtime {
508 // No readable mtime means the check cannot pass: -1 never matches.
509 if mtime_secs(&meta).unwrap_or(-1) != expected {
510 return Err(FsError::Conflict);
511 }
512 }
513 std::fs::write(full, content).map_err(|e| io_err(e, full))?;
514 // Read the new mtime so the client can anchor the next conflict check.
515 let new_meta = std::fs::metadata(full).map_err(|_| FsError::NotFound)?;
516 Ok(mtime_secs(&new_meta).unwrap_or(0))
517}
518
519fn io_err(e: std::io::Error, p: &Path) -> FsError {
520 tracing::warn!(error = %e, path = %p.display(), "filesystem error");
521 match e.kind() {
522 std::io::ErrorKind::NotFound => FsError::NotFound,
523 _ => FsError::Forbidden,
524 }
525}
526
527/// True if `a` is `b` or a descendant of `b` (both canonical).
528pub(crate) fn is_within_or_eq(base: &Path, p: &Path) -> bool {
529 p == base || p.starts_with(base)
530}
531
532/// Move an item (possibly across roots). `dst_dir_rel` is the destination
533/// directory (relative to `dst_root_rel`); the item keeps its base name.
534///
535/// Returns the path the item was moved *away from*, like [`rename_item`].
536pub fn move_item(
537 server_root: &Path,
538 src_root_rel: &str,
539 src_rel: &str,
540 dst_root_rel: &str,
541 dst_dir_rel: &str,
542 overwrite: bool,
543) -> Result<PathBuf, FsError> {
544 let from = resolve_path(server_root, src_root_rel, src_rel)?;
545 let dst_dir = resolve_dir(server_root, dst_root_rel, dst_dir_rel)?;
546 let name = from
547 .file_name()
548 .ok_or_else(|| FsError::Invalid("invalid path".to_string()))?
549 .to_owned();
550 let to = dst_dir.join(&name);
551
552 // A no-op (item already at the destination) — treat as success. Nothing
553 // was vacated.
554 if to == from {
555 return Ok(to);
556 }
557
558 // Refuse moving a directory into itself or a descendant.
559 if from.is_dir() && is_within_or_eq(&from, &dst_dir) {
560 return Err(FsError::Invalid(
561 "cannot move a folder into itself".to_string(),
562 ));
563 }
564 check_move_conflict(&to, &from, overwrite)?;
565
566 match std::fs::rename(&from, &to) {
567 Ok(()) => Ok(from),
568 Err(e) if e.kind() == std::io::ErrorKind::CrossesDevices => {
569 copy_recursive(&from, &to)?;
570 if from.is_dir() {
571 std::fs::remove_dir_all(&from).map_err(|_| FsError::Forbidden)?;
572 } else {
573 std::fs::remove_file(&from).map_err(|_| FsError::Forbidden)?;
574 }
575 Ok(from)
576 }
577 Err(e) => Err(io_err(e, &to)),
578 }
579}
580
581/// Copy an item (possibly across roots).
582pub fn copy_item(
583 server_root: &Path,
584 src_root_rel: &str,
585 src_rel: &str,
586 dst_root_rel: &str,
587 dst_dir_rel: &str,
588 overwrite: bool,
589) -> Result<(), FsError> {
590 let from = resolve_path(server_root, src_root_rel, src_rel)?;
591 let dst_dir = resolve_dir(server_root, dst_root_rel, dst_dir_rel)?;
592 let name = from
593 .file_name()
594 .ok_or_else(|| FsError::Invalid("invalid path".to_string()))?
595 .to_owned();
596 let to = dst_dir.join(&name);
597
598 // A no-op (item already at the destination) — treat as success.
599 if to == from {
600 return Ok(());
601 }
602
603 if from.is_dir() && is_within_or_eq(&from, &dst_dir) {
604 return Err(FsError::Invalid(
605 "cannot copy a folder into itself".to_string(),
606 ));
607 }
608 check_move_conflict(&to, &from, overwrite)?;
609 copy_recursive(&from, &to)?;
610 Ok(())
611}
612
613/// Conflict rules shared by move and copy:
614/// - target is a directory → always conflict (no silent merge)
615/// - target is a file → conflict unless overwriting a file with a file
616fn check_move_conflict(to: &Path, from: &Path, overwrite: bool) -> Result<(), FsError> {
617 if to.exists() {
618 let to_dir = to.is_dir();
619 let from_dir = from.is_dir();
620 if to_dir || from_dir || !overwrite {
621 return Err(FsError::Conflict);
622 }
623 }
624 Ok(())
625}
626
627/// Recursively copy a file or directory tree, preserving mtime.
628fn copy_recursive(src: &Path, dst: &Path) -> Result<(), FsError> {
629 let meta = std::fs::metadata(src).map_err(|e| io_err(e, src))?;
630 if meta.is_dir() {
631 std::fs::create_dir(dst).map_err(|e| io_err(e, dst))?;
632 for e in std::fs::read_dir(src)
633 .map_err(|e| io_err(e, src))?
634 .flatten()
635 {
636 copy_recursive(&e.path(), &dst.join(e.file_name()))?;
637 }
638 } else {
639 std::fs::copy(src, dst).map_err(|e| io_err(e, dst))?;
640 }
641 set_mtime(dst, meta.modified().ok());
642 Ok(())
643}
644
645fn set_mtime(p: &Path, t: Option<std::time::SystemTime>) {
646 if let (Some(t), Ok(f)) = (t, std::fs::File::open(p)) {
647 let _ = f.set_modified(t);
648 }
649}
650
651// ---------------------------------------------------------------------------
652// Tests
653// ---------------------------------------------------------------------------
654
655#[cfg(test)]
656mod tests {
657 use super::*;
658
659 /// A temp dir used as the "server root" with a small fixture tree:
660 ///
661 /// ```text
662 /// root/
663 /// docs/
664 /// inner/
665 /// hello.txt
666 /// a.txt
667 /// src/
668 /// main.rs
669 /// file.txt
670 /// ```
671 struct T {
672 tmp: tempfile::TempDir,
673 root: PathBuf,
674 }
675
676 impl T {
677 fn new() -> Self {
678 let tmp = tempfile::tempdir().unwrap();
679 let root = tmp.path().to_path_buf();
680 std::fs::create_dir_all(root.join("docs/inner")).unwrap();
681 std::fs::create_dir_all(root.join("src")).unwrap();
682 std::fs::write(root.join("docs/inner/hello.txt"), "hello").unwrap();
683 std::fs::write(root.join("docs/a.txt"), "a").unwrap();
684 std::fs::write(root.join("src/main.rs"), "fn main() {}").unwrap();
685 std::fs::write(root.join("file.txt"), "top file").unwrap();
686 Self { tmp, root }
687 }
688
689 /// A directory that lives *next to* the root (outside of it), for
690 /// symlink/escape tests. The tempdir name is unique, so the sibling
691 /// name is unique too.
692 fn sibling(&self, name: &str) -> PathBuf {
693 let base = self
694 .tmp
695 .path()
696 .file_name()
697 .unwrap()
698 .to_string_lossy()
699 .into_owned();
700 let p = self.tmp.path().with_file_name(format!("{base}-{name}"));
701 std::fs::create_dir_all(&p).unwrap();
702 p
703 }
704 }
705
706 // ---------- validate_component ----------
707
708 #[test]
709 fn validate_name_accepts_simple_names() {
710 for ok in ["a", "file.txt", "my folder", "Ünïcödé", "with-dash_1.2.3"] {
711 assert!(validate_component(ok).is_ok(), "{ok:?} should be valid");
712 }
713 }
714
715 #[test]
716 fn validate_name_rejects_traversal_and_paths() {
717 for bad in [
718 "", ".", "..", "a/b", "a\\b", "a\0b", "/abs", "../x", "x/../y", "x/", "/x",
719 ] {
720 assert!(
721 validate_component(bad).is_err(),
722 "{bad:?} should be invalid"
723 );
724 }
725 }
726
727 // ---------- resolve_root ----------
728
729 #[test]
730 fn resolve_root_whole_root_and_subdir() {
731 let t = T::new();
732 let root = t.root.canonicalize().unwrap();
733 // "." means the whole root.
734 assert_eq!(resolve_root(&root, ".").unwrap(), root);
735 assert_eq!(resolve_root(&root, "docs").unwrap(), root.join("docs"));
736 assert_eq!(
737 resolve_root(&root, "docs/inner").unwrap(),
738 root.join("docs/inner")
739 );
740 }
741
742 #[test]
743 fn resolve_root_rejects_escape_and_missing() {
744 let t = T::new();
745 let root = t.root.canonicalize().unwrap();
746 let sib = t.sibling("escape");
747 let sib_rel = sib.file_name().unwrap().to_string_lossy().into_owned();
748 // Escapes that land on *existing* paths outside the root.
749 for esc in [
750 "..".to_string(),
751 "docs/../..".to_string(),
752 format!("../{sib_rel}"),
753 ] {
754 assert!(
755 matches!(resolve_root(&root, &esc), Err(FsError::Forbidden)),
756 "{esc:?} should be forbidden"
757 );
758 }
759 // Escapes to non-existing paths simply don't exist.
760 for esc in ["../no-such-dir", "a/b/../../..", "nope"] {
761 assert!(
762 matches!(resolve_root(&root, esc), Err(FsError::RootMissing)),
763 "{esc:?} should be missing"
764 );
765 }
766 // A file is not a valid root.
767 assert!(matches!(
768 resolve_root(&root, "file.txt"),
769 Err(FsError::RootMissing)
770 ));
771 }
772
773 #[cfg(unix)]
774 #[test]
775 fn resolve_root_rejects_symlink_escape() {
776 let t = T::new();
777 let root = t.root.canonicalize().unwrap();
778 let outside = t.sibling("outside");
779 std::os::unix::fs::symlink(&outside, root.join("link")).unwrap();
780 assert!(matches!(
781 resolve_root(&root, "link"),
782 Err(FsError::Forbidden)
783 ));
784 }
785
786 // ---------- resolve_path ----------
787
788 #[test]
789 fn resolve_path_traverses_inside_root() {
790 let t = T::new();
791 let root = t.root.canonicalize().unwrap();
792 // Empty relative path → the root itself.
793 assert_eq!(resolve_path(&root, ".", "").unwrap(), root);
794 assert_eq!(
795 resolve_path(&root, "docs", "inner/hello.txt").unwrap(),
796 root.join("docs/inner/hello.txt")
797 );
798 assert_eq!(
799 resolve_path(&root, ".", "file.txt").unwrap(),
800 root.join("file.txt")
801 );
802 }
803
804 #[test]
805 fn resolve_path_rejects_parent_traversal() {
806 let t = T::new();
807 let root = t.root.canonicalize().unwrap();
808 for p in ["..", "../file.txt", "docs/../../file.txt", "a/../../b"] {
809 assert!(
810 matches!(resolve_path(&root, ".", p), Err(FsError::Forbidden)),
811 "{p:?} should be forbidden"
812 );
813 }
814 }
815
816 #[test]
817 fn resolve_path_missing_is_not_found() {
818 let t = T::new();
819 let root = t.root.canonicalize().unwrap();
820 assert!(matches!(
821 resolve_path(&root, "docs", "nope.txt"),
822 Err(FsError::NotFound)
823 ));
824 assert!(matches!(
825 resolve_path(&root, "missing-root", ""),
826 Err(FsError::RootMissing)
827 ));
828 }
829
830 #[cfg(unix)]
831 #[test]
832 fn resolve_path_rejects_symlink_escape() {
833 let t = T::new();
834 let root = t.root.canonicalize().unwrap();
835 let outside = t.sibling("outside");
836 let secret = outside.join("secret.txt");
837 std::fs::write(&secret, "top secret").unwrap();
838 std::os::unix::fs::symlink(&secret, root.join("evil")).unwrap();
839 assert!(matches!(
840 resolve_path(&root, ".", "evil"),
841 Err(FsError::Forbidden)
842 ));
843 // A symlink that stays inside the root is fine.
844 std::os::unix::fs::symlink(root.join("file.txt"), root.join("alias")).unwrap();
845 assert_eq!(
846 resolve_path(&root, ".", "alias").unwrap(),
847 root.join("file.txt")
848 );
849 }
850
851 // ---------- resolve_file / resolve_dir ----------
852
853 #[test]
854 fn resolve_file_targets_files() {
855 let t = T::new();
856 let root = t.root.canonicalize().unwrap();
857 assert_eq!(
858 resolve_file(&root, "file.txt").unwrap(),
859 root.join("file.txt")
860 );
861 assert!(matches!(
862 resolve_file(&root, "nope.txt"),
863 Err(FsError::NotFound)
864 ));
865 // Escape to an existing sibling file.
866 let sib = t.sibling("escape");
867 let sib_rel = sib.file_name().unwrap().to_string_lossy().into_owned();
868 std::fs::write(sib.join("s.txt"), "x").unwrap();
869 assert!(matches!(
870 resolve_file(&root, &format!("../{sib_rel}/s.txt")),
871 Err(FsError::Forbidden)
872 ));
873 }
874
875 #[test]
876 fn resolve_dir_requires_existing_directory() {
877 let t = T::new();
878 let root = t.root.canonicalize().unwrap();
879 assert_eq!(resolve_dir(&root, ".", "docs").unwrap(), root.join("docs"));
880 assert!(matches!(
881 resolve_dir(&root, ".", "file.txt"),
882 Err(FsError::NotADirectory)
883 ));
884 assert!(matches!(
885 resolve_dir(&root, ".", "nope"),
886 Err(FsError::NotFound)
887 ));
888 }
889
890 // ---------- list_dir ----------
891
892 #[test]
893 fn list_dir_sorts_folders_first_then_case_insensitive() {
894 let t = T::new();
895 let d = t.root.join("sortme");
896 std::fs::create_dir_all(d.join("Zeta")).unwrap();
897 std::fs::create_dir_all(d.join("alpha-dir")).unwrap();
898 std::fs::write(d.join("b.txt"), "x").unwrap();
899 std::fs::write(d.join("A.txt"), "x").unwrap();
900 std::fs::write(d.join("C.md"), "x").unwrap();
901 let (entries, _) = list_dir(&d).unwrap();
902 let names: Vec<&str> = entries.iter().map(|e| e.name.as_str()).collect();
903 // Folders first (alpha-dir, Zeta), then files case-insensitively.
904 assert_eq!(names, vec!["alpha-dir", "Zeta", "A.txt", "b.txt", "C.md"]);
905 let a = &entries[2];
906 assert!(!a.is_dir);
907 assert_eq!(a.size, 1);
908 assert!(!a.mtime.is_empty());
909 }
910
911 #[test]
912 fn list_dir_error_cases() {
913 let t = T::new();
914 let root = t.root.canonicalize().unwrap();
915 assert!(matches!(
916 list_dir(&root.join("missing")),
917 Err(FsError::NotFound)
918 ));
919 assert!(matches!(
920 list_dir(&root.join("file.txt")),
921 Err(FsError::NotADirectory)
922 ));
923 }
924
925 #[cfg(unix)]
926 #[test]
927 fn list_dir_reports_broken_symlink_as_empty_file() {
928 let t = T::new();
929 let d = t.root.join("withlink");
930 std::fs::create_dir_all(&d).unwrap();
931 std::os::unix::fs::symlink(d.join("does-not-exist"), d.join("broken")).unwrap();
932 let (entries, _) = list_dir(&d).unwrap();
933 assert_eq!(entries.len(), 1);
934 assert_eq!(entries[0].name, "broken");
935 assert!(!entries[0].is_dir);
936 assert_eq!(entries[0].size, 0);
937 }
938
939 // ---------- mkdir ----------
940
941 #[test]
942 fn mkdir_creates_nested_dirs() {
943 let t = T::new();
944 let root = t.root.canonicalize().unwrap();
945 // The parent must exist; "new" first, then "new/sub".
946 mkdir(&root, ".", "new").unwrap();
947 assert!(root.join("new").is_dir());
948 mkdir(&root, ".", "new/sub").unwrap();
949 assert!(root.join("new/sub").is_dir());
950 }
951
952 #[test]
953 fn mkdir_rejects_conflict_and_bad_names() {
954 let t = T::new();
955 let root = t.root.canonicalize().unwrap();
956 assert!(matches!(mkdir(&root, ".", "docs"), Err(FsError::Conflict)));
957 assert!(matches!(
958 mkdir(&root, ".", "a/b/../../c"),
959 Err(FsError::Forbidden)
960 ));
961 assert!(matches!(
962 mkdir(&root, ".", "file.txt/x"),
963 Err(FsError::Forbidden) // parent is a file → ENOTDIR
964 ));
965 }
966
967 // ---------- rename ----------
968
969 #[test]
970 fn rename_moves_file_and_dir() {
971 let t = T::new();
972 let root = t.root.canonicalize().unwrap();
973 let vacated = rename_item(&root, ".", "file.txt", "renamed.txt", false).unwrap();
974 assert_eq!(vacated, root.join("file.txt"));
975 assert!(!root.join("file.txt").exists());
976 assert_eq!(
977 std::fs::read_to_string(root.join("renamed.txt")).unwrap(),
978 "top file"
979 );
980 rename_item(&root, ".", "docs", "docs2", false).unwrap();
981 assert!(root.join("docs2/inner/hello.txt").exists());
982 }
983
984 #[test]
985 fn rename_conflicts_and_overwrite() {
986 let t = T::new();
987 let root = t.root.canonicalize().unwrap();
988 std::fs::write(root.join("other.txt"), "other").unwrap();
989 // Target file exists, no overwrite → conflict.
990 assert!(matches!(
991 rename_item(&root, ".", "file.txt", "other.txt", false),
992 Err(FsError::Conflict)
993 ));
994 // Overwrite a file target → replaces it.
995 rename_item(&root, ".", "file.txt", "other.txt", true).unwrap();
996 assert_eq!(
997 std::fs::read_to_string(root.join("other.txt")).unwrap(),
998 "top file"
999 );
1000 // A dir target is never overwritten, even with the flag.
1001 assert!(matches!(
1002 rename_item(&root, ".", "other.txt", "docs", true),
1003 Err(FsError::Conflict)
1004 ));
1005 // Renaming into a free slot works, then onto itself is a no-op.
1006 rename_item(&root, ".", "other.txt", "free.txt", false).unwrap();
1007 assert!(root.join("free.txt").exists());
1008 rename_item(&root, ".", "free.txt", "free.txt", false).unwrap();
1009 assert!(root.join("free.txt").exists());
1010 assert!(root.join("free.txt").is_file());
1011 }
1012
1013 #[test]
1014 fn rename_validates_new_name() {
1015 let t = T::new();
1016 let root = t.root.canonicalize().unwrap();
1017 for bad in ["a/b", "", ".", ".."] {
1018 assert!(matches!(
1019 rename_item(&root, ".", "file.txt", bad, false),
1020 Err(FsError::Invalid(_))
1021 ));
1022 }
1023 assert!(matches!(
1024 rename_item(&root, ".", "missing", "x", false),
1025 Err(FsError::NotFound)
1026 ));
1027 }
1028
1029 // ---------- remove ----------
1030
1031 #[test]
1032 fn remove_file_and_dir() {
1033 let t = T::new();
1034 let root = t.root.canonicalize().unwrap();
1035 let (is_dir, gone) = remove_item(&root, ".", "file.txt").unwrap();
1036 assert!(!is_dir);
1037 assert_eq!(gone, root.join("file.txt"));
1038 assert!(!root.join("file.txt").exists());
1039 let (is_dir, gone) = remove_item(&root, ".", "docs").unwrap();
1040 assert!(is_dir);
1041 assert_eq!(gone, root.join("docs"));
1042 assert!(!root.join("docs").exists());
1043 assert!(matches!(
1044 remove_item(&root, ".", "file.txt"),
1045 Err(FsError::NotFound)
1046 ));
1047 }
1048
1049 // ---------- save_file ----------
1050
1051 fn mtime_of(p: &Path) -> i64 {
1052 std::fs::metadata(p)
1053 .unwrap()
1054 .modified()
1055 .unwrap()
1056 .duration_since(std::time::UNIX_EPOCH)
1057 .unwrap()
1058 .as_secs() as i64
1059 }
1060
1061 #[test]
1062 fn save_file_updates_content_and_returns_new_mtime() {
1063 let t = T::new();
1064 let root = t.root.canonicalize().unwrap();
1065 let before = mtime_of(&root.join("file.txt"));
1066 // Sleep so the mtime actually advances (filesystem granularity).
1067 std::thread::sleep(std::time::Duration::from_millis(1100));
1068 let new = save_file(&root, ".", "file.txt", b"brand new", Some(before)).unwrap();
1069 assert_eq!(std::fs::read(root.join("file.txt")).unwrap(), b"brand new");
1070 assert!(new >= before);
1071 // A second save with the *returned* mtime succeeds.
1072 let new2 = save_file(&root, ".", "file.txt", b"again", Some(new)).unwrap();
1073 assert!(new2 >= new);
1074 // Without an expected mtime, always saves.
1075 let _ = save_file(&root, ".", "file.txt", b"force", None).unwrap();
1076 assert_eq!(std::fs::read(root.join("file.txt")).unwrap(), b"force");
1077 }
1078
1079 #[test]
1080 fn save_file_conflict_on_stale_mtime() {
1081 let t = T::new();
1082 let root = t.root.canonicalize().unwrap();
1083 std::thread::sleep(std::time::Duration::from_millis(1100));
1084 // The mtime we pass is older than the file's real mtime → conflict.
1085 assert!(matches!(
1086 save_file(&root, ".", "file.txt", b"x", Some(1)),
1087 Err(FsError::Conflict)
1088 ));
1089 }
1090
1091 #[test]
1092 fn save_file_error_cases() {
1093 let t = T::new();
1094 let root = t.root.canonicalize().unwrap();
1095 assert!(matches!(
1096 save_file(&root, ".", "nope.txt", b"x", None),
1097 Err(FsError::NotFound)
1098 ));
1099 assert!(matches!(
1100 save_file(&root, ".", "docs", b"x", None),
1101 Err(FsError::NotADirectory)
1102 ));
1103 assert!(matches!(
1104 save_file(&root, ".", "../evil.txt", b"x", None),
1105 Err(FsError::Forbidden)
1106 ));
1107 }
1108
1109 // ---------- move / copy ----------
1110
1111 #[test]
1112 fn move_file_and_dir_across_dirs() {
1113 let t = T::new();
1114 let root = t.root.canonicalize().unwrap();
1115 let vacated = move_item(&root, ".", "file.txt", ".", "src", false).unwrap();
1116 assert_eq!(vacated, root.join("file.txt"));
1117 assert!(!root.join("file.txt").exists());
1118 assert!(root.join("src/file.txt").exists());
1119 move_item(&root, ".", "src", ".", "docs", false).unwrap();
1120 assert!(root.join("docs/src/main.rs").exists());
1121 assert!(!root.join("src").exists());
1122 }
1123
1124 #[test]
1125 fn move_refuses_into_self_and_conflicts() {
1126 let t = T::new();
1127 let root = t.root.canonicalize().unwrap();
1128 // A dir cannot be moved into itself or a descendant.
1129 assert!(matches!(
1130 move_item(&root, ".", "docs", ".", "docs", false),
1131 Err(FsError::Invalid(_))
1132 ));
1133 assert!(matches!(
1134 move_item(&root, ".", "docs", ".", "docs/inner", false),
1135 Err(FsError::Invalid(_))
1136 ));
1137 // A dir target always conflicts, even with overwrite: move the file
1138 // "x" into a folder that already contains a subfolder "x".
1139 std::fs::create_dir_all(root.join("mv/case/x")).unwrap();
1140 std::fs::create_dir_all(root.join("mv/out")).unwrap();
1141 std::fs::write(root.join("mv/out/x"), "a file named x").unwrap();
1142 assert!(matches!(
1143 move_item(&root, ".", "mv/out/x", ".", "mv/case", true),
1144 Err(FsError::Conflict)
1145 ));
1146 // File onto file: conflict without overwrite, replaced with.
1147 std::fs::write(root.join("tmp-x.txt"), "x").unwrap();
1148 std::fs::write(root.join("tmp-y.txt"), "y").unwrap();
1149 std::fs::rename(root.join("tmp-x.txt"), root.join("tmp-target.txt")).unwrap();
1150 std::fs::rename(root.join("tmp-y.txt"), root.join("tmp-target2.txt")).unwrap();
1151 // Two distinct files with the same name in one folder.
1152 std::fs::create_dir_all(root.join("mv/dst")).unwrap();
1153 std::fs::create_dir_all(root.join("mv/out2")).unwrap();
1154 std::fs::write(root.join("mv/dst/dup.txt"), "old").unwrap();
1155 std::fs::write(root.join("mv/out2/dup.txt"), "new").unwrap();
1156 assert!(matches!(
1157 move_item(&root, ".", "mv/out2/dup.txt", ".", "mv/dst", false),
1158 Err(FsError::Conflict)
1159 ));
1160 move_item(&root, ".", "mv/out2/dup.txt", ".", "mv/dst", true).unwrap();
1161 assert_eq!(
1162 std::fs::read_to_string(root.join("mv/dst/dup.txt")).unwrap(),
1163 "new"
1164 );
1165 // Moving onto itself is a no-op success.
1166 move_item(&root, ".", "tmp-target.txt", ".", ".", false).unwrap();
1167 assert!(root.join("tmp-target.txt").exists());
1168 // Missing destination dir.
1169 assert!(matches!(
1170 move_item(&root, ".", "file.txt", ".", "nope", false),
1171 Err(FsError::NotFound)
1172 ));
1173 }
1174
1175 #[test]
1176 fn copy_file_and_dir_preserves_mtime() {
1177 let t = T::new();
1178 let root = t.root.canonicalize().unwrap();
1179 let before = mtime_of(&root.join("file.txt"));
1180 copy_item(&root, ".", "file.txt", ".", "src", false).unwrap();
1181 let copy = root.join("src/file.txt");
1182 assert_eq!(std::fs::read(&copy).unwrap(), b"top file");
1183 assert_eq!(mtime_of(&copy), before);
1184 // Dir copy.
1185 copy_item(&root, ".", "docs", ".", "src", false).unwrap();
1186 assert_eq!(
1187 std::fs::read_to_string(root.join("src/docs/inner/hello.txt")).unwrap(),
1188 "hello"
1189 );
1190 // Originals still there.
1191 assert!(root.join("file.txt").exists());
1192 assert!(root.join("docs/a.txt").exists());
1193 }
1194
1195 #[test]
1196 fn copy_refuses_into_self_and_handles_conflict() {
1197 let t = T::new();
1198 let root = t.root.canonicalize().unwrap();
1199 assert!(matches!(
1200 copy_item(&root, ".", "docs", ".", "docs", false),
1201 Err(FsError::Invalid(_))
1202 ));
1203 assert!(matches!(
1204 copy_item(&root, ".", "docs", ".", "docs/inner", false),
1205 Err(FsError::Invalid(_))
1206 ));
1207 // First copy is fine, the second one conflicts, overwrite replaces.
1208 copy_item(&root, ".", "file.txt", ".", "src", false).unwrap();
1209 assert!(matches!(
1210 copy_item(&root, ".", "file.txt", ".", "src", false),
1211 Err(FsError::Conflict)
1212 ));
1213 std::fs::write(root.join("file.txt"), "v2").unwrap();
1214 copy_item(&root, ".", "file.txt", ".", "src", true).unwrap();
1215 assert_eq!(
1216 std::fs::read_to_string(root.join("src/file.txt")).unwrap(),
1217 "v2"
1218 );
1219 // Copying onto itself is a no-op success.
1220 copy_item(&root, ".", "src/file.txt", ".", "src", false).unwrap();
1221 assert_eq!(
1222 std::fs::read_to_string(root.join("src/file.txt")).unwrap(),
1223 "v2"
1224 );
1225 // Missing destination dir.
1226 assert!(matches!(
1227 copy_item(&root, ".", "file.txt", ".", "nope", false),
1228 Err(FsError::NotFound)
1229 ));
1230 }
1231
1232 #[test]
1233 fn copy_recursive_missing_source() {
1234 let t = T::new();
1235 let dst = t.tmp.path().join("dst");
1236 assert!(matches!(
1237 copy_recursive(&t.root.join("nope"), &dst),
1238 Err(FsError::NotFound)
1239 ));
1240 }
1241
1242 // ---------- is_within_or_eq ----------
1243
1244 #[test]
1245 fn is_within_or_eq_matrix() {
1246 let t = T::new();
1247 let root = t.root.canonicalize().unwrap();
1248 let docs = root.join("docs");
1249 assert!(is_within_or_eq(&docs, &docs));
1250 assert!(is_within_or_eq(&docs, &root.join("docs/inner")));
1251 assert!(!is_within_or_eq(&docs, &root));
1252 assert!(!is_within_or_eq(&docs, &root.join("src")));
1253 }
1254
1255 // ---------- content sniffing ----------
1256
1257 fn kind(bytes: &[u8], name: &str) -> FileKind {
1258 kind_from_bytes(bytes, Path::new(name))
1259 }
1260
1261 #[test]
1262 fn magic_numbers_classify_by_content() {
1263 let png = [0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0];
1264 // The name is a lie in every case: the bytes decide.
1265 assert_eq!(kind(&png, "notes.txt"), FileKind::Image);
1266 assert_eq!(kind(b"%PDF-1.7\n%aaa\n", "x.bin"), FileKind::Pdf);
1267 assert_eq!(
1268 kind(b"PK\x03\x04\x14\x00\x00\x00", "x.png"),
1269 FileKind::Archive
1270 );
1271 assert_eq!(
1272 kind(&[0x1F, 0x8B, 0x08, 0, 0, 0, 0, 0], "x"),
1273 FileKind::Archive
1274 );
1275 assert_eq!(
1276 kind(
1277 &[
1278 0, 0, 0, 0x20, b'f', b't', b'y', b'p', b'i', b's', b'o', b'm'
1279 ],
1280 "x"
1281 ),
1282 FileKind::Video
1283 );
1284 assert_eq!(
1285 kind(b"ID3\x04\x00\x00\x00\x00\x00\x00", "x"),
1286 FileKind::Audio
1287 );
1288 assert_eq!(kind(b"RIFF\x24\x00\x00\x00WAVEfmt ", "x"), FileKind::Audio);
1289 assert_eq!(kind(b"<!doctype html><p>hi", "x"), FileKind::Text);
1290 // Recognized but not viewable in a browser.
1291 assert_eq!(
1292 kind(&[0x00, 0x61, 0x73, 0x6d, 1, 0, 0, 0], "x.wasm"),
1293 FileKind::Binary
1294 );
1295 }
1296
1297 #[test]
1298 fn unsigned_files_fall_back_to_the_text_heuristic() {
1299 // No magic number: plain text, source, config.
1300 assert_eq!(kind(b"hello world\n", "notes"), FileKind::Text);
1301 assert_eq!(kind(b"fn main() {}\n", "main.rs"), FileKind::Text);
1302 assert_eq!(
1303 kind("# über\nkey: wert\n".as_bytes(), "c.yaml"),
1304 FileKind::Text
1305 );
1306 // Extensionless text files work, which the old extension list missed.
1307 assert_eq!(kind(b"all:\n\tcargo build\n", "Makefile"), FileKind::Text);
1308 // Empty file → editable.
1309 assert_eq!(kind(b"", "new.txt"), FileKind::Text);
1310 // A NUL byte means binary, whatever the name says. (ELF has no
1311 // `infer` signature, so this is the path that catches it.)
1312 assert_eq!(
1313 kind(&[0x7F, b'E', b'L', b'F', 2, 1, 1, 0, 0], "run.txt"),
1314 FileKind::Binary
1315 );
1316 assert_eq!(kind(&[0xC3, 0x28, 0xFF, 0xFE], "x.txt"), FileKind::Binary);
1317 }
1318
1319 #[test]
1320 fn svg_is_offered_as_an_image() {
1321 // SVG is XML text with no magic number, but browsers draw it, so the
1322 // extension is the only signal available.
1323 let svg = b"<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>";
1324 assert_eq!(kind(svg, "logo.svg"), FileKind::Image);
1325 assert_eq!(kind(svg, "logo.txt"), FileKind::Text);
1326 }
1327
1328 #[test]
1329 fn truncated_utf8_at_the_read_boundary_is_still_text() {
1330 // 255 ASCII bytes plus the first byte of a 2-byte character: the read
1331 // cut a character in half, which must not read as binary.
1332 let mut b = vec![b'a'; SNIFF_BYTES - 1];
1333 b.push(0xC3);
1334 assert_eq!(kind(&b, "x.txt"), FileKind::Text);
1335 }
1336
1337 #[test]
1338 fn detect_kind_reads_from_disk() {
1339 let t = T::new();
1340 assert_eq!(detect_kind(&t.root.join("docs"), true), FileKind::Dir);
1341 assert_eq!(detect_kind(&t.root.join("file.txt"), false), FileKind::Text);
1342 // Unreadable / missing → Binary, never a failed listing.
1343 assert_eq!(detect_kind(&t.root.join("nope"), false), FileKind::Binary);
1344 }
1345
1346 /// `SNIFF_BUDGET` is process-wide, so the two tests that assert on it must
1347 /// not run at the same time as each other.
1348 static BUDGET_TESTS: std::sync::Mutex<()> = std::sync::Mutex::new(());
1349
1350 /// A directory big enough to take the fan-out path must produce exactly
1351 /// what the serial path would. Pass 2 fills `is_dir`, `size`, `mtime` and
1352 /// `kind`, all on worker threads, so a chunk-boundary mistake would show up
1353 /// as a row carrying another row's metadata or the untouched placeholders.
1354 #[test]
1355 fn parallel_rows_match_serial() {
1356 use std::sync::atomic::Ordering;
1357 let _guard = BUDGET_TESTS.lock().unwrap();
1358 let t = T::new();
1359 let big = t.root.join("big");
1360 std::fs::create_dir_all(&big).unwrap();
1361 // Well over SNIFF_CHUNK, so several chunks are handed out.
1362 let n = SNIFF_CHUNK * 3 + 7;
1363 for i in 0..n {
1364 let p = big.join(format!("f{i:05}"));
1365 // Every file gets a distinct length, so `size` pins the row identity.
1366 let pad = vec![b'A'; i];
1367 let mut body = match i % 3 {
1368 0 => vec![0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A],
1369 1 => b"plain text\n".to_vec(),
1370 _ => vec![0u8, 1, 2, 3],
1371 };
1372 body.extend_from_slice(&pad);
1373 std::fs::write(&p, &body).unwrap();
1374 }
1375 std::fs::create_dir(big.join("a-subdir")).unwrap();
1376
1377 let (entries, _) = list_dir(&big).unwrap();
1378 assert_eq!(entries.len(), n + 1);
1379
1380 // Every row must agree with what a single-threaded read of that same
1381 // file reports: kind, size and directory flag.
1382 for e in &entries {
1383 let p = big.join(&e.name);
1384 let m = std::fs::metadata(&p).unwrap();
1385 assert_eq!(e.is_dir, m.is_dir(), "{}", e.name);
1386 assert_eq!(e.size, m.len(), "size mismatch on {}", e.name);
1387 assert_eq!(e.mtime, mtime_str(&m), "mtime mismatch on {}", e.name);
1388 assert_eq!(
1389 e.kind,
1390 detect_kind(&p, e.is_dir),
1391 "kind mismatch on {}",
1392 e.name
1393 );
1394 }
1395
1396 // Sanity: several kinds are actually present, so the loop above is not
1397 // trivially true, and the directory sorts first.
1398 let kinds: Vec<FileKind> = entries.iter().map(|e| e.kind).collect();
1399 assert!(kinds.contains(&FileKind::Image));
1400 assert!(kinds.contains(&FileKind::Text));
1401 assert!(kinds.contains(&FileKind::Binary));
1402 assert_eq!(entries[0].name, "a-subdir");
1403 assert_eq!(entries[0].kind, FileKind::Dir);
1404
1405 // The thread budget is fully returned once the listing is done.
1406 assert_eq!(SNIFF_BUDGET.load(Ordering::Acquire), 0);
1407 }
1408
1409 #[test]
1410 fn sniff_permit_never_exceeds_the_budget() {
1411 use std::sync::atomic::Ordering;
1412 let _guard = BUDGET_TESTS.lock().unwrap();
1413 let total = sniff_budget_total();
1414 let a = SniffPermit::claim(total * 2);
1415 assert_eq!(a.0, total, "a single claim is capped at the total");
1416 // Nothing left: the next listing runs serially rather than queueing.
1417 let b = SniffPermit::claim(4);
1418 assert_eq!(b.0, 0);
1419 drop(a);
1420 drop(b);
1421 assert_eq!(SNIFF_BUDGET.load(Ordering::Acquire), 0);
1422 }
1423
1424 #[test]
1425 fn list_dir_reports_kinds() {
1426 let t = T::new();
1427 std::fs::write(
1428 t.root.join("docs/pic.dat"),
1429 [0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A],
1430 )
1431 .unwrap();
1432 let (entries, _) = list_dir(&t.root.join("docs")).unwrap();
1433 let kind_of = |n: &str| entries.iter().find(|e| e.name == n).unwrap().kind;
1434 assert_eq!(kind_of("inner"), FileKind::Dir);
1435 assert_eq!(kind_of("a.txt"), FileKind::Text);
1436 assert_eq!(kind_of("pic.dat"), FileKind::Image);
1437 }
1438}
1439