1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
//! Lease-based [`CoordinationLock`] — a file lease with TTL auto-expiry.
//!
//! Unlike the kernel `flock` backend ([`crate::FileLock`]), the liveness signal
//! here is the **lease TTL**, not a kernel lock: the holder renews the lease
//! periodically, and if it crashes *or* stops heartbeating, the lease expires
//! and another owner may acquire it. This is the primitive Subsystem B
//! (leader/follower) uses as its election lease.
//!
//! The renew loop runs on a [`tokio::task::spawn_blocking`] thread.
use serde::{Deserialize, Serialize};
use std::{
io,
path::{Path, PathBuf},
sync::{
Arc,
atomic::{AtomicBool, Ordering},
},
time::{Duration, SystemTime, UNIX_EPOCH},
};
use async_trait::async_trait;
use crate::traits::{CoordinationLock, LockError, LockGuard};
/// Filesystem lease lock. One lease file per `key` under `root`.
pub struct LeaseLock {
root: PathBuf,
}
impl LeaseLock {
#[must_use]
pub fn new(root: impl Into<PathBuf>) -> Self {
Self { root: root.into() }
}
}
#[derive(Serialize, Deserialize)]
struct LeaseRecord {
owner: String,
/// Expiry as milliseconds since the Unix epoch.
expires_at_ms: u64,
}
struct LeaseGuard {
path: PathBuf,
owner: String,
stop: Arc<AtomicBool>,
handle: Option<std::thread::JoinHandle<()>>,
}
#[async_trait]
impl LockGuard for LeaseGuard {
async fn release(&mut self) {
self.stop.store(true, Ordering::Release);
if let Some(h) = self.handle.take() {
let _ = h.join();
}
// Remove the lease only if we still own it.
if let Ok(content) = std::fs::read(&self.path) {
if let Ok(rec) = serde_json::from_slice::<LeaseRecord>(&content) {
if rec.owner == self.owner {
let _ = std::fs::remove_file(&self.path);
}
}
}
}
}
impl Drop for LeaseGuard {
fn drop(&mut self) {
self.stop.store(true, Ordering::Release);
if let Some(h) = self.handle.take() {
let _ = h.join();
}
// Clean up the lease file if we still own it (covers abandoned/panicked
// guards, not just an explicit release()).
if let Ok(content) = std::fs::read(&self.path) {
if let Ok(rec) = serde_json::from_slice::<LeaseRecord>(&content) {
if rec.owner == self.owner {
let _ = std::fs::remove_file(&self.path);
}
}
}
}
}
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0)
}
fn next_owner() -> String {
use std::sync::atomic::{AtomicU64, Ordering};
static COUNTER: AtomicU64 = AtomicU64::new(0);
format!(
"pid{}-{}-{}",
std::process::id(),
COUNTER.fetch_add(1, Ordering::Relaxed),
now_ms()
)
}
#[async_trait]
impl CoordinationLock for LeaseLock {
/// Acquire the file lease for `key` with a single non-blocking try.
///
/// # Semantics
///
/// Unlike the other backends, `lease` **is** honored — as the lease
/// **TTL**, not a wait duration: it is written into the lease record and
/// a background task renews it (TTL/3 cadence) while the guard lives. If
/// the holder crashes or stops renewing, the lease expires on its own and
/// another owner may take over — this is the only backend with true
/// automatic expiry. [`LockGuard::release`] (or the guard's `Drop`
/// fallback) removes the lease file immediately when the caller is done.
///
/// On contention (a live, unexpired lease held by another owner) this
/// returns [`LockError::Contended`] immediately; it never queues or
/// waits for the lease to lapse.
async fn acquire(&self, key: &str, lease: Duration) -> Result<Box<dyn LockGuard>, LockError> {
let root = self.root.clone();
let key_msg = key.to_string();
let path = root.join(sanitize(key));
let ttl = lease;
// Best-effort, NON-blocking acquire: try once. (A retry loop on a
// detached thread would outlive a dropped `acquire` future and could
// spuriously win the lease later — so we don't.) `lease` is the TTL
// written into the lease record, not a wait duration.
let result = tokio::task::spawn_blocking(move || -> Result<LeaseGuard, LockError> {
std::fs::create_dir_all(&root)?;
let owner = next_owner();
if try_take(&path, &owner, ttl)? {
let stop = Arc::new(AtomicBool::new(false));
let stop_c = Arc::clone(&stop);
let renew_path = path.clone();
let renew_owner = owner.clone();
let renew_ttl = ttl;
let handle = std::thread::spawn(move || {
let step = renew_ttl.max(Duration::from_secs(1)) / 3;
while !stop_c.load(Ordering::Acquire) {
let mut waited = Duration::ZERO;
while waited < step {
if stop_c.load(Ordering::Acquire) {
return;
}
std::thread::sleep(Duration::from_millis(50));
waited += Duration::from_millis(50);
}
let rec = LeaseRecord {
owner: renew_owner.clone(),
expires_at_ms: now_ms() + renew_ttl.as_millis() as u64,
};
let _ = write_atomic(&renew_path, &rec);
}
});
return Ok(LeaseGuard {
path,
owner,
stop,
handle: Some(handle),
});
}
Err(LockError::Contended(format!(
"lease on '{}' held by another live owner",
key_msg
)))
})
.await
.map_err(|e| LockError::Io(io::Error::other(format!("blocking task failed: {e}"))))?;
match result {
Ok(g) => Ok(Box::new(g)),
Err(e) => Err(e),
}
}
}
/// Try to claim the lease at `path` for `owner` with `ttl`. Returns true if we
/// now own it. CAS via atomic temp-file rename; re-read to confirm we won.
fn try_take(path: &Path, owner: &str, ttl: Duration) -> Result<bool, LockError> {
if let Ok(content) = std::fs::read(path) {
if let Ok(rec) = serde_json::from_slice::<LeaseRecord>(&content) {
if rec.expires_at_ms > now_ms() && rec.owner != owner {
// Live lease held by someone else.
return Ok(false);
}
}
}
// Expired or absent — (re)claim it.
let rec = LeaseRecord {
owner: owner.to_string(),
expires_at_ms: now_ms() + ttl.as_millis() as u64,
};
write_atomic(path, &rec)?;
// Confirm we won the race.
if let Ok(content) = std::fs::read(path) {
if let Ok(rec) = serde_json::from_slice::<LeaseRecord>(&content) {
return Ok(rec.owner == owner);
}
}
Ok(false)
}
/// Atomic write: temp file in the same dir, then rename over the target.
fn write_atomic(path: &Path, rec: &LeaseRecord) -> Result<(), LockError> {
let data =
serde_json::to_vec(rec).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
let tmp = path.with_extension("tmp");
std::fs::write(&tmp, &data)?;
std::fs::rename(&tmp, path)?;
Ok(())
}
fn sanitize(key: &str) -> String {
let mut out = String::with_capacity(key.len());
for c in key.chars() {
if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
out.push(c);
} else {
out.push('_');
}
}
if out.is_empty() {
out.push_str("default");
}
out.push_str(".lease");
out
}
#[cfg(test)]
mod tests {
use super::*;
use crate::traits::CoordinationLock;
#[tokio::test]
async fn acquire_renew_release() {
let dir = tempdir();
let lock = LeaseLock::new(&dir);
let mut g = lock
.acquire("device-a", Duration::from_secs(2))
.await
.unwrap();
// A second acquirer is contended while the lease is live.
let r = tokio::time::timeout(
Duration::from_millis(300),
lock.acquire("device-a", Duration::from_secs(2)),
)
.await;
assert!(
r.is_err() || r.unwrap().is_err(),
"second acquire should be contended"
);
g.release().await;
// After release, the lease file is gone — a new owner can take it.
let g2 = lock
.acquire("device-a", Duration::from_secs(2))
.await
.unwrap();
drop(g2);
}
fn tempdir() -> PathBuf {
let p =
std::env::temp_dir().join(format!("malkuth-lease-{}-{}", std::process::id(), now_ms()));
std::fs::create_dir_all(&p).unwrap();
p
}
}