use std::collections::BTreeMap;
use std::fs::File;
use std::prelude::v1::*;
use std::future::Future;
use std::ops::Deref;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use crate::{GeneralHeader, Link, DATA_VERSION, GENERAL_HEADER_SIZE, INNER_PAGE_SIZE, PAGE_SIZE};
use memmap2::{Mmap, MmapOptions};
use rkyv::Archive;
use sha2::{Digest as _, Sha256};
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct BucketId(String);
impl BucketId {
pub fn parse(value: impl Into<String>) -> crate::error::Result<Self> {
let value = value.into();
if value.len() != 64
|| !value
.bytes()
.all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
{
return Err(crate::error::Error::Message(
"DataBucket identity must be a lowercase hexadecimal SHA-256".to_string()
));
}
Ok(Self(value))
}
pub fn of_bytes(bytes: &[u8]) -> Self {
Self(format!("{:x}", Sha256::digest(bytes)))
}
pub fn as_str(&self) -> &str {
&self.0
}
}
#[derive(Clone, Copy, Debug)]
pub struct AttachedPage<'a> {
pub header: GeneralHeader,
pub data: &'a [u8],
}
pub struct AttachedBucket {
path: PathBuf,
id: BucketId,
map: Mmap,
headers: Vec<GeneralHeader>,
memory_locked: bool,
private_file_checked: bool,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct AttachPolicy {
pub require_private_file: bool,
pub lock_memory: bool,
}
impl Default for AttachPolicy {
fn default() -> Self {
Self {
require_private_file: true,
lock_memory: false,
}
}
}
impl AttachPolicy {
pub const fn sensitive() -> Self {
Self {
require_private_file: true,
lock_memory: true,
}
}
}
impl std::fmt::Debug for AttachedBucket {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("AttachedBucket")
.field("path", &self.path)
.field("id", &self.id)
.field("bytes", &self.map.len())
.field("pages", &self.headers.len())
.finish()
}
}
impl AttachedBucket {
pub fn attach(path: impl AsRef<Path>, expected_id: BucketId) -> crate::error::Result<Self> {
Self::attach_with_policy(path, expected_id, AttachPolicy::default())
}
pub fn attach_with_policy(
path: impl AsRef<Path>,
expected_id: BucketId,
policy: AttachPolicy,
) -> crate::error::Result<Self> {
Self::attach_inner(path, Some(expected_id), policy)
}
pub fn attach_observed(path: impl AsRef<Path>, policy: AttachPolicy) -> crate::error::Result<Self> {
Self::attach_inner(path, None, policy)
}
fn attach_inner(
path: impl AsRef<Path>,
expected_id: Option<BucketId>,
policy: AttachPolicy,
) -> crate::error::Result<Self> {
let path = path.as_ref().to_path_buf();
let file = open_readonly_nofollow(&path)
.map_err(|error| crate::error::Error::Message(format!("opening DataBucket {}: {error}", path.display())))?;
let metadata = file
.metadata()
.map_err(|error| crate::error::Error::Message(format!("reading DataBucket metadata: {error}")))?;
if !metadata.is_file() {
return Err(crate::error::Error::Message("DataBucket object is not a regular file".to_string()));
}
#[cfg(not(unix))]
if policy.require_private_file {
return Err(crate::error::Error::Message(
"private file policy is unsupported on this platform".to_string()
));
}
#[cfg(unix)]
if policy.require_private_file {
use std::os::unix::fs::MetadataExt as _;
if metadata.mode() & 0o077 != 0 {
return Err(crate::error::Error::Message(
format!("sensitive DataBucket {} must not grant group/world permissions", path.display())
));
}
}
if metadata.len() < GENERAL_HEADER_SIZE as u64 {
return Err(crate::error::Error::Message(
"DataBucket object is shorter than one page header".to_string()
));
}
let map = unsafe { MmapOptions::new().map(&file) }
.map_err(|error| crate::error::Error::Message(format!("mapping DataBucket {}: {error}", path.display())))?;
struct MlockRollback {
ptr: *const libc::c_void,
len: usize,
active: bool,
}
impl Drop for MlockRollback {
fn drop(&mut self) {
if self.active && self.len > 0 {
unsafe {
let _ = libc::munlock(self.ptr, self.len);
}
}
}
}
let mut mlock_guard = MlockRollback {
ptr: map.as_ptr().cast(),
len: map.len(),
active: false,
};
if policy.lock_memory && !map.is_empty() {
let status = unsafe { libc::mlock(map.as_ptr().cast(), map.len()) };
if status != 0 {
return Err(crate::error::Error::Message(
format!("locking sensitive DataBucket {} in memory: {}",
path.display(),
std::io::Error::last_os_error())
));
}
mlock_guard.active = true;
}
let observed_id = BucketId::of_bytes(&map);
if let Some(expected_id) = expected_id.as_ref() {
if observed_id != *expected_id {
return Err(crate::error::Error::Message(
format!("DataBucket identity mismatch: expected {}, observed {}",
expected_id.as_str(),
observed_id.as_str())
));
}
}
let page_count = map.len().div_ceil(PAGE_SIZE);
let mut headers = Vec::with_capacity(page_count);
for index in 0..page_count {
let start = (index as u64)
.checked_mul(PAGE_SIZE as u64)
.ok_or_else(|| crate::error::Error::Message("DataBucket page offset overflow".to_string()))?;
let header_end = start
.checked_add(GENERAL_HEADER_SIZE as u64)
.ok_or_else(|| crate::error::Error::Message("DataBucket header offset overflow".to_string()))?;
if header_end > (map.len() as u64) {
return Err(crate::error::Error::Message(
format!("DataBucket page {index} has a truncated header")
));
}
let archived = crate::access_archived::<<GeneralHeader as Archive>::Archived>(
&map[start as usize..header_end as usize],
)
.map_err(|error| {
crate::error::Error::Message(format!("DataBucket page {index} header failed validation: {error}"))
})?;
let header: GeneralHeader = rkyv::deserialize::<_, rkyv::rancor::Error>(archived)
.map_err(|error| {
crate::error::Error::Message(format!("DataBucket page {index} header failed decode: {error}"))
})?;
if header.data_version != DATA_VERSION {
return Err(crate::error::Error::Message(
format!("DataBucket page {index} version {} differs from supported {DATA_VERSION}",
header.data_version)
));
}
if usize::from(header.page_id) != index {
return Err(crate::error::Error::Message(
format!("DataBucket physical page {index} declares page id {}",
header.page_id)
));
}
let length = payload_length(header)?;
let data_end = header_end
.checked_add(length as u64)
.ok_or_else(|| crate::error::Error::Message(format!("DataBucket page {index} length overflow")))?;
let page_end = start
.checked_add(PAGE_SIZE as u64)
.ok_or_else(|| crate::error::Error::Message(format!("DataBucket page {index} end overflow")))?;
if data_end > (map.len() as u64) || data_end > page_end {
return Err(crate::error::Error::Message(
format!("DataBucket page {index} payload exceeds its page or file")
));
}
headers.push(header);
}
mlock_guard.active = false;
Ok(Self {
path,
id: observed_id,
map,
headers,
memory_locked: policy.lock_memory,
private_file_checked: cfg!(unix) && policy.require_private_file,
})
}
pub fn id(&self) -> &BucketId {
&self.id
}
pub fn path(&self) -> &Path {
&self.path
}
pub fn len(&self) -> usize {
self.map.len()
}
pub fn is_empty(&self) -> bool {
self.map.is_empty()
}
pub fn page_count(&self) -> usize {
self.headers.len()
}
pub fn memory_locked(&self) -> bool {
self.memory_locked
}
pub fn page(&self, index: usize) -> crate::error::Result<AttachedPage<'_>> {
let header = *self
.headers
.get(index)
.ok_or_else(|| crate::error::Error::Message(format!("DataBucket page {index} is absent")))?;
let start = index
.checked_mul(PAGE_SIZE)
.and_then(|base| base.checked_add(GENERAL_HEADER_SIZE))
.ok_or_else(|| crate::error::Error::Message(format!("DataBucket page {index} offset overflow")))?;
let end = start
.checked_add(payload_length(header)?)
.ok_or_else(|| crate::error::Error::Message(format!("DataBucket page {index} payload end overflow")))?;
let data = self
.map
.get(start..end)
.ok_or_else(|| crate::error::Error::Message(format!("DataBucket page {index} slice out of bounds")))?;
Ok(AttachedPage { header, data })
}
pub fn get(&self, link: Link) -> crate::error::Result<&[u8]> {
let page_index = usize::from(link.page_id);
let page = self.page(page_index)?;
let start = link.offset as usize;
let end = start
.checked_add(link.length as usize)
.ok_or_else(|| crate::error::Error::Message("DataBucket Link range overflow".to_string()))?;
if end > page.data.len() {
return Err(crate::error::Error::Message(
format!("DataBucket Link [{start}..{end}] exceeds page {page_index} payload {}",
page.data.len())
));
}
Ok(&page.data[start..end])
}
}
impl Drop for AttachedBucket {
fn drop(&mut self) {
if self.memory_locked {
unsafe {
libc::munlock(self.map.as_ptr().cast(), self.map.len());
}
}
}
}
#[cfg(unix)]
fn open_readonly_nofollow(path: &Path) -> std::io::Result<File> {
use std::os::unix::fs::OpenOptionsExt as _;
std::fs::OpenOptions::new()
.read(true)
.custom_flags(libc::O_NOFOLLOW)
.open(path)
}
#[cfg(not(unix))]
fn open_readonly_nofollow(path: &Path) -> std::io::Result<File> {
let metadata = std::fs::symlink_metadata(path)?;
if metadata.file_type().is_symlink() {
return Err(std::io::Error::new(
std::io::ErrorKind::InvalidInput,
"symbolic links are forbidden for sensitive DataBucket attachments",
));
}
File::open(path)
}
#[derive(Clone, Debug)]
pub struct BucketLease(Arc<AttachedBucket>);
impl Deref for BucketLease {
type Target = AttachedBucket;
fn deref(&self) -> &Self::Target {
&self.0
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct UnloadReport {
pub id: BucketId,
pub removed: bool,
pub outstanding_leases: usize,
}
#[derive(Debug, Default)]
pub struct BucketLoader {
loaded: Mutex<BTreeMap<BucketId, Arc<AttachedBucket>>>,
}
impl BucketLoader {
pub fn new() -> Self {
Self::default()
}
pub fn load(&self, path: impl AsRef<Path>, id: BucketId) -> crate::error::Result<BucketLease> {
self.load_with_policy(path, id, AttachPolicy::default())
}
pub fn load_observed(
&self,
path: impl AsRef<Path>,
policy: AttachPolicy,
) -> crate::error::Result<BucketLease> {
let attached = Arc::new(AttachedBucket::attach_observed(path, policy)?);
let id = attached.id().clone();
let mut loaded = self
.loaded
.lock()
.map_err(|_| crate::error::Error::Message("DataBucket loader registry is poisoned".to_string()))?;
let attached = loaded.entry(id).or_insert(attached).clone();
Self::check_policy(&attached, policy)?;
Ok(BucketLease(attached))
}
pub fn load_with_policy(
&self,
path: impl AsRef<Path>,
id: BucketId,
policy: AttachPolicy,
) -> crate::error::Result<BucketLease> {
if let Some(existing) = self.get(&id)? {
Self::check_policy(&existing.0, policy)?;
return Ok(existing);
}
let candidate = Arc::new(AttachedBucket::attach_with_policy(
path,
id.clone(),
policy,
)?);
let mut loaded = self
.loaded
.lock()
.map_err(|_| crate::error::Error::Message("DataBucket loader registry is poisoned".to_string()))?;
let attached = loaded.entry(id).or_insert(candidate).clone();
Self::check_policy(&attached, policy)?;
Ok(BucketLease(attached))
}
fn check_policy(attached: &AttachedBucket, policy: AttachPolicy) -> crate::error::Result<()> {
if (policy.lock_memory && !attached.memory_locked)
|| (policy.require_private_file && !attached.private_file_checked)
{
return Err(crate::error::Error::Message(
"existing attachment does not satisfy the requested policy".to_string()
));
}
Ok(())
}
pub fn get(&self, id: &BucketId) -> crate::error::Result<Option<BucketLease>> {
let loaded = self
.loaded
.lock()
.map_err(|_| crate::error::Error::Message(format!("DataBucket loader registry is poisoned"))).map_err(|_| crate::error::Error::Message("DataBucket loader registry is poisoned".to_string()))?;
Ok(loaded.get(id).cloned().map(BucketLease))
}
pub fn unload(&self, id: &BucketId) -> crate::error::Result<UnloadReport> {
let mut loaded = self
.loaded
.lock()
.map_err(|_| crate::error::Error::Message("DataBucket loader registry is poisoned".to_string()))?;
let Some(attachment) = loaded.remove(id) else {
return Ok(UnloadReport {
id: id.clone(),
removed: false,
outstanding_leases: 0,
});
};
let outstanding_leases = Arc::strong_count(&attachment).saturating_sub(1);
Ok(UnloadReport {
id: id.clone(),
removed: true,
outstanding_leases,
})
}
pub async fn unload_gracefully<F, Fut>(
&self,
id: &BucketId,
timeout: std::time::Duration,
quiesce: F,
) -> crate::error::Result<UnloadReport>
where
F: FnOnce() -> Fut,
Fut: Future<Output = crate::error::Result<()>>,
{
let Some(target_lease) = self.get(id)? else {
return Ok(UnloadReport {
id: id.clone(),
removed: false,
outstanding_leases: 0,
});
};
let target_arc = target_lease.0;
nagoya::timeout(timeout, quiesce())
.await
.map_err(|_| crate::error::Error::Message(format!("timed out while quiescing indexes for {}", id.as_str())))?;
let mut loaded = self
.loaded
.lock()
.map_err(|_| crate::error::Error::Message("DataBucket loader registry is poisoned".to_string()))?;
match loaded.get(id) {
Some(current) if Arc::ptr_eq(current, &target_arc) => {
let removed = loaded.remove(id).expect("checked Some above");
drop(target_arc);
let outstanding_leases = Arc::strong_count(&removed).saturating_sub(1);
Ok(UnloadReport {
id: id.clone(),
removed: true,
outstanding_leases,
})
}
_ => Ok(UnloadReport {
id: id.clone(),
removed: false,
outstanding_leases: 0,
}),
}
}
pub fn loaded_ids(&self) -> crate::error::Result<Vec<BucketId>> {
let loaded = self
.loaded
.lock()
.map_err(|_| crate::error::Error::Message(format!("DataBucket loader registry is poisoned"))).map_err(|_| crate::error::Error::Message("DataBucket loader registry is poisoned".to_string()))?;
Ok(loaded.keys().cloned().collect())
}
}
fn payload_length(header: GeneralHeader) -> crate::error::Result<usize> {
let length = if header.data_length == 0 {
INNER_PAGE_SIZE
} else {
header.data_length as usize
};
if length > INNER_PAGE_SIZE {
return Err(crate::error::Error::Message(
format!("DataBucket page {} declares {} payload bytes, exceeding {}",
header.page_id,
length,
INNER_PAGE_SIZE)
));
}
Ok(length)
}
#[cfg(test)]
mod tests {
use std::io::Write;
use crate::{GeneralHeader, PageType, Persistable, SpaceId};
use super::*;
fn fixture(payload: &[u8]) -> (tempfile::NamedTempFile, BucketId) {
let mut header = GeneralHeader::new(0.into(), PageType::Data, SpaceId::from(7));
header.data_length = payload.len() as u32;
let mut bytes = vec![0u8; PAGE_SIZE];
bytes[..GENERAL_HEADER_SIZE].copy_from_slice(header.as_bytes().as_ref());
bytes[GENERAL_HEADER_SIZE..GENERAL_HEADER_SIZE + payload.len()].copy_from_slice(payload);
let mut file = tempfile::NamedTempFile::new().unwrap();
file.write_all(&bytes).unwrap();
file.as_file().sync_all().unwrap();
(file, BucketId::of_bytes(&bytes))
}
#[test]
fn attachment_exposes_page_and_link_from_the_mapping() {
let (file, id) = fixture(b"typed-node-data");
let bucket = AttachedBucket::attach(file.path(), id).unwrap();
assert_eq!(bucket.page_count(), 1);
assert_eq!(bucket.page(0).unwrap().data, b"typed-node-data");
assert_eq!(
bucket
.get(Link {
page_id: 0.into(),
offset: 6,
length: 4,
})
.unwrap(),
b"node"
);
}
#[test]
fn identity_and_page_corruption_fail_closed() {
let (mut file, id) = fixture(b"evidence");
let wrong = BucketId::of_bytes(b"other");
assert!(AttachedBucket::attach(file.path(), wrong).is_err());
file.as_file_mut().write_all(&[0xff]).unwrap();
file.as_file_mut().sync_all().unwrap();
assert!(AttachedBucket::attach(file.path(), id).is_err());
}
#[cfg(unix)]
#[test]
fn sensitive_attach_rejects_public_permissions_and_symlinks() {
use std::os::unix::fs::{symlink, PermissionsExt as _};
let (file, id) = fixture(b"secret");
std::fs::set_permissions(file.path(), std::fs::Permissions::from_mode(0o644)).unwrap();
assert!(AttachedBucket::attach(file.path(), id.clone()).is_err());
std::fs::set_permissions(file.path(), std::fs::Permissions::from_mode(0o600)).unwrap();
let link_dir = tempfile::tempdir().unwrap();
let link = link_dir.path().join("bucket.db");
symlink(file.path(), &link).unwrap();
assert!(AttachedBucket::attach(link, id).is_err());
}
#[test]
fn unload_removes_discovery_but_preserves_outstanding_leases() {
let (file, id) = fixture(b"resident");
let loader = BucketLoader::new();
let lease = loader.load(file.path(), id.clone()).unwrap();
let second = loader.get(&id).unwrap().unwrap();
assert_eq!(loader.loaded_ids().unwrap(), vec![id.clone()]);
let report = loader.unload(&id).unwrap();
assert!(report.removed);
assert_eq!(report.outstanding_leases, 2);
assert!(loader.get(&id).unwrap().is_none());
assert_eq!(lease.page(0).unwrap().data, b"resident");
assert_eq!(second.page(0).unwrap().data, b"resident");
}
#[test]
fn repeated_load_reuses_the_same_attachment_identity() {
let (file, id) = fixture(b"shared");
let loader = BucketLoader::new();
let first = loader.load(file.path(), id.clone()).unwrap();
let second = loader.load(file.path(), id).unwrap();
assert!(Arc::ptr_eq(&first.0, &second.0));
}
#[test]
fn graceful_unload_waits_for_the_index_owner() {
nagoya::block_on(async {
let (file, id) = fixture(b"durable");
let loader = BucketLoader::new();
let lease = loader.load(file.path(), id.clone()).unwrap();
let flushed = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let observed = flushed.clone();
let report = loader
.unload_gracefully(&id, std::time::Duration::from_secs(1), || async move {
observed.store(true, std::sync::atomic::Ordering::SeqCst);
Ok(())
})
.await
.unwrap();
assert!(flushed.load(std::sync::atomic::Ordering::SeqCst));
assert!(report.removed);
assert!(loader.get(&id).unwrap().is_none());
assert_eq!(lease.page(0).unwrap().data, b"durable");
});
}
#[test]
fn failed_or_timed_out_quiescence_keeps_the_bucket_loaded() {
nagoya::block_on(async {
let (file, id) = fixture(b"no-wal");
let loader = BucketLoader::new();
loader.load(file.path(), id.clone()).unwrap();
let failed = loader
.unload_gracefully(&id, std::time::Duration::from_secs(1), || async {
Err(crate::error::Error::Message("flush failed".to_string()))
})
.await;
assert!(failed.is_err());
assert!(loader.get(&id).unwrap().is_some());
let timed_out = loader
.unload_gracefully(&id, std::time::Duration::from_millis(1), || async {
nagoya::sleep(std::time::Duration::from_secs(1)).await;
Ok(())
})
.await;
assert!(timed_out.is_err());
assert!(loader.get(&id).unwrap().is_some());
});
}
}