use std::io::Write as _;
use std::path::{Component, Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use cap_std::ambient_authority;
use cap_std::fs::Dir;
use super::authority::AuthorityRefusal;
static NEXT_ROOT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
static NEXT_TEMP: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
const MAX_TEMP_ATTEMPTS: u32 = 16;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PhysicalRootIdentity(std::num::NonZeroU64);
impl PhysicalRootIdentity {
pub fn fresh() -> Self {
let raw = NEXT_ROOT.fetch_add(1, Ordering::Relaxed);
Self(std::num::NonZeroU64::new(raw).expect("root counter starts at 1"))
}
pub fn as_u64(self) -> u64 {
self.0.get()
}
pub fn from_stored(raw: u64) -> Option<Self> {
std::num::NonZeroU64::new(raw).map(Self)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PhysicalRootAnchor {
dev: u64,
ino: u64,
}
impl PhysicalRootAnchor {
pub fn observe(path: &Path) -> Option<Self> {
observe_physical_root_anchor(path)
}
}
#[cfg(unix)]
fn observe_physical_root_anchor(path: &Path) -> Option<PhysicalRootAnchor> {
use std::os::unix::fs::MetadataExt;
let metadata = std::fs::metadata(path).ok()?;
Some(PhysicalRootAnchor {
dev: metadata.dev(),
ino: metadata.ino(),
})
}
#[cfg(windows)]
#[allow(unsafe_code)]
fn observe_physical_root_anchor(path: &Path) -> Option<PhysicalRootAnchor> {
use std::os::windows::fs::OpenOptionsExt;
use std::os::windows::io::AsRawHandle;
use windows::Win32::Foundation::HANDLE;
use windows::Win32::Storage::FileSystem::{
BY_HANDLE_FILE_INFORMATION, FILE_FLAG_BACKUP_SEMANTICS, FILE_READ_ATTRIBUTES,
FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE, GetFileInformationByHandle,
};
let opened = std::fs::OpenOptions::new()
.access_mode(FILE_READ_ATTRIBUTES.0)
.share_mode((FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE).0)
.attributes(FILE_FLAG_BACKUP_SEMANTICS.0)
.open(path)
.ok()?;
let mut info = BY_HANDLE_FILE_INFORMATION::default();
let queried = unsafe { GetFileInformationByHandle(HANDLE(opened.as_raw_handle()), &mut info) };
queried.ok()?;
Some(PhysicalRootAnchor {
dev: u64::from(info.dwVolumeSerialNumber),
ino: (u64::from(info.nFileIndexHigh) << 32) | u64::from(info.nFileIndexLow),
})
}
#[cfg(not(any(unix, windows)))]
fn observe_physical_root_anchor(_path: &Path) -> Option<PhysicalRootAnchor> {
None
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RootRefusal {
LeaseRevoked,
EscapesRoot {
requested: PathBuf,
},
LinkComponent {
component: PathBuf,
},
Unreadable {
path: PathBuf,
message: String,
},
}
impl From<RootRefusal> for AuthorityRefusal {
fn from(_: RootRefusal) -> Self {
AuthorityRefusal::PhysicalRootReplaced
}
}
#[derive(Debug)]
pub struct PhysicalRootLease {
identity: PhysicalRootIdentity,
root: PathBuf,
dir: Option<Dir>,
revoked: Arc<AtomicBool>,
}
impl PhysicalRootLease {
pub fn take(root: impl Into<PathBuf>) -> Self {
let root = root.into();
let dir = Dir::open_ambient_dir(&root, ambient_authority()).ok();
Self {
identity: PhysicalRootIdentity::fresh(),
root,
dir,
revoked: Arc::new(AtomicBool::new(false)),
}
}
pub fn parked(&self) -> Self {
Self {
identity: self.identity,
root: self.root.clone(),
dir: None,
revoked: Arc::clone(&self.revoked),
}
}
pub fn reopened(&self) -> Self {
Self {
identity: self.identity,
root: self.root.clone(),
dir: Dir::open_ambient_dir(&self.root, ambient_authority()).ok(),
revoked: Arc::clone(&self.revoked),
}
}
fn capability(&self) -> Result<&Dir, RootRefusal> {
if !self.is_live() {
return Err(RootRefusal::LeaseRevoked);
}
self.dir.as_ref().ok_or_else(|| RootRefusal::Unreadable {
path: self.root.clone(),
message: "the leased root could not be opened as a directory capability".to_owned(),
})
}
pub fn identity(&self) -> PhysicalRootIdentity {
self.identity
}
pub fn root(&self) -> &Path {
&self.root
}
pub fn is_live(&self) -> bool {
!self.revoked.load(Ordering::Acquire)
}
pub fn revoke(&self) {
self.revoked.store(true, Ordering::Release);
}
fn revocation(&self) -> &Arc<AtomicBool> {
&self.revoked
}
pub fn resolve_beneath(&self, relative: &Path) -> Result<ResolvedTarget, RootRefusal> {
let dir = self.capability()?;
let mut components = Vec::new();
for component in relative.components() {
match component {
Component::Normal(part) => components.push(part.to_os_string()),
Component::CurDir => {}
Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
return Err(RootRefusal::EscapesRoot {
requested: relative.to_path_buf(),
});
}
}
}
let Some((leaf, parents)) = components.split_last() else {
return Err(RootRefusal::EscapesRoot {
requested: relative.to_path_buf(),
});
};
let mut walked = PathBuf::new();
let mut parent = self.root.clone();
for part in parents {
walked.push(part);
parent.push(part);
match dir.symlink_metadata(&walked) {
Ok(metadata) if metadata.is_symlink() => {
return Err(RootRefusal::LinkComponent { component: parent });
}
Ok(_) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(RootRefusal::Unreadable {
path: parent,
message: error.to_string(),
});
}
}
}
let mut relative_path = walked.clone();
relative_path.push(leaf);
Ok(ResolvedTarget {
parent,
leaf: leaf.clone(),
relative: relative_path,
})
}
fn refuse_link_relative(&self, relative: &Path) -> Result<(), RootRefusal> {
let dir = self.capability()?;
match dir.symlink_metadata(relative) {
Ok(metadata) if metadata.is_symlink() => Err(RootRefusal::LinkComponent {
component: self.root.join(relative),
}),
Ok(_) => Ok(()),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(error) => Err(RootRefusal::Unreadable {
path: self.root.join(relative),
message: error.to_string(),
}),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedTarget {
parent: PathBuf,
leaf: std::ffi::OsString,
relative: PathBuf,
}
impl ResolvedTarget {
pub fn parent(&self) -> &Path {
&self.parent
}
pub fn leaf(&self) -> &std::ffi::OsStr {
&self.leaf
}
pub fn path(&self) -> PathBuf {
self.parent.join(&self.leaf)
}
pub fn relative(&self) -> &Path {
&self.relative
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReplacementStep {
TempCreated,
Replaced,
DelegatedVerified,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WriteReceipt {
steps: Vec<ReplacementStep>,
target: PathBuf,
lease: PhysicalRootIdentity,
}
impl WriteReceipt {
pub fn steps(&self) -> &[ReplacementStep] {
&self.steps
}
pub fn target(&self) -> &Path {
&self.target
}
pub fn lease(&self) -> PhysicalRootIdentity {
self.lease
}
}
pub fn replace_beneath(
lease: &PhysicalRootLease,
relative: &Path,
contents: &[u8],
) -> Result<WriteReceipt, RootRefusal> {
stage_replacement(lease, relative, contents)?.commit()
}
pub fn verify_replacement_beneath(
lease: &PhysicalRootLease,
relative: &Path,
expected: &[u8],
) -> Result<Option<WriteReceipt>, RootRefusal> {
let target = lease.resolve_beneath(relative)?;
lease.refuse_link_relative(target.relative())?;
let dir = lease.capability()?;
let observed = dir
.read(target.relative())
.map_err(|error| RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
})?;
if observed != expected {
return Ok(None);
}
Ok(Some(WriteReceipt {
steps: vec![ReplacementStep::DelegatedVerified],
target: target.path(),
lease: lease.identity(),
}))
}
pub fn stage_replacement(
lease: &PhysicalRootLease,
relative: &Path,
contents: &[u8],
) -> Result<StagedReplacement, RootRefusal> {
let target = lease.resolve_beneath(relative)?;
lease.refuse_link_relative(target.relative())?;
let dir = lease.capability()?;
let staged_dir = dir.try_clone().map_err(|error| RootRefusal::Unreadable {
path: lease.root().to_path_buf(),
message: error.to_string(),
})?;
let mut steps = Vec::new();
if let Some(parent) = target.relative().parent()
&& !parent.as_os_str().is_empty()
{
dir.create_dir_all(parent)
.map_err(|error| RootRefusal::Unreadable {
path: target.parent().to_path_buf(),
message: error.to_string(),
})?;
}
let mut temp_relative = PathBuf::new();
let mut file = None;
for attempt in 0..MAX_TEMP_ATTEMPTS {
let mut name = target.leaf().to_os_string();
name.push(format!(
".symforge-tmp-{}-{}-{attempt}",
std::process::id(),
NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
));
let candidate = match target.relative().parent() {
Some(parent) if !parent.as_os_str().is_empty() => parent.join(&name),
_ => PathBuf::from(&name),
};
let mut options = cap_std::fs::OpenOptions::new();
options.write(true).create_new(true);
match dir.open_with(&candidate, &options) {
Ok(handle) => {
temp_relative = candidate;
file = Some(handle);
break;
}
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(error) => {
return Err(RootRefusal::Unreadable {
path: lease.root().join(&candidate),
message: error.to_string(),
});
}
}
}
let Some(mut handle) = file else {
return Err(RootRefusal::Unreadable {
path: target.parent().to_path_buf(),
message: "no unused temporary name was available beneath the leased root".to_owned(),
});
};
let written = handle.write_all(contents).and_then(|()| handle.sync_all());
drop(handle);
if let Err(error) = written {
let _ = dir.remove_file(&temp_relative);
return Err(RootRefusal::Unreadable {
path: lease.root().join(&temp_relative),
message: error.to_string(),
});
}
steps.push(ReplacementStep::TempCreated);
let temp_path = lease.root().join(&temp_relative);
Ok(StagedReplacement {
temp_relative,
temp_path,
target_relative: target.relative().to_path_buf(),
target: target.path(),
lease: lease.identity(),
revoked: Arc::clone(lease.revocation()),
dir: staged_dir,
steps,
})
}
#[derive(Debug)]
pub struct StagedReplacement {
temp_relative: PathBuf,
temp_path: PathBuf,
target_relative: PathBuf,
target: PathBuf,
lease: PhysicalRootIdentity,
revoked: Arc<AtomicBool>,
dir: Dir,
steps: Vec<ReplacementStep>,
}
impl StagedReplacement {
pub fn temp_path(&self) -> &Path {
&self.temp_path
}
pub fn target(&self) -> &Path {
&self.target
}
pub fn commit(mut self) -> Result<WriteReceipt, RootRefusal> {
if self.revoked.load(Ordering::Acquire) {
return Err(RootRefusal::LeaseRevoked);
}
if let Err(error) = self
.dir
.rename(&self.temp_relative, &self.dir, &self.target_relative)
{
let _ = self.dir.remove_file(&self.temp_relative);
self.steps.clear();
return Err(RootRefusal::Unreadable {
path: self.target.clone(),
message: error.to_string(),
});
}
let receipt = WriteReceipt {
steps: {
let mut steps = std::mem::take(&mut self.steps);
steps.push(ReplacementStep::Replaced);
steps
},
target: self.target.clone(),
lease: self.lease,
};
self.temp_relative = PathBuf::new();
self.temp_path = PathBuf::new();
Ok(receipt)
}
}
impl Drop for StagedReplacement {
fn drop(&mut self) {
if !self.temp_relative.as_os_str().is_empty() {
let _ = self.dir.remove_file(&self.temp_relative);
}
}
}
#[cfg(all(test, any(unix, windows)))]
mod anchor_tests {
use super::PhysicalRootAnchor;
use std::fs;
fn temp_root() -> tempfile::TempDir {
tempfile::tempdir().expect("temporary root directory")
}
#[test]
fn distinct_directories_yield_distinct_anchors() {
let root = temp_root();
let a = root.path().join("a");
let b = root.path().join("b");
fs::create_dir(&a).unwrap();
fs::create_dir(&b).unwrap();
let anchor_a = PhysicalRootAnchor::observe(&a).expect("anchor for a");
let anchor_b = PhysicalRootAnchor::observe(&b).expect("anchor for b");
assert_ne!(
anchor_a, anchor_b,
"distinct directories at distinct paths must not share an anchor"
);
}
#[test]
fn same_directory_observed_twice_yields_same_anchor() {
let root = temp_root();
let a = root.path().join("a");
fs::create_dir(&a).unwrap();
let first = PhysicalRootAnchor::observe(&a).expect("first observation");
let second = PhysicalRootAnchor::observe(&a).expect("second observation");
assert_eq!(
first, second,
"a stable directory must not change identity between observations"
);
}
#[test]
fn directory_replaced_at_same_path_yields_new_anchor() {
let root = temp_root();
let a = root.path().join("a");
fs::create_dir_all(a.join("occupied")).unwrap();
let b = root.path().join("b");
fs::create_dir(&b).unwrap();
let before = PhysicalRootAnchor::observe(&a).expect("anchor before replacement");
fs::remove_dir_all(&a).unwrap();
fs::rename(&b, &a).unwrap();
let after = PhysicalRootAnchor::observe(&a).expect("anchor after replacement");
assert_ne!(
before, after,
"a different directory installed at the same path must change the anchor (ABA)"
);
}
#[test]
fn missing_path_yields_none() {
let root = temp_root();
let missing = root.path().join("does-not-exist");
assert_eq!(
PhysicalRootAnchor::observe(&missing),
None,
"a nonexistent path must observe to None, not error or panic"
);
}
#[test]
fn file_yields_some_stable_anchor() {
let root = temp_root();
let f = root.path().join("file.txt");
fs::write(&f, b"payload").unwrap();
let first = PhysicalRootAnchor::observe(&f).expect("file must observe to Some");
let second = PhysicalRootAnchor::observe(&f).expect("re-observation of file");
assert_eq!(
first, second,
"file identity must be stable across observations"
);
}
}