Skip to main content

crabshell_services/
file.rs

1//! Files a config reads and writes, as Quickshell's `FileView` and
2//! `JsonAdapter`.
3
4#[cfg(test)]
5mod tests;
6
7use std::cell::{Cell, RefCell};
8use std::ffi::OsString;
9use std::io::{ErrorKind, Read, Write};
10use std::panic::{self, AssertUnwindSafe};
11use std::path::{Path, PathBuf};
12use std::rc::{Rc, Weak};
13use std::time::{Duration, Instant};
14
15use calloop::RegistrationToken;
16use calloop::timer::TimeoutAction;
17use crabshell_reactive::{ReadSignal, Signal, untrack};
18use crabshell_ui::Cx;
19use inotify::{EventMask, WatchMask};
20use serde::Serialize;
21use serde::de::DeserializeOwned;
22
23use crate::Shared;
24use crate::lines::panic_message;
25use crate::watch::{self, Watch};
26
27/// The largest file read; a larger one reads as missing, and that is
28/// logged.
29pub(crate) const MAX_FILE: u64 = 16 * 1024 * 1024;
30
31/// How long after a write to a file still open it is read, unless its
32/// writer closes it first: a log shows its lines within a frame or
33/// three, and one written in many pieces is read once per wait, not per
34/// piece.
35const WRITING: Duration = Duration::from_millis(50);
36
37/// What `cx.file_view` and `cx.json_file` need from the shell: the loop,
38/// to watch files.
39pub(crate) struct Files(pub(crate) Rc<Shared>);
40
41/// Follows the file at a path through whatever happens to the directories
42/// on the way: one not made yet is waited for from the nearest one that
43/// is there, and one removed, renamed or made again is followed anew.
44// shortcut: watches the directory the path names, not a link's target's,
45// so a target replaced by a rename in its own directory isn't seen, while
46// writes to it are, through its inode; follow the link when a config
47// needs that.
48struct Follow {
49  shared: Rc<Shared>,
50  path: PathBuf,
51  watch: RefCell<Option<Watch>>,
52  /// A watch on the file's own inode for writes while it is open, as its
53  /// directory's watch hears only their close.
54  file: RefCell<Option<Watch>>,
55  /// The timer that reads a file still being written, while one waits.
56  writing: Cell<Option<RegistrationToken>>,
57  /// Reads the file again.
58  changed: Box<dyn Fn()>,
59}
60
61impl Follow {
62  /// Calls `changed` when the file at `path` may have changed: written,
63  /// replaced or removed.
64  fn new(shared: &Rc<Shared>, path: PathBuf, changed: impl Fn() + 'static) -> Rc<Follow> {
65    let follow = Rc::new(Follow {
66      shared: Rc::clone(shared),
67      path,
68      watch: RefCell::new(None),
69      file: RefCell::new(None),
70      writing: Cell::new(None),
71      changed: Box::new(changed),
72    });
73    follow.rewatch();
74    follow
75  }
76
77  /// Watches the file's directory, or while it is missing the nearest
78  /// directory above it that is there, for the next name on the way.
79  fn rewatch(self: &Rc<Self>) {
80    self.watch.replace(None);
81    self.file.replace(None);
82    let (Some(dir), Some(name)) = (self.path.parent(), self.path.file_name()) else {
83      return;
84    };
85    let mut dir = if dir.as_os_str().is_empty() {
86      Path::new(".")
87    } else {
88      dir
89    };
90    let mut next: OsString = name.to_owned();
91    let own = dir.is_dir();
92    while !dir.is_dir() {
93      let (Some(above), Some(name)) = (dir.parent(), dir.file_name()) else {
94        return;
95      };
96      next = name.to_owned();
97      dir = if above.as_os_str().is_empty() {
98        Path::new(".")
99      } else {
100        above
101      };
102    }
103    let weak = Rc::downgrade(self);
104    let listener = move |change: &watch::Change| {
105      let Some(follow) = weak.upgrade() else {
106        return;
107      };
108      let moved = EventMask::DELETE_SELF | EventMask::MOVE_SELF;
109      match &change.name {
110        // The directory itself went, or changes were lost: start over.
111        None => {
112          if change.mask.intersects(moved) || change.mask.contains(EventMask::Q_OVERFLOW) {
113            follow.rewatch();
114          }
115          follow.read();
116        }
117        // Not on a create, when a writer hasn't written yet: its
118        // writes or its close come next. One that wrote before the
119        // watch on the new file was in is read after [`WRITING`].
120        Some(changed) if *changed == next && own => {
121          follow.watch_file();
122          if !change.mask.contains(EventMask::CREATE) {
123            follow.read();
124          } else if follow.path.metadata().is_ok_and(|meta| meta.len() > 0) {
125            follow.written();
126          }
127        }
128        // A directory on the way came or went.
129        Some(changed) if *changed == next => {
130          follow.rewatch();
131          follow.read();
132        }
133        Some(_) => {}
134      }
135    };
136    match watch::watch(&self.shared, dir, watch::DIRECTORY, listener) {
137      Ok(watch) => {
138        self.watch.replace(Some(watch));
139      }
140      Err(error) => {
141        let path = self.path.display();
142        tracing::info!(%path, %error, "can't watch the file, so changes to it aren't seen");
143      }
144    }
145    if own {
146      self.watch_file();
147    }
148  }
149
150  /// Watches the regular file at the path, if one is there, for writes
151  /// while it is open; a directory or a pipe is left to its directory's
152  /// watch, as the kernel keeps one mask per inode.
153  fn watch_file(self: &Rc<Self>) {
154    if !self.path.metadata().is_ok_and(|meta| meta.is_file()) {
155      self.file.replace(None);
156      return;
157    }
158    let weak = Rc::downgrade(self);
159    let listener = move |change: &watch::Change| {
160      if let Some(follow) = weak
161        .upgrade()
162        .filter(|_| change.mask.contains(EventMask::MODIFY))
163      {
164        follow.written();
165      }
166    };
167    // The new one first, so the same inode keeps its kernel watch.
168    // shortcut: a directory swapped in for the file between the check and
169    // the add would get this mask in place of its own, and dropping ours
170    // wouldn't give it back; watch by descriptor if that ever happens.
171    let watched = watch::watch(&self.shared, &self.path, WatchMask::MODIFY, listener);
172    if let Err(error) = &watched {
173      let path = self.path.display();
174      tracing::debug!(%path, %error, "can't watch the file's writes; its close still counts");
175    }
176    self.file.replace(watched.ok());
177  }
178}
179
180impl Follow {
181  /// The file was written and is still open: reads it after [`WRITING`],
182  /// on a timer that exists only while it waits, unless a close or
183  /// another change reads it first.
184  fn written(self: &Rc<Self>) {
185    if self.writing.get().is_some() {
186      return;
187    }
188    let Some(event_loop) = self.shared.event_loop() else {
189      return;
190    };
191    let weak = Rc::downgrade(self);
192    let tick = Box::new(move || {
193      if let Some(follow) = weak.upgrade() {
194        follow.writing.set(None);
195        (follow.changed)();
196      }
197      TimeoutAction::Drop
198    });
199    let token = event_loop.insert_timer(Instant::now() + WRITING, tick);
200    self.writing.set(token);
201  }
202
203  /// Reads the file now, so a read waiting for a writer is dropped.
204  fn read(&self) {
205    self.stop_waiting();
206    (self.changed)();
207  }
208
209  fn stop_waiting(&self) {
210    if let (Some(token), Some(event_loop)) = (self.writing.take(), self.shared.event_loop()) {
211      event_loop.remove(token);
212    }
213  }
214}
215
216impl Drop for Follow {
217  fn drop(&mut self) {
218    self.stop_waiting();
219  }
220}
221
222/// Keeps a file's watch for as long as the opening context's owner.
223struct Keep<T>(#[allow(dead_code, reason = "held for its drop")] Rc<T>);
224
225/// A text file, from `cx.file_view(path)`. Its text is read at once and
226/// again when it changes on disk. A clone is cheap and shares it.
227#[derive(Clone)]
228pub struct FileView {
229  inner: Rc<ViewInner>,
230}
231
232/// Why a file can't be read, from [`FileView::error`], as Quickshell's
233/// `FileViewError`.
234#[derive(Clone, Debug, PartialEq, Eq)]
235pub struct FileError {
236  /// What kind of failure it is.
237  pub kind: FileErrorKind,
238  /// What the system said, such as `No such file or directory (os error
239  /// 2)`, or the shell, such as `it isn't UTF-8`.
240  pub message: String,
241}
242
243/// The kinds of [`FileError`].
244#[derive(Clone, Copy, Debug, PartialEq, Eq)]
245pub enum FileErrorKind {
246  /// Nothing is at the path.
247  NotFound,
248  /// The shell may not read it.
249  PermissionDenied,
250  /// Something is there, but it isn't a regular file, such as a directory
251  /// or a pipe.
252  NotAFile,
253  /// Anything else, such as a file that isn't UTF-8 or is over 16 MiB.
254  Other,
255}
256
257impl FileError {
258  fn new(kind: FileErrorKind, message: &str) -> FileError {
259    let message = message.to_owned();
260    FileError { kind, message }
261  }
262}
263
264impl From<std::io::Error> for FileError {
265  fn from(error: std::io::Error) -> FileError {
266    let kind = match error.kind() {
267      ErrorKind::NotFound => FileErrorKind::NotFound,
268      ErrorKind::PermissionDenied => FileErrorKind::PermissionDenied,
269      ErrorKind::IsADirectory => FileErrorKind::NotAFile,
270      _ => FileErrorKind::Other,
271    };
272    FileError::new(kind, &error.to_string())
273  }
274}
275
276struct ViewInner {
277  path: PathBuf,
278  follow: RefCell<Option<Rc<Follow>>>,
279  /// These live under the opening context's owner.
280  text: Signal<Option<String>>,
281  error: Signal<Option<FileError>>,
282}
283
284/// `cx.file_view(path)`.
285pub(crate) fn file_view(cx: &Cx, path: PathBuf) -> FileView {
286  let inner = Rc::new(ViewInner {
287    text: cx.signal(None),
288    error: cx.signal(None),
289    follow: RefCell::new(None),
290    path,
291  });
292  inner.reread();
293  if let Some(files) = cx.service::<Files>() {
294    let weak = Rc::downgrade(&inner);
295    let follow = Follow::new(&files.0, inner.path.clone(), move || {
296      if let Some(inner) = Weak::upgrade(&weak) {
297        inner.reread();
298      }
299    });
300    inner.follow.replace(Some(follow));
301  }
302  // So `text()` follows the file even once every `FileView` is dropped.
303  cx.owner().signal(Keep(Rc::clone(&inner)));
304  FileView { inner }
305}
306
307impl FileView {
308  /// The file's text, or `None` while it is missing, can't be read, isn't
309  /// UTF-8, or is over 16 MiB, each logged once until it reads again.
310  /// [`error`](Self::error) says why.
311  pub fn text(&self) -> ReadSignal<Option<String>> {
312    self.inner.text.read_only()
313  }
314
315  /// Why the last read failed, or `None` once a read or a
316  /// [`write`](Self::write) worked. A pipe, a directory or a device is
317  /// [`NotAFile`](FileErrorKind::NotAFile) and never opened.
318  pub fn error(&self) -> ReadSignal<Option<FileError>> {
319    self.inner.error.read_only()
320  }
321
322  /// Replaces the file's text, through a new file beside it renamed over
323  /// it, so a reader never sees half of it, making its directory if it is
324  /// missing. A link is followed and the file it names is replaced,
325  /// keeping its permissions. A failure is logged and the text stays as
326  /// it was.
327  pub fn write(&self, text: impl AsRef<str>) {
328    let text = text.as_ref();
329    match write_whole(&self.inner.path, text.as_bytes()) {
330      Ok(()) => {
331        set(self.inner.text, Some(text.to_owned()));
332        set(self.inner.error, None);
333      }
334      Err(error) => {
335        let path = self.inner.path.display();
336        tracing::warn!(%path, %error, "couldn't write the file");
337      }
338    }
339  }
340}
341
342impl ViewInner {
343  /// Reads the file again and shows what it holds now.
344  fn reread(&self) {
345    let (text, error) = match read_text(&self.path) {
346      Ok(text) => (Some(text), None),
347      Err(error) => {
348        // Once, while the same error stays.
349        if untrack(|| self.error.try_with(|old| old.as_ref() != Some(&error))) == Some(true) {
350          let path = self.path.display();
351          tracing::info!(%path, error = error.message, "can't read the file");
352        }
353        (None, Some(error))
354      }
355    };
356    set(self.text, text);
357    set(self.error, error);
358  }
359}
360
361/// A JSON file kept in step with a signal: `cx.json_file(path, default)`.
362pub(crate) fn json_file<T>(cx: &Cx, path: PathBuf, default: T) -> Signal<T>
363where
364  T: Serialize + DeserializeOwned + PartialEq + 'static,
365{
366  let value = cx.signal(default);
367  let file = Rc::new(JsonInner {
368    path,
369    value,
370    // What the file holds, as far as this shell knows.
371    on_disk: RefCell::new(None),
372    logged: RefCell::new(None),
373    follow: RefCell::new(None),
374  });
375  file.reread();
376  if let Some(files) = cx.service::<Files>() {
377    let weak = Rc::downgrade(&file);
378    let follow = Follow::new(&files.0, file.path.clone(), move || {
379      if let Some(file) = Weak::upgrade(&weak) {
380        file.reread();
381      }
382    });
383    file.follow.replace(Some(follow));
384  }
385  // The value it starts from, so the first run doesn't make a missing
386  // file the config never set.
387  let start = untrack(|| value.try_with(|value| file.to_json(value))).flatten();
388  let writer = Rc::clone(&file);
389  let first = Cell::new(true);
390  cx.effect(move || {
391    let text = value.with(|value| writer.to_json(value));
392    let unset = first.replace(false) && start.is_some() && text == start;
393    if let (Some(text), false) = (text, unset) {
394      untrack(|| writer.write(text));
395    }
396  })
397  .named(format!("cx.json_file {}", file.path.display()));
398  value
399}
400
401struct JsonInner<T: 'static> {
402  path: PathBuf,
403  value: Signal<T>,
404  on_disk: RefCell<Option<String>>,
405  /// The last read problem logged, so it logs once until it reads again.
406  logged: RefCell<Option<String>>,
407  follow: RefCell<Option<Rc<Follow>>>,
408}
409
410impl<T> JsonInner<T>
411where
412  T: Serialize + DeserializeOwned + PartialEq + 'static,
413{
414  /// Reads the file again. A missing file keeps the value; one that
415  /// isn't the type's JSON is logged and keeps it too. The config's
416  /// `Deserialize`, `Serialize` and `PartialEq` may panic, and this may
417  /// run from the loop, where nothing else would catch them.
418  fn reread(&self) {
419    let text = match read_text(&self.path) {
420      Ok(text) => text,
421      Err(error) => {
422        self.log_once(format!("can't read the file: {}", error.message));
423        return;
424      }
425    };
426    let applied = panic::catch_unwind(AssertUnwindSafe(|| {
427      let read = serde_json::from_str::<T>(&text)?;
428      let normal = serde_json::to_string_pretty(&read).unwrap_or_else(|_| text.clone());
429      self.on_disk.replace(Some(normal));
430      set(self.value, read);
431      serde_json::Result::Ok(())
432    }));
433    match applied {
434      Ok(Ok(())) => {
435        self.logged.replace(None);
436      }
437      Ok(Err(error)) => self.log_once(format!("the file isn't the JSON expected: {error}")),
438      Err(payload) => {
439        let message = panic_message(payload.as_ref());
440        self.log_once(format!("reading it panicked: {message}"));
441      }
442    }
443  }
444
445  /// `value` as JSON, or `None` when the config's `Serialize` fails or
446  /// panics, which is logged.
447  fn to_json(&self, value: &T) -> Option<String> {
448    let path = self.path.display();
449    match panic::catch_unwind(AssertUnwindSafe(|| serde_json::to_string_pretty(value))) {
450      Ok(Ok(text)) => Some(text),
451      Ok(Err(error)) => {
452        tracing::warn!(%path, %error, "couldn't turn the value into JSON");
453        None
454      }
455      Err(payload) => {
456        let message = panic_message(payload.as_ref());
457        tracing::error!("cx.json_file {path}: turning the value into JSON panicked: {message}");
458        None
459      }
460    }
461  }
462
463  fn write(&self, text: String) {
464    if self.on_disk.borrow().as_deref() == Some(text.as_str()) {
465      return;
466    }
467    match write_whole(&self.path, format!("{text}\n").as_bytes()) {
468      Ok(()) => {
469        self.on_disk.replace(Some(text));
470      }
471      Err(error) => {
472        let path = self.path.display();
473        tracing::warn!(%path, %error, "couldn't write the file");
474      }
475    }
476  }
477
478  fn log_once(&self, problem: String) {
479    if self.logged.borrow().as_deref() != Some(problem.as_str()) {
480      let path = self.path.display();
481      tracing::info!(%path, problem, "the JSON file keeps its value");
482      self.logged.replace(Some(problem));
483    }
484  }
485}
486
487/// The whole of `path` as UTF-8, up to [`MAX_FILE`].
488fn read_text(path: &Path) -> Result<String, FileError> {
489  // Checked before the open, so a device or a pipe is never opened.
490  if !std::fs::metadata(path)?.is_file() {
491    return Err(FileError::new(FileErrorKind::NotAFile, "it isn't a file"));
492  }
493  let file = open_file(path)?;
494  let mut bytes = Vec::new();
495  file.take(MAX_FILE + 1).read_to_end(&mut bytes)?;
496  if bytes.len() as u64 > MAX_FILE {
497    return Err(FileError::new(FileErrorKind::Other, "it is over 16 MiB"));
498  }
499  String::from_utf8(bytes).map_err(|_| FileError::new(FileErrorKind::Other, "it isn't UTF-8"))
500}
501
502/// `path` opened to read, if it is a regular file. The open doesn't wait,
503/// as it would for a writer on a pipe put there since a check.
504fn open_file(path: &Path) -> Result<std::fs::File, FileError> {
505  use rustix::fs::{Mode, OFlags};
506
507  let flags = OFlags::RDONLY | OFlags::NONBLOCK | OFlags::NOCTTY | OFlags::CLOEXEC;
508  let fd = rustix::fs::open(path, flags, Mode::empty()).map_err(std::io::Error::from)?;
509  let file = std::fs::File::from(fd);
510  if !file.metadata()?.is_file() {
511    return Err(FileError::new(FileErrorKind::NotAFile, "it isn't a file"));
512  }
513  // A regular file's reads never wait anyway; this says so.
514  rustix::fs::fcntl_setfl(&file, OFlags::empty()).map_err(std::io::Error::from)?;
515  Ok(file)
516}
517
518/// Replaces the file at `path` with `bytes` through a new file beside it,
519/// renamed over it, making its directory if it is missing. A link is
520/// followed, so the file it names is replaced, and a file's permissions
521/// are kept.
522fn write_whole(path: &Path, bytes: &[u8]) -> std::io::Result<()> {
523  use std::os::unix::fs::OpenOptionsExt;
524
525  if let Some(dir) = path.parent()
526    && !dir.as_os_str().is_empty()
527    && !dir.exists()
528  {
529    std::fs::create_dir_all(dir)?;
530  }
531  let target = match std::fs::canonicalize(path) {
532    Ok(target) => target,
533    Err(error) if error.kind() == ErrorKind::NotFound => path.to_owned(),
534    Err(error) => return Err(error),
535  };
536  let name = target
537    .file_name()
538    .ok_or_else(|| std::io::Error::other("the path names no file"))?;
539  let mut partial_name = std::ffi::OsString::from(".");
540  partial_name.push(name);
541  partial_name.push(".crabshell-partial");
542  let partial = target.with_file_name(partial_name);
543  match std::fs::remove_file(&partial) {
544    Err(error) if error.kind() != ErrorKind::NotFound => return Err(error),
545    _ => {}
546  }
547  let mode = std::fs::metadata(&target).map_or(0o644, |meta| {
548    use std::os::unix::fs::PermissionsExt;
549    meta.permissions().mode() & 0o7777
550  });
551  // New, so it never writes through a link left in its place.
552  let mut file = std::fs::OpenOptions::new()
553    .write(true)
554    .create_new(true)
555    .mode(mode)
556    .open(&partial)?;
557  let written = file.write_all(bytes).and_then(|()| file.sync_all());
558  drop(file);
559  if let Err(error) = written.and_then(|()| std::fs::rename(&partial, &target)) {
560    let _ = std::fs::remove_file(&partial);
561    return Err(error);
562  }
563  Ok(())
564}
565
566/// Sets `signal` unless it holds `value` or is gone. The read is
567/// untracked, so an effect that opens a file doesn't run again for it.
568fn set<T: PartialEq + 'static>(signal: Signal<T>, value: T) {
569  if untrack(|| signal.try_with(|old| *old != value)) == Some(true) {
570    signal.try_set(value);
571  }
572}