Skip to main content

mnemo_engine/shared/
sidecar.rs

1//! The sidecar directory next to a shared brain, `<brain>.mnemo-shared/`
2//! (12.4 design note, "Sidecar files"): the writer-preference lock
3//! (`intent.lock`) and the long-operation line (`lock-info`); step 7 adds the
4//! presence locks.
5//!
6//! It sits where others may be able to create names, so it's never trusted
7//! by name:
8//! - it's created with `mkdir`, never "create if missing, else use";
9//! - one that's already there is opened with `O_NOFOLLOW | O_DIRECTORY` and
10//!   checked through its descriptor: a real directory, owned by this user,
11//!   with no group or other access (and given 0700 if a umask left the
12//!   owner without full access);
13//! - files in it are opened relative to that descriptor (`openat`), with
14//!   `O_NOFOLLOW`, and with `O_EXCL` when they're new;
15//! - `lock-info` is written to a new temp name and renamed into place, never
16//!   truncated in place.
17//!
18//! If the directory can't be created (the caller can't write there) or
19//! fails a check, the handle doesn't use it and takes the main lock alone,
20//! and says why once ([`SidecarState::Unavailable`]).
21//!
22//! On Windows the checks are what std offers safely: the directory must be
23//! a real directory (not a symlink or junction), and files are opened
24//! without following reparse points. There's no owner or mode check there.
25
26use std::fs::File;
27use std::io::{Read, Write};
28use std::path::{Path, PathBuf};
29
30/// The sidecar directory's suffix, after the brain's full file name. One
31/// `.gitignore` pattern matches it wherever the brain lives:
32/// `*.mnemo-shared/`.
33pub const SUFFIX: &str = ".mnemo-shared";
34
35/// The writer-preference lock's file name.
36pub const INTENT: &str = "intent.lock";
37
38/// The long-operation line's file name.
39pub const LOCK_INFO: &str = "lock-info";
40
41/// LOCK-2's valve: the lock a writer that has waited past the threshold
42/// holds, which readers try (shared, without waiting) before the intent
43/// lock and back off from while it's held. Only writers ever hold it. Made
44/// up front by a v0.15 shared handle's sidecar, or by the first writer that
45/// needs it; never by a reader (12.4 design note, "LOCK-2").
46pub const VALVE: &str = "writer.lock";
47
48/// `<brain>.mnemo-shared` for an already resolved brain path.
49pub(crate) fn sidecar_path(brain: &Path) -> PathBuf {
50    let mut p = brain.as_os_str().to_os_string();
51    p.push(SUFFIX);
52    PathBuf::from(p)
53}
54
55/// Whether a brain can use its sidecar directory.
56pub(crate) enum SidecarState {
57    Ready(Sidecar),
58    /// Why not, for the one notice the handle gives.
59    Unavailable(String),
60}
61
62/// An opened, checked sidecar directory.
63pub(crate) struct Sidecar {
64    path: PathBuf,
65    #[cfg(unix)]
66    dir: rustix::fd::OwnedFd,
67    /// LOCK-2: the valve file, kept open once a reader has found it, so a
68    /// reader's check is a lock try and an unlock, not an `openat` too. It
69    /// holds no lock between calls. A replaced directory gets a new
70    /// `Sidecar`, and with it a new descriptor.
71    valve: std::sync::OnceLock<File>,
72}
73
74impl std::fmt::Debug for Sidecar {
75    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76        f.debug_struct("Sidecar").field("path", &self.path).finish()
77    }
78}
79
80impl Sidecar {
81    /// The directory's path.
82    pub(crate) fn path(&self) -> &Path {
83        &self.path
84    }
85
86    /// Read `lock-info`, if there is one: at most 512 bytes, one line.
87    pub(crate) fn read_lock_info(&self) -> Option<String> {
88        let mut f = self.open_existing(LOCK_INFO, false).ok()?;
89        let mut buf = vec![0u8; 512];
90        let n = f.read(&mut buf).ok()?;
91        buf.truncate(n);
92        let text = String::from_utf8_lossy(&buf).into_owned();
93        Some(text.lines().next().unwrap_or("").to_string())
94    }
95
96    /// Replace `lock-info` with `line`: written to a new exclusive temp name
97    /// in the directory, then renamed into place.
98    pub(crate) fn write_lock_info(&self, line: &str) -> std::io::Result<()> {
99        use std::sync::atomic::{AtomicU64, Ordering};
100        static NEXT: AtomicU64 = AtomicU64::new(0);
101        let tmp = format!(
102            "{LOCK_INFO}.{}-{}.tmp",
103            std::process::id(),
104            NEXT.fetch_add(1, Ordering::Relaxed)
105        );
106        let result = (|| {
107            let mut f = self.create_new(&tmp)?;
108            f.write_all(line.as_bytes())?;
109            f.write_all(b"\n")?;
110            drop(f);
111            self.rename(&tmp, LOCK_INFO)
112        })();
113        if result.is_err() {
114            let _ = self.remove(&tmp);
115        }
116        result
117    }
118
119    /// 13a: a hook's note, `hook.*` (at most 512 bytes, one line).
120    pub(crate) fn read_note(&self, name: &str) -> Option<String> {
121        let mut f = self.open_existing(name, false).ok()?;
122        let mut buf = vec![0u8; 512];
123        let n = f.read(&mut buf).ok()?;
124        buf.truncate(n);
125        Some(
126            String::from_utf8_lossy(&buf)
127                .lines()
128                .next()
129                .unwrap_or("")
130                .to_string(),
131        )
132    }
133
134    /// 13a: replace a hook's note, by a new temp name and a rename.
135    pub(crate) fn write_note(&self, name: &str, line: &str) -> std::io::Result<()> {
136        use std::sync::atomic::{AtomicU64, Ordering};
137        static NEXT: AtomicU64 = AtomicU64::new(0);
138        let tmp = format!(
139            "{name}.{}-{}.tmp",
140            std::process::id(),
141            NEXT.fetch_add(1, Ordering::Relaxed)
142        );
143        let result = (|| {
144            let mut f = self.create_new(&tmp)?;
145            f.write_all(line.as_bytes())?;
146            f.write_all(b"\n")?;
147            drop(f);
148            self.rename(&tmp, name)
149        })();
150        if result.is_err() {
151            let _ = self.remove(&tmp);
152        }
153        result
154    }
155
156    /// Remove `lock-info` (best effort: a hint, not a lock).
157    pub(crate) fn remove_lock_info(&self) {
158        let _ = self.remove(LOCK_INFO);
159    }
160
161    /// LOCK-2: the valve file for a reader's check, opened read-only and kept
162    /// once it exists. `None` while it doesn't (a sidecar made before v0.15,
163    /// until a writer needs it): no valve, the reader goes on.
164    pub(crate) fn valve_for_reading(&self) -> Option<&File> {
165        if let Some(f) = self.valve.get() {
166            return Some(f);
167        }
168        let f = self.open_existing(VALVE, false).ok()?;
169        Some(self.valve.get_or_init(|| f))
170    }
171}
172
173#[cfg(unix)]
174mod imp {
175    use super::*;
176    use rustix::fs::{self as rfs, AtFlags, FileType, Mode, OFlags};
177    use rustix::io::Errno;
178
179    /// Create (or find) and check the sidecar directory for `brain`, which
180    /// is already resolved (symlinks followed).
181    pub(crate) fn open(brain: &Path) -> SidecarState {
182        let path = sidecar_path(brain);
183        match rfs::mkdir(&path, Mode::RWXU) {
184            Ok(()) | Err(Errno::EXIST) => {}
185            Err(Errno::ACCESS | Errno::PERM | Errno::ROFS) => {
186                return SidecarState::Unavailable(format!(
187                    "can't create {} (the directory isn't writable)",
188                    path.display()
189                ))
190            }
191            Err(e) => {
192                return SidecarState::Unavailable(format!("can't create {}: {e}", path.display()))
193            }
194        }
195        let dir = match rfs::open(
196            &path,
197            OFlags::RDONLY | OFlags::DIRECTORY | OFlags::NOFOLLOW | OFlags::CLOEXEC,
198            Mode::empty(),
199        ) {
200            Ok(fd) => fd,
201            Err(e) => {
202                return SidecarState::Unavailable(format!(
203                    "{} isn't a real directory ({e})",
204                    path.display()
205                ))
206            }
207        };
208        let st = match rfs::fstat(&dir) {
209            Ok(st) => st,
210            Err(e) => return SidecarState::Unavailable(format!("{}: {e}", path.display())),
211        };
212        if FileType::from_raw_mode(st.st_mode) != FileType::Directory {
213            return SidecarState::Unavailable(format!("{} isn't a directory", path.display()));
214        }
215        if st.st_uid != rustix::process::geteuid().as_raw() {
216            return SidecarState::Unavailable(format!(
217                "{} belongs to another user",
218                path.display()
219            ));
220        }
221        if st.st_mode & 0o077 != 0 {
222            return SidecarState::Unavailable(format!(
223                "{} is open to other users (mode {:o}; it must be 0700)",
224                path.display(),
225                st.st_mode & 0o777
226            ));
227        }
228        // A umask that clears owner bits (0277, say) makes a directory
229        // nothing can be created in, and every call would then skip the
230        // intent lock without a word. It's this user's own directory with
231        // no access for others, so give it 0700.
232        if st.st_mode & 0o700 != 0o700 {
233            if let Err(e) = rfs::fchmod(&dir, Mode::RWXU) {
234                return SidecarState::Unavailable(format!(
235                    "{} has mode {:o} and can't be given 0700: {e}",
236                    path.display(),
237                    st.st_mode & 0o777
238                ));
239            }
240        }
241        SidecarState::Ready(Sidecar {
242            path,
243            dir,
244            valve: std::sync::OnceLock::new(),
245        })
246    }
247
248    fn check_regular(f: &File) -> std::io::Result<()> {
249        let st = rfs::fstat(f)?;
250        if FileType::from_raw_mode(st.st_mode) != FileType::RegularFile
251            || st.st_uid != rustix::process::geteuid().as_raw()
252        {
253            return Err(std::io::Error::other("not a regular file of this user's"));
254        }
255        Ok(())
256    }
257
258    impl Sidecar {
259        /// Open (creating if new) one of the directory's lock files.
260        pub(crate) fn lock_file(&self, name: &str) -> std::io::Result<File> {
261            let base = OFlags::RDWR | OFlags::NOFOLLOW | OFlags::CLOEXEC | OFlags::NONBLOCK;
262            match rfs::openat(
263                &self.dir,
264                name,
265                base | OFlags::CREATE | OFlags::EXCL,
266                Mode::RUSR | Mode::WUSR,
267            ) {
268                Ok(fd) => Ok(File::from(fd)),
269                Err(Errno::EXIST) => self.open_existing(name, true),
270                Err(e) => Err(e.into()),
271            }
272        }
273
274        pub(crate) fn open_existing(&self, name: &str, write: bool) -> std::io::Result<File> {
275            let mode = if write { OFlags::RDWR } else { OFlags::RDONLY };
276            let fd = rfs::openat(
277                &self.dir,
278                name,
279                mode | OFlags::NOFOLLOW | OFlags::CLOEXEC | OFlags::NONBLOCK,
280                Mode::empty(),
281            )?;
282            let f = File::from(fd);
283            check_regular(&f)?;
284            Ok(f)
285        }
286
287        pub(super) fn create_new(&self, name: &str) -> std::io::Result<File> {
288            let fd = rfs::openat(
289                &self.dir,
290                name,
291                OFlags::WRONLY | OFlags::CREATE | OFlags::EXCL | OFlags::NOFOLLOW | OFlags::CLOEXEC,
292                Mode::RUSR | Mode::WUSR,
293            )?;
294            Ok(File::from(fd))
295        }
296
297        pub(super) fn rename(&self, from: &str, to: &str) -> std::io::Result<()> {
298            Ok(rfs::renameat(&self.dir, from, &self.dir, to)?)
299        }
300
301        pub(super) fn remove(&self, name: &str) -> std::io::Result<()> {
302            Ok(rfs::unlinkat(&self.dir, name, AtFlags::empty())?)
303        }
304    }
305
306    /// Whether `pid` names a running process (signal 0). A process of
307    /// another user counts as running.
308    pub(crate) fn pid_alive(pid: u32) -> bool {
309        let Some(pid) = i32::try_from(pid)
310            .ok()
311            .and_then(rustix::process::Pid::from_raw)
312        else {
313            return false;
314        };
315        !matches!(rustix::process::test_kill_process(pid), Err(Errno::SRCH))
316    }
317}
318
319#[cfg(not(unix))]
320mod imp {
321    use super::*;
322    use std::fs::OpenOptions;
323
324    /// Don't follow a reparse point (symlink or junction) when opening.
325    #[cfg(windows)]
326    const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
327
328    fn no_follow(o: &mut OpenOptions) -> &mut OpenOptions {
329        #[cfg(windows)]
330        {
331            use std::os::windows::fs::OpenOptionsExt;
332            o.custom_flags(FILE_FLAG_OPEN_REPARSE_POINT);
333        }
334        o
335    }
336
337    pub(crate) fn open(brain: &Path) -> SidecarState {
338        let path = sidecar_path(brain);
339        match std::fs::create_dir(&path) {
340            Ok(()) => {}
341            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {}
342            Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
343                return SidecarState::Unavailable(format!(
344                    "can't create {} (the directory isn't writable)",
345                    path.display()
346                ))
347            }
348            Err(e) => {
349                return SidecarState::Unavailable(format!("can't create {}: {e}", path.display()))
350            }
351        }
352        match std::fs::symlink_metadata(&path) {
353            Ok(m) if m.is_dir() && !m.file_type().is_symlink() => SidecarState::Ready(Sidecar {
354                path,
355                valve: std::sync::OnceLock::new(),
356            }),
357            _ => SidecarState::Unavailable(format!("{} isn't a real directory", path.display())),
358        }
359    }
360
361    fn check_regular(f: &File) -> std::io::Result<()> {
362        let m = f.metadata()?;
363        if !m.is_file() || m.file_type().is_symlink() {
364            return Err(std::io::Error::other("not a regular file"));
365        }
366        Ok(())
367    }
368
369    impl Sidecar {
370        pub(crate) fn lock_file(&self, name: &str) -> std::io::Result<File> {
371            let p = self.path.join(name);
372            match no_follow(OpenOptions::new().read(true).write(true).create_new(true)).open(&p) {
373                Ok(f) => Ok(f),
374                Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
375                    self.open_existing(name, true)
376                }
377                Err(e) => Err(e),
378            }
379        }
380
381        pub(crate) fn open_existing(&self, name: &str, write: bool) -> std::io::Result<File> {
382            let f =
383                no_follow(OpenOptions::new().read(true).write(write)).open(self.path.join(name))?;
384            check_regular(&f)?;
385            Ok(f)
386        }
387
388        pub(super) fn create_new(&self, name: &str) -> std::io::Result<File> {
389            no_follow(OpenOptions::new().write(true).create_new(true)).open(self.path.join(name))
390        }
391
392        pub(super) fn rename(&self, from: &str, to: &str) -> std::io::Result<()> {
393            std::fs::rename(self.path.join(from), self.path.join(to))
394        }
395
396        pub(super) fn remove(&self, name: &str) -> std::io::Result<()> {
397            std::fs::remove_file(self.path.join(name))
398        }
399    }
400
401    /// No safe liveness check off Unix: a note is shown as it is.
402    pub(crate) fn pid_alive(_pid: u32) -> bool {
403        true
404    }
405}
406
407pub(crate) use imp::{open, pid_alive};
408
409/// 13a: the hooks' small notes in a brain's sidecar directory (the
410/// per-session stamps): names start with `hook.` and are 1 to 80 of
411/// `a-z0-9.-`, so they never collide with the lock files.
412pub mod notes {
413    use super::*;
414
415    fn ok_name(name: &str) -> bool {
416        name.starts_with("hook.")
417            && name.len() <= 80
418            && name
419                .bytes()
420                .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'.' || b == b'-')
421    }
422
423    /// A note's line, if the directory and the note are there.
424    pub fn read(brain: &Path, name: &str) -> Option<String> {
425        if !ok_name(name) {
426            return None;
427        }
428        let brain = std::fs::canonicalize(brain).ok()?;
429        open_if_present(&brain)?.read_note(name)
430    }
431
432    /// Remove the notes named `prefix*` last written more than `older_than`
433    /// ago; returns how many went. Best effort.
434    pub fn prune(brain: &Path, prefix: &str, older_than: std::time::Duration) -> usize {
435        if !ok_name(prefix) {
436            return 0;
437        }
438        let Some(brain) = std::fs::canonicalize(brain).ok() else {
439            return 0;
440        };
441        let Some(side) = open_if_present(&brain) else {
442            return 0;
443        };
444        let Ok(entries) = std::fs::read_dir(side.path()) else {
445            return 0;
446        };
447        let now = std::time::SystemTime::now();
448        let mut n = 0;
449        for e in entries.flatten() {
450            let name = e.file_name().to_string_lossy().into_owned();
451            if !name.starts_with(prefix) || !ok_name(&name) {
452                continue;
453            }
454            let old = e
455                .metadata()
456                .ok()
457                .and_then(|m| m.modified().ok())
458                .and_then(|t| now.duration_since(t).ok())
459                .is_some_and(|age| age > older_than);
460            if old && side.remove(&name).is_ok() {
461                n += 1;
462            }
463        }
464        n
465    }
466
467    /// Write a note (creating the checked directory if needed).
468    pub fn write(brain: &Path, name: &str, line: &str) -> std::io::Result<()> {
469        if !ok_name(name) || line.contains('\n') || line.len() > 500 {
470            return Err(std::io::Error::other("not a hook note"));
471        }
472        let brain = std::fs::canonicalize(brain)?;
473        match open(&brain) {
474            SidecarState::Ready(s) => s.write_note(name, line),
475            SidecarState::Unavailable(why) => Err(std::io::Error::other(why)),
476        }
477    }
478}
479
480/// The sidecar directory for `brain` if it's already there (checked as
481/// [`open`] checks it), never creating it.
482pub(crate) fn open_if_present(brain: &Path) -> Option<Sidecar> {
483    std::fs::symlink_metadata(sidecar_path(brain)).ok()?;
484    match open(brain) {
485        SidecarState::Ready(s) => Some(s),
486        SidecarState::Unavailable(_) => None,
487    }
488}