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