use std::fs::File;
use std::io::BufWriter;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use xxhash_rust::xxh3::{Xxh3, xxh3_64};
use super::block::{BlockBuilder, parse_entry};
use super::filter::build_sorted_filter;
use super::filter::{MAX_PARTITION_BITS, PARTITION_TARGET_KEYS, PartitionedFilterBuilder};
use super::fs::SegFs;
use super::hash::{cmp_hk, key_hash, partition_bits_for};
use super::key_index::{KeyRange, SeparatorIndexBuilder, shortest_separator};
use super::manifest::{Location, SegRecord, SegState};
use super::sidecar::{
BlockIndexBuilder, FORMAT_VERSION, Properties, SDAT_MAGIC, SECTION_BLOCK_INDEX, SECTION_FILTER,
SECTION_PROPERTIES, SegHeader, encode_sidecar_paged,
};
use super::sidecar::{
OrderKind, SECTION_KEY_RANGE, SECTION_PREFIX_FILTER, SECTION_SEPARATOR_INDEX,
};
use crate::error::{DbError, DbResult};
pub(crate) const SEG_DIR: &str = "seg";
const TMP_SUFFIX: &str = ".tmp";
const WRITE_BUFFER: usize = 1 << 20;
pub(crate) fn sdat_name(segment_id: u64, version: u32) -> String {
format!("{segment_id:016x}-{version:04x}.sdat")
}
pub(crate) fn sidx_name(segment_id: u64, version: u32) -> String {
format!("{segment_id:016x}-{version:04x}.sidx")
}
fn tmp_of(path: &Path) -> PathBuf {
let mut name = path.as_os_str().to_owned();
name.push(TMP_SUFFIX);
PathBuf::from(name)
}
#[derive(Debug, Clone, Copy)]
pub(crate) struct SegTimes {
pub opened_at_ms: u64,
pub frozen_at_ms: u64,
pub sealed_at_ms: u64,
}
#[derive(Debug, Clone)]
pub(crate) struct SealedFiles {
pub header: SegHeader,
pub sdat_len: u64,
pub sdat_checksum: u64,
pub sidx_len: u64,
pub sidx_checksum: u64,
pub props: Properties,
}
impl SealedFiles {
pub(crate) fn into_record(self) -> SegRecord {
SegRecord {
segment_id: self.header.segment_id,
version: self.header.version,
state: SegState::Sealed,
order: self.header.order,
format_version: FORMAT_VERSION,
min_gsn: self.props.min_gsn,
max_gsn: self.props.max_gsn,
entries: self.props.entries,
tombstones: self.props.tombstones,
opened_at_ms: self.props.opened_at_ms,
frozen_at_ms: self.props.frozen_at_ms,
sealed_at_ms: self.props.sealed_at_ms,
sdat_len: self.sdat_len,
sdat_checksum: self.sdat_checksum,
sidx_len: self.sidx_len,
sidx_checksum: self.sidx_checksum,
typ_hash: self.props.typ_hash,
value_version: self.props.value_version,
location: Location::Local,
}
}
}
pub(crate) struct SegmentWriter {
fs: Arc<dyn SegFs>,
seg_dir: PathBuf,
header: SegHeader,
sdat: PathBuf,
sidx: PathBuf,
out: Option<BufWriter<File>>,
hasher: Xxh3,
block: BlockBuilder,
index: BlockIndexBuilder,
filter: PartitionedFilterBuilder,
key_index: Option<SeparatorIndexBuilder>,
key_hashes: Vec<u64>,
prefix_hashes: Vec<(usize, Vec<u64>)>,
min_key: Vec<u8>,
block_separator: Vec<u8>,
has_last: bool,
last_h: u64,
last_key: Vec<u8>,
entries: u64,
tombstones: u64,
min_gsn: u64,
max_gsn: u64,
min_h: u64,
max_h: u64,
raw_bytes: u64,
owns_sdat_tmp: bool,
owns_sidx_tmp: bool,
poisoned: bool,
renamed_sdat: bool,
renamed_sidx: bool,
finished: bool,
#[cfg(test)]
trust_caller_hash: bool,
}
impl SegmentWriter {
#[cfg(test)]
pub(crate) fn force_filter_bits(&mut self, bits: u8) {
assert_eq!(self.entries, 0);
self.filter = PartitionedFilterBuilder::new(bits);
}
pub(crate) fn create(
fs: Arc<dyn SegFs>,
seg_dir: &Path,
header: SegHeader,
expected_keys: u64,
) -> DbResult<Self> {
if header.order != OrderKind::ByHash {
return Err(DbError::Internal(
"segment writer: hash writer requires ByHash",
));
}
Self::create_inner(fs, seg_dir, header, expected_keys)
}
fn create_inner(
fs: Arc<dyn SegFs>,
seg_dir: &Path,
header: SegHeader,
expected_keys: u64,
) -> DbResult<Self> {
let sdat = seg_dir.join(sdat_name(header.segment_id, header.version));
let sidx = seg_dir.join(sidx_name(header.segment_id, header.version));
if sdat.try_exists()? || sidx.try_exists()? {
return Err(DbError::Internal(
"segment writer: target file already exists",
));
}
let file = fs.create_new(&tmp_of(&sdat))?;
let out = BufWriter::with_capacity(WRITE_BUFFER, file);
let mut hasher = Xxh3::new();
let header_bytes = header.encode(SDAT_MAGIC);
let bits = partition_bits_for(expected_keys, PARTITION_TARGET_KEYS, MAX_PARTITION_BITS);
let mut writer = Self {
fs,
seg_dir: seg_dir.to_path_buf(),
header,
sdat,
sidx,
out: None,
hasher: Xxh3::new(),
block: BlockBuilder::new(header.block_size),
index: BlockIndexBuilder::new(),
filter: PartitionedFilterBuilder::new(bits),
key_index: None,
key_hashes: Vec::new(),
prefix_hashes: Vec::new(),
min_key: Vec::new(),
block_separator: Vec::new(),
has_last: false,
last_h: 0,
last_key: Vec::with_capacity(header.key_len as usize),
entries: 0,
tombstones: 0,
min_gsn: u64::MAX,
max_gsn: 0,
min_h: 0,
max_h: 0,
raw_bytes: 0,
owns_sdat_tmp: true,
owns_sidx_tmp: false,
poisoned: false,
renamed_sdat: false,
renamed_sidx: false,
finished: false,
#[cfg(test)]
trust_caller_hash: false,
};
writer.out = Some(out);
let output = writer
.out
.as_mut()
.ok_or(DbError::Internal("segment writer: output file missing"))?;
writer
.fs
.write_all(output, &tmp_of(&writer.sdat), &header_bytes)?;
hasher.update(&header_bytes);
writer.hasher = hasher;
Ok(writer)
}
pub(crate) fn create_key(
fs: Arc<dyn SegFs>,
seg_dir: &Path,
header: SegHeader,
prefix_filters: &[usize],
expected_keys: u64,
) -> DbResult<Self> {
if header.order != OrderKind::ByKey
|| prefix_filters
.iter()
.any(|&n| n == 0 || n >= header.key_len as usize)
|| prefix_filters
.iter()
.enumerate()
.any(|(i, n)| prefix_filters[..i].contains(n))
{
return Err(DbError::Internal(
"segment writer: invalid key order or prefix lengths",
));
}
let mut writer = Self::create_inner(fs, seg_dir, header, expected_keys)?;
writer.key_index = Some(SeparatorIndexBuilder::new());
writer.key_hashes = Vec::with_capacity(usize::try_from(expected_keys).unwrap_or(0));
writer.prefix_hashes = prefix_filters.iter().map(|&n| (n, Vec::new())).collect();
Ok(writer)
}
pub(crate) fn entries(&self) -> u64 {
self.entries
}
#[cfg(test)]
pub(crate) fn trust_caller_hash(&mut self) {
self.trust_caller_hash = true;
}
pub(crate) fn push(&mut self, h: u64, entry: &[u8]) -> DbResult<()> {
if self.poisoned {
return Err(DbError::Internal("segment writer: previous write failed"));
}
let pushed = self.push_entry(h, entry);
if pushed.is_err() {
self.poisoned = true;
}
pushed
}
fn push_entry(&mut self, h: u64, entry: &[u8]) -> DbResult<()> {
let parsed = parse_entry(entry, self.header.key_len as usize).map_err(|fault| {
tracing::error!(?fault, "segment writer refused a malformed entry");
DbError::Internal("segment writer: malformed entry")
})?;
if parsed.raw.len() != entry.len() {
return Err(DbError::Internal(
"segment writer: entry length does not match its header",
));
}
parsed.verify_crc().map_err(|fault| {
tracing::error!(?fault, "segment writer refused an entry");
DbError::Internal("segment writer: entry fails its CRC")
})?;
#[cfg(test)]
let check_hash = !self.trust_caller_hash;
#[cfg(not(test))]
let check_hash = true;
if check_hash && key_hash(parsed.key, self.header.seed) != h {
return Err(DbError::Internal(
"segment writer: hash does not match the entry key",
));
}
let key = parsed.key;
let by_key = self.header.order == OrderKind::ByKey;
if self.has_last
&& if by_key {
self.last_key.as_slice() >= key
} else {
cmp_hk(self.last_h, &self.last_key, h, key).is_ge()
}
{
return Err(DbError::Internal(
"segment writer: entries are out of order",
));
}
if !(if by_key {
self.block.fits_key(entry.len())
} else {
self.block.fits(h, entry.len())
}) {
self.flush_block()?;
if by_key {
self.block_separator = shortest_separator(&self.last_key, key);
}
}
if by_key {
self.key_hashes.push(h);
for (len, hashes) in &mut self.prefix_hashes {
let ph = key_hash(&key[..*len], self.header.seed);
if hashes.last() != Some(&ph) {
hashes.push(ph);
}
}
} else {
self.filter.push(h).map_err(|e| {
tracing::error!(error = ?e, "segment filter refused a hash");
DbError::Internal("segment writer: filter refused a hash")
})?;
}
self.block.push(h, entry).map_err(|e| {
tracing::error!(error = ?e, "segment block refused an entry");
DbError::Internal("segment writer: block refused an entry")
})?;
if !self.has_last {
if by_key {
self.min_key.extend_from_slice(key);
} else {
self.min_h = h;
}
}
if !by_key {
self.max_h = h;
}
self.has_last = true;
self.last_h = h;
self.last_key.clear();
self.last_key.extend_from_slice(key);
let sequence = parsed.sequence();
self.min_gsn = self.min_gsn.min(sequence);
self.max_gsn = self.max_gsn.max(sequence);
self.entries += 1;
if parsed.is_tombstone() {
self.tombstones += 1;
}
Ok(())
}
fn flush_block(&mut self) -> DbResult<()> {
if self.poisoned {
return Err(DbError::Internal("segment writer: previous write failed"));
}
if self.block.is_empty() {
return Ok(());
}
let block = self.block.finish();
let block_len = u32::try_from(block.len()).map_err(|_| {
self.poisoned = true;
DbError::Internal("segment writer: block length exceeds u32")
})?;
let sdat_tmp = tmp_of(&self.sdat);
let out = self
.out
.as_mut()
.expect("the data file is open until finish");
let written = self
.fs
.write_all(out, &sdat_tmp, &block.header)
.and_then(|()| self.fs.write_all(out, &sdat_tmp, &block.payload));
if let Err(e) = written {
self.poisoned = true;
return Err(e.into());
}
super::failpoint!(SEGMENT_BEING_WRITTEN);
if let Some(index) = &mut self.key_index {
index
.push(&self.block_separator, block_len, block.entries)
.map_err(|_| {
self.poisoned = true;
DbError::Internal("segment writer: invalid key index")
})?;
} else {
self.index.push(block.first_h, block_len, block.entries);
}
self.raw_bytes += block.payload.len() as u64;
self.hasher.update(&block.header);
self.hasher.update(&block.payload);
Ok(())
}
pub(crate) fn finish(
mut self,
times: SegTimes,
value_version: u16,
typ_hash: u64,
) -> DbResult<SealedFiles> {
if self.poisoned {
return Err(DbError::Internal("segment writer: previous write failed"));
}
if self.entries == 0 {
return Err(DbError::Internal("segment writer: no entries"));
}
self.flush_block()?;
let sdat_tmp = tmp_of(&self.sdat);
let sidx_tmp = tmp_of(&self.sidx);
let out = self.out.take().expect("the data file is open until finish");
let file = out.into_inner().map_err(|e| e.into_error())?;
self.fs.sync_file(&file, &sdat_tmp)?;
drop(file);
let props = Properties {
entries: self.entries,
tombstones: self.tombstones,
min_gsn: self.min_gsn,
max_gsn: self.max_gsn,
min_h: self.min_h,
max_h: self.max_h,
raw_bytes: self.raw_bytes,
opened_at_ms: times.opened_at_ms,
frozen_at_ms: times.frozen_at_ms,
sealed_at_ms: times.sealed_at_ms,
typ_hash,
value_version,
writer: format!("armdb {}", env!("CARGO_PKG_VERSION")),
};
let filter_error = |e| {
tracing::error!(error = ?e, "segment filter construction failed");
DbError::Internal("segment writer: filter construction failed")
};
let (sdat_len, sections) = if let Some(index) = self.key_index.take() {
let sdat_len = index.end_offset();
let wire = index
.finish()
.map_err(|_| DbError::Internal("segment writer: invalid key index"))?;
let mut sections = vec![
(SECTION_SEPARATOR_INDEX, wire),
(
SECTION_KEY_RANGE,
KeyRange {
min: self.min_key.clone(),
max: self.last_key.clone(),
}
.encode(),
),
(
SECTION_FILTER,
build_sorted_filter(&mut self.key_hashes).map_err(filter_error)?,
),
(SECTION_PROPERTIES, props.encode()),
];
for (len, hashes) in &mut self.prefix_hashes {
let mut section = (*len as u16).to_le_bytes().to_vec();
section.extend_from_slice(&[0; 6]);
section.extend(build_sorted_filter(hashes).map_err(filter_error)?);
sections.push((SECTION_PREFIX_FILTER, section));
}
(sdat_len, sections)
} else {
let index = std::mem::replace(&mut self.index, BlockIndexBuilder::new());
let filter = std::mem::replace(&mut self.filter, PartitionedFilterBuilder::new(0));
(
index.end_offset(),
vec![
(SECTION_BLOCK_INDEX, index.finish()),
(SECTION_FILTER, filter.finish().map_err(filter_error)?),
(SECTION_PROPERTIES, props.encode()),
],
)
};
let sidecar = encode_sidecar_paged(&self.header, §ions)?;
let mut file = self.fs.create_new(&sidx_tmp)?;
self.owns_sidx_tmp = true;
self.fs.write_all(&mut file, &sidx_tmp, &sidecar)?;
self.fs.sync_file(&file, &sidx_tmp)?;
drop(file);
self.fs.rename(&sdat_tmp, &self.sdat)?;
self.owns_sdat_tmp = false;
self.renamed_sdat = true;
self.fs.rename(&sidx_tmp, &self.sidx)?;
self.owns_sidx_tmp = false;
self.renamed_sidx = true;
self.fs.sync_dir(&self.seg_dir)?;
super::failpoint!(SEGMENT_FILES_RENAMED);
self.finished = true;
Ok(SealedFiles {
header: self.header,
sdat_len,
sdat_checksum: self.hasher.digest(),
sidx_len: sidecar.len() as u64,
sidx_checksum: xxh3_64(&sidecar),
props,
})
}
}
impl Drop for SegmentWriter {
fn drop(&mut self) {
if self.finished {
return;
}
self.out = None;
let mut paths = Vec::new();
if self.owns_sdat_tmp {
paths.push(tmp_of(&self.sdat));
}
if self.owns_sidx_tmp {
paths.push(tmp_of(&self.sidx));
}
if self.renamed_sdat {
paths.push(self.sdat.clone());
}
if self.renamed_sidx {
paths.push(self.sidx.clone());
}
for path in paths {
if let Err(e) = self.fs.remove_file(&path) {
tracing::warn!(error = %e, path = %path.display(), "could not remove an unfinished segment file");
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::entry::EntryHeader;
use crate::seg::block::{Found, decode_block, find_in_block};
use crate::seg::fs::{FsOpKind, TraceFs, real};
use crate::seg::sidecar::Sidecar;
use crate::seg::testkit::{self, TestEntry};
use xxhash_rust::xxh3::xxh3_64;
const ENTRY_HEADER_LEN: usize = size_of::<EntryHeader>();
fn dir_is_empty(dir: &Path) -> bool {
std::fs::read_dir(dir).unwrap().next().is_none()
}
fn write_all(writer: &mut SegmentWriter, entries: &[TestEntry]) {
for e in entries {
writer.push(e.h, &e.bytes()).unwrap();
}
}
#[test]
fn a_sealed_sidecar_carries_a_consistent_page_index() {
use crate::seg::{page_index::PageIndex, sidecar::*, testkit};
let dir = tempfile::tempdir().unwrap();
for rec in [
testkit::write_segment(
crate::seg::fs::real(),
dir.path(),
1,
&testkit::entries(3_000, 1),
),
testkit::write_key_segment(dir.path(), &testkit::key_entries()),
] {
let bytes =
std::fs::read(dir.path().join(sidx_name(rec.segment_id, rec.version))).unwrap();
let footer_at = bytes.len() - SIDX_FOOTER_LEN;
let (at, count, crc) = parse_footer(&bytes[footer_at..], bytes.len() as u64).unwrap();
let records = parse_table(&bytes[at as usize..footer_at], count, crc, at).unwrap();
let record = records
.iter()
.find(|r| r.kind == SECTION_PAGE_INDEX)
.expect("sealed segment must carry PAGE_INDEX");
let header = SegHeader::decode(&bytes, SIDX_MAGIC).unwrap();
let body = &bytes[record.offset as usize..(record.offset + record.len) as usize];
assert_eq!(
PageIndex::decode(body, &records, &header).unwrap(),
PageIndex::derive(&bytes, &records, &header).unwrap()
);
assert!(Sidecar::parse(&bytes).unwrap().page_index.is_some());
}
}
#[test]
fn by_key_one_entry_and_failed_finish_preserve_writer_ownership() {
for fault in [
None,
Some((FsOpKind::WriteAll, ".sidx.tmp")),
Some((FsOpKind::Rename, ".sidx")),
Some((FsOpKind::SyncDir, "")),
] {
let dir = tempfile::tempdir().unwrap();
let fs = TraceFs::new();
let mut header = testkit::header(44);
header.order = OrderKind::ByKey;
let entry = &testkit::key_entries()[99];
let mut writer =
SegmentWriter::create_key(fs.clone(), dir.path(), header, &[8], 1).unwrap();
writer.push(entry.h, &entry.bytes()).unwrap();
if let Some((op, suffix)) = fault {
fs.fail_on(op, suffix, 0);
}
let result = writer.finish(testkit::times(), 0, 0);
if fault.is_some() {
assert!(result.is_err());
assert!(dir_is_empty(dir.path()));
} else {
let record = result.unwrap().into_record();
let segment = crate::seg::segment::Segment::open(
real(),
dir.path(),
&record,
32,
header.seed,
&std::sync::Arc::new(crate::seg::core::SegShared::new()),
)
.unwrap();
let mut report = crate::seg::verify::VerifyReport::default();
crate::seg::verify::verify_segment(&segment, &mut report).unwrap();
assert!(report.is_clean(), "{:?}", report.problems);
assert_eq!(record.tombstones, 1);
assert_eq!(segment.key_range().unwrap().min, entry.key);
assert_eq!(segment.key_range().unwrap().max, entry.key);
}
}
}
#[test]
fn by_key_refused_order_poisons_and_cleans_up() {
for duplicate in [true, false] {
let dir = tempfile::tempdir().unwrap();
let mut header = testkit::header(42);
header.order = OrderKind::ByKey;
let entries = testkit::key_entries();
let mut writer =
SegmentWriter::create_key(real(), dir.path(), header, &[], 100).unwrap();
writer.push(entries[1].h, &entries[1].bytes()).unwrap();
let bad = &entries[if duplicate { 1 } else { 0 }];
assert!(writer.push(bad.h, &bad.bytes()).is_err());
assert!(writer.push(entries[2].h, &entries[2].bytes()).is_err());
assert!(writer.finish(testkit::times(), 0, 0).is_err());
assert!(dir_is_empty(dir.path()));
}
}
#[test]
fn by_key_refuses_a_prefix_as_long_as_the_key() {
let dir = tempfile::tempdir().unwrap();
let mut header = testkit::header(44);
header.order = OrderKind::ByKey;
let n = header.key_len as usize;
for bad in [vec![0], vec![n], vec![n + 1], vec![4, 4]] {
assert!(SegmentWriter::create_key(real(), dir.path(), header, &bad, 100).is_err());
}
assert!(SegmentWriter::create_key(real(), dir.path(), header, &[n - 1], 100).is_ok());
}
#[test]
fn by_key_colliding_hashes_split_by_size_and_deduplicate() {
let dir = tempfile::tempdir().unwrap();
let mut header = testkit::header(43);
header.order = OrderKind::ByKey;
header.block_size = 128;
let entries = testkit::key_entries();
let mut writer = SegmentWriter::create_key(real(), dir.path(), header, &[4], 100).unwrap();
writer.trust_caller_hash();
for entry in &entries {
writer.push(7, &entry.bytes()).unwrap();
}
writer.finish(testkit::times(), 0, 0).unwrap();
let sidecar =
Sidecar::parse(&std::fs::read(dir.path().join(sidx_name(43, 1))).unwrap()).unwrap();
let crate::seg::key_index::SegmentIndex::Key(index) = sidecar.index else {
panic!("expected key index");
};
assert_eq!(index.len(), 100);
assert_eq!(sidecar.filter.keys(), 1);
assert!(sidecar.filter.may_contain(7));
assert_eq!(sidecar.prefix_filters[0].1.keys(), 1);
}
#[test]
fn by_key_seal_stream_is_strictly_ordered() {
let dir = tempfile::tempdir().unwrap();
let mut header = testkit::header(41);
header.order = super::super::sidecar::OrderKind::ByKey;
header.block_size = 256;
let entries: Vec<_> = (0..100)
.map(|n| {
let key = testkit::ordered_key(n);
TestEntry {
h: key_hash(&key, header.seed),
key,
value: Some(vec![42; if n == 50 { 1024 } else { 80 }]),
gsn: n + 1,
}
})
.collect();
let mut writer = SegmentWriter::create_key(real(), dir.path(), header, &[8], 100).unwrap();
write_all(&mut writer, &entries);
let files = writer.finish(testkit::times(), 0, 0).unwrap();
assert_eq!((files.props.min_h, files.props.max_h), (0, 0));
let segment = crate::seg::segment::Segment::open(
real(),
dir.path(),
&files.into_record(),
32,
header.seed,
&std::sync::Arc::new(crate::seg::core::SegShared::new()),
)
.unwrap();
let cache = crate::seg::cache::SegBlockCache::new(1 << 20);
for entry in &entries {
let before = segment.block_reads();
assert_eq!(
segment.lookup(entry.h, &entry.key, &cache).unwrap(),
crate::seg::segment::Lookup::Live(entry.value.clone().unwrap())
);
assert!(segment.block_reads() - before <= 1);
}
let mut report = crate::seg::verify::VerifyReport::default();
crate::seg::verify::verify_segment(&segment, &mut report).unwrap();
assert!(report.is_clean(), "{:?}", report.problems);
}
#[test]
fn a_segment_is_written_under_its_final_names() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(5_000, 100);
let header = testkit::header(0x2a);
let mut w = SegmentWriter::create(real(), dir.path(), header, 5_000).unwrap();
write_all(&mut w, &entries);
assert_eq!(w.entries(), 5_000);
let files = w.finish(testkit::times(), 3, 0xcafe).unwrap();
let sdat = dir.path().join("000000000000002a-0001.sdat");
let sidx = dir.path().join("000000000000002a-0001.sidx");
let sdat_bytes = std::fs::read(&sdat).unwrap();
let sidx_bytes = std::fs::read(&sidx).unwrap();
assert_eq!(
std::fs::read_dir(dir.path()).unwrap().count(),
2,
"no temporary file is left"
);
assert_eq!(files.header, header);
assert_eq!(files.sdat_len, sdat_bytes.len() as u64);
assert_eq!(files.sidx_len, sidx_bytes.len() as u64);
assert_eq!(files.sdat_checksum, xxh3_64(&sdat_bytes));
assert_eq!(files.sidx_checksum, xxh3_64(&sidx_bytes));
assert_eq!(files.props.entries, 5_000);
assert_eq!(files.props.tombstones, 500);
assert_eq!(files.props.min_gsn, 100);
assert_eq!(files.props.max_gsn, 5_099);
assert_eq!(files.props.min_h, entries.first().unwrap().h);
assert_eq!(files.props.max_h, entries.last().unwrap().h);
assert_eq!(files.props.frozen_at_ms, 2_000);
assert_eq!(files.props.value_version, 3);
assert_eq!(files.props.typ_hash, 0xcafe);
assert!(files.props.writer.starts_with("armdb "));
}
#[test]
fn every_entry_is_reachable_through_the_sidecar() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(3_000, 1);
let header = testkit::header(1);
let mut w = SegmentWriter::create(real(), dir.path(), header, 3_000).unwrap();
write_all(&mut w, &entries);
let files = w.finish(testkit::times(), 0, 0).unwrap();
let sdat = std::fs::read(dir.path().join(sdat_name(1, 1))).unwrap();
let sidecar =
Sidecar::parse(&std::fs::read(dir.path().join(sidx_name(1, 1))).unwrap()).unwrap();
assert_eq!(sidecar.header, header);
assert_eq!(sidecar.props, files.props);
let super::super::key_index::SegmentIndex::Hash(index) = &sidecar.index else {
panic!("expected hash index");
};
assert_eq!(index.end_offset(), files.sdat_len);
assert!(index.len() > 10, "4 KiB blocks: many blocks expected");
for e in &entries {
assert!(sidecar.filter.may_contain(e.h));
let block = index.locate(e.h).unwrap();
let (offset, len) = index.range(block);
let payload = decode_block(&sdat[offset as usize..offset as usize + len]).unwrap();
let found = find_in_block(payload, &e.key).unwrap().unwrap();
match &e.value {
Some(v) => assert_eq!(found, Found::Live(v.clone())),
None => assert_eq!(found, Found::Tombstone),
}
}
}
#[test]
fn equal_hashes_stay_in_one_block_even_past_the_target_size() {
let dir = tempfile::tempdir().unwrap();
let mut entries: Vec<TestEntry> = (0..200)
.map(|i| TestEntry {
h: 7,
key: testkit::key_of(i),
value: Some(testkit::value_of(i)),
gsn: i + 1,
})
.collect();
entries.sort_by_key(|a| a.key);
let mut writer =
SegmentWriter::create(real(), dir.path(), testkit::header(2), 200).unwrap();
writer.trust_caller_hash();
write_all(&mut writer, &entries);
writer.finish(testkit::times(), 0, 0).unwrap();
let data = std::fs::read(dir.path().join(sdat_name(2, 1))).unwrap();
let sidecar =
Sidecar::parse(&std::fs::read(dir.path().join(sidx_name(2, 1))).unwrap()).unwrap();
let super::super::key_index::SegmentIndex::Hash(index) = &sidecar.index else {
panic!("expected hash index");
};
assert_eq!(index.len(), 1);
let (offset, len) = index.range(0);
let payload = decode_block(&data[offset as usize..offset as usize + len]).unwrap();
for entry in &entries {
assert_eq!(
find_in_block(payload, &entry.key).unwrap(),
Some(Found::Live(entry.value.clone().unwrap()))
);
}
}
#[test]
fn the_record_carries_what_the_manifest_needs() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(100, 7);
let rec = testkit::write_segment(real(), dir.path(), 9, &entries);
assert_eq!(rec.segment_id, 9);
assert_eq!(rec.version, 1);
assert_eq!(rec.format_version, 1);
assert_eq!(rec.entries, 100);
assert_eq!(rec.tombstones, 10);
assert_eq!(rec.min_gsn, 7);
assert_eq!(rec.max_gsn, 106);
assert_eq!(rec.frozen_at_ms, 2_000);
assert_eq!(
rec.sdat_len,
std::fs::metadata(dir.path().join(sdat_name(9, 1)))
.unwrap()
.len()
);
}
#[test]
fn entries_out_of_order_are_refused() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(10, 1);
let mut w = SegmentWriter::create(real(), dir.path(), testkit::header(1), 10).unwrap();
w.push(entries[1].h, &entries[1].bytes()).unwrap();
assert!(w.push(entries[0].h, &entries[0].bytes()).is_err());
assert!(w.push(entries[1].h, &entries[1].bytes()).is_err());
}
#[test]
fn an_entry_of_the_wrong_shape_is_refused() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(1, 1);
let mut w = SegmentWriter::create(real(), dir.path(), testkit::header(1), 1).unwrap();
let bytes = entries[0].bytes();
assert!(w.push(entries[0].h, &bytes[..bytes.len() - 8]).is_err());
assert!(w.push(entries[0].h, &bytes[..10]).is_err());
}
fn a_live_entry(entries: &[TestEntry]) -> &TestEntry {
entries[2..]
.iter()
.find(|e| e.value.as_ref().is_some_and(|v| !v.is_empty()))
.unwrap()
}
#[test]
fn a_refused_entry_poisons_the_writer() {
let entries = testkit::entries(20, 1);
let next = a_live_entry(&entries);
let value_at = ENTRY_HEADER_LEN + testkit::KEY_LEN;
let mut bad_value = next.bytes();
bad_value[value_at] ^= 0x01;
let mut too_long = next.bytes();
too_long.extend_from_slice(&[0u8; 8]);
let whole = next.bytes();
let cases: [(&str, u64, Vec<u8>); 6] = [
("shorter than a header", next.h, whole[..10].to_vec()),
(
"shorter than its header says",
next.h,
whole[..whole.len() - 8].to_vec(),
),
("longer than its header says", next.h, too_long),
("a damaged value", next.h, bad_value),
(
"a hash that is not the key's",
next.h.wrapping_add(1),
whole.clone(),
),
("out of order", entries[0].h, entries[0].bytes()),
];
for (what, h, bytes) in cases {
let dir = tempfile::tempdir().unwrap();
let mut w = SegmentWriter::create(real(), dir.path(), testkit::header(1), 20).unwrap();
w.push(entries[1].h, &entries[1].bytes()).unwrap();
assert!(w.push(h, &bytes).is_err(), "{what} was accepted");
let last = entries.last().unwrap();
assert!(
w.push(last.h, &last.bytes()).is_err(),
"{what}: a valid entry was accepted after the refusal"
);
assert!(w.finish(testkit::times(), 0, 0).is_err(), "{what}");
assert!(dir_is_empty(dir.path()), "{what} left a file behind");
}
}
#[test]
fn a_trusted_caller_hash_still_needs_a_sound_entry() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(20, 1);
let entry = a_live_entry(&entries);
let mut w = SegmentWriter::create(real(), dir.path(), testkit::header(1), 20).unwrap();
w.trust_caller_hash();
let mut bytes = entry.bytes();
bytes[ENTRY_HEADER_LEN + testkit::KEY_LEN] ^= 0x01;
assert!(w.push(7, &bytes).is_err());
}
#[test]
fn a_writer_with_no_entries_leaves_nothing() {
let dir = tempfile::tempdir().unwrap();
let w = SegmentWriter::create(real(), dir.path(), testkit::header(1), 0).unwrap();
assert!(w.finish(testkit::times(), 0, 0).is_err());
assert!(dir_is_empty(dir.path()));
}
#[test]
fn dropping_an_unfinished_writer_removes_its_files() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(1_000, 1);
let mut w = SegmentWriter::create(real(), dir.path(), testkit::header(1), 1_000).unwrap();
write_all(&mut w, &entries);
assert!(!dir_is_empty(dir.path()));
drop(w);
assert!(dir_is_empty(dir.path()));
}
#[test]
fn both_files_are_durable_before_they_get_their_names() {
let dir = tempfile::tempdir().unwrap();
let fs = TraceFs::new();
let entries = testkit::entries(500, 1);
testkit::write_segment(fs.clone(), dir.path(), 1, &entries);
let sync_sdat = fs.position(FsOpKind::SyncFile, ".sdat.tmp").unwrap();
let sync_sidx = fs.position(FsOpKind::SyncFile, ".sidx.tmp").unwrap();
let rename_sdat = fs.position(FsOpKind::Rename, ".sdat").unwrap();
let rename_sidx = fs.position(FsOpKind::Rename, ".sidx").unwrap();
let sync_dir = fs.position(FsOpKind::SyncDir, "").unwrap();
assert!(sync_sdat < rename_sdat);
assert!(sync_sidx < rename_sidx);
assert!(sync_sdat < rename_sidx && sync_sidx < rename_sdat);
assert!(rename_sdat < sync_dir && rename_sidx < sync_dir);
}
#[test]
fn a_failure_at_any_step_leaves_no_file() {
let faults = [
(FsOpKind::WriteAll, ".sdat.tmp"),
(FsOpKind::SyncFile, ".sdat.tmp"),
(FsOpKind::CreateNew, ".sidx.tmp"),
(FsOpKind::WriteAll, ".sidx.tmp"),
(FsOpKind::SyncFile, ".sidx.tmp"),
(FsOpKind::Rename, ".sdat"),
(FsOpKind::Rename, ".sidx"),
(FsOpKind::SyncDir, ""),
];
for (kind, name) in faults {
let dir = tempfile::tempdir().unwrap();
let fs = TraceFs::new();
let entries = testkit::entries(500, 1);
let mut w =
SegmentWriter::create(fs.clone(), dir.path(), testkit::header(1), 500).unwrap();
write_all(&mut w, &entries);
fs.fail_on(kind, name, 0);
assert!(w.finish(testkit::times(), 0, 0).is_err(), "{kind:?} {name}");
assert!(
dir_is_empty(dir.path()),
"{kind:?} {name} left a file behind"
);
}
}
#[test]
fn dropping_a_new_writer_preserves_existing_finished_files() {
let dir = tempfile::tempdir().unwrap();
let entries = testkit::entries(10, 1);
testkit::write_segment(real(), dir.path(), 1, &entries);
let sdat = dir.path().join(sdat_name(1, 1));
let sidx = dir.path().join(sidx_name(1, 1));
let before_data = std::fs::read(&sdat).unwrap();
let before_index = std::fs::read(&sidx).unwrap();
assert!(SegmentWriter::create(real(), dir.path(), testkit::header(1), 10).is_err());
assert_eq!(std::fs::read(sdat).unwrap(), before_data);
assert_eq!(std::fs::read(sidx).unwrap(), before_index);
}
#[test]
fn existing_data_temporary_file_is_preserved() {
let dir = tempfile::tempdir().unwrap();
let tmp = tmp_of(&dir.path().join(sdat_name(1, 1)));
std::fs::write(&tmp, b"another writer").unwrap();
assert!(SegmentWriter::create(real(), dir.path(), testkit::header(1), 1).is_err());
assert_eq!(std::fs::read(&tmp).unwrap(), b"another writer");
}
#[test]
fn existing_sidecar_temporary_file_is_preserved() {
let dir = tempfile::tempdir().unwrap();
let tmp = tmp_of(&dir.path().join(sidx_name(1, 1)));
std::fs::write(&tmp, b"another writer").unwrap();
let entries = testkit::entries(1, 1);
let mut writer = SegmentWriter::create(real(), dir.path(), testkit::header(1), 1).unwrap();
write_all(&mut writer, &entries);
assert!(writer.finish(testkit::times(), 0, 0).is_err());
assert_eq!(std::fs::read(&tmp).unwrap(), b"another writer");
assert!(!tmp_of(&dir.path().join(sdat_name(1, 1))).exists());
}
#[test]
fn finish_refuses_to_publish_after_a_push_write_failure() {
let dir = tempfile::tempdir().unwrap();
let fs = TraceFs::new();
let entries = testkit::entries(100, 1);
let mut writer =
SegmentWriter::create(fs.clone(), dir.path(), testkit::header(1), 100).unwrap();
fs.fail_on(FsOpKind::WriteAll, ".sdat.tmp", 0);
let mut failure_seen = false;
for entry in &entries {
if writer.push(entry.h, &entry.bytes()).is_err() {
failure_seen = true;
break;
}
}
assert!(
failure_seen,
"a block flush should attempt the injected write"
);
assert!(writer.finish(testkit::times(), 0, 0).is_err());
assert!(dir_is_empty(dir.path()));
}
}