armdb 0.15.0

sharded bitcask key-value storage optimized for NVMe
Documentation
//! Durable append-only key-range salts for one encrypted data file.

use std::fs::{File, OpenOptions};
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};

use crate::error::{DbError, DbResult};

const HEADER: &[u8; 8] = b"AKY1\x01\0\0\0";
const RECORD_LEN: usize = 28;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct KeyRecord {
    pub first_page: u64,
    pub salt: [u8; 16],
}

impl KeyRecord {
    fn encode(self) -> [u8; RECORD_LEN] {
        let mut bytes = [0; RECORD_LEN];
        bytes[..8].copy_from_slice(&self.first_page.to_le_bytes());
        bytes[8..24].copy_from_slice(&self.salt);
        let crc = crc32fast::hash(&bytes[..24]);
        bytes[24..].copy_from_slice(&crc.to_le_bytes());
        bytes
    }
}

/// A key sidecar with a remembered valid prefix and a fail-closed append handle.
pub(crate) struct KeyFile {
    file: File,
    valid_offset: u64,
    poisoned: bool,
}

impl KeyFile {
    /// Write and sync a new sidecar. The caller must sync its directory.
    pub(crate) fn create(path: &Path, first: KeyRecord) -> DbResult<Self> {
        let mut file = File::create(path)?;
        file.write_all(HEADER)?;
        file.write_all(&first.encode())?;
        file.sync_all()?;
        Ok(Self {
            file,
            valid_offset: (HEADER.len() + RECORD_LEN) as u64,
            poisoned: false,
        })
    }

    /// Open a sidecar for appending, ignoring only a short or CRC-invalid
    /// final record. Opening does not repair or otherwise mutate the file.
    pub(crate) fn open(path: &Path) -> DbResult<(Self, Vec<KeyRecord>)> {
        let mut file = OpenOptions::new().read(true).write(true).open(path)?;
        let mut bytes = Vec::new();
        file.read_to_end(&mut bytes)?;
        let (records, valid_offset) = parse(&bytes)?;
        Ok((
            Self {
                file,
                valid_offset,
                poisoned: false,
            },
            records,
        ))
    }

    /// Durably repair a torn tail, then append and sync the new key-range record.
    /// Any I/O failure poisons this handle until it is reopened.
    pub(crate) fn append(&mut self, record: KeyRecord) -> DbResult<()> {
        if self.poisoned {
            return Err(DbError::Internal("key file poisoned"));
        }
        self.poisoned = true;
        self.file.set_len(self.valid_offset)?;
        self.file.sync_all()?;
        self.file.seek(SeekFrom::Start(self.valid_offset))?;
        self.file.write_all(&record.encode())?;
        self.file.sync_all()?;
        self.valid_offset += RECORD_LEN as u64;
        self.poisoned = false;
        Ok(())
    }

    #[cfg(test)]
    pub(crate) fn force_read_only_for_test(&mut self, path: &Path) {
        self.file = File::open(path).expect("read-only key sidecar");
    }

    pub(crate) fn is_poisoned(&self) -> bool {
        self.poisoned
    }
}

/// Parse a sidecar image into its records and the end of its valid prefix.
fn parse(bytes: &[u8]) -> DbResult<(Vec<KeyRecord>, u64)> {
    if bytes.len() < HEADER.len() || &bytes[..HEADER.len()] != HEADER {
        return Err(DbError::FormatMismatch("invalid .keys header".into()));
    }
    let mut records = Vec::new();
    let mut valid_offset = HEADER.len();
    for chunk in bytes[HEADER.len()..].chunks(RECORD_LEN) {
        if chunk.len() < RECORD_LEN {
            break;
        }
        let crc = u32::from_le_bytes(chunk[24..28].try_into().expect("record CRC"));
        if crc32fast::hash(&chunk[..24]) != crc {
            if valid_offset + RECORD_LEN != bytes.len() {
                return Err(DbError::FormatMismatch(
                    "torn .keys record before file end".into(),
                ));
            }
            break;
        }
        records.push(KeyRecord {
            first_page: u64::from_le_bytes(chunk[..8].try_into().expect("record boundary")),
            salt: chunk[8..24].try_into().expect("record salt"),
        });
        valid_offset += RECORD_LEN;
    }
    Ok((records, valid_offset as u64))
}

/// Which handle `load` keeps: readers never need write access to a sidecar.
enum Access {
    Read,
    Append,
}

fn load(
    domain: &crate::crypto::KeyDomain,
    data_path: &Path,
    access: Access,
) -> DbResult<(
    Option<KeyFile>,
    Option<std::sync::Arc<crate::crypto::FileKeys>>,
)> {
    let path = keys_path_for_data(data_path);
    let len = std::fs::metadata(data_path)?.len();
    if !path.exists() {
        if len == 0 {
            return Ok((None, None));
        }
        return Err(DbError::FormatMismatch(format!(
            "key ranges missing for {}",
            data_path.display()
        )));
    }
    let loaded = match access {
        Access::Read => std::fs::read(&path)
            .map_err(DbError::from)
            .and_then(|bytes| parse(&bytes))
            .map(|(records, _)| (None, records)),
        Access::Append => KeyFile::open(&path).map(|(file, records)| (Some(file), records)),
    };
    let (file, records) = match loaded {
        Ok(loaded) => loaded,
        // No page was sealed into an empty file, so a sidecar torn while it was
        // being created is as good as absent: the next write recreates it.
        Err(DbError::FormatMismatch(_)) if len == 0 => return Ok((None, None)),
        Err(error) => return Err(error),
    };
    let keys = crate::crypto::FileKeys::from_records(domain, &records)?;
    if len > 0 && keys.cipher_for(0).is_err() {
        return Err(DbError::FormatMismatch(format!(
            "no key range covers page zero in {}",
            path.display()
        )));
    }
    Ok((file, Some(std::sync::Arc::new(keys))))
}

