use std::fs::File;
use std::io::{Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};
use std::time::{Duration, SystemTime};
use anyhow::{Context as _, Result};
use codewhale_config::private_directory::PrivateDirectory;
const HOLDER_RECORD_MAX_BYTES: u64 = 512;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WorkspaceLeaseHolder {
pub pid: u32,
pub process_start: Option<String>,
pub client: Option<String>,
pub store_root: Option<PathBuf>,
pub since_ms: u64,
}
impl WorkspaceLeaseHolder {
fn to_record(&self) -> String {
let mut record = format!("version=1\npid={}\nsince_ms={}\n", self.pid, self.since_ms);
if let Some(process_start) = &self.process_start {
record.push_str(&format!("process_start={process_start}\n"));
}
if let Some(client) = &self.client {
record.push_str(&format!("client={}\n", client.replace(['\n', '='], " ")));
}
if let Some(store_root) = &self.store_root {
record.push_str(&format!(
"store_root={}\n",
store_root.to_string_lossy().replace(['\n', '='], " ")
));
}
record
}
fn from_record(text: &str) -> Option<Self> {
let mut version = None;
let mut pid = None;
let mut process_start = None;
let mut client = None;
let mut store_root = None;
let mut since_ms = None;
for line in text.lines() {
match line.split_once('=') {
Some(("version", value)) => version = value.parse::<u32>().ok(),
Some(("pid", value)) => pid = value.parse::<u32>().ok(),
Some(("process_start", value)) => process_start = Some(value.to_string()),
Some(("client", value)) => client = Some(value.to_string()),
Some(("store_root", value)) => store_root = Some(PathBuf::from(value)),
Some(("since_ms", value)) => since_ms = value.parse::<u64>().ok(),
_ => {}
}
}
if version != Some(1) {
return None;
}
Some(Self {
pid: pid?,
process_start,
client,
store_root,
since_ms: since_ms?,
})
}
pub fn held_for(&self) -> Duration {
SystemTime::now()
.duration_since(SystemTime::UNIX_EPOCH + Duration::from_millis(self.since_ms))
.unwrap_or_default()
}
}
pub struct SharedWorkspaceDriveLease {
inner: std::sync::Arc<LeaseInner>,
}
struct LeaseInner {
state: std::sync::Mutex<Option<(WorkspaceDriveLease, usize)>>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LeaseUnavailability {
pub directory: PathBuf,
pub reason: String,
}
impl LeaseUnavailability {
#[cfg(unix)]
fn new(directory: &Path, reason: impl Into<String>) -> Self {
Self {
directory: directory.to_path_buf(),
reason: reason.into(),
}
}
}
impl std::fmt::Display for LeaseUnavailability {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"{} cannot provide workspace exclusivity: {}",
self.directory.display(),
self.reason
)
}
}
pub enum LeaseAttempt {
Acquired(WorkspaceDriveLease),
Contended,
Unsupported(LeaseUnavailability),
}
pub enum LeaseAdmission {
Held(SharedWorkspaceDriveLease),
Contended,
Unsupported(LeaseUnavailability),
}
impl std::fmt::Debug for LeaseAdmission {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Held(_) => f.write_str("Held(..)"),
Self::Contended => f.write_str("Contended"),
Self::Unsupported(unavailable) => {
f.debug_tuple("Unsupported").field(unavailable).finish()
}
}
}
}
impl SharedWorkspaceDriveLease {
pub fn acquire(
workspace: &Path,
client: Option<&str>,
store_root: Option<&Path>,
) -> Result<LeaseAdmission> {
let lease_key = WorkspaceDriveLease::lease_path(workspace)?;
let slot = {
let mut registry = registry()
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
if let Some(slot) = registry.get(&lease_key) {
slot.clone()
} else {
let lease = match WorkspaceDriveLease::try_acquire(workspace, client, store_root)? {
LeaseAttempt::Acquired(lease) => lease,
LeaseAttempt::Contended => return Ok(LeaseAdmission::Contended),
LeaseAttempt::Unsupported(unavailable) => {
return Ok(LeaseAdmission::Unsupported(unavailable));
}
};
let inner = std::sync::Arc::new(LeaseInner {
state: std::sync::Mutex::new(Some((lease, 1))),
});
registry.insert(lease_key, inner.clone());
return Ok(LeaseAdmission::Held(Self { inner }));
}
};
let inner = slot.clone();
let mut state = slot
.state
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
if let Some((_lease, count)) = state.as_mut() {
*count += 1;
return Ok(LeaseAdmission::Held(Self { inner }));
}
let lease = match WorkspaceDriveLease::try_acquire(workspace, client, store_root)? {
LeaseAttempt::Acquired(lease) => lease,
LeaseAttempt::Contended => return Ok(LeaseAdmission::Contended),
LeaseAttempt::Unsupported(unavailable) => {
return Ok(LeaseAdmission::Unsupported(unavailable));
}
};
*state = Some((lease, 1));
Ok(LeaseAdmission::Held(Self { inner }))
}
}
impl Drop for SharedWorkspaceDriveLease {
fn drop(&mut self) {
let Ok(mut state) = self.inner.state.lock() else {
return;
};
let Some((_lease, count)) = state.as_mut() else {
return;
};
*count -= 1;
if *count == 0 {
state.take();
}
}
}
type LeaseRegistry =
std::sync::Mutex<std::collections::HashMap<PathBuf, std::sync::Arc<LeaseInner>>>;
fn registry() -> &'static LeaseRegistry {
static REGISTRY: std::sync::OnceLock<LeaseRegistry> = std::sync::OnceLock::new();
REGISTRY.get_or_init(|| std::sync::Mutex::new(std::collections::HashMap::new()))
}
pub struct WorkspaceDriveLease {
file: File,
_base: PrivateDirectory,
_directory: PrivateDirectory,
}
impl WorkspaceDriveLease {
pub fn lease_path(workspace: &Path) -> Result<PathBuf> {
let base = lease_state_base()?;
let canonical = workspace
.canonicalize()
.unwrap_or_else(|_| workspace.to_path_buf());
let project = codewhale_paths::strip_worktree_suffix(&canonical);
Ok(base
.join(codewhale_paths::stable_hex(&project))
.join(codewhale_paths::stable_hex(&canonical))
.with_extension("lease"))
}
pub fn try_acquire(
workspace: &Path,
client: Option<&str>,
store_root: Option<&Path>,
) -> Result<LeaseAttempt> {
let path = Self::lease_path(workspace)?;
let parent = path.parent().context("Workspace lease has no parent")?;
let state_root = parent
.parent()
.context("Workspace lease has no state root")?;
let name = path
.file_name()
.and_then(|name| name.to_str())
.context("Workspace lease name is invalid")?;
let base = PrivateDirectory::admit_trusting_mount(state_root)?;
let directory = PrivateDirectory::admit_trusting_mount(parent)?;
let file = directory.open_internal_file(name)?;
#[cfg(unix)]
let contention = {
use std::os::fd::AsRawFd as _;
if unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) } != 0 {
Some(std::io::Error::last_os_error())
} else {
None
}
};
#[cfg(windows)]
let contention = {
use std::os::windows::io::AsRawHandle as _;
use windows_sys::Win32::Storage::FileSystem::LockFile;
let (offset_low, offset_high, length_low, length_high) =
(HOLDER_RECORD_MAX_BYTES as u32, 0, u32::MAX, 0x7FFF_FFFF);
if unsafe {
LockFile(
file.as_raw_handle() as _,
offset_low,
offset_high,
length_low,
length_high,
)
} == 0
{
Some(std::io::Error::last_os_error())
} else {
None
}
};
#[cfg(not(any(unix, windows)))]
let contention: Option<std::io::Error> = None;
if let Some(error) = contention {
if codewhale_util::lock::is_contention(&error) {
return Ok(LeaseAttempt::Contended);
}
#[cfg(unix)]
if codewhale_util::lock::advisory_locking_unavailable(&error) {
return Ok(LeaseAttempt::Unsupported(LeaseUnavailability::new(
state_root,
format!("this filesystem refuses advisory file locks ({error})"),
)));
}
return Err(error).context("Failed to lock workspace lease");
}
#[cfg(any(unix, windows))]
anyhow::ensure!(
base.is_at_selected_path()? && directory.is_at_selected_path()?,
"Workspace lease directory identity changed"
);
let selected = directory.open_internal_file(name)?;
anyhow::ensure!(
PrivateDirectory::same_file_identity(&file, &selected)?,
"Workspace lease file identity changed"
);
let holder = WorkspaceLeaseHolder {
pid: std::process::id(),
process_start: current_process_start(),
client: client.map(ToString::to_string),
store_root: store_root.map(Path::to_path_buf),
since_ms: SystemTime::now()
.duration_since(SystemTime::UNIX_EPOCH)
.map_or(0, |elapsed| elapsed.as_millis() as u64),
};
let mut lease = Self {
file,
_base: base,
_directory: directory,
};
let _ = lease
.file
.set_len(0)
.and_then(|()| lease.file.seek(SeekFrom::Start(0)).map(|_| ()))
.and_then(|()| lease.file.write_all(holder.to_record().as_bytes()));
Ok(LeaseAttempt::Acquired(lease))
}
pub fn read_holder(workspace: &Path) -> Result<Option<WorkspaceLeaseHolder>> {
let path = Self::lease_path(workspace)?;
let parent = path.parent().context("Workspace lease has no parent")?;
let name = path
.file_name()
.and_then(|name| name.to_str())
.context("Workspace lease name is invalid")?;
let directory = match PrivateDirectory::inspect_trusting_mount(parent) {
Ok(directory) => directory,
Err(error)
if error.chain().any(|cause| {
cause
.downcast_ref::<std::io::Error>()
.is_some_and(|error| error.kind() == std::io::ErrorKind::NotFound)
}) =>
{
return Ok(None);
}
Err(error) => return Err(error).context("Failed to inspect workspace lease directory"),
};
#[cfg(unix)]
let bytes =
match directory.read_private_receipt(name, HOLDER_RECORD_MAX_BYTES as usize - 1)? {
Some((bytes, _file)) => bytes,
None => return Ok(None),
};
#[cfg(windows)]
let bytes = {
use std::io::Read as _;
let Some(file) = directory.open_owned_file_for_read(name)? else {
return Ok(None);
};
let mut bytes = Vec::new();
file.take(HOLDER_RECORD_MAX_BYTES).read_to_end(&mut bytes)?;
bytes
};
#[cfg(not(any(unix, windows)))]
anyhow::bail!("Workspace drive lease is unsupported on this platform");
#[cfg(any(unix, windows))]
{
anyhow::ensure!(
directory.is_at_selected_path()?,
"Workspace lease directory identity changed"
);
let text = std::str::from_utf8(&bytes)?;
Ok(WorkspaceLeaseHolder::from_record(text))
}
}
}
impl Drop for WorkspaceDriveLease {
fn drop(&mut self) {
#[cfg(unix)]
{
use std::os::fd::AsRawFd as _;
unsafe { libc::flock(self.file.as_raw_fd(), libc::LOCK_UN) };
}
#[cfg(windows)]
{
use std::os::windows::io::AsRawHandle as _;
use windows_sys::Win32::Storage::FileSystem::UnlockFile;
let (offset_low, offset_high, length_low, length_high) =
(HOLDER_RECORD_MAX_BYTES as u32, 0, u32::MAX, 0x7FFF_FFFF);
unsafe {
UnlockFile(
self.file.as_raw_handle() as _,
offset_low,
offset_high,
length_low,
length_high,
);
}
}
}
}
#[cfg(all(test, unix))]
fn holder_is_dead(path: &Path) -> bool {
use codewhale_config::private_directory::{UnixProcessStatus, unix_process_status};
let Some(holder) =
WorkspaceLeaseHolder::from_record(&std::fs::read_to_string(path).unwrap_or_default())
else {
return false;
};
let Some(recorded_start) = holder.process_start.as_deref() else {
return false;
};
if holder.pid == std::process::id() {
return current_process_start().as_deref() != Some(recorded_start);
}
match unix_process_status(holder.pid) {
Ok(UnixProcessStatus::Present { start }) => start != recorded_start,
Ok(UnixProcessStatus::Absent) => true,
Err(_) => false,
}
}
#[cfg(unix)]
fn current_process_start() -> Option<String> {
use codewhale_config::private_directory::{UnixProcessStatus, unix_process_status};
match unix_process_status(std::process::id()) {
Ok(UnixProcessStatus::Present { start }) => Some(start),
_ => None,
}
}
#[cfg(not(unix))]
fn current_process_start() -> Option<String> {
None
}
fn lease_state_base() -> Result<PathBuf> {
#[cfg(test)]
{
if let Some(base) = crate::test_support::unsealed_state_dir("workspace-leases") {
PrivateDirectory::open(&base)?;
return Ok(base);
}
}
codewhale_config::resolve_state_dir("workspace-leases")
.context("Failed to resolve workspace lease state dir")
}
#[cfg(test)]
mod tests {
use super::*;
fn temp_workspace(tag: &str) -> PathBuf {
let dir = crate::test_support::test_scratch_dir(&format!("cw-ws-lease-{tag}"));
std::fs::create_dir_all(&dir).expect("create workspace");
dir
}
fn write_record(workspace: &Path, holder: &WorkspaceLeaseHolder) -> PathBuf {
let path = WorkspaceDriveLease::lease_path(workspace).expect("lease path");
let parent = path.parent().expect("lease dir");
let _base = PrivateDirectory::open(parent.parent().expect("lease state root"))
.expect("private lease state root");
let directory = PrivateDirectory::open(parent).expect("private lease dir");
let mut file = directory
.open_internal_file(path.file_name().unwrap().to_str().unwrap())
.expect("private lease file");
file.set_len(0).expect("truncate holder record");
file.write_all(holder.to_record().as_bytes())
.expect("write holder record");
path
}
fn expect_held(admission: LeaseAdmission) -> SharedWorkspaceDriveLease {
match admission {
LeaseAdmission::Held(lease) => lease,
LeaseAdmission::Contended => panic!("expected a held lease, got contention"),
LeaseAdmission::Unsupported(unavailable) => {
panic!("expected a held lease, got {unavailable}")
}
}
}
#[test]
fn acquire_then_contend_reports_holder() {
let workspace = temp_workspace("contend");
let first =
WorkspaceDriveLease::try_acquire(&workspace, Some("tui"), None).expect("first acquire");
assert!(
matches!(first, LeaseAttempt::Acquired(_)),
"first drive is admitted"
);
let second = WorkspaceDriveLease::try_acquire(&workspace, Some("vscode"), None)
.expect("contend probe");
assert!(
matches!(second, LeaseAttempt::Contended),
"second drive must be refused"
);
let holder = WorkspaceDriveLease::read_holder(&workspace)
.expect("read holder")
.expect("holder recorded");
assert_eq!(holder.pid, std::process::id());
assert_eq!(holder.client.as_deref(), Some("tui"));
assert_eq!(holder.process_start, current_process_start());
drop(first);
let third =
WorkspaceDriveLease::try_acquire(&workspace, Some("vscode"), None).expect("reacquire");
assert!(
matches!(third, LeaseAttempt::Acquired(_)),
"lease frees after drop"
);
}
#[test]
fn shared_lease_reenters_within_a_process() {
let workspace = temp_workspace("shared");
let first = expect_held(
SharedWorkspaceDriveLease::acquire(&workspace, Some("tui"), None)
.expect("first shared acquire"),
);
let second = expect_held(
SharedWorkspaceDriveLease::acquire(&workspace, Some("vscode"), None)
.expect("second shared acquire"),
);
drop(first);
let refused =
WorkspaceDriveLease::try_acquire(&workspace, Some("probe"), None).expect("probe");
assert!(
matches!(refused, LeaseAttempt::Contended),
"lease still held while shared"
);
drop(second);
let after = expect_held(
SharedWorkspaceDriveLease::acquire(&workspace, Some("next"), None)
.expect("reacquire after full release"),
);
drop(after);
}
#[test]
fn shared_handles_survive_concurrent_acquire_and_release() {
let workspace = temp_workspace("churn");
let mut workers = Vec::new();
for _ in 0..8 {
let workspace = workspace.clone();
workers.push(std::thread::spawn(move || {
for _ in 0..25 {
let lease = expect_held(
SharedWorkspaceDriveLease::acquire(&workspace, Some("churn"), None)
.expect("acquire"),
);
drop(lease);
}
}));
}
for worker in workers {
worker.join().expect("churn worker");
}
let lease = expect_held(
SharedWorkspaceDriveLease::acquire(&workspace, Some("after"), None)
.expect("acquire after churn"),
);
let holder = WorkspaceDriveLease::read_holder(&workspace)
.expect("read holder")
.expect("holder recorded");
assert_eq!(holder.client.as_deref(), Some("after"));
drop(lease);
}
#[cfg(unix)]
#[test]
fn only_a_held_lock_is_contention_and_only_a_lockless_mount_is_unsupported() {
use std::io::Error;
let held = Error::from_raw_os_error(libc::EWOULDBLOCK);
assert!(
codewhale_util::lock::is_contention(&held),
"a held lock is contention"
);
assert!(
!codewhale_util::lock::advisory_locking_unavailable(&held),
"a held lock is not a mount without locks"
);
for code in [
libc::EPERM,
libc::EACCES,
libc::ENOTSUP,
libc::EINVAL,
libc::ENOSYS,
] {
let absent = Error::from_raw_os_error(code);
assert!(
!codewhale_util::lock::is_contention(&absent),
"{code} is the mount answering, not a holder"
);
assert!(
codewhale_util::lock::advisory_locking_unavailable(&absent),
"{code} means this mount has no advisory locks"
);
}
}
#[test]
fn lease_path_is_stable_and_worktree_aware() {
let workspace = temp_workspace("paths");
let one = WorkspaceDriveLease::lease_path(&workspace).expect("path");
let two = WorkspaceDriveLease::lease_path(&workspace).expect("path");
assert_eq!(one, two);
assert_eq!(one.extension().and_then(|ext| ext.to_str()), Some("lease"));
let worktree = workspace.join(".worktrees").join("feat");
std::fs::create_dir_all(&worktree).expect("create worktree");
let sibling = workspace.join(".worktrees").join("other");
std::fs::create_dir_all(&sibling).expect("create sibling");
let a = WorkspaceDriveLease::lease_path(&worktree).expect("path");
let b = WorkspaceDriveLease::lease_path(&sibling).expect("path");
assert_ne!(a, b, "distinct worktrees get distinct leases");
assert_eq!(
a.parent().unwrap(),
b.parent().unwrap(),
"worktrees of one project share a bucket"
);
}
#[test]
fn holder_record_round_trips_and_needs_a_version() {
let holder = WorkspaceLeaseHolder {
pid: 4242,
process_start: Some("macos:1:2".into()),
client: Some("vscode".into()),
store_root: Some(PathBuf::from("/tmp/store")),
since_ms: 1_700_000_000_000,
};
assert_eq!(
WorkspaceLeaseHolder::from_record(&holder.to_record()),
Some(holder)
);
assert_eq!(
WorkspaceLeaseHolder::from_record("pid=1\nsince_ms=0\n"),
None
);
}
#[test]
fn absent_or_malformed_records_read_none() {
let workspace = temp_workspace("records");
assert_eq!(
WorkspaceDriveLease::read_holder(&workspace).expect("absent"),
None
);
let path = write_record(
&workspace,
&WorkspaceLeaseHolder {
pid: 7,
process_start: None,
client: None,
store_root: None,
since_ms: 5,
},
);
assert!(
WorkspaceDriveLease::read_holder(&workspace)
.expect("present")
.is_some()
);
std::fs::write(&path, "not a record\n").expect("write malformed");
assert_eq!(
WorkspaceDriveLease::read_holder(&workspace).expect("malformed"),
None
);
}
#[cfg(unix)]
#[test]
fn a_provably_dead_holder_record_does_not_replace_a_locked_lease() {
fn holder_of_a_reaped_child(workspace: &Path) -> PathBuf {
use codewhale_config::private_directory::{UnixProcessStatus, unix_process_status};
let mut child = std::process::Command::new("/bin/sh")
.args(["-c", "exit 0"])
.spawn()
.expect("spawn child");
let pid = child.id();
let start = match unix_process_status(pid) {
Ok(UnixProcessStatus::Present { start }) => Some(start),
other => panic!("live child must be present: {other:?}"),
};
child.wait().expect("reap child");
let path = write_record(
workspace,
&WorkspaceLeaseHolder {
pid,
process_start: start,
client: Some("crashed".into()),
store_root: None,
since_ms: 0,
},
);
assert!(holder_is_dead(&path), "a reaped holder is provably dead");
path
}
let workspace = temp_workspace("dead");
holder_of_a_reaped_child(&workspace);
let first =
WorkspaceDriveLease::try_acquire(&workspace, Some("next"), None).expect("acquire");
assert!(
matches!(first, LeaseAttempt::Acquired(_)),
"an unlocked lease remains acquirable despite a stale record"
);
holder_of_a_reaped_child(&workspace);
assert!(
matches!(
WorkspaceDriveLease::try_acquire(&workspace, Some("contender"), None)
.expect("contend"),
LeaseAttempt::Contended
),
"a stale holder record must not replace a held kernel lock"
);
drop(first);
assert!(
matches!(
WorkspaceDriveLease::try_acquire(&workspace, Some("after"), None)
.expect("reacquire"),
LeaseAttempt::Acquired(_)
),
"the same lease is available after its holder releases it"
);
}
#[cfg(unix)]
#[test]
fn a_live_holder_with_a_matching_token_is_never_dead() {
use codewhale_config::private_directory::{UnixProcessStatus, unix_process_status};
let workspace = temp_workspace("live");
let mut child = std::process::Command::new("/bin/sh")
.args(["-c", "exec sleep 30"])
.spawn()
.expect("spawn child");
let pid = child.id();
let start = match unix_process_status(pid) {
Ok(UnixProcessStatus::Present { start }) => start,
other => panic!("live child must be present: {other:?}"),
};
let path = write_record(
&workspace,
&WorkspaceLeaseHolder {
pid,
process_start: Some(start),
client: Some("driving".into()),
store_root: None,
since_ms: 0,
},
);
assert!(
!holder_is_dead(&path),
"a live holder's recorded token must never read dead"
);
let _ = child.kill();
let _ = child.wait();
}
#[cfg(unix)]
#[test]
fn a_record_without_a_liveness_token_is_never_taken_over() {
let workspace = temp_workspace("no-token");
let path = write_record(
&workspace,
&WorkspaceLeaseHolder {
pid: u32::MAX,
process_start: None,
client: None,
store_root: None,
since_ms: 0,
},
);
assert!(
!holder_is_dead(&path),
"without a liveness token, only a live-holder conclusion is safe"
);
}
}