Skip to main content

subc_daemon/config_store/
writer_lock.rs

1//! A service store has one live writer, independent of daemon discovery paths.
2
3use fs4::{FileExt, TryLockError};
4use std::{
5    fs::{self, File},
6    io,
7    path::{Component, Path, PathBuf},
8};
9
10#[derive(Debug)]
11pub enum WriterLockError {
12    Busy { root: PathBuf },
13    Invalid { root: PathBuf, source: io::Error },
14}
15
16impl std::fmt::Display for WriterLockError {
17    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
18        match self {
19            Self::Busy { root } => write!(
20                f,
21                "config_store_busy: configuration store {} already has a live owner",
22                root.display()
23            ),
24            Self::Invalid { root, source } => write!(
25                f,
26                "config_store_lock_invalid: configuration store {}: {source}",
27                root.display()
28            ),
29        }
30    }
31}
32impl std::error::Error for WriterLockError {
33    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
34        match self {
35            Self::Invalid { source, .. } => Some(source),
36            _ => None,
37        }
38    }
39}
40
41/// An OS lock held until the store owner exits. The sibling file is never
42/// deleted: removing a locked inode would let another daemon lock its replacement.
43#[derive(Debug)]
44pub struct StoreWriterLock {
45    file: File,
46}
47
48impl StoreWriterLock {
49    /// Canonicalize the owned parent and lock a sibling without creating the
50    /// store root. This preserves the store's read-only startup contract.
51    pub fn acquire(root: &Path) -> Result<(super::StoreRoot, Self), WriterLockError> {
52        let invalid = |source| WriterLockError::Invalid {
53            root: root.into(),
54            source,
55        };
56        let leaf = match root.components().next_back() {
57            Some(Component::Normal(leaf)) if root.is_absolute() => leaf,
58            _ => {
59                return Err(invalid(io::Error::other(
60                    "store root must have an absolute ordinary name",
61                )))
62            }
63        };
64        let parent = root
65            .parent()
66            .ok_or_else(|| invalid(io::Error::other("store root has no parent")))?;
67        ensure_parent(parent).map_err(invalid)?;
68        let parent = fs::canonicalize(parent).map_err(invalid)?;
69        verify_directory(&parent).map_err(invalid)?;
70        let canonical_root = parent.join(leaf);
71        match fs::symlink_metadata(&canonical_root) {
72            Ok(_) => verify_directory(&canonical_root).map_err(invalid)?,
73            Err(error) if error.kind() == io::ErrorKind::NotFound => {}
74            Err(error) => return Err(invalid(error)),
75        }
76        let mut name = leaf.to_os_string();
77        name.push(".lock");
78        let path = parent.join(name);
79        let file = match create_lock(&path) {
80            Ok(file) => file,
81            Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {
82                subc_os::open_regular_nofollow(&path)
83                    .map_err(|error| invalid(io::Error::other(error)))?
84            }
85            Err(error) => return Err(invalid(error)),
86        };
87        verify_file(&file).map_err(invalid)?;
88        match FileExt::try_lock(&file) {
89            Ok(()) => {}
90            Err(TryLockError::WouldBlock) => {
91                return Err(WriterLockError::Busy {
92                    root: canonical_root,
93                })
94            }
95            Err(TryLockError::Error(error)) => return Err(invalid(error)),
96        }
97        let root = super::StoreRoot::from_service_definition(canonical_root).map_err(invalid)?;
98        Ok((root, Self { file }))
99    }
100}
101
102impl Drop for StoreWriterLock {
103    fn drop(&mut self) {
104        // Explicit unlock also releases a description briefly inherited by fork
105        // before exec; an unrelated child must not prolong daemon ownership.
106        let _ = FileExt::unlock(&self.file);
107    }
108}
109
110fn ensure_parent(path: &Path) -> io::Result<()> {
111    match fs::symlink_metadata(path) {
112        Ok(_) => verify_directory(path),
113        Err(error) if error.kind() == io::ErrorKind::NotFound => {
114            if let Some(parent) = path.parent() {
115                ensure_parent(parent)?;
116            }
117            #[cfg(unix)]
118            {
119                use std::os::unix::fs::DirBuilderExt;
120                match fs::DirBuilder::new().mode(0o700).create(path) {
121                    Ok(()) => {}
122                    Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {}
123                    Err(error) => return Err(error),
124                }
125            }
126            #[cfg(windows)]
127            subc_os::windows_acl::create_private_dir(path)?;
128            verify_directory(path)
129        }
130        Err(error) => Err(error),
131    }
132}
133
134fn verify_directory(path: &Path) -> io::Result<()> {
135    let metadata = fs::symlink_metadata(path)?;
136    if !metadata.is_dir() || metadata.file_type().is_symlink() {
137        return Err(io::Error::other(
138            "store parent/root must be an owned non-symlink directory",
139        ));
140    }
141    #[cfg(unix)]
142    {
143        use std::os::unix::fs::MetadataExt;
144        if metadata.uid() != subc_os::effective_uid() || metadata.mode() & 0o022 != 0 {
145            return Err(io::Error::other(
146                "store parent/root must be owned and not writable by other users",
147            ));
148        }
149    }
150    #[cfg(windows)]
151    subc_os::windows_acl::verify_private_dir(path)?;
152    Ok(())
153}
154
155fn create_lock(path: &Path) -> io::Result<File> {
156    #[cfg(windows)]
157    {
158        subc_os::windows_acl::create_private_file(path)
159    }
160    #[cfg(not(windows))]
161    {
162        let mut options = fs::OpenOptions::new();
163        options.read(true).write(true).create_new(true);
164        #[cfg(unix)]
165        {
166            use std::os::unix::fs::OpenOptionsExt;
167            options.mode(0o600);
168        }
169        options.open(path)
170    }
171}
172
173fn verify_file(file: &File) -> io::Result<()> {
174    let metadata = file.metadata()?;
175    if !metadata.is_file() {
176        return Err(io::Error::other("writer lock is not a regular file"));
177    }
178    #[cfg(unix)]
179    {
180        use std::os::unix::fs::MetadataExt;
181        if metadata.uid() != subc_os::effective_uid() || metadata.mode() & 0o077 != 0 {
182            return Err(io::Error::other("writer lock must be owner-only"));
183        }
184    }
185    #[cfg(windows)]
186    subc_os::windows_acl::verify_owner_only(file)?;
187    Ok(())
188}
189
190#[cfg(test)]
191mod tests {
192    use super::*;
193    use std::{
194        process::{Child, Command, Stdio},
195        time::{Duration, Instant},
196    };
197
198    struct Rig(cortexkit_test_support::ScratchDir);
199    impl Rig {
200        fn new() -> Self {
201            let path = cortexkit_test_support::ScratchDir::new("subc-store-lock");
202            #[cfg(windows)]
203            subc_os::windows_acl::create_private_dir(path.path()).unwrap();
204            Self(path)
205        }
206        fn root(&self) -> PathBuf {
207            self.0.join("authority")
208        }
209    }
210    struct KillOnDrop(Child);
211    impl Drop for KillOnDrop {
212        fn drop(&mut self) {
213            let _ = self.0.kill();
214            let _ = self.0.wait();
215        }
216    }
217
218    #[test]
219    fn config_store_writer_lock_refuses_second_owner_without_creating_root() {
220        let rig = Rig::new();
221        let root = rig.root();
222        let (canonical, first) = StoreWriterLock::acquire(&root).unwrap();
223        assert_eq!(
224            canonical.path(),
225            fs::canonicalize(rig.0.path()).unwrap().join("authority")
226        );
227        assert!(!root.exists());
228        assert!(
229            matches!(StoreWriterLock::acquire(&root),Err(WriterLockError::Busy { root: refused }) if refused == canonical.path())
230        );
231        let text = StoreWriterLock::acquire(&root).err().unwrap().to_string();
232        assert!(text.contains("config_store_busy") && text.contains("authority"));
233        drop(first);
234        let (_, _next) = StoreWriterLock::acquire(&root).unwrap();
235        assert!(!root.exists());
236        #[cfg(unix)]
237        {
238            use std::os::unix::fs::MetadataExt;
239            assert_eq!(
240                fs::metadata(rig.0.join("authority.lock")).unwrap().mode() & 0o777,
241                0o600
242            );
243        }
244    }
245
246    #[test]
247    fn config_store_writer_lock_releases_when_owning_process_exits() {
248        let rig = Rig::new();
249        let root = rig.root();
250        let mut child = KillOnDrop(
251            Command::new(std::env::current_exe().unwrap())
252                .arg("--exact")
253                .arg("config_store::writer_lock::tests::config_store_writer_lock_child_probe")
254                .arg("--ignored")
255                .env("SUBC_WRITER_LOCK_CHILD_ROOT", &root)
256                .stdout(Stdio::null())
257                .stderr(Stdio::null())
258                .spawn()
259                .unwrap(),
260        );
261        let deadline = Instant::now() + Duration::from_secs(5);
262        while !rig.0.join("held").exists() {
263            assert!(
264                child.0.try_wait().unwrap().is_none(),
265                "writer-lock probe exited before acquiring"
266            );
267            assert!(
268                Instant::now() < deadline,
269                "writer-lock probe did not acquire before deadline"
270            );
271            std::thread::sleep(Duration::from_millis(10));
272        }
273        assert!(matches!(
274            StoreWriterLock::acquire(&root),
275            Err(WriterLockError::Busy { .. })
276        ));
277        child.0.kill().unwrap();
278        child.0.wait().unwrap();
279        let (_, _next) = StoreWriterLock::acquire(&root).unwrap();
280        assert!(!root.exists());
281    }
282
283    #[test]
284    #[ignore = "child probe invoked by its bounded parent test"]
285    fn config_store_writer_lock_child_probe() {
286        let root =
287            PathBuf::from(std::env::var_os("SUBC_WRITER_LOCK_CHILD_ROOT").expect("isolated root"));
288        let (_, _lock) = StoreWriterLock::acquire(&root).unwrap();
289        fs::write(root.parent().unwrap().join("held"), b"held").unwrap();
290        loop {
291            std::thread::park();
292        }
293    }
294
295    #[test]
296    fn config_store_writer_lock_creates_only_private_missing_parents() {
297        let rig = Rig::new();
298        let root = rig.0.join("missing/parent/authority");
299        let (_, _lock) = StoreWriterLock::acquire(&root).unwrap();
300        assert!(!root.exists());
301        #[cfg(unix)]
302        {
303            use std::os::unix::fs::MetadataExt;
304            for parent in [rig.0.join("missing"), rig.0.join("missing/parent")] {
305                assert_eq!(fs::metadata(parent).unwrap().mode() & 0o777, 0o700);
306            }
307        }
308    }
309
310    #[cfg(unix)]
311    #[test]
312    fn config_store_writer_lock_refuses_symlink_parent_or_lock_and_broad_lock() {
313        use std::os::unix::fs::{symlink, PermissionsExt};
314        let rig = Rig::new();
315        symlink(&rig.0, rig.0.join("alias")).unwrap();
316        assert!(matches!(
317            StoreWriterLock::acquire(&rig.0.join("alias/authority")),
318            Err(WriterLockError::Invalid { .. })
319        ));
320
321        let ordinary = rig.0.join("ordinary");
322        let lock = rig.0.join("authority.lock");
323        fs::write(&ordinary, b"not a lock").unwrap();
324        fs::set_permissions(&ordinary, fs::Permissions::from_mode(0o600)).unwrap();
325        symlink(&ordinary, &lock).unwrap();
326        assert!(matches!(
327            StoreWriterLock::acquire(&rig.root()),
328            Err(WriterLockError::Invalid { .. })
329        ));
330        fs::remove_file(&lock).unwrap();
331
332        fs::write(&lock, b"broad").unwrap();
333        fs::set_permissions(&lock, fs::Permissions::from_mode(0o644)).unwrap();
334        assert!(matches!(
335            StoreWriterLock::acquire(&rig.root()),
336            Err(WriterLockError::Invalid { .. })
337        ));
338        fs::set_permissions(&lock, fs::Permissions::from_mode(0o600)).unwrap();
339        drop(StoreWriterLock::acquire(&rig.root()).unwrap());
340
341        fs::set_permissions(&rig.0, fs::Permissions::from_mode(0o777)).unwrap();
342        assert!(matches!(
343            StoreWriterLock::acquire(&rig.root()),
344            Err(WriterLockError::Invalid { .. })
345        ));
346        fs::set_permissions(&rig.0, fs::Permissions::from_mode(0o700)).unwrap();
347        drop(StoreWriterLock::acquire(&rig.root()).unwrap());
348    }
349}