/// Load and validate a file's range map read-only, without changing any file.
pub(crate) fn load_file_keys(
    domain: &crate::crypto::KeyDomain,
    data_path: &Path,
) -> DbResult<Option<std::sync::Arc<crate::crypto::FileKeys>>> {
    load(domain, data_path, Access::Read).map(|(_, keys)| keys)
}

/// Load the active file's range map together with its append handle.
pub(crate) fn load_active_file_keys(
    domain: &crate::crypto::KeyDomain,
    data_path: &Path,
) -> DbResult<(
    Option<KeyFile>,
    Option<std::sync::Arc<crate::crypto::FileKeys>>,
)> {
    load(domain, data_path, Access::Append)
}

/// Compute the sidecar path, preserving the `.tmp` suffix of staged data files.
pub(crate) fn keys_path_for_data(data_path: &Path) -> PathBuf {
    if data_path
        .extension()
        .is_some_and(|extension| extension == "tmp")
    {
        data_path.with_extension("").with_extension("keys.tmp")
    } else {
        data_path.with_extension("keys")
    }
}

#[cfg(test)]
#[cfg(feature = "encryption")]
mod tests {
    use super::*;
    use std::io::Write;
    use tempfile::tempdir;

    fn rec(first_page: u64) -> KeyRecord {
        KeyRecord {
            first_page,
            salt: [first_page as u8; 16],
        }
    }

    #[test]
    fn keyrange_keys_file_round_trips() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("000001.keys");
        let mut keys = KeyFile::create(&path, rec(0)).unwrap();
        keys.append(rec(10)).unwrap();
        drop(keys);
        let (_, records) = KeyFile::open(&path).unwrap();
        assert_eq!(records, vec![rec(0), rec(10)]);
        let bytes = std::fs::read(&path).unwrap();
        assert_eq!(&bytes[..8], b"AKY1\x01\0\0\0");
        assert_eq!(keys_path_for_data(&dir.path().join("000001.data")), path);
        assert_eq!(
            keys_path_for_data(&dir.path().join("000001.data.tmp")),
            dir.path().join("000001.keys.tmp")
        );
    }

    #[test]
    fn keyrange_torn_short_tail_is_ignored_then_repaired_before_append() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("000001.keys");
        let mut keys = KeyFile::create(&path, rec(0)).unwrap();
        keys.append(rec(10)).unwrap();
        drop(keys);
        std::fs::OpenOptions::new()
            .append(true)
            .open(&path)
            .unwrap()
            .write_all(&[0xff; 13])
            .unwrap();
        let (mut keys, records) = KeyFile::open(&path).unwrap();
        assert_eq!(records, vec![rec(0), rec(10)]);
        assert_eq!(std::fs::metadata(&path).unwrap().len(), 8 + 2 * 28 + 13);
        keys.append(rec(20)).unwrap();
        assert_eq!(
            KeyFile::open(&path).unwrap().1,
            vec![rec(0), rec(10), rec(20)]
        );
        assert_eq!(std::fs::metadata(&path).unwrap().len(), 8 + 3 * 28);
    }

    #[test]
    fn keyrange_crc_bad_full_length_tail_is_ignored_then_repaired() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("000001.keys");
        drop(KeyFile::create(&path, rec(0)).unwrap());
        std::fs::OpenOptions::new()
            .append(true)
            .open(&path)
            .unwrap()
            .write_all(&[0xff; 28])
            .unwrap();
        let (mut keys, records) = KeyFile::open(&path).unwrap();
        assert_eq!(records, vec![rec(0)]);
        keys.append(rec(10)).unwrap();
        assert_eq!(KeyFile::open(&path).unwrap().1, vec![rec(0), rec(10)]);
        assert_eq!(std::fs::metadata(&path).unwrap().len(), 8 + 2 * 28);
    }

    #[test]
    fn keyrange_torn_record_not_last_fails_open() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("000001.keys");
        let mut keys = KeyFile::create(&path, rec(0)).unwrap();
        keys.append(rec(10)).unwrap();
        keys.append(rec(20)).unwrap();
        drop(keys);
        let mut bytes = std::fs::read(&path).unwrap();
        bytes[8 + 28 + 24] ^= 1;
        std::fs::write(&path, bytes).unwrap();
        assert!(matches!(
            KeyFile::open(&path),
            Err(DbError::FormatMismatch(_))
        ));
    }

    #[test]
    fn keyrange_failed_append_poisons_the_handle() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("000001.keys");
        drop(KeyFile::create(&path, rec(0)).unwrap());
        let (mut keys, _) = KeyFile::open(&path).unwrap();
        // An actual read-only FD deterministically rejects set_len/write, including as root.
        keys.file = std::fs::File::open(&path).unwrap();
        assert!(matches!(keys.append(rec(10)), Err(DbError::Io(_))));
        assert!(keys.is_poisoned());
        assert!(matches!(
            keys.append(rec(10)),
            Err(DbError::Internal("key file poisoned"))
        ));
        assert_eq!(KeyFile::open(&path).unwrap().1, vec![rec(0)]);
    }

    #[test]
    fn keyrange_bad_and_short_headers_fail_open() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("000001.keys");
        for header in [
            b"AKY1".as_slice(),
            b"AKY1\x02\0\0\0",
            b"AKY1\x01\0\x01\0",
            b"bad!\x01\0\0\0",
        ] {
            std::fs::write(&path, header).unwrap();
            assert!(matches!(
                KeyFile::open(&path),
                Err(DbError::FormatMismatch(_))
            ));
        }
    }
}