Skip to main content

crate_plugin_kit/
lock.rs

1//! 安装 / 卸载期间的排他文件锁。
2//!
3//! 两个终端同时 `plugin add` 会写坏 `.plugins.json`、或让两个 `cargo build`
4//! 往同一个 wrapper 目录里写。用一把**跨进程**的锁挡住。
5//!
6//! # 实现
7//!
8//! 用 `create_new(true)` 创建锁文件 —— 这个操作在主流文件系统上是原子的,
9//! 谁创建成功谁持锁。内容写入 pid 与时间戳,方便排查。
10//!
11//! **不做 OS 级文件锁**(`flock` / `LockFileEx`):那需要额外的平台代码,
12//! 而本 crate 已经有一个更简单的判据 —— 锁文件是否存在 + 是否过期。
13//! 代价是"进程被 kill -9 会留下陈旧的锁文件",所以加了过期接管。
14
15use std::io::Write;
16use std::path::{Path, PathBuf};
17use std::time::{Duration, Instant, SystemTime};
18
19use crate::error::{KitError, KitResult};
20
21/// 锁文件多久算过期。超过这个年龄的锁会被后来者接管。
22///
23/// 取值要比任何合理的安装耗时长(`cargo build` 可能好几分钟),
24/// 又要比"用户已经忘了这件事"的时长短。
25pub const STALE_AFTER: Duration = Duration::from_secs(30 * 60);
26
27/// 轮询间隔。
28const POLL_INTERVAL: Duration = Duration::from_millis(120);
29
30/// 持有一把排他锁。`Drop` 时释放。
31#[derive(Debug)]
32pub struct FileLock {
33    path: PathBuf,
34}
35
36impl FileLock {
37    /// 取锁,最多等 `timeout`。
38    ///
39    /// # Errors
40    ///
41    /// - [`KitError::LockTimeout`]:超时仍是别人持有。
42    /// - [`KitError::LockIo`]:IO 出错,或锁文件所在目录建不出来。
43    pub fn acquire(path: &Path, timeout: Duration) -> KitResult<Self> {
44        Self::acquire_with_stale_after(path, timeout, STALE_AFTER)
45    }
46
47    /// 同 [`Self::acquire`],但可以指定"多久算过期"。
48    ///
49    /// 单独开这个口子是为了可测:把阈值设成 0,就能在不碰文件时间戳(那需要平台 API)
50    /// 的前提下验证接管逻辑。
51    pub(crate) fn acquire_with_stale_after(
52        path: &Path,
53        timeout: Duration,
54        stale_after: Duration,
55    ) -> KitResult<Self> {
56        if let Some(parent) = path.parent() {
57            std::fs::create_dir_all(parent).map_err(|source| KitError::LockIo {
58                path: path.to_path_buf(),
59                source,
60            })?;
61        }
62
63        let deadline = Instant::now() + timeout;
64
65        loop {
66            match Self::try_create(path) {
67                Ok(lock) => return Ok(lock),
68                Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
69                    // 别人持着。先看看是不是过期了。
70                    if Self::take_over_if_stale(path, stale_after)? {
71                        continue;
72                    }
73                    if Instant::now() >= deadline {
74                        return Err(KitError::LockTimeout {
75                            path: path.to_path_buf(),
76                            secs: timeout.as_secs(),
77                        });
78                    }
79                    std::thread::sleep(POLL_INTERVAL);
80                }
81                Err(source) => {
82                    return Err(KitError::LockIo {
83                        path: path.to_path_buf(),
84                        source,
85                    })
86                }
87            }
88        }
89    }
90
91    fn try_create(path: &Path) -> std::io::Result<Self> {
92        let mut f = std::fs::OpenOptions::new()
93            .write(true)
94            .create_new(true)
95            .open(path)?;
96
97        // 写点诊断信息。失败无所谓 —— 锁本身已经拿到了。
98        let _ = writeln!(f, "pid={} at={:?}", std::process::id(), SystemTime::now());
99
100        Ok(Self {
101            path: path.to_path_buf(),
102        })
103    }
104
105    /// 锁文件太老就把它删掉,返回 `true` 表示"删掉了,可以重试"。
106    fn take_over_if_stale(path: &Path, stale_after: Duration) -> KitResult<bool> {
107        let Ok(meta) = std::fs::metadata(path) else {
108            // 已经没了(别人刚释放),直接让调用方重试。
109            return Ok(true);
110        };
111        let Ok(modified) = meta.modified() else {
112            return Ok(false);
113        };
114        let Ok(age) = SystemTime::now().duration_since(modified) else {
115            // 时间戳在未来 —— 时钟有问题,保守起见不接管。
116            return Ok(false);
117        };
118
119        if age < stale_after {
120            return Ok(false);
121        }
122
123        match std::fs::remove_file(path) {
124            Ok(()) => Ok(true),
125            // 别人刚好也删了 —— 那更好,让调用方重试。
126            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(true),
127            Err(source) => Err(KitError::LockIo {
128                path: path.to_path_buf(),
129                source,
130            }),
131        }
132    }
133}
134
135impl Drop for FileLock {
136    fn drop(&mut self) {
137        let _ = std::fs::remove_file(&self.path);
138    }
139}
140
141#[cfg(test)]
142mod tests {
143    use super::*;
144
145    fn lock_path(dir: &tempfile::TempDir) -> PathBuf {
146        dir.path().join(".lock")
147    }
148
149    #[test]
150    fn acquires_and_creates_parent_directories() {
151        let dir = tempfile::tempdir().unwrap();
152        // 父目录还不存在 —— acquire 应当自己建出来
153        let path = dir.path().join("nested").join("deeper").join(".lock");
154
155        let lock = FileLock::acquire(&path, Duration::from_millis(50)).expect("应当能取到锁");
156        assert!(path.is_file(), "锁文件应当已创建");
157        drop(lock);
158    }
159
160    #[test]
161    fn releases_on_drop() {
162        let dir = tempfile::tempdir().unwrap();
163        let path = lock_path(&dir);
164
165        {
166            let _lock = FileLock::acquire(&path, Duration::from_millis(50)).unwrap();
167            assert!(path.is_file());
168        }
169
170        assert!(!path.exists(), "drop 之后锁文件应当被删掉");
171    }
172
173    /// 第二个持有者要等,等到超时就报 `LockTimeout` —— 而不是静默放行。
174    #[test]
175    fn a_second_holder_times_out() {
176        let dir = tempfile::tempdir().unwrap();
177        let path = lock_path(&dir);
178
179        let _first = FileLock::acquire(&path, Duration::from_millis(50)).unwrap();
180
181        let err = FileLock::acquire(&path, Duration::from_millis(120));
182        assert!(
183            matches!(err, Err(KitError::LockTimeout { .. })),
184            "期望 LockTimeout,得到 {err:?}"
185        );
186    }
187
188    /// 拿到锁之后再释放,后来者应当能立刻接上。
189    #[test]
190    fn a_later_holder_succeeds_after_release() {
191        let dir = tempfile::tempdir().unwrap();
192        let path = lock_path(&dir);
193
194        let first = FileLock::acquire(&path, Duration::from_millis(50)).unwrap();
195        drop(first);
196
197        let _second = FileLock::acquire(&path, Duration::from_millis(200)).expect("应当能接上");
198    }
199
200    /// 陈旧的锁(`kill -9` 的遗留物)要被接管,否则用户会被永久挡住。
201    ///
202    /// 把 stale 阈值设成 0,任何已存在的锁都算过期 —— 这样不用去改文件时间戳
203    /// (那要平台 API),测试是可移植的。
204    #[test]
205    fn takes_over_a_stale_lock() {
206        let dir = tempfile::tempdir().unwrap();
207        let path = lock_path(&dir);
208
209        std::fs::write(&path, "pid=1 at=<stale>").unwrap();
210
211        let _lock =
212            FileLock::acquire_with_stale_after(&path, Duration::from_millis(500), Duration::ZERO)
213                .expect("陈旧的锁应当被接管");
214    }
215
216    /// 新鲜的锁不能被抢。
217    #[test]
218    fn does_not_steal_a_fresh_lock() {
219        let dir = tempfile::tempdir().unwrap();
220        let path = lock_path(&dir);
221
222        std::fs::write(&path, "pid=1 at=<fresh>").unwrap();
223
224        // 阈值给足,刚写下的锁远没到过期
225        let err =
226            FileLock::acquire_with_stale_after(&path, Duration::from_millis(120), STALE_AFTER);
227        assert!(
228            matches!(err, Err(KitError::LockTimeout { .. })),
229            "新鲜的锁不该被抢走"
230        );
231    }
232
233    /// 锁文件写着 pid,方便排查是谁占着。
234    #[test]
235    fn writes_diagnostic_content() {
236        let dir = tempfile::tempdir().unwrap();
237        let path = lock_path(&dir);
238
239        let _lock = FileLock::acquire(&path, Duration::from_millis(50)).unwrap();
240
241        let text = std::fs::read_to_string(&path).unwrap();
242        assert!(text.contains("pid="), "锁文件内容:{text:?}");
243        assert!(text.contains(&std::process::id().to_string()));
244    }
245}