//! Volume: the core storage unit — a .dat file + .idx index. //! //! Each volume contains many needles (files). It manages: //! - Reading/writing/deleting needles from the .dat file //! - Maintaining the in-memory NeedleMap (NeedleId → Offset+Size) //! - SuperBlock at offset 0 of the .dat file //! - Metrics (file count, content size, deleted count) //! //! Matches Go's storage/volume.go, volume_loading.go, volume_read.go, //! volume_write.go, volume_super_block.go. use std::collections::HashSet; use std::fs::{self, File, OpenOptions}; use std::io::{self, Read, Seek, SeekFrom, Write}; use std::ops::ControlFlow; use std::path::Path; use std::sync::Arc; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::{Condvar, Mutex}; use std::time::{SystemTime, UNIX_EPOCH}; use tracing::{debug, error, info, warn}; use crate::storage::idx; use crate::storage::io::read_exact_at; use crate::storage::io_error::{IoErrorTracker, StreakMark}; use crate::storage::needle::needle::{self, Needle, NeedleError, get_actual_size}; use crate::storage::needle_map::sorted_file::SortedFileNeedleMap; use crate::storage::needle_map::{CompactNeedleMap, NeedleMap, NeedleMapKind, RedbNeedleMap}; use crate::storage::super_block::{ReplicaPlacement, SUPER_BLOCK_SIZE, SuperBlock}; use crate::storage::types::*; use crate::storage::volume_open::open_volume_file; // ============================================================================ // Errors // ============================================================================ #[derive(Debug, thiserror::Error)] pub enum VolumeError { #[error("not found")] NotFound, #[error("volume id {0} is not found")] VolumeNotFound(VolumeId), #[error("already deleted")] Deleted, #[error("needle size mismatch")] SizeMismatch, #[error("unsupported version: {0}")] UnsupportedVersion(u8), #[error("cookie mismatch: {0:#x}")] CookieMismatch(u32), #[error("volume not empty")] NotEmpty, #[error("volume already exists")] AlreadyExists, #[error("volume {0} is read only")] ReadOnly(VolumeId), #[error("volume is unavailable: {0}")] Unavailable(String), #[error("volume size limit exceeded: current {current}, limit {limit}")] SizeLimitExceeded { current: u64, limit: u64 }, #[error("not enough free space: required {required}, free {free}")] InsufficientSpace { vid: VolumeId, required: u64, free: u64, }, #[error("volume not initialized")] NotInitialized, #[error("needle error: {0}")] Needle(#[from] NeedleError), #[error("super block error: {0}")] SuperBlock(#[from] crate::storage::super_block::SuperBlockError), #[error("IO error: {0}")] Io(#[from] io::Error), #[error(transparent)] Tier(#[from] crate::remote_storage::s3_tier::TierError), } /// Returns true when a needle read failed because the on-disk bytes are /// unreadable in a permanent way (offset past EOF, header corruption, CRC /// mismatch, malformed v2/v3/v4 fields). Vacuum can safely drop such entries /// during compaction. Anything else (real disk EIO, ERROR_CRC on Windows, /// network timeouts, EROFS, etc.) is transient or environmental and must /// abort the compaction so an operator notices. fn is_skippable_needle_read_error(e: &VolumeError) -> bool { match e { VolumeError::Io(io_err) => io_err.kind() == io::ErrorKind::UnexpectedEof, VolumeError::Needle(NeedleError::SizeMismatch { .. }) => true, VolumeError::Needle(NeedleError::CrcMismatch { .. }) => true, VolumeError::Needle(NeedleError::IndexOutOfRange(_)) => true, VolumeError::Needle(NeedleError::TailTooShort) => true, VolumeError::SizeMismatch => true, _ => false, } } /// Reports whether the compacted .dat is short of the live bytes the /// pre-compaction index snapshot expected. fn exceeds_expected_compacted_size(expected_live_bytes: u64, dst_dat_size: u64) -> bool { expected_live_bytes > dst_dat_size } /// Read and parse the needle at `offset` through `read_at`. fn read_needle_with( read_at: impl Fn(&mut [u8], u64) -> Result<(), VolumeError>, n: &mut Needle, offset: i64, size: Size, version: Version, ) -> Result<(), VolumeError> { match parse_needle_at(&read_at, n, offset, size, version) { Ok(()) => Ok(()), #[cfg(not(feature = "5bytes"))] Err(VolumeError::Needle(NeedleError::SizeMismatch { offset: o, .. })) if o < MAX_POSSIBLE_VOLUME_SIZE as i64 => { // Double-read: in 4-byte offset mode, the actual data may be // beyond 32GB due to offset wrapping. Retry at offset + 32GB. parse_needle_at( &read_at, n, offset + MAX_POSSIBLE_VOLUME_SIZE as i64, size, version, ) } Err(e) => Err(e), } } fn parse_needle_at( read_at: &impl Fn(&mut [u8], u64) -> Result<(), VolumeError>, n: &mut Needle, offset: i64, size: Size, version: Version, ) -> Result<(), VolumeError> { // Storage guard: negativity-only (Go parity — storage allocates what the // index says). Size(0) and >1GiB map sizes must still read; only // negative wraps/panics. Transport cap lives in RPC handlers only. if size.0 < 0 { return Err(VolumeError::Io(std::io::Error::new( std::io::ErrorKind::InvalidData, format!("invalid needle size {}", size.0), ))); } let actual_size = get_actual_size(size, version); let mut buf = vec![0u8; actual_size as usize]; #[cfg(test)] needle_read_hook::fire(n.id, buf.len()); read_at(&mut buf, offset as u64)?; n.read_bytes(&buf, offset, size, version)?; Ok(()) } // ============================================================================ // VolumeInfo (.vif persistence) // ============================================================================ /// Legacy simple VolumeInfo for backward compat with old .vif files. #[derive(serde::Serialize, serde::Deserialize)] struct VolumeInfo { read_only: bool, } pub use crate::pb::volume_server_pb::RemoteFile as PbRemoteFile; /// Protobuf VolumeInfo type alias. pub use crate::pb::volume_server_pb::VolumeInfo as PbVolumeInfo; /// Helper module for deserializing protojson uint64 fields that may be strings or numbers. mod string_or_u64 { use serde::{self, Deserialize, Deserializer, Serializer}; pub fn serialize(value: &u64, serializer: S) -> Result where S: Serializer, { // Emit as string to match Go's protojson format for uint64 serializer.serialize_str(&value.to_string()) } pub fn deserialize<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, { #[derive(Deserialize)] #[serde(untagged)] enum StringOrNum { Str(String), Num(u64), } match StringOrNum::deserialize(deserializer)? { StringOrNum::Str(s) => s.parse::().map_err(serde::de::Error::custom), StringOrNum::Num(n) => Ok(n), } } } mod string_or_i64 { use serde::{self, Deserialize, Deserializer, Serializer}; pub fn serialize(value: &i64, serializer: S) -> Result where S: Serializer, { serializer.serialize_str(&value.to_string()) } pub fn deserialize<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, { #[derive(Deserialize)] #[serde(untagged)] enum StringOrNum { Str(String), Num(i64), } match StringOrNum::deserialize(deserializer)? { StringOrNum::Str(s) => s.parse::().map_err(serde::de::Error::custom), StringOrNum::Num(n) => Ok(n), } } } /// Serde-compatible representation of RemoteFile for .vif JSON serialization. /// Field names use snake_case to match Go's protobuf JSON output (jsonpb). #[derive(serde::Serialize, serde::Deserialize, Default, Clone)] pub struct VifRemoteFile { #[serde(default, rename = "backendType")] pub backend_type: String, #[serde(default, rename = "backendId")] pub backend_id: String, #[serde(default)] pub key: String, #[serde(default, with = "string_or_u64")] pub offset: u64, #[serde(default, rename = "fileSize", with = "string_or_u64")] pub file_size: u64, #[serde(default, rename = "modifiedTime", with = "string_or_u64")] pub modified_time: u64, #[serde(default)] pub extension: String, } #[derive(serde::Serialize, serde::Deserialize, Default, Clone)] pub struct VifEcShardConfig { #[serde(default, rename = "dataShards")] pub data_shards: u32, #[serde(default, rename = "parityShards")] pub parity_shards: u32, /// Encode time (unix nanos). Shards and .ecx of one encode run share it, /// so a read served from a different run's shard is rejected. #[serde(default, rename = "encodeTsNs", with = "string_or_i64")] pub encode_ts_ns: i64, /// Uniform block layout: each shard is a single contiguous block of this /// many bytes. 0 = legacy 1GiB/1MiB two-tier layout. #[serde(default, rename = "blockSize", with = "string_or_i64")] pub block_size: i64, } /// Serde-compatible representation of OldVersionVolumeInfo for legacy .vif JSON deserialization. /// Matches Go's protobuf OldVersionVolumeInfo where `DestroyTime` maps to `expire_at_sec`. #[derive(serde::Deserialize, Default)] struct OldVersionVifVolumeInfo { #[serde(default)] pub files: Vec, #[serde(default)] pub version: u32, #[serde(default)] pub replication: String, #[serde(default, alias = "bytesOffset", alias = "BytesOffset")] pub bytes_offset: u32, #[serde( default, alias = "datFileSize", alias = "dat_file_size", with = "string_or_i64" )] pub dat_file_size: i64, #[serde( default, alias = "destroyTime", alias = "DestroyTime", with = "string_or_u64" )] pub destroy_time: u64, #[serde(default, alias = "readOnly", alias = "read_only")] pub read_only: bool, } impl OldVersionVifVolumeInfo { /// Convert to the standard VifVolumeInfo, mapping destroy_time -> expire_at_sec. fn into_vif(self) -> VifVolumeInfo { VifVolumeInfo { files: self.files, version: self.version, replication: self.replication, bytes_offset: self.bytes_offset, dat_file_size: self.dat_file_size, expire_at_sec: self.destroy_time, read_only: self.read_only, ec_shard_config: None, read_only_can_delete: false, } } } /// Serde-compatible representation of VolumeInfo for .vif JSON serialization. /// Matches Go's protobuf JSON format (jsonpb with EmitUnpopulated=true). #[derive(serde::Serialize, serde::Deserialize, Default, Clone)] pub struct VifVolumeInfo { #[serde(default)] pub files: Vec, #[serde(default)] pub version: u32, #[serde(default)] pub replication: String, #[serde(default, rename = "bytesOffset")] pub bytes_offset: u32, #[serde(default, rename = "datFileSize", with = "string_or_i64")] pub dat_file_size: i64, #[serde(default, rename = "expireAtSec", with = "string_or_u64")] pub expire_at_sec: u64, #[serde(default, rename = "readOnly")] pub read_only: bool, #[serde( default, rename = "ecShardConfig", skip_serializing_if = "Option::is_none" )] pub ec_shard_config: Option, #[serde(default, rename = "readOnlyCanDelete")] pub read_only_can_delete: bool, } impl VifVolumeInfo { /// Convert from protobuf VolumeInfo to the serde-compatible struct. pub fn from_pb(pb: &PbVolumeInfo) -> Self { Self { files: pb .files .iter() .map(|f| VifRemoteFile { backend_type: f.backend_type.clone(), backend_id: f.backend_id.clone(), key: f.key.clone(), offset: f.offset, file_size: f.file_size, modified_time: f.modified_time, extension: f.extension.clone(), }) .collect(), version: pb.version, replication: pb.replication.clone(), bytes_offset: pb.bytes_offset, dat_file_size: pb.dat_file_size, expire_at_sec: pb.expire_at_sec, read_only: pb.read_only, ec_shard_config: pb.ec_shard_config.as_ref().map(|c| VifEcShardConfig { data_shards: c.data_shards, parity_shards: c.parity_shards, encode_ts_ns: c.encode_ts_ns, block_size: c.block_size, }), read_only_can_delete: pb.read_only_can_delete, } } /// Convert to protobuf VolumeInfo. pub fn to_pb(&self) -> PbVolumeInfo { PbVolumeInfo { files: self .files .iter() .map(|f| PbRemoteFile { backend_type: f.backend_type.clone(), backend_id: f.backend_id.clone(), key: f.key.clone(), offset: f.offset, file_size: f.file_size, modified_time: f.modified_time, extension: f.extension.clone(), }) .collect(), version: self.version, replication: self.replication.clone(), bytes_offset: self.bytes_offset, dat_file_size: self.dat_file_size, expire_at_sec: self.expire_at_sec, read_only: self.read_only, ec_shard_config: self.ec_shard_config.as_ref().map(|c| { crate::pb::volume_server_pb::EcShardConfig { data_shards: c.data_shards, parity_shards: c.parity_shards, encode_ts_ns: c.encode_ts_ns, block_size: c.block_size, } }), read_only_can_delete: self.read_only_can_delete, } } } // ============================================================================ // Streaming read support // ============================================================================ #[derive(Default)] struct DataFileAccessState { readers: usize, writer_active: bool, } #[derive(Default)] pub struct DataFileAccessControl { state: Mutex, condvar: Condvar, } pub struct DataFileReadLease { control: Arc, } pub struct DataFileWriteLease { control: Arc, } impl DataFileAccessControl { pub fn read_lock(self: &Arc) -> DataFileReadLease { let mut state = self.state.lock().unwrap(); while state.writer_active { state = self.condvar.wait(state).unwrap(); } state.readers += 1; drop(state); DataFileReadLease { control: self.clone(), } } pub fn write_lock(self: &Arc) -> DataFileWriteLease { let mut state = self.state.lock().unwrap(); while state.writer_active || state.readers > 0 { state = self.condvar.wait(state).unwrap(); } state.writer_active = true; drop(state); DataFileWriteLease { control: self.clone(), } } } impl Drop for DataFileReadLease { fn drop(&mut self) { let mut state = self.control.state.lock().unwrap(); state.readers -= 1; if state.readers == 0 { self.control.condvar.notify_all(); } } } impl Drop for DataFileWriteLease { fn drop(&mut self) { let mut state = self.control.state.lock().unwrap(); state.writer_active = false; self.control.condvar.notify_all(); } } /// Test seam: a hook sees (and may park) every data read of its needle. #[cfg(test)] pub(crate) mod needle_read_hook { use super::NeedleId; use std::sync::{Arc, Mutex}; type Hook = Arc; static HOOKS: Mutex> = Mutex::new(Vec::new()); pub(crate) struct Registration(NeedleId); impl Drop for Registration { fn drop(&mut self) { HOOKS.lock().unwrap().retain(|(id, _)| *id != self.0); } } /// Needle ids are the key, so tests running in parallel must use distinct ones. pub(crate) fn register( id: NeedleId, hook: impl Fn(usize) + Send + Sync + 'static, ) -> Registration { HOOKS.lock().unwrap().push((id, Arc::new(hook))); Registration(id) } pub(crate) fn fire(id: NeedleId, len: usize) { let hook = HOOKS .lock() .unwrap() .iter() .find(|(hook_id, _)| *hook_id == id) .map(|(_, hook)| hook.clone()); if let Some(hook) = hook { hook(len); } } } /// Information needed to stream needle data directly from the dat file /// without loading the entire payload into memory. pub(crate) enum NeedleStreamSource { Local(File), Remote(RemoteDatFile), } impl NeedleStreamSource { pub(crate) fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> io::Result<()> { match self { NeedleStreamSource::Local(file) => read_exact_at(file, buf, offset), NeedleStreamSource::Remote(remote) => remote.read_exact_at(buf, offset), } } } /// A `.dat` scan that runs with the store lock released, built by /// `Volume::dat_scan_plan` while the caller holds a store guard. /// /// The start offset, the handle and the end bound are captured together /// while the guard excludes every writer. The handle pins the inode the /// offset was resolved against: a vacuum commit replaces `.dat` by rename, /// and unmount or destroy close and unlink it, none of which rewrites the /// pinned bytes. `.dat` is otherwise append-only and a failed append /// truncates only its own bytes, so `[from, end)` holds complete records /// that nothing rewrites while the scan runs. A short read below `end` can /// therefore only mean the inode was truncated under the plan (an unmount /// followed by a `VolumeCopy` of the same id reopens `.dat` with /// `truncate(true)`), and the scan fails rather than ending as if the /// snapshot had been read. The fields are private so a plan can only come /// from `dat_scan_plan`. pub(crate) struct DatScanPlan { source: NeedleStreamSource, version: Version, from: u64, end: u64, /// The volume instance and revision the plan was taken from: after a /// vacuum or a re-create, the needle map's offsets name another file. owner: Arc, compaction_revision: u16, } /// One record visited by `DatScanPlan::scan`: the raw on-disk bytes and the /// parsed append timestamp. pub(crate) struct RawNeedle<'a> { pub header: &'a [u8], pub body: &'a [u8], pub append_at_ns: u64, } /// One record visited by `DatScanPlan::scan_records`, not yet parsed. pub(crate) struct DatRecord<'a> { pub offset: u64, pub id: NeedleId, pub size: Size, /// Header and body. pub bytes: &'a [u8], version: Version, } impl DatRecord<'_> { pub(crate) fn parse(&self) -> Result { let mut n = Needle::default(); n.read_bytes(self.bytes, self.offset as i64, self.size, self.version)?; Ok(n) } } impl DatScanPlan { /// Visit the records in `[from, end)` in file order, the way Go's /// `ScanVolumeFileFrom` feeds a `VolumeFileScanner`: only the record being /// visited is in memory. Reads are positional and never touch the /// `Volume`. The pass ends `Ok` at the end of the data, at a record that /// does not fit before `end`, or when `visit` breaks. A corrupt header /// fails the pass: ending early would let a truncated tail look complete. /// It also fails on any read error, including a short read below `end`: /// every byte below `end` existed when the plan was taken, so a short read /// means the file was truncated under the plan and the pass is incomplete. pub(crate) fn scan( &self, mut visit: impl FnMut(RawNeedle<'_>) -> ControlFlow<()>, ) -> Result<(), VolumeError> { self.scan_records(|record| { let append_at_ns = record.parse()?.append_at_ns; Ok(visit(RawNeedle { header: &record.bytes[..NEEDLE_HEADER_SIZE], body: &record.bytes[NEEDLE_HEADER_SIZE..], append_at_ns, })) }) } /// `scan` without the parse: a visitor that skips a record never fails on /// a body it did not need. pub(crate) fn scan_records( &self, mut visit: impl FnMut(DatRecord<'_>) -> Result, VolumeError>, ) -> Result<(), VolumeError> { let mut offset = self.from; while offset + NEEDLE_HEADER_SIZE as u64 <= self.end { let mut header = [0u8; NEEDLE_HEADER_SIZE]; self.source .read_exact_at(&mut header, offset) .map_err(|e| self.read_error(e, offset))?; let (_cookie, id, size) = Needle::parse_header(&header); if size.0 == 0 && id.is_empty() { break; } // A negative size is a corrupt header: the record length it // implies cannot advance the scan past it, and stopping quietly // would let a truncated tail look complete. Go's scan fails here. if size.0 < 0 { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "corrupt needle header at offset {offset}: size {}, record length {}", size.0, get_actual_size(size, self.version) ), ))); } // Nothing past `end` was a complete record when the plan was // taken. The size is checked against the bytes left, and the // whole record after it. Both run before allocating, so a corrupt // size cannot size the buffer. (The size check alone does not // keep a corrupt size out of the padding arithmetic on a volume // with more than 2 GiB left, which is why `padding_length` sums // in i64.) if size.0 as u64 > self.end - offset - NEEDLE_HEADER_SIZE as u64 { break; } let body_length = needle::needle_body_length(size, self.version) as u64; let total_size = NEEDLE_HEADER_SIZE as u64 + body_length; if offset + total_size > self.end { break; } // Match Go's ScanVolumeFileFrom: visit ALL needles including deleted ones. // This is critical for incremental copy where tombstones must be propagated. let mut record = vec![0u8; total_size as usize]; record[..NEEDLE_HEADER_SIZE].copy_from_slice(&header); self.source .read_exact_at( &mut record[NEEDLE_HEADER_SIZE..], offset + NEEDLE_HEADER_SIZE as u64, ) .map_err(|e| self.read_error(e, offset + NEEDLE_HEADER_SIZE as u64))?; let record = DatRecord { offset, id, size, bytes: &record, version: self.version, }; if visit(record)?.is_break() { break; } offset += total_size; } Ok(()) } /// Name the snapshot in a read failure. A short read is the truncation /// case described on the type; every other error is passed through with /// the offset. fn read_error(&self, e: io::Error, offset: u64) -> VolumeError { let what = if e.kind() == io::ErrorKind::UnexpectedEof { "short read below the snapshot end, the dat file was truncated under the scan" } else { "read failed" }; VolumeError::Io(io::Error::new( e.kind(), format!( "{} (offset {}, snapshot end {}): {}", what, offset, self.end, e ), )) } } /// Why a volume refuses all I/O, shared with its in-flight needle streams so /// they see a mark made after they left the store lock. A leaf lock. #[derive(Debug, Default)] pub(crate) struct IoUnavailable(Mutex>); impl IoUnavailable { fn set(&self, reason: String) { *self.0.lock().unwrap() = Some(reason); } fn is_set(&self) -> bool { self.0.lock().unwrap().is_some() } pub(crate) fn error(&self) -> Option { self.0 .lock() .unwrap() .as_ref() .map(|reason| VolumeError::Unavailable(reason.clone())) } } /// A needle read resolved under a store guard and run after it is released; /// the handle pins the inode, as for `DatScanPlan`. It takes no data-file /// lease: writers wait for one while holding the store write lock. pub(crate) struct NeedleReadPlan { source: NeedleStreamSource, offset: i64, size: Size, version: Version, needle_id: NeedleId, data_file_access_control: Arc, io_errors: Arc, io_unavailable: Arc, } impl NeedleReadPlan { /// The needle's size in the index. pub(crate) fn size(&self) -> Size { self.size } /// Read the whole needle and verify its checksum. pub(crate) fn read_full(&mut self, n: &mut Needle) -> Result<(), VolumeError> { let (source, size, version) = (&self.source, self.size, self.version); let read_at = |buf: &mut [u8], at: u64| Ok(source.read_exact_at(buf, at)?); let result = with_offset_retry(&mut self.offset, |off| { parse_needle_at(&read_at, n, off, size, version) }); match &result { Ok(()) => self.io_errors.check_read_write_error(None), Err(VolumeError::Io(e)) => self.io_errors.check_read_write_error(Some(e)), Err(_) => {} } result?; if needle_expired(n) { return Err(VolumeError::NotFound); } Ok(()) } /// Read only the needle's metadata, skipping the payload. pub(crate) fn read_meta(&mut self, n: &mut Needle) -> Result<(), VolumeError> { let (source, size, version) = (&self.source, self.size, self.version); let read_at = |buf: &mut [u8], at: u64| Ok(source.read_exact_at(buf, at)?); with_offset_retry(&mut self.offset, |off| { if version == VERSION_1 { // A V1 body is all data, so its "meta" is the whole record. let mut buf = vec![0u8; get_actual_size(size, version) as usize]; #[cfg(test)] needle_read_hook::fire(n.id, buf.len()); read_at(&mut buf, off as u64)?; Ok(n.read_bytes_meta_only(&buf, off, size, version)?) } else { Volume::read_needle_meta_blob_and_parse(read_at, n, off, size, version) } })?; if needle_expired(n) { return Err(VolumeError::NotFound); } Ok(()) } /// For a reply served from the data file, after `read_meta` filled `n`. pub(crate) fn into_stream_info(self, n: &Needle) -> NeedleStreamInfo { // V1 data starts right after the header, V2/V3 after the DataSize field. let data_file_offset = if self.version == VERSION_1 { self.offset as u64 + NEEDLE_HEADER_SIZE as u64 } else { self.offset as u64 + NEEDLE_HEADER_SIZE as u64 + DATA_SIZE_SIZE as u64 }; NeedleStreamInfo { source: self.source, data_file_offset, data_size: n.data_size, data_file_access_control: self.data_file_access_control, io_unavailable: self.io_unavailable, needle_id: self.needle_id, checksum: n.checksum.0, } } } /// Run `read` at `offset`, retrying past the 32 GiB wrap of 4-byte offsets /// on a size mismatch, and leave `offset` where the needle parsed. fn with_offset_retry( offset: &mut i64, mut read: impl FnMut(i64) -> Result<(), VolumeError>, ) -> Result<(), VolumeError> { match read(*offset) { #[cfg(not(feature = "5bytes"))] Err(VolumeError::Needle(NeedleError::SizeMismatch { offset: o, .. })) if o < MAX_POSSIBLE_VOLUME_SIZE as i64 => { *offset += MAX_POSSIBLE_VOLUME_SIZE as i64; read(*offset) } result => result, } } fn needle_expired(n: &Needle) -> bool { let Some(ttl) = n.ttl.as_ref().filter(|_| n.has_ttl()) else { return false; }; let ttl_minutes = ttl.minutes(); if ttl_minutes == 0 || !n.has_last_modified_date() { return false; } let expire_at_ns = n.append_at_ns + (ttl_minutes as u64) * 60 * 1_000_000_000; let now_ns = SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_nanos() as u64; now_ns >= expire_at_ns } /// Holds `Volume::is_compacting` set; dropping it clears the flag. struct CompactionClaim(Arc); impl CompactionClaim { fn try_claim(flag: &Arc) -> Option { flag.compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire) .ok() .map(|_| CompactionClaim(flag.clone())) } } impl Drop for CompactionClaim { fn drop(&mut self) { self.0.store(false, Ordering::Release); } } /// A compaction copy that runs off the store lock: `.dat`/`.idx` are /// append-only below `idx_size`, and `makeup_diff` replays what lands after. pub(crate) struct CompactionJob { id: VolumeId, src_dat: NeedleStreamSource, src_idx: File, idx_size: u64, cpd_path: String, cpx_path: String, version: Version, super_block: SuperBlock, io_errors: Arc, _claim: CompactionClaim, } impl CompactionJob { pub(crate) fn run(self, progress_fn: F) -> Result<(), VolumeError> where F: Fn(i64) -> bool, { let cpd_path = &self.cpd_path; let cpx_path = &self.cpx_path; let version = self.version; // Write new super block with incremented compaction revision let mut new_sb = self.super_block.clone(); new_sb.compaction_revision += 1; let sb_bytes = new_sb.to_bytes(); let mut dst = OpenOptions::new() .read(true) .write(true) .create(true) .truncate(true) .open(cpd_path)?; dst.write_all(&sb_bytes)?; let mut new_offset = sb_bytes.len() as i64; // Build new index in memory let mut new_nm = CompactNeedleMap::new(); let now = SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_secs(); let entries = self.live_entries()?; let mut skipped_needles: u64 = 0; let mut skipped_data_bytes: u64 = 0; let mut expected_live_bytes: u64 = 0; for (id, offset, size) in entries { // Progress callback if !progress_fn(offset.to_actual_offset()) { // Interrupted let _ = fs::remove_file(cpd_path); return Err(VolumeError::Io(io::Error::new( io::ErrorKind::Interrupted, "compaction interrupted", ))); } // Read needle from source let mut n = Needle { id, ..Needle::default() }; let read = read_needle_with( |buf, at| self.src_dat.read_exact_at(buf, at).map_err(VolumeError::Io), &mut n, offset.to_actual_offset(), size, version, ); if let Err(e) = read { // Record EIO for health monitoring (parity with Go's checkReadWriteError). if let VolumeError::Io(ref io_err) = e { self.io_errors.check_read_write_error(Some(io_err)); } // Only drop the entry when the failure is one of the well- // known permanent-corruption shapes. A transient disk fault, // a tiered-read timeout, or a Windows hardware error (which // surfaces as a generic Io rather than UnexpectedEof) must // abort so an operator notices, rather than silently // compacting away data that might come back on retry. if !is_skippable_needle_read_error(&e) { return Err(VolumeError::Io(io::Error::other(format!( "cannot hydrate needle from file: {}", e )))); } skipped_needles += 1; if size.is_valid() { skipped_data_bytes += size.0 as u64; } warn!( volume_id = self.id.0, key = id.0, offset = offset.to_actual_offset(), size = size.0, error = %e, "vacuum: dropping unreadable needle" ); continue; } // Skip TTL-expired needles using the volume's TTL (matches Go's volume_vacuum.go) if n.has_ttl() { let ttl_minutes = self.super_block.ttl.minutes(); if ttl_minutes > 0 && n.last_modified > 0 { let expire_at = n.last_modified + (ttl_minutes as u64) * 60; if now >= expire_at { continue; } } } // Tally the live bytes from the frozen snapshot this loop copied // from, not the live needle map. Unreadable needles return before // this point, so no further skipped-byte adjustment is needed. expected_live_bytes += size.0 as u64; // Write needle to destination let bytes = n.write_bytes(version); dst.write_all(&bytes)?; // Update new index new_nm.put(id, Offset::from_actual_offset(new_offset), n.size)?; new_offset += bytes.len() as i64; } if skipped_needles > 0 { warn!( volume_id = self.id.0, skipped_needles, skipped_data_bytes, "vacuum: dropped unreadable index entries during compaction" ); } dst.sync_all()?; if self.super_block.ttl.is_empty() { let dst_dat_size = dst.metadata()?.len(); if exceeds_expected_compacted_size(expected_live_bytes, dst_dat_size) { let _ = fs::remove_file(cpd_path); let _ = fs::remove_file(cpx_path); return Err(VolumeError::Io(io::Error::new( io::ErrorKind::UnexpectedEof, format!( "volume {} unexpected new data size: {} does not match expected live content size {} from the pre-compaction snapshot", self.id.0, dst_dat_size, expected_live_bytes ), ))); } } // Save new index new_nm.save_to_idx(cpx_path)?; Ok(()) } /// Replay `.idx` up to the recorded size, as Go's `LoadFromIdx` does, and /// return the live entries in `.dat` order. A short read fails: treating /// it as the whole index would compact away every needle past it. fn live_entries(&self) -> Result, VolumeError> { let rows = self.idx_size / NEEDLE_MAP_ENTRY_SIZE as u64; let mut snapshot = CompactNeedleMap::new(); let mut seen = 0u64; // Rows past the recorded size are makeup_diff's; do not read them. let mut reader = io::BufReader::new((&self.src_idx).take(self.idx_size)); let mut buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; while seen < rows { match reader.read_exact(&mut buf) { Ok(()) => {} Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => break, Err(e) => return Err(e.into()), } let (key, offset, size) = idx_entry_from_bytes(&buf); if offset.is_zero() || size.is_deleted() { snapshot.delete(key, offset)?; } else { snapshot.put(key, offset, size)?; } seen += 1; } if seen < rows { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::UnexpectedEof, format!( "volume {} index has {} entries, expected {}", self.id.0, seen, rows ), ))); } let mut entries: Vec<(NeedleId, Offset, Size)> = Vec::new(); let _ = snapshot.ascending_visit(|id, nv| { if !nv.offset.is_zero() && !nv.size.is_deleted() { entries.push((id, nv.offset, nv.size)); } Ok::<(), std::convert::Infallible>(()) }); entries.sort_by_key(|(_, offset, _)| *offset); Ok(entries) } } pub struct NeedleStreamInfo { /// Stream source for the dat file, local or remote. pub(crate) source: NeedleStreamSource, /// Absolute byte offset within the dat file where needle data starts. pub data_file_offset: u64, /// Size of the data payload in bytes. pub data_size: u32, /// Per-volume file access lock used to match Go's slow-read behavior. pub data_file_access_control: Arc, /// Checked before each chunk: the volume can become unavailable mid-stream. pub(crate) io_unavailable: Arc, pub needle_id: NeedleId, /// Checksum stored in the needle tail, verified once the last chunk has /// been read — before that frame is emitted. pub checksum: u32, } #[derive(Clone)] pub(crate) struct RemoteDatFile { backend: Arc, key: String, file_size: u64, modified_time: u64, } impl RemoteDatFile { /// Read up to `size` bytes at `offset`, bounded by the remote file size. /// Mirrors `Volume::read_dat_slice` for a remote-only backend, but holds no /// volume/store lock so callers can stream off the store lock entirely. pub(crate) fn read_slice(&self, offset: u64, size: usize) -> io::Result> { if size == 0 || offset >= self.file_size { return Ok(Vec::new()); } let read_len = std::cmp::min(size as u64, self.file_size - offset) as usize; let mut buf = vec![0u8; read_len]; self.read_exact_at(&mut buf, offset)?; Ok(buf) } pub(crate) fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> io::Result<()> { let data = self .backend .read_range_blocking(&self.key, offset, buf.len()) .map_err(io::Error::other)?; if data.len() != buf.len() { return Err(io::Error::new( io::ErrorKind::UnexpectedEof, format!( "remote read short read at offset {}: got {}, expected {}", offset, data.len(), buf.len() ), )); } buf.copy_from_slice(&data); Ok(()) } } // ============================================================================ // Volume // ============================================================================ pub struct Volume { pub id: VolumeId, dir: String, dir_idx: String, pub collection: String, dat_file: Option, remote_dat_file: Option, nm: Option, /// Make the next .dat or .idx flush fail, so tests can exercise the durable /// write's failure paths without a real disk fault. #[cfg(test)] fail_fsync_for_test: bool, #[cfg(test)] fail_idx_sync_for_test: bool, #[cfg(test)] fail_truncate_for_test: bool, /// Needle ids whose .dat append fails with a media error. #[cfg(test)] fail_append_for_test: HashSet, #[cfg(test)] dat_syncs_for_test: std::sync::atomic::AtomicUsize, #[cfg(test)] idx_syncs_for_test: std::sync::atomic::AtomicUsize, needle_map_kind: NeedleMapKind, data_file_access_control: Arc, pub super_block: SuperBlock, no_write_or_delete: bool, no_write_can_delete: bool, /// Set when a failed recovery leaves the .dat/index pair unverified: all /// I/O is refused and a `.unavailable` marker keeps the volume quarantined /// across restarts. Mirrors Go's ioUnavailable. io_unavailable: Arc, /// Shared flag from the parent DiskLocation indicating low disk space. /// Matches Go's `v.location.isDiskSpaceLow` checked in `IsReadOnly()`. pub location_disk_space_low: Arc, last_modified_ts_seconds: u64, last_append_at_ns: u64, pub last_disk_check_ns: Arc, // for phantom volume detection cache last_compact_index_offset: u64, last_compact_revision: u16, /// Shared with an in-flight `CompactionJob`, which runs off the store lock. is_compacting: Arc, /// Compaction speed limit in bytes per second (0 = unlimited). pub compaction_byte_per_second: i64, /// Consecutive storage-media errors and the quarantine they lead to, /// for volume health monitoring. io_errors: Arc, /// Protobuf VolumeInfo for tiered storage (.vif file). /// /// Private: `volume_info.files` and the write mode derived from it are the /// same fact, so outside callers edit the list through /// [`Volume::update_remote_files`] and read it through /// [`Volume::volume_info`]. volume_info: PbVolumeInfo, } /// What a volume is created with beyond its id, directories and index kind: /// the tail of Go's `NewVolume` argument list. The default is an empty /// collection with no replication, no TTL and no preallocation at the /// current needle version, which is what most tests want. #[derive(Clone, Copy, Debug)] pub struct VolumeSpec<'a> { pub collection: &'a str, pub replica_placement: Option, pub ttl: Option, /// Bytes to reserve for the .dat up front; 0 grows on demand. pub preallocate: u64, pub version: Version, } impl Default for VolumeSpec<'_> { fn default() -> Self { VolumeSpec { collection: "", replica_placement: None, ttl: None, preallocate: 0, version: Version::current(), } } } impl Volume { /// Create and load a volume from disk. pub fn new( dirname: &str, dir_idx: &str, id: VolumeId, needle_map_kind: NeedleMapKind, spec: &VolumeSpec<'_>, ) -> Result { let VolumeSpec { collection, replica_placement, ttl, preallocate, version, } = *spec; let mut v = Volume { id, dir: dirname.to_string(), dir_idx: dir_idx.to_string(), collection: collection.to_string(), dat_file: None, remote_dat_file: None, #[cfg(test)] fail_fsync_for_test: false, #[cfg(test)] fail_idx_sync_for_test: false, #[cfg(test)] fail_truncate_for_test: false, #[cfg(test)] fail_append_for_test: HashSet::new(), #[cfg(test)] dat_syncs_for_test: Default::default(), #[cfg(test)] idx_syncs_for_test: Default::default(), nm: None, needle_map_kind, data_file_access_control: Arc::new(DataFileAccessControl::default()), super_block: SuperBlock { replica_placement: replica_placement.unwrap_or_default(), ttl: ttl.unwrap_or(crate::storage::needle::ttl::TTL::EMPTY), ..SuperBlock::default() }, no_write_or_delete: false, no_write_can_delete: false, io_unavailable: Arc::default(), location_disk_space_low: Arc::new(AtomicBool::new(false)), last_modified_ts_seconds: 0, last_append_at_ns: 0, last_disk_check_ns: Arc::new(std::sync::atomic::AtomicI64::new(0)), last_compact_index_offset: 0, last_compact_revision: 0, is_compacting: Arc::new(AtomicBool::new(false)), compaction_byte_per_second: 0, io_errors: Arc::default(), volume_info: PbVolumeInfo::default(), }; v.load(true, true, preallocate, version)?; Ok(v) } /// Build a minimal, unloaded Volume holding only the identity/path fields /// reconcile_compact_state needs. Used by the disk-location load pre-pass to /// recover an interrupted commit before the volume itself is loaded. pub fn new_unloaded(dirname: &str, dir_idx: &str, collection: &str, id: VolumeId) -> Self { Volume { id, dir: dirname.to_string(), dir_idx: dir_idx.to_string(), collection: collection.to_string(), dat_file: None, remote_dat_file: None, #[cfg(test)] fail_fsync_for_test: false, #[cfg(test)] fail_idx_sync_for_test: false, #[cfg(test)] fail_truncate_for_test: false, #[cfg(test)] fail_append_for_test: HashSet::new(), #[cfg(test)] dat_syncs_for_test: Default::default(), #[cfg(test)] idx_syncs_for_test: Default::default(), nm: None, needle_map_kind: NeedleMapKind::InMemory, data_file_access_control: Arc::new(DataFileAccessControl::default()), super_block: SuperBlock::default(), no_write_or_delete: false, no_write_can_delete: false, io_unavailable: Arc::default(), location_disk_space_low: Arc::new(AtomicBool::new(false)), last_modified_ts_seconds: 0, last_append_at_ns: 0, last_disk_check_ns: Arc::new(std::sync::atomic::AtomicI64::new(0)), last_compact_index_offset: 0, last_compact_revision: 0, is_compacting: Arc::new(AtomicBool::new(false)), compaction_byte_per_second: 0, io_errors: Arc::default(), volume_info: PbVolumeInfo::default(), } } /// Identifies this volume instance: a re-created or remounted volume gets /// a new one, even at the same compaction revision. pub(crate) fn instance(&self) -> Arc { self.data_file_access_control.clone() } pub(crate) fn is_instance(&self, instance: &Arc) -> bool { Arc::ptr_eq(instance, &self.data_file_access_control) } /// Returns true if the volume is currently being compacted. pub fn is_compacting(&self) -> bool { self.is_compacting.load(Ordering::Acquire) } pub(crate) fn compacting_error(&self) -> VolumeError { VolumeError::Io(io::Error::other(format!( "volume {} is compacting", self.id ))) } // ---- File naming (matching Go) ---- /// Base filename: dir/collection_id or dir/id pub fn data_file_name(&self) -> String { volume_file_name(&self.dir, &self.collection, self.id) } pub fn index_file_name(&self) -> String { volume_file_name(&self.dir_idx, &self.collection, self.id) } pub fn file_name(&self, ext: &str) -> String { match ext { ".idx" | ".cpx" | ".ldb" | ".cpldb" | ".rdb" => { format!("{}{}", self.index_file_name(), ext) } _ => { format!("{}{}", self.data_file_name(), ext) } } } pub fn version(&self) -> Version { if self.volume_info.version != 0 { Version(self.volume_info.version as u8) } else { self.super_block.version } } // ---- Loading ---- fn load( &mut self, also_load_index: bool, create_dat_if_missing: bool, preallocate: u64, version: Version, ) -> Result<(), VolumeError> { let dat_path = self.file_name(".dat"); let mut already_has_super_block = false; let has_volume_info_file = self.load_vif()?; if self.volume_info.read_only && !self.has_remote_file() { if self.volume_info.read_only_can_delete { self.no_write_can_delete = true; } else { self.no_write_or_delete = true; } } if self.has_remote_file() { self.load_remote_dat_file()?; if let Some(remote_file) = self.volume_info.files.first() { if remote_file.modified_time > 0 { self.last_modified_ts_seconds = remote_file.modified_time; } else if let Ok(metadata) = fs::metadata(self.vif_path()) { self.last_modified_ts_seconds = metadata .modified() .unwrap_or(SystemTime::UNIX_EPOCH) .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_secs(); } } already_has_super_block = true; } else if Path::new(&dat_path).exists() { let metadata = fs::metadata(&dat_path)?; // Try to open read-write; fall back to read-only match open_volume_file(OpenOptions::new().read(true).write(true), &dat_path) { Ok(file) => { self.dat_file = Some(file); } Err(e) if e.kind() == io::ErrorKind::PermissionDenied => { self.dat_file = Some(open_volume_file(OpenOptions::new().read(true), &dat_path)?); self.no_write_or_delete = true; } Err(e) => return Err(e.into()), } self.last_modified_ts_seconds = metadata .modified() .unwrap_or(SystemTime::UNIX_EPOCH) .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_secs(); if metadata.len() >= SUPER_BLOCK_SIZE as u64 { already_has_super_block = true; } } else if create_dat_if_missing { // Create directory if needed if let Some(parent) = Path::new(&dat_path).parent() { fs::create_dir_all(parent)?; } let file = open_volume_file( OpenOptions::new().read(true).write(true).create(true), &dat_path, )?; if preallocate > 0 { preallocate_file(&file, preallocate); } self.dat_file = Some(file); } else { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::NotFound, format!("volume data file {} does not exist", dat_path), ))); } if already_has_super_block { match self.read_super_block() { Ok(()) => { if !self.super_block.version.is_supported() { return Err(VolumeError::UnsupportedVersion(self.super_block.version.0)); } // Match Go: v.volumeInfo.Version = uint32(v.SuperBlock.Version) self.volume_info.version = self.super_block.version.0 as u32; } Err(e) if self.has_remote_file() => { warn!( volume_id = self.id.0, error = %e, "failed to read remote super block during load" ); } Err(e) => return Err(e), } } else { self.maybe_write_super_block(version)?; } if also_load_index { // Adjust for existing volumes with .idx together with .dat files: // an index already beside the data keeps serving after --dir.idx // named a different directory. if self.dir_idx != self.dir && Path::new(&format!("{}.idx", self.data_file_name())).exists() { self.dir_idx = self.dir.clone(); } // A changed --dir.idx leaves the new directory without an index. // The .dat still holds every row, so rebuild rather than mount the // volume with every needle invisible. if !self.has_remote_file() && !Path::new(&self.file_name(".idx")).exists() && self.current_dat_file_size()? > SUPER_BLOCK_SIZE as u64 { self.rebuild_idx_file()?; info!( volume_id = self.id.0, idx = %self.file_name(".idx"), "rebuilt the index from the data file" ); } // Recover rows that deletes on a tiered read-only volume overwrote // at the front of .idx. Best effort: a volume that cannot be // repaired is still servable for everything the surviving rows // index. match self.repair_idx_head_tombstones() { Ok(0) => {} Ok(restored) => info!( volume_id = self.id.0, restored, "recovered overwritten .idx rows from .dat" ), Err(e) => warn!( volume_id = self.id.0, error = %e, "recover overwritten .idx rows" ), } self.load_index()?; // Match Go: CheckVolumeDataIntegrity after loading index (volume_loading.go L154-159) // Only for non-remote volumes (remote storage may not have local .dat) if !self.has_remote_file() { if let Err(e) = self.check_volume_data_integrity() { self.no_write_or_delete = true; warn!( volume_id = self.id.0, error = %e, "volumeDataIntegrityChecking failed" ); } self.recover_last_modified_ts(); // Structural check: no .idx entry may reference bytes past the // end of .dat. The needle map's load walk above already // populated max_needle_end, so this is a numeric comparison // — no extra disk I/O. A violation marks the volume read-only // so vacuum doesn't silently drop reachable data based on a // corrupt .idx left over from a crashed batched write. if let Some(ref nm) = self.nm && let Ok(dat_size) = self.current_dat_file_size() { let max_end = nm.max_needle_end(); if dat_size > 0 && max_end > dat_size as i64 { self.no_write_or_delete = true; warn!( volume_id = self.id.0, max_needle_end = max_end, dat_size, "idx references bytes past end of .dat; marking volume read-only" ); } } } } self.restore_unavailable(); // Match Go: if no .vif file existed, create one with version and bytes_offset if !has_volume_info_file { self.volume_info.version = self.super_block.version.0 as u32; self.volume_info.bytes_offset = OFFSET_SIZE as u32; if let Err(e) = self.save_volume_info() { warn!( volume_id = self.id.0, error = %e, "failed to save volume info" ); } } Ok(()) } fn nm_or_not_found(&self) -> Result<&NeedleMap, VolumeError> { self.nm.as_ref().ok_or_else(|| { tracing::warn!(volume_id = self.id.0, "needle map not loaded"); VolumeError::NotFound }) } fn load_index(&mut self) -> Result<(), VolumeError> { let use_redb = matches!( self.needle_map_kind, NeedleMapKind::Redb | NeedleMapKind::RedbMedium | NeedleMapKind::RedbLarge ); let idx_path = self.file_name(".idx"); // Ensure idx directory exists if let Some(parent) = Path::new(&idx_path).parent() { fs::create_dir_all(parent)?; } // Go picks the sorted-file map for both read-only modes, which is every // cloud-tiered volume: the index stays on disk in .sdx instead of in // RAM, and nothing is held open between lookups. if self.use_sorted_index() { self.load_index_sorted_file(&idx_path)?; } else if use_redb { self.load_index_redb(&idx_path)?; } else { self.load_index_inmemory(&idx_path)?; } Ok(()) } /// Whether this volume's index belongs in a `.sdx`. Mirrors Go's /// `v.noWriteOrDelete || v.noWriteCanDelete` branch in volume_loading.go — /// a tiered volume is always the second of the two. fn use_sorted_index(&self) -> bool { self.no_write_or_delete || self.no_write_can_delete } /// Load the on-disk sorted index for a read-only or cloud-tiered volume. fn load_index_sorted_file(&mut self, idx_path: &str) -> Result<(), VolumeError> { if !Path::new(idx_path).exists() { // Missing .idx with existing .dat could orphan needles let dat_path = self.file_name(".dat"); if Path::new(&dat_path).exists() { let dat_size = fs::metadata(&dat_path).map(|m| m.len()).unwrap_or(0); if dat_size > SUPER_BLOCK_SIZE as u64 { warn!( volume_id = self.id.0, ".idx file missing but .dat exists with data; needles may be orphaned" ); } } // Go opens .idx with O_CREATE only where deletes are allowed; an // empty index yields an empty .sdx and a volume that still mounts. // A volume that takes neither writes nor deletes must not write // here, since its index directory can sit on a read-only mount. if !self.no_write_or_delete { File::create(idx_path)?; } } // Building .sdx writes to the index directory. Where that cannot be // done — a read-only mount, a full disk — keep this volume's index in // memory rather than failing the load and taking its data offline. match SortedFileNeedleMap::open(&self.index_file_name(), self.version()) { Ok(nm) => { self.nm = Some(NeedleMap::SortedFile(nm)); Ok(()) } Err(e) => { warn!( volume_id = self.id.0, error = %e, "cannot build the sorted index; keeping this volume's index in memory" ); match self.load_index_inmemory(idx_path) { Ok(()) => Ok(()), // Where deletes are allowed the in-memory loader opens .idx // read-write, which fails on the same directory that just // refused the .sdx. Give up the deletes rather than the // volume: without a writer no tombstone could be recorded // anyway, so refusing them is the honest answer, and a // remount on a writable directory restores them. Err(retry_err) if !self.no_write_or_delete => { warn!( volume_id = self.id.0, error = %retry_err, "cannot open the index for write; serving this volume without deletes" ); self.no_write_or_delete = true; // Deletes are gone with the writer, so stop advertising // them: leaving no_write_can_delete set would report // this volume as delete-capable in metrics and mode // checks while every delete is refused. self.no_write_can_delete = false; self.load_index_inmemory(idx_path) } Err(retry_err) => Err(retry_err), } } } } /// Load index using in-memory CompactNeedleMap. fn load_index_inmemory(&mut self, idx_path: &str) -> Result<(), VolumeError> { if self.no_write_or_delete { // Open read-only if Path::new(&idx_path).exists() { let mut idx_file = open_volume_file(OpenOptions::new().read(true), idx_path)?; let nm = CompactNeedleMap::load_from_idx(&mut idx_file, self.version())?; self.nm = Some(NeedleMap::InMemory(nm)); } else { // Missing .idx with existing .dat could orphan needles let dat_path = self.file_name(".dat"); if Path::new(&dat_path).exists() { let dat_size = fs::metadata(&dat_path).map(|m| m.len()).unwrap_or(0); if dat_size > SUPER_BLOCK_SIZE as u64 { warn!( volume_id = self.id.0, ".idx file missing but .dat exists with data; needles may be orphaned" ); } } self.nm = Some(NeedleMap::InMemory(CompactNeedleMap::new())); } } else { // Open read-write (create if missing) let idx_file = open_volume_file( OpenOptions::new().read(true).write(true).create(true), idx_path, )?; let idx_size = trim_torn_idx_tail(&idx_file, idx_path)?; let mut idx_reader = io::BufReader::new(&idx_file); let mut nm = CompactNeedleMap::load_from_idx(&mut idx_reader, self.version())?; // Re-open for positioned writes: rows are written at // idx_file_offset so a torn tail can be trimmed (an append-mode // handle cannot set_len on Windows). let write_file = OpenOptions::new().write(true).open(idx_path)?; nm.set_idx_file(Box::new(write_file), idx_size); self.nm = Some(NeedleMap::InMemory(nm)); } Ok(()) } /// Load index using disk-backed RedbNeedleMap. fn load_index_redb(&mut self, idx_path: &str) -> Result<(), VolumeError> { // The redb database file is stored alongside the volume files let rdb_path = self.file_name(".rdb"); // One redb database per volume: keep its page cache small, or the // process grows by up to redb's 1 GiB default per volume (#11179). let cache_bytes = self.needle_map_kind.redb_cache_bytes(); if self.no_write_or_delete { // Open read-only if Path::new(&idx_path).exists() { let mut idx_file = open_volume_file(OpenOptions::new().read(true), idx_path)?; let nm = RedbNeedleMap::load_from_idx( &rdb_path, &mut idx_file, self.version(), cache_bytes, )?; self.nm = Some(NeedleMap::Redb(nm)); } else { // Missing .idx with existing .dat could orphan needles let dat_path = self.file_name(".dat"); if Path::new(&dat_path).exists() { let dat_size = fs::metadata(&dat_path).map(|m| m.len()).unwrap_or(0); if dat_size > SUPER_BLOCK_SIZE as u64 { warn!( volume_id = self.id.0, ".idx file missing but .dat exists with data; needles may be orphaned" ); } } self.nm = Some(NeedleMap::Redb(RedbNeedleMap::new(&rdb_path, cache_bytes)?)); } } else { // Open read-write (create if missing) let idx_file = open_volume_file( OpenOptions::new().read(true).write(true).create(true), idx_path, )?; let idx_size = trim_torn_idx_tail(&idx_file, idx_path)?; let mut idx_reader = io::BufReader::new(&idx_file); let mut nm = RedbNeedleMap::load_from_idx( &rdb_path, &mut idx_reader, self.version(), cache_bytes, )?; // Re-open for positioned writes: rows are written at // idx_file_offset so a torn tail can be trimmed (an append-mode // handle cannot set_len on Windows). let write_file = OpenOptions::new().write(true).open(idx_path)?; nm.set_idx_file(Box::new(write_file), idx_size); self.nm = Some(NeedleMap::Redb(nm)); } Ok(()) } pub(crate) fn load_remote_dat_file(&mut self) -> Result<(), VolumeError> { let (storage_name, storage_key) = self.remote_storage_name_key(); let backend = crate::remote_storage::s3_tier::global_s3_tier_registry() .read() .unwrap() .get(&storage_name) .ok_or_else(|| { VolumeError::Io(io::Error::new( io::ErrorKind::NotFound, format!("remote tier backend {} not found", storage_name), )) })?; let remote_file = self.volume_info.files.first().ok_or_else(|| { VolumeError::Io(io::Error::new( io::ErrorKind::NotFound, "remote volume has no remote file entries", )) })?; let file_size = if remote_file.file_size > 0 { remote_file.file_size } else if self.volume_info.dat_file_size > 0 { self.volume_info.dat_file_size as u64 } else { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!("remote volume {} is missing file size metadata", self.id.0), ))); }; self.dat_file = None; self.remote_dat_file = Some(RemoteDatFile { backend, key: storage_key, file_size, modified_time: remote_file.modified_time, }); Ok(()) } pub(crate) fn read_exact_at_backend( &self, buf: &mut [u8], offset: u64, ) -> Result<(), VolumeError> { if let Some(dat_file) = self.dat_file.as_ref() { read_exact_at(dat_file, buf, offset)?; Ok(()) } else if let Some(remote_dat_file) = self.remote_dat_file.as_ref() { remote_dat_file.read_exact_at(buf, offset)?; Ok(()) } else { Err(VolumeError::Io(io::Error::other("dat file not open"))) } } /// Returns true when the volume has a data backend (local .dat file or /// remote tiered storage). Mirrors Go's `v.DataBackend != nil` check. pub fn has_data_backend(&self) -> bool { self.dat_file.is_some() || self.remote_dat_file.is_some() } pub(crate) fn current_dat_file_size(&self) -> io::Result { if let Some(ref f) = self.dat_file { Ok(f.metadata()?.len()) } else if let Some(ref remote_dat_file) = self.remote_dat_file { Ok(remote_dat_file.file_size) } else { Ok(0) } } /// Read a raw byte range from the current .dat backend. /// /// This matches Go paths that stream directly from `DataBackend`, including /// remote-only tiered volumes whose `.dat` is no longer present locally. pub fn read_dat_slice(&self, offset: u64, size: usize) -> Result, VolumeError> { let _guard = self.data_file_access_control.read_lock(); if let Some(e) = self.unavailable_error() { return Err(e); } let dat_size = self.current_dat_file_size()?; if size == 0 || offset >= dat_size { return Ok(Vec::new()); } let read_len = std::cmp::min(size as u64, dat_size - offset) as usize; let mut buf = vec![0u8; read_len]; self.read_exact_at_backend(&mut buf, offset)?; Ok(buf) } /// Clone the remote backend handle (cheap: an `Arc` plus key/size) so a /// caller can stream a tiered `.dat` from S3 after dropping the store lock. /// Returns `None` for local volumes. `has_remote_file()` implies `dat_file` /// is `None`, so this selects the same backend `read_dat_slice` would. pub(crate) fn remote_dat_file(&self) -> Option { self.remote_dat_file.clone() } // ---- SuperBlock I/O ---- fn read_super_block(&mut self) -> Result<(), VolumeError> { let mut header = [0u8; SUPER_BLOCK_SIZE]; self.read_exact_at_backend(&mut header, 0)?; let extra_size = u16::from_be_bytes([header[6], header[7]]); let total_size = SUPER_BLOCK_SIZE + extra_size as usize; let mut full_buf = vec![0u8; total_size]; full_buf[..SUPER_BLOCK_SIZE].copy_from_slice(&header); if extra_size > 0 { self.read_exact_at_backend(&mut full_buf[SUPER_BLOCK_SIZE..], SUPER_BLOCK_SIZE as u64)?; } self.super_block = SuperBlock::from_bytes(&full_buf)?; // Match Go: if volumeInfo.Replication is set, override super block's ReplicaPlacement if !self.volume_info.replication.is_empty() { let rp = ReplicaPlacement::from_string(&self.volume_info.replication)?; self.super_block.replica_placement = rp; } Ok(()) } fn maybe_write_super_block(&mut self, version: Version) -> Result<(), VolumeError> { let dat_file = self .dat_file .as_mut() .ok_or_else(|| VolumeError::Io(io::Error::other("dat file not open")))?; let dat_size = dat_file.metadata()?.len(); if dat_size == 0 { if !version.is_supported() { return Err(VolumeError::UnsupportedVersion(version.0)); } self.super_block.version = version; let bytes = self.super_block.to_bytes(); dat_file.seek(SeekFrom::Start(0))?; dat_file.write_all(&bytes)?; dat_file.sync_all()?; } Ok(()) } // ---- Read ---- /// Read a needle by its ID from the volume. pub fn read_needle(&self, n: &mut Needle) -> Result { let mut read_option = ReadOption::default(); self.read_needle_with_option(n, &mut read_option) } pub fn read_needle_opt(&self, n: &mut Needle, read_deleted: bool) -> Result { let mut read_option = ReadOption { read_deleted, ..ReadOption::default() }; self.read_needle_with_option(n, &mut read_option) } pub fn read_needle_with_option( &self, n: &mut Needle, read_option: &mut ReadOption, ) -> Result { let _guard = self.data_file_access_control.read_lock(); if let Some(e) = self.unavailable_error() { return Err(e); } let nm = self.nm_or_not_found()?; let nv = nm.get(n.id)?.ok_or(VolumeError::NotFound)?; if nv.offset.is_zero() { return Err(VolumeError::NotFound); } let mut read_size = nv.size; if read_size.is_deleted() { if read_option.read_deleted && !read_size.is_tombstone() { // Negate to get original size read_size = Size(-read_size.0); } else { return Err(VolumeError::Deleted); } } if read_size.0 == 0 { return Ok(0); } match self.read_needle_data_at_unlocked( n, nv.offset.to_actual_offset(), read_size, read_option, ) { Ok(()) => self.check_read_write_error(None), Err(VolumeError::Io(ref e)) => { self.check_read_write_error(Some(e)); return Err(VolumeError::Io(io::Error::new(e.kind(), e.to_string()))); } Err(e) => return Err(e), } if needle_expired(n) { return Err(VolumeError::NotFound); } Ok(n.data_size as i32) } /// Read needle data from .dat file at given offset. pub fn read_needle_data_at( &self, n: &mut Needle, offset: i64, size: Size, ) -> Result<(), VolumeError> { let _guard = self.data_file_access_control.read_lock(); if let Some(e) = self.unavailable_error() { return Err(e); } let mut read_option = ReadOption::default(); self.read_needle_data_at_unlocked(n, offset, size, &mut read_option) } fn read_needle_data_at_unlocked( &self, n: &mut Needle, offset: i64, size: Size, _read_option: &mut ReadOption, ) -> Result<(), VolumeError> { read_needle_with( |buf, at| self.read_exact_at_backend(buf, at), n, offset, size, self.version(), ) } /// Read raw needle blob at a specific offset. pub fn read_needle_blob(&self, offset: i64, size: Size) -> Result, VolumeError> { let _guard = self.data_file_access_control.read_lock(); if let Some(e) = self.unavailable_error() { return Err(e); } self.read_needle_blob_unlocked(offset, size) } fn read_needle_blob_unlocked(&self, offset: i64, size: Size) -> Result, VolumeError> { let version = self.version(); // Storage guard: negativity-only (Go parity). See parse_needle_at. if size.0 < 0 { return Err(VolumeError::Io(std::io::Error::new( std::io::ErrorKind::InvalidData, format!("invalid needle size {}", size.0), ))); } let actual_size = get_actual_size(size, version); let mut buf = vec![0u8; actual_size as usize]; self.read_exact_at_backend(&mut buf, offset as u64)?; Ok(buf) } /// Read needle metadata at a specific offset without loading the data payload. /// /// Matches Go's `readNeedleMetaAt`, including the tombstone path where a /// deleted idx entry passes a negative size and the tombstone record itself /// is read as size 0 metadata. pub fn read_needle_meta_at( &self, n: &mut Needle, offset: i64, size: Size, ) -> Result<(), VolumeError> { let _guard = self.data_file_access_control.read_lock(); if let Some(e) = self.unavailable_error() { return Err(e); } self.read_needle_meta_at_unlocked(n, offset, size) } fn read_needle_meta_at_unlocked( &self, n: &mut Needle, offset: i64, size: Size, ) -> Result<(), VolumeError> { let normalized_size = if size.is_deleted() { Size(0) } else { size }; let read_at = |buf: &mut [u8], at: u64| self.read_exact_at_backend(buf, at); let version = self.version(); let mut offset = offset; with_offset_retry(&mut offset, |off| { Self::read_needle_meta_blob_and_parse(read_at, n, off, normalized_size, version) }) } fn read_needle_meta_blob_and_parse( read_at: impl Fn(&mut [u8], u64) -> Result<(), VolumeError>, n: &mut Needle, offset: i64, size: Size, version: Version, ) -> Result<(), VolumeError> { // Step 1: Read only the first 20 bytes (header + DataSize). // Matches Go's ReadNeedleMeta which reads NeedleHeaderSize+DataSizeSize first. const HEADER_PREFIX: usize = NEEDLE_HEADER_SIZE + DATA_SIZE_SIZE; // 20 let mut header_buf = [0u8; HEADER_PREFIX]; #[cfg(test)] needle_read_hook::fire(n.id, header_buf.len()); read_at(&mut header_buf, offset as u64)?; // Parse header to get the needle's Size field for validation let (_, _, found_size) = Needle::parse_header(&header_buf); if found_size != size { return Err(VolumeError::Needle(NeedleError::SizeMismatch { offset, id: n.id, found: found_size, expected: size, })); } // Step 2: Calculate how much meta tail to read (skip the data payload) let actual_size = get_actual_size(size, version); if size.0 == 0 || version == VERSION_1 { // Tombstone or V1: no body data section, tail starts right after header let meta_size = actual_size - NEEDLE_HEADER_SIZE as i64; if !(0..=128 * 1024).contains(&meta_size) { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "invalid needle meta size {}: DataSize=0, size={}, offset={}", meta_size, size.0, offset ), ))); } let mut meta_buf = vec![0u8; meta_size as usize]; #[cfg(test)] needle_read_hook::fire(n.id, meta_buf.len()); read_at(&mut meta_buf, (offset + NEEDLE_HEADER_SIZE as i64) as u64)?; n.read_paged_meta(&header_buf, &meta_buf, offset, size, version)?; } else { // V2/V3: extract DataSize from bytes 16..20 let data_size = u32::from_be_bytes([ header_buf[NEEDLE_HEADER_SIZE], header_buf[NEEDLE_HEADER_SIZE + 1], header_buf[NEEDLE_HEADER_SIZE + 2], header_buf[NEEDLE_HEADER_SIZE + 3], ]); // Skip past: header(16) + DataSize(4) + data(data_size) let start_offset = offset + NEEDLE_HEADER_SIZE as i64 + DATA_SIZE_SIZE as i64 + data_size as i64; let stop_offset = offset + actual_size; let meta_size = stop_offset - start_offset; // Sanity check: reject metadata sizes > 128KB (matching Go's ReadNeedleMeta guard) if !(0..=128 * 1024).contains(&meta_size) { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "invalid needle meta size {}: DataSize={}, size={}, offset={}", meta_size, data_size, size.0, offset ), ))); } // Step 3: Read only the meta tail (skip the data payload entirely) let mut meta_buf = vec![0u8; meta_size as usize]; #[cfg(test)] needle_read_hook::fire(n.id, meta_buf.len()); read_at(&mut meta_buf, start_offset as u64)?; n.read_paged_meta(&header_buf, &meta_buf, offset, size, version)?; } Ok(()) } /// Resolve a needle read under the caller's store guard, without data I/O. pub(crate) fn needle_read_plan( &self, id: NeedleId, read_deleted: bool, ) -> Result { if let Some(e) = self.unavailable_error() { return Err(e); } let nm = self.nm_or_not_found()?; let nv = nm.get(id)?.ok_or(VolumeError::NotFound)?; if nv.offset.is_zero() { return Err(VolumeError::NotFound); } let mut size = nv.size; if size.is_deleted() { if read_deleted && !size.is_tombstone() { debug!("reading deleted {}", id); crate::metrics::HANDLER_COUNTER .with_label_values(&[crate::metrics::READ_DELETED_NEEDLE]) .inc(); size = Size(-size.0); } else { return Err(VolumeError::Deleted); } } if size.0 == 0 { return Err(VolumeError::NotFound); } Ok(NeedleReadPlan { source: self.read_source()?, offset: nv.offset.to_actual_offset(), size, version: self.version(), needle_id: id, data_file_access_control: self.data_file_access_control.clone(), io_errors: self.io_errors.clone(), io_unavailable: self.io_unavailable.clone(), }) } /// A read handle on the data backend that stays valid without the guard. fn read_source(&self) -> Result { if self.dat_file.is_some() { // A fresh open, not `try_clone`: a duplicated handle shares the // file position, and on Windows `read_exact_at` goes through // `seek_read`, which moves it under a concurrent append. Opened // while the caller's guard excludes a vacuum swap, the path names // the inode `dat_file` holds. Ok(NeedleStreamSource::Local(open_volume_file( OpenOptions::new().read(true), self.file_name(".dat"), )?)) } else if let Some(remote) = self.remote_dat_file() { Ok(NeedleStreamSource::Remote(remote)) } else { Err(VolumeError::Io(io::Error::other("dat file not open"))) } } // ---- Write ---- /// Write a needle to the volume (synchronous path). /// /// With `fsync` the write is only reported successful once both the .dat /// record and the .idx row that indexes it are on disk, so an ack survives a /// crash rather than sitting in the page cache. The two flushes fail /// differently: a failed .dat flush happens before anything is published, so /// it takes its own append back off the end and nobody else's, while a /// failed .idx flush cannot be undone and stops the volume taking writes. pub fn write_needle( &mut self, n: &mut Needle, check_cookie: bool, fsync: bool, ) -> Result<(u64, Size, bool), VolumeError> { let _guard = self.data_file_access_control.write_lock(); self.check_writable()?; self.do_write_request(n, check_cookie, fsync) } /// Write a batch of needles the way Go's processBatch does: one .dat /// sync and one .idx sync per run of distinct needle ids that holds a /// durable write, instead of two per durable needle. Nothing in such a /// run is published before its sync, so a failed sync takes the whole /// run back off the .dat and fails every entry. A durable entry that /// fails to index stops the volume taking writes, and the entries after /// it in the run are refused read only. A repeated id starts a new run, /// so its dedup and cookie checks see the earlier write. pub fn write_needles_grouped( &mut self, writes: &mut [(Needle, bool)], ) -> Vec> { let _guard = self.data_file_access_control.write_lock(); let mut results = Vec::with_capacity(writes.len()); let mut rest = writes; while !rest.is_empty() { let mut ids = HashSet::new(); let len = rest.iter().take_while(|(n, _)| ids.insert(n.id)).count(); let (run, tail) = std::mem::take(&mut rest).split_at_mut(len); if run.iter().any(|(_, fsync)| *fsync) { results.extend(self.write_synced_run(run)); } else { for (n, _) in run.iter_mut() { results.push( self.check_writable() .and_then(|()| self.do_write_request(n, true, false)), ); } } rest = tail; } results } fn write_synced_run( &mut self, run: &mut [(Needle, bool)], ) -> Vec> { // Per entry: Some(offset) once appended, None when it dedups. let mut staged = Vec::with_capacity(run.len()); // Per entry: the I/O error streak once it is staged, where a write // sent on its own would have recorded its success. let mut marks = Vec::with_capacity(run.len()); let mut last_append_at_ns = self.last_append_at_ns; let mut run_start = None; let mut sync = false; for (n, fsync) in run.iter_mut() { let r = self.append_unpublished(n, &mut last_append_at_ns); marks.push(self.io_errors.mark()); if let Ok(Some(offset)) = r { run_start.get_or_insert(offset); } // Only a durable entry that got this far needs the sync. sync |= *fsync && r.is_ok(); staged.push(r); } if sync && let Err(e) = self.flush_dat() { self.check_read_write_error(Some(&e)); if let Some(start) = run_start { self.undo_unsynced_append(start); } let e = VolumeError::Io(e); return staged .into_iter() .map(|r| r.and_then(|_| Err(run_error(&e)))) .collect(); } self.last_append_at_ns = last_append_at_ns; // A durable entry that fails to publish stops the volume taking // writes, so the entries after it are refused the way a lone // write would be. let mut refused = false; for ((n, fsync), r) in run.iter().zip(staged.iter_mut()) { if refused { *r = Err(self .check_writable() .err() .unwrap_or(VolumeError::ReadOnly(self.id))); } else if let Ok(Some(offset)) = *r && let Err(e) = self.publish_write(n, offset, *fsync) { *r = Err(e); refused = *fsync; } } if sync && let Err(e) = self.flush_idx() { return staged .into_iter() .map(|r| r.and_then(|_| Err(run_error(&e)))) .collect(); } let written = run .iter() .zip(&staged) .filter(|(_, r)| matches!(r, Ok(Some(_)))) .map(|((n, _), _)| n.last_modified) .max(); let last = staged.iter().rposition(|r| matches!(r, Ok(Some(_)))); if let (Some(last_modified), Some(last)) = (written, last) { // Sent one at a time, the last write to land would have cleared // the streak of the appends before it, and the ones after it // would have failed on top of that. self.finish_write(last_modified, sync, marks[last]); } run.iter() .zip(staged) .map(|((n, _), r)| { let size = Size(n.data_size as i32); r.map(|staged| match staged { Some(offset) => (offset, size, false), None => (0, size, true), }) }) .collect() } /// The checks and the append for one entry of a synced run, leaving the /// publish to the caller. Returns the offset, or None when it dedups. fn append_unpublished( &mut self, n: &mut Needle, last_append_at_ns: &mut u64, ) -> Result, VolumeError> { self.check_writable()?; if self.prepare_write(n, true)? { return Ok(None); } n.append_at_ns = get_append_at_ns(*last_append_at_ns); let (offset, _, _) = self.append_needle(n)?; *last_append_at_ns = n.append_at_ns; Ok(Some(offset)) } fn check_writable(&self) -> Result<(), VolumeError> { if let Some(e) = self.unavailable_error() { return Err(e); } if self.is_read_only() { return Err(VolumeError::ReadOnly(self.id)); } Ok(()) } /// Flush the .dat, the first half of a durable write. The .idx is flushed /// separately by flush_idx once the row is published; the two are split so /// nothing is indexed before the bytes it points at are down. fn flush_dat(&self) -> io::Result<()> { #[cfg(test)] self.dat_syncs_for_test.fetch_add(1, Ordering::Relaxed); #[cfg(test)] if self.fail_fsync_for_test { return Err(io::Error::other("injected fsync failure")); } match self.dat_file.as_ref() { Some(dat_file) => dat_file.sync_all(), None => Err(io::Error::other("dat file not open")), } } /// Flush the .idx, the second half of a durable write. load() rebuilds the /// map from .idx, not from .dat, so the row has to be down before the write /// is acked: lose it and the volume comes back with a .dat tail the /// integrity check cannot account for, and loads read only. /// /// By the time this runs the row is published and cannot be taken back - /// undoing it would mean writing to a disk that is already failing, and /// would leave an .idx row pointing past a truncated .dat. So a failure /// stops the volume taking writes instead: nothing more gets appended past a /// record whose index may not survive, and the master routes writes /// elsewhere once the volume heartbeats read only. fn flush_idx(&mut self) -> Result<(), VolumeError> { #[cfg(test)] self.idx_syncs_for_test.fetch_add(1, Ordering::Relaxed); #[cfg(test)] if self.fail_idx_sync_for_test { let e = io::Error::other("injected idx sync failure"); self.no_write_or_delete = true; return Err(VolumeError::Io(e)); } let synced = match self.nm.as_ref() { Some(nm) => nm.sync(), None => Ok(()), }; if let Err(e) = synced { self.check_read_write_error(Some(&e)); self.no_write_or_delete = true; tracing::error!( "volume {}: failed to flush the index after a durable write, \ marking read only: {}", self.id.0, e ); return Err(VolumeError::Io(e)); } Ok(()) } /// Take an unflushed append back off the .dat after its sync failed. fn truncate_dat(&self, len: u64) -> io::Result<()> { #[cfg(test)] if self.fail_truncate_for_test { return Err(io::Error::other("injected truncate failure")); } match self.dat_file.as_ref() { Some(dat_file) => dat_file.set_len(len), None => Ok(()), } } fn do_write_request( &mut self, n: &mut Needle, check_cookie: bool, fsync: bool, ) -> Result<(u64, Size, bool), VolumeError> { if self.prepare_write(n, check_cookie)? { // Nothing to append, but the write this matched may have been // non-durable, and the caller is asking for the content to be on // disk. Its .idx row can be sitting in the page cache too, so both // files get flushed exactly as they would for a fresh append. if fsync { self.flush_dat().map_err(|e| { self.check_read_write_error(Some(&e)); VolumeError::Io(e) })?; self.flush_idx()?; } return Ok((0, Size(n.data_size as i32), true)); } // Update append timestamp n.append_at_ns = get_append_at_ns(self.last_append_at_ns); // Append to .dat file let (offset, _body_size, _actual_size) = self.append_needle(n)?; // Nothing is published until the bytes are down: an index entry for an // unflushed append would resolve past the end of the file after a crash, // and undoing it afterwards would double-count the volume's metrics. if fsync && let Err(e) = self.flush_dat() { self.check_read_write_error(Some(&e)); self.undo_unsynced_append(offset); return Err(VolumeError::Io(e)); } self.last_append_at_ns = n.append_at_ns; self.publish_write(n, offset, fsync)?; if fsync { self.flush_idx()?; } self.finish_write(n.last_modified, fsync, self.io_errors.mark()); // Return Size(n.DataSize) as the logical size, matching Go's doWriteRequest Ok((offset, Size(n.data_size as i32), false)) } /// The checks a write passes before anything is appended: TTL /// inheritance, checksum, dedup and cookie. Returns true when the needle /// matches the stored copy and there is nothing to append. fn prepare_write(&self, n: &mut Needle, check_cookie: bool) -> Result { // TTL inheritance from volume (matching Go's writeNeedle2) { use crate::storage::needle::ttl::TTL; let needle_ttl = n.ttl.unwrap_or(TTL::EMPTY); if needle_ttl == TTL::EMPTY && self.super_block.ttl != TTL::EMPTY { n.set_has_ttl(); n.ttl = Some(self.super_block.ttl); } } // Ensure checksum is computed before dedup check if n.checksum == crate::storage::needle::crc::CRC(0) && !n.data.is_empty() { n.checksum = crate::storage::needle::crc::CRC::new(&n.data); } // Dedup check (matches Go: n.DataSize = oldNeedle.DataSize on dedup) if let Some(old_data_size) = self.is_file_unchanged(n) { n.data_size = old_data_size; return Ok(true); } // Cookie validation for existing needle (matches Go: check whenever nm.Get returns ok) if let Some(nm) = &self.nm && let Some(nv) = nm.get(n.id)? { let mut existing = Needle::default(); // Read only the header to check cookie self.read_needle_header_unlocked(&mut existing, nv.offset.to_actual_offset())?; if n.cookie.0 == 0 && !check_cookie { n.cookie = existing.cookie; } if existing.cookie != n.cookie { return Err(VolumeError::CookieMismatch(n.cookie.0)); } } Ok(false) } /// Take an append whose sync failed back off the .dat. fn undo_unsynced_append(&mut self, offset: u64) { if let Err(te) = self.truncate_dat(offset) { // The rejected record is still on the end. A later append // would bury it mid-file, where the .dat tail check cannot // see it, so the volume fails closed instead. self.mark_io_unavailable(format!( "failed to truncate back to {} after a failed fsync: {}", offset, te )); } } /// Index an appended needle. `fsync` means its record is already down. fn publish_write(&mut self, n: &Needle, offset: u64, fsync: bool) -> Result<(), VolumeError> { // Update needle map (uses n.size = full body size, matching Go's nm.Put) let prior = match self.nm.as_ref() { Some(nm) => nm.get(n.id), None => Ok(None), }; let should_update = match prior { Ok(Some(nv)) => (nv.offset.to_actual_offset() as u64) < offset, Ok(None) => true, Err(e) => { if fsync { // Leaves the same durable-but-unindexed record a failed put // below does, so it gets the same treatment. self.no_write_or_delete = true; tracing::error!( "volume {}: failed to read the prior mapping for a durable write at {}, \ marking read only: {}", self.id.0, offset, e ); } return Err(VolumeError::Io(e)); } }; if should_update { let indexed = match self.nm.as_mut() { Some(nm) => nm.put(n.id, Offset::from_actual_offset(offset as i64), n.size), None => Ok(()), }; if let Err(e) = indexed { if fsync { // The record is already down but nothing indexes it, the // same state a failed .idx flush leaves behind, so it gets // the same treatment rather than another write on top. self.no_write_or_delete = true; tracing::error!( "volume {}: failed to index a durable write at {}, \ marking read only: {}", self.id.0, offset, e ); } return Err(VolumeError::Io(e)); } } Ok(()) } /// The bookkeeping after a write is fully down. `landed_at` is the point /// in the I/O error streak where the write landed; errors counted after /// it, by later appends of the same run, are not cleared. fn finish_write(&mut self, last_modified: u64, idx_synced: bool, landed_at: StreakMark) { if self.last_modified_ts_seconds < last_modified { self.last_modified_ts_seconds = last_modified; } let checkpoint_ok = self.maybe_checkpoint_index(idx_synced); // Clear the EIO streak only after the full write (data + flush + // index + checkpoint) succeeds, so a failed fsync or checkpoint // does not get its EIO erased by the success reset. if checkpoint_ok { self.io_errors.record_success_at(landed_at); } } /// Take the index checkpoint the needle map asked for, data first: the /// checkpoint makes the index durable, and an index row that outlives /// the bytes it points at loads read-only (see load()). A failed .dat /// flush therefore skips the checkpoint; the map keeps asking, so it is /// retried on the next write. /// /// When `idx_already_synced` is true the .idx has already been fsynced by /// `flush_idx` on the fsync=true write path, so the checkpoint skips its /// own .idx fsync to avoid a redundant one. fn maybe_checkpoint_index(&mut self, idx_already_synced: bool) -> bool { let due = self.nm.as_ref().is_some_and(|nm| nm.checkpoint_due()); if !due { return true; } if let Err(e) = self.flush_dat() { self.check_read_write_error(Some(&e)); tracing::warn!( "volume {}: skipping index checkpoint, .dat flush failed: {}", self.id.0, e ); return false; } let checkpointed = match self.nm.as_mut() { Some(nm) => nm.checkpoint(!idx_already_synced), None => Ok(()), }; if let Err(e) = checkpointed { self.check_read_write_error(Some(&e)); tracing::warn!("volume {}: index checkpoint failed: {}", self.id.0, e); return false; } true } fn read_needle_header_unlocked(&self, n: &mut Needle, offset: i64) -> Result<(), VolumeError> { let mut header = [0u8; NEEDLE_HEADER_SIZE]; self.read_exact_at_backend(&mut header, offset as u64)?; n.read_header(&header); Ok(()) } /// Check if the needle is unchanged from the existing one on disk. /// Returns `Some(old_data_size)` if unchanged, `None` otherwise. /// Matches Go's isFileUnchanged which also sets n.DataSize = oldNeedle.DataSize. fn is_file_unchanged(&self, n: &Needle) -> Option { // Don't dedup for volumes with TTL if self.super_block.ttl != crate::storage::needle::ttl::TTL::EMPTY { return None; } if let Some(nm) = &self.nm { let existing = match nm.get(n.id) { Ok(existing) => existing, Err(e) => { // Not a lookup miss: the index could not be read. Report // "unknown" so the caller writes the needle again rather // than treating an unreadable index as proof of a change. warn!(volume_id = self.id.0, error = %e, "needle map lookup failed"); return None; } }; if let Some(nv) = existing && !nv.offset.is_zero() && nv.size.is_valid() { let mut old = Needle::default(); let mut ro = ReadOption::default(); if self .read_needle_data_at_unlocked( &mut old, nv.offset.to_actual_offset(), nv.size, &mut ro, ) .is_ok() && old.cookie == n.cookie && old.checksum == n.checksum && old.data == n.data { return Some(old.data_size); } } } None } /// Append a needle to the .dat file. Returns (offset, size, actual_size). fn append_needle(&mut self, n: &mut Needle) -> Result<(u64, Size, i64), VolumeError> { let version = self.version(); let bytes = n.write_bytes(version); let actual_size = bytes.len() as i64; let dat_file = self .dat_file .as_mut() .ok_or_else(|| VolumeError::Io(io::Error::other("dat file not open")))?; let offset = dat_file.seek(SeekFrom::End(0))?; // Check volume size limit before writing (matching Go's Append) if offset >= MAX_POSSIBLE_VOLUME_SIZE && !n.data.is_empty() { return Err(VolumeError::SizeLimitExceeded { current: offset, limit: MAX_POSSIBLE_VOLUME_SIZE, }); } let written = dat_file.write_all(&bytes); #[cfg(test)] let written = if self.fail_append_for_test.contains(&n.id) { Err(media_error_for_test()) } else { written }; if let Err(e) = written { self.undo_unsynced_append(offset); self.check_read_write_error(Some(&e)); return Err(VolumeError::Io(e)); } Ok((offset, n.size, actual_size)) } // ---- Delete ---- /// Delete a needle from the volume. pub fn delete_needle(&mut self, n: &mut Needle) -> Result { let _guard = self.data_file_access_control.write_lock(); if let Some(e) = self.unavailable_error() { return Err(e); } if self.no_write_or_delete { return Err(VolumeError::ReadOnly(self.id)); } self.do_delete_request(n) } fn do_delete_request(&mut self, n: &mut Needle) -> Result { let (found, size, _stored_offset) = if let Some(nm) = &self.nm { // Propagate: acknowledging the delete as a no-op because the index // could not be read would drop the tombstone on the floor while the // caller believes the needle is gone. if let Some(nv) = nm.get(n.id)? { if !nv.size.is_deleted() { (true, nv.size, nv.offset) } else { (false, Size(0), Offset::default()) } } else { (false, Size(0), Offset::default()) } } else { return Ok(Size(0)); }; if !found { return Ok(Size(0)); } // Write tombstone: append needle with empty data n.data = vec![]; n.append_at_ns = get_append_at_ns(self.last_append_at_ns); let offset = if !self.has_remote_file() { // Normal volume: append tombstone to .dat file let (offset, _, _) = self.append_needle(n)?; offset } else { // Remote-tiered volume: skip .dat append, use offset 0 0 }; self.last_append_at_ns = n.append_at_ns; // Update index if let Some(nm) = &mut self.nm { nm.delete(n.id, Offset::from_actual_offset(offset as i64))?; } let checkpoint_ok = self.maybe_checkpoint_index(false); // Clear the EIO streak after a successful delete (tombstone append + // index update + checkpoint), mirroring do_write_request. if checkpoint_ok { self.check_read_write_error(None); } Ok(size) } // ---- Metrics ---- pub fn content_size(&self) -> u64 { self.nm.as_ref().map_or(0, |nm| nm.content_size()) } pub fn deleted_size(&self) -> u64 { self.nm.as_ref().map_or(0, |nm| nm.deleted_size()) } pub fn file_count(&self) -> i64 { self.nm.as_ref().map_or(0, |nm| nm.file_count()) } pub fn deleted_count(&self) -> i64 { self.nm.as_ref().map_or(0, |nm| nm.deleted_count()) } pub fn max_file_key(&self) -> NeedleId { self.nm.as_ref().map_or(NeedleId(0), |nm| nm.max_file_key()) } pub fn is_read_only(&self) -> bool { self.no_write_or_delete || self.no_write_can_delete || self.io_unavailable.is_set() || self.location_disk_space_low.load(Ordering::Relaxed) } /// Mirrors Go's ReadOnlyReasons: `no_write_or_delete` already covers the /// io_unavailable quarantine. pub fn read_only_reasons(&self) -> (bool, bool, bool, bool) { let no_write_or_delete = self.no_write_or_delete || self.io_unavailable.is_set(); let disk_space_low = self.location_disk_space_low.load(Ordering::Relaxed); ( no_write_or_delete || self.no_write_can_delete || disk_space_low, no_write_or_delete, self.no_write_can_delete, disk_space_low, ) } /// The reason the volume refuses all I/O, when a failed recovery left the /// .dat/index pair unverified. Mirrors Go's unavailableError. pub fn unavailable_error(&self) -> Option { self.io_unavailable.error() } /// Fail closed after a recovery could not return the volume to a verified /// state: refuse all I/O, leave heartbeats out, and record the state so a /// reload stays unavailable until an operator verifies the volume. fn mark_io_unavailable(&mut self, reason: String) { self.no_write_or_delete = true; self.io_unavailable.set(reason.clone()); self.mark_io_quarantined(); if let Err(e) = self.persist_unavailable(&reason) { warn!( volume_id = self.id.0, error = %e, "failed to persist unavailable marker" ); } if let Err(e) = self.set_read_only_persist(false, true) { warn!( volume_id = self.id.0, error = %e, "failed to persist unavailable state" ); } error!( volume_id = self.id.0, "volume entered unavailable state after failed recovery: {}", reason ); } fn persist_unavailable(&self, reason: &str) -> io::Result<()> { let marker = self.file_name(".unavailable"); let mut f = OpenOptions::new() .write(true) .create(true) .truncate(true) .open(&marker)?; f.write_all(reason.as_bytes())?; f.sync_all()?; drop(f); fsync_dir(&marker) } /// Re-arm the state a `.unavailable` marker recorded. The marker is /// deleted manually once the .dat/index pair is verified. fn restore_unavailable(&mut self) { let Ok(reason) = fs::read_to_string(self.file_name(".unavailable")) else { return; }; self.no_write_or_delete = true; self.io_unavailable.set(reason.trim().to_string()); self.mark_io_quarantined(); warn!( volume_id = self.id.0, "volume is unavailable: {}", reason.trim() ); } pub fn is_no_write_or_delete(&self) -> bool { self.no_write_or_delete } pub fn set_no_write_or_delete(&mut self, value: bool) { self.no_write_or_delete = value; } pub fn is_no_write_can_delete(&self) -> bool { self.no_write_can_delete } pub fn last_compact_revision(&self) -> u16 { self.last_compact_revision } pub fn last_modified_ts(&self) -> u64 { self.last_modified_ts_seconds } pub fn is_expired(&self, volume_size: u64, volume_size_limit: u64) -> bool { if volume_size_limit == 0 { return false; } if volume_size <= SUPER_BLOCK_SIZE as u64 { return false; } let ttl_minutes = self.super_block.ttl.minutes(); if ttl_minutes == 0 { return false; } let lived_minutes = SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_secs() .saturating_sub(self.last_modified_ts_seconds) / 60; (ttl_minutes as u64) < lived_minutes } /// When this volume's data becomes garbage, counted from its last write. /// Counting from the current time instead let every .vif rewrite — a /// read-only mark, a tier upload, an EC encode — hand an already expiring /// volume another full TTL. Zero when the volume has no TTL. Mirrors Go's /// ExpireAtSec. pub fn expire_at_sec(&self) -> u64 { let ttl_seconds = self.super_block.ttl.to_seconds(); if ttl_seconds == 0 { return 0; } let mut last_write_sec = self.last_modified_ts_seconds; if last_write_sec == 0 { last_write_sec = SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_secs(); } last_write_sec + ttl_seconds } pub fn is_expired_long_enough(&self, max_delay_minutes: u32) -> bool { let ttl_minutes = self.super_block.ttl.minutes(); if ttl_minutes == 0 { return false; } let removal_delay = std::cmp::min(ttl_minutes / 10, max_delay_minutes); ((ttl_minutes + removal_delay) as u64) * 60 + self.last_modified_ts_seconds < SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_secs() } /// Check volume data integrity by verifying the last index entries against the .dat file. /// Matches Go's CheckVolumeDataIntegrity (volume_checking.go L117-141). /// Reads the last few index entries, verifies each needle header is readable and /// consistent. On failure, marks the volume read-only. fn check_volume_data_integrity(&mut self) -> Result<(), VolumeError> { let idx_path = self.file_name(".idx"); if !Path::new(&idx_path).exists() { return Ok(()); } let idx_size = fs::metadata(&idx_path).map(|m| m.len()).unwrap_or(0) as i64; if idx_size == 0 { return Ok(()); } if idx_size % NEEDLE_MAP_ENTRY_SIZE as i64 != 0 { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!("index file's size is {} bytes, maybe corrupted", idx_size), ))); } let version = self.version(); // The deeper-than-tail structural check (every (offset + actual size) // fits inside .dat) is now handled in load() via the // needle map's max_needle_end accumulator, so we don't pay for a // second linear scan of the .idx here. // Verify the needle physically last in the .dat (the highest offset) // and that the .dat ends exactly at it. The .idx is not always in .dat // append order: weed fix and other rebuilds could rewrite it sorted by // key, which puts the highest-key needle last instead of the .dat-tail // needle. Picking the last file-position entry there compares a // mid-file needle's tail against the full .dat size and falsely flips // the volume read-only on every load. Mirrors Go's // findDatTailEntryOffset + doCheckAndFixVolumeData. let mut idx_file = File::open(&idx_path)?; let tail_entry_pos = self.find_dat_tail_entry_offset(&mut idx_file, idx_size, version)?; if tail_entry_pos < 0 { // pre-allocated / all-zero index, nothing to verify against the .dat return Ok(()); } let mut buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; idx_file.seek(SeekFrom::Start(tail_entry_pos as u64))?; idx_file.read_exact(&mut buf)?; let (key, offset, size) = idx_entry_from_bytes(&buf); if offset.is_zero() { return Ok(()); } if size.is_deleted() { // Deletion tombstone: the .idx carries TombstoneFileSize (-1) but // the appended needle in .dat carries Size=0, so verify with // Size=0 — comparing against -1 would mismatch the on-disk header // and send every volume with a trailing deletion read-only. self.verify_deleted_needle_integrity(offset.to_actual_offset(), key, version) } else { self.verify_needle_integrity(offset.to_actual_offset(), key, size, version) } } /// Bounds the work a vacuumed volume's recovery does, where key order makes /// every write a candidate for the newest one. A volume with more live /// needles than this keeps the .dat mtime: reading a subset could recover a /// timestamp older than the newest write and expire data still inside its /// TTL, so a scan that will not fit declines instead of guessing. const VACUUMED_LAST_WRITE_SCAN_ENTRIES: usize = 1 << 16; /// Point the TTL clock at the newest write recorded in the volume, replacing /// the .dat mtime the loader starts from. A delete appends a tombstone and /// vacuum rewrites the .dat wholesale, so the mtime moves without any write /// ever landing: every restart of a volume taking delete traffic re-armed /// is_expired() for another full TTL and the volume was never reclaimed. /// Mirrors Go's recoverLastModifiedTs. fn recover_last_modified_ts(&mut self) { if self.super_block.ttl.minutes() == 0 { return; } match self.find_last_write_append_at_ns() { Ok(0) => {} Ok(append_at_ns) => self.last_modified_ts_seconds = append_at_ns / 1_000_000_000, Err(e) => warn!( volume_id = self.id.0, error = %e, "recover the last write from the index" ), } } /// Scan the .idx backwards for the newest write — an entry that is not a /// deletion tombstone — and return that needle's append timestamp. The .idx /// and the .dat share an order, so an append-ordered volume answers with the /// first write the scan reaches. Vacuum rewrites both in key order, which /// tracks write order only because the master issues keys increasing: an /// overwrite keeps its original, lower key, so a vacuumed volume has to take /// the maximum over every write it indexes. Returns 0 when the .idx holds /// nothing but tombstones, when a vacuumed volume holds more needles than /// the scan budget, or for a volume older than version 3, whose needles /// carry no append timestamp. Mirrors Go's findLastWriteAppendAtNs. fn find_last_write_append_at_ns(&self) -> Result { let version = self.version(); if version != VERSION_3 { return Ok(0); } let idx_path = self.file_name(".idx"); let idx_size = fs::metadata(&idx_path).map(|m| m.len()).unwrap_or(0) as i64; if idx_size == 0 || idx_size % NEEDLE_MAP_ENTRY_SIZE as i64 != 0 { return Ok(0); } let scan_every_write = self.super_block.compaction_revision > 0; let mut entry_budget = Self::VACUUMED_LAST_WRITE_SCAN_ENTRIES; let mut last_write_append_at_ns = 0u64; let mut idx_file = File::open(&idx_path)?; let mut block = vec![0u8; NEEDLE_MAP_ENTRY_SIZE * idx::ROWS_TO_READ]; let mut end = idx_size; while end > 0 { let start = (end - block.len() as i64).max(0); let entries = &mut block[..(end - start) as usize]; idx_file.seek(SeekFrom::Start(start as u64))?; idx_file.read_exact(entries)?; for entry in entries.as_chunks::().0.iter().rev() { let (key, offset, size) = idx_entry_from_bytes(entry); if offset.is_zero() || size.is_deleted() { continue; } let Some(needle_offset) = self.find_needle_offset(offset.to_actual_offset(), key, size) else { continue; }; last_write_append_at_ns = last_write_append_at_ns .max(self.read_needle_append_at_ns(needle_offset, size)?); if !scan_every_write { return Ok(last_write_append_at_ns); } entry_budget -= 1; if entry_budget == 0 { warn!( volume_id = self.id.0, budget = Self::VACUUMED_LAST_WRITE_SCAN_ENTRIES, "too many needles to scan for the last write, keeping the .dat mtime" ); return Ok(0); } } end = start; } Ok(last_write_append_at_ns) } /// The .dat offset holding the needle an .idx entry describes, or None when /// no needle there matches it. A .dat past MAX_POSSIBLE_VOLUME_SIZE wraps the /// offsets in its .idx, so the needle can sit one volume size further in; /// verify_needle_integrity retries the same way. Mirrors Go's /// findNeedleOffset. fn find_needle_offset(&self, actual_offset: i64, key: NeedleId, size: Size) -> Option { for at in [ actual_offset, actual_offset + MAX_POSSIBLE_VOLUME_SIZE as i64, ] { let mut header = [0u8; NEEDLE_HEADER_SIZE]; if self.read_exact_at_backend(&mut header, at as u64).is_err() { continue; } let (_, needle_id, needle_size) = Needle::parse_header(&header); if needle_id == key && needle_size == size { return Some(at); } } None } /// Read the append timestamp a version 3 needle carries past its checksum. fn read_needle_append_at_ns(&self, actual_offset: i64, size: Size) -> Result { let ts_offset = actual_offset as u64 + NEEDLE_HEADER_SIZE as u64 + size.0 as u64 + NEEDLE_CHECKSUM_SIZE as u64; let mut ts = [0u8; TIMESTAMP_SIZE]; self.read_exact_at_backend(&mut ts, ts_offset)?; Ok(u64::from_be_bytes(ts)) } /// .idx file position of the entry whose needle is physically last in the /// .dat (highest offset). The common case — an append-ordered .idx — is /// resolved in O(1): the last entry's on-disk end equals the .dat size. A /// key-sorted .idx (e.g. legacy weed fix output) falls back to a single /// linear scan for the maximum offset. Returns -1 when no entry has a /// non-zero offset (a pre-allocated / all-zero index). fn find_dat_tail_entry_offset( &self, idx_file: &mut File, idx_size: i64, version: Version, ) -> Result { if let Ok(dat_size) = self.dat_file_size() && dat_size > 0 { let last_pos = idx_size - NEEDLE_MAP_ENTRY_SIZE as i64; let mut buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; idx_file.seek(SeekFrom::Start(last_pos as u64))?; idx_file.read_exact(&mut buf)?; let (_, offset, size) = idx_entry_from_bytes(&buf); if !offset.is_zero() && needle_disk_end(offset, size, version) == dat_size as i64 { return Ok(last_pos); } } // Slow path: scan the whole .idx for the entry at the maximum offset. // Tombstone entries are not skipped: a trailing deletion is a real // on-disk record and can be the needle physically last in the .dat. let mut max_entry_pos: i64 = -1; let mut max_actual_offset: i64 = -1; let mut entry_pos: i64 = 0; let mut buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; idx_file.seek(SeekFrom::Start(0))?; let mut reader = io::BufReader::new(idx_file); while entry_pos < idx_size { reader.read_exact(&mut buf)?; let (_, offset, _) = idx_entry_from_bytes(&buf); if !offset.is_zero() { let ao = offset.to_actual_offset(); if ao > max_actual_offset { max_actual_offset = ao; max_entry_pos = entry_pos; } } entry_pos += NEEDLE_MAP_ENTRY_SIZE as i64; } Ok(max_entry_pos) } /// Verify the live needle at the .dat tail: its header must match the /// .idx entry and, on v3, the .dat must end exactly at its on-disk end. /// Extra bytes mean an unindexed trailing record (a torn append); /// appending after one would place the next needle at an offset the /// 8-byte .idx encoding may not represent, so the volume is quarantined /// read-only instead. Mirrors Go's verifyNeedleIntegrity, whose tail /// check is v3-only -- a v1/v2 volume Go serves read-write must not go /// read-only here. fn verify_needle_integrity( &mut self, actual_offset: i64, key: NeedleId, size: Size, version: Version, ) -> Result<(), VolumeError> { let mut header = [0u8; NEEDLE_HEADER_SIZE]; self.read_exact_at_backend(&mut header, actual_offset as u64)?; let (_cookie, needle_id, needle_size) = Needle::parse_header(&header); let mut checked_offset = actual_offset; let mut checked_id = needle_id; if needle_size != size { // Go parity: on a size mismatch, retry past the 32GB offset // wrap-around before giving up. let alt_offset = actual_offset + MAX_POSSIBLE_VOLUME_SIZE as i64; let mut alt_header = [0u8; NEEDLE_HEADER_SIZE]; self.read_exact_at_backend(&mut alt_header, alt_offset as u64) .map_err(|_| size_mismatch_error(actual_offset, needle_id, needle_size, size))?; let (_, alt_id, alt_size) = Needle::parse_header(&alt_header); if alt_size != size { return Err(size_mismatch_error( actual_offset, needle_id, needle_size, size, )); } checked_offset = alt_offset; checked_id = alt_id; } if !key.is_empty() && checked_id != key { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "index key {:?} does not match needle Id {:?} at offset {}", key, checked_id, checked_offset ), ))); } if version != VERSION_3 { return Ok(()); } let ts = self.read_needle_append_at_ns(checked_offset, size)?; if ts > 0 { self.last_append_at_ns = ts; } self.verify_dat_ends_at(checked_offset + get_actual_size(size, version)) } /// Verify the deletion tombstone at the .dat tail. Tombstones are appended /// with DataSize=0, so the on-disk header carries Size=0; verify with that /// and then require the .dat to end exactly at the tombstone. Mirrors Go's /// verifyDeletedNeedleIntegrity. fn verify_deleted_needle_integrity( &mut self, actual_offset: i64, key: NeedleId, version: Version, ) -> Result<(), VolumeError> { let record_size = get_actual_size(Size(0), version) as usize; let mut record = vec![0u8; record_size]; self.read_exact_at_backend(&mut record, actual_offset as u64)?; let mut n = Needle::default(); n.read_bytes(&record, actual_offset, Size(0), version) .map_err(|e| { VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!("read tombstone at offset {}: {}", actual_offset, e), )) })?; if !key.is_empty() && n.id != key { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "index key {:?} does not match needle Id {:?} at offset {}", key, n.id, actual_offset ), ))); } if n.append_at_ns > 0 { self.last_append_at_ns = n.append_at_ns; } self.verify_dat_ends_at(actual_offset + get_actual_size(Size(0), version)) } /// The checked needle is the one physically last in the .dat, so the file /// must end exactly at it; extra bytes mean an unindexed trailing record. fn verify_dat_ends_at(&self, file_tail_offset: i64) -> Result<(), VolumeError> { let file_size = self.dat_file_size().map_err(VolumeError::Io)? as i64; if file_size == file_tail_offset { return Ok(()); } let dat_path = self.file_name(".dat"); if file_size > file_tail_offset { warn!( "data file {} actual {} bytes expected {} bytes!", dat_path, file_size, file_tail_offset ); return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "data file {} actual {} bytes expected {} bytes", dat_path, file_size, file_tail_offset ), ))); } warn!( "data file {} has {} bytes, less than expected {} bytes!", dat_path, file_size, file_tail_offset ); Err(VolumeError::Io(io::Error::new( io::ErrorKind::UnexpectedEof, format!( "data file {} has {} bytes, less than expected {} bytes", dat_path, file_size, file_tail_offset ), ))) } /// Open the on-disk .idx for scrubbing and apply Go openIndex's zero-size /// guard: a zero-size index is only legal for a pre-allocated volume whose /// .dat is superblock-only; an empty index over a populated .dat is /// corruption. Returns the open file + size, or the messages to report. fn open_index_for_scrub(&self) -> Result<(File, i64), Vec> { let idx_path = self.file_name(".idx"); let idx_file = File::open(&idx_path) .map_err(|e| vec![format!("open index file {}: {}", idx_path, e)])?; let idx_file_size = idx_file .metadata() .map_err(|e| vec![format!("stat index file {}: {}", idx_path, e)])? .len() as i64; if idx_file_size == 0 { match self.dat_file_size() { Ok(dat_size) if dat_size > SUPER_BLOCK_SIZE as u64 => { return Err(vec![format!( "zero-size IDX file for volume {} with store size {}", self.id.0, dat_size )]); } Ok(_) => {} Err(e) => { return Err(vec![format!( "stat data file for volume {}: {}", self.id.0, e )]); } } } Ok((idx_file, idx_file_size)) } /// Scrub the volume index: verify the on-disk .idx for overlapping needles /// and a size that is a whole number of entries. Mirrors Go's Volume.ScrubIndex /// → idx.CheckIndexFile. Index-only; does not read the .dat. pub fn scrub_index(&self) -> Result<(u64, Vec), VolumeError> { let _guard = self.data_file_access_control.read_lock(); let (mut idx_file, idx_file_size) = match self.open_index_for_scrub() { Ok(v) => v, Err(msgs) => return Ok((0, msgs)), }; Ok(crate::storage::idx::check_index_file( &mut idx_file, idx_file_size, self.version(), )) } /// Scrub the volume: walk the on-disk .idx (every physical row, including /// superseded and deleted entries), CRC-verify each live needle, and reconcile /// the .dat size against the needles it indexes. Mirrors Go's Volume.Scrub → /// scrubVolumeData. Returns (rows_walked, broken_needles). pub fn scrub(&self) -> Result<(u64, Vec), VolumeError> { // Matches Go's scrubVolumeData: a volume with no data backend can't be // scrubbed (and a zero dat_size would flag every needle out of range). if !self.has_data_backend() { return Err(VolumeError::NotFound); } let _guard = self.data_file_access_control.read_lock(); let (mut idx_file, idx_file_size) = match self.open_index_for_scrub() { Ok(v) => v, Err(msgs) => return Ok((0, msgs)), }; let version = self.version(); let dat_size = self.dat_file_size().map_err(VolumeError::Io)?; // Full scrub also runs the index structural check. let (_, mut broken) = crate::storage::idx::check_index_file(&mut idx_file, idx_file_size, version); let mut count: u64 = 0; let mut total_read: i64 = 0; let walk = crate::storage::idx::walk_index_file(&mut idx_file, 0, |needle_id, offset, size| { count += 1; // A remote-tier delete records an offset-0 tombstone with no physical // .dat bytes, so it must not contribute to total_read. if offset.is_zero() && size.is_deleted() { return Ok(()); } let on_disk_size = Size(size.raw() as i32); // compute the actual size of the needle in disk, including needle header, body and alignment padding. total_read += get_actual_size(on_disk_size, version); let actual_offset = offset.to_actual_offset(); if actual_offset < 0 || actual_offset as u64 >= dat_size { broken.push(format!( "needle {} offset {} out of range (dat_size={})", needle_id.0, actual_offset, dat_size )); return Ok(()); } // Lock held above; read directly via the unlocked path (matches Go). let mut n = Needle { id: needle_id, ..Needle::default() }; let mut read_option = ReadOption::default(); if let Err(e) = self.read_needle_data_at_unlocked( &mut n, actual_offset, on_disk_size, &mut read_option, ) { broken.push(format!( "failed to read needle {} on volume {}: {}", needle_id.0, self.id.0, e )); } else if n.id != needle_id { // The data CRC does not cover the header: a damaged needle id // still reads clean while every live-needle lookup on this // replica keeps finding the index key here. (Go parity: // the check covers live needles too, not just tombstones.) broken.push(format!( "index key {} does not match needle's Id {} on volume {}", needle_id.0, n.id.0, self.id.0 )); } Ok(()) }); if let Err(e) = walk { broken.push(format!("walk index file: {}", e)); } // Reconcile the physical .dat size against the needles read. let want_size = total_read + SUPER_BLOCK_SIZE as i64; if (dat_size as i64) < want_size { broken.push(format!( "data file for volume {} is smaller ({}) than the {} needles it contains ({})", self.id.0, dat_size, count, want_size )); } else if dat_size as i64 != want_size { broken.push(format!( "data file size for volume {} ({}) doesn't match the size for {} needles read ({})", self.id.0, dat_size, count, want_size )); } Ok((count, broken)) } /// Capture a `.dat` scan from `from_offset` that the caller can run after /// dropping its store guard. See `DatScanPlan` for why the offset, the /// handle and the end bound must come from the same guard. pub(crate) fn dat_scan_plan(&self, from_offset: u64) -> Result { if let Some(e) = self.unavailable_error() { return Err(e); } Ok(DatScanPlan { source: self.read_source()?, version: self.version(), from: from_offset, end: self.current_dat_file_size()?, owner: self.data_file_access_control.clone(), compaction_revision: self.super_block.compaction_revision, }) } /// Fail unless `plan` was taken from this volume at its current /// compaction revision. fn check_plan_source(&self, plan: &DatScanPlan) -> Result<(), VolumeError> { if let Some(e) = self.unavailable_error() { return Err(e); } if !Arc::ptr_eq(&plan.owner, &self.data_file_access_control) || plan.compaction_revision != self.super_block.compaction_revision { return Err(VolumeError::Io(io::Error::other(format!( "volume {} was compacted or replaced during the scan", self.id )))); } Ok(()) } /// Whether the record of `key` at `offset` in `plan` is the one the /// needle map points at now. pub(crate) fn is_live_in_plan( &self, plan: &DatScanPlan, key: NeedleId, offset: u64, ) -> Result { self.check_plan_source(plan)?; let nv = self.nm_or_not_found()?.get(key)?; Ok(nv.is_some_and(|nv| nv.offset.to_actual_offset() == offset as i64)) } /// A plan for the records appended since `plan` was taken, or `None` when /// there are none. `next` is the offset after the last record the pass /// visited; a pass that stopped short of its end bound is not continued. pub(crate) fn dat_scan_plan_after( &self, plan: &DatScanPlan, next: Option, ) -> Result, VolumeError> { self.check_plan_source(plan)?; if next.unwrap_or(plan.from) != plan.end || self.current_dat_file_size()? <= plan.end { return Ok(None); } self.dat_scan_plan(plan.end).map(Some) } /// Insert or update a needle index entry (for low-level blob writes). pub fn put_needle_index( &mut self, key: NeedleId, offset: Offset, size: Size, ) -> Result<(), VolumeError> { if let Some(ref mut nm) = self.nm { nm.put(key, offset, size).map_err(VolumeError::Io)?; } self.maybe_checkpoint_index(false); Ok(()) } /// Mark this volume as read-only (no writes or deletes) and persist. pub fn set_read_only(&mut self) -> Result<(), VolumeError> { self.set_read_only_persist(false, true) } /// Mark this volume as read-only, optionally persisting to .vif. /// With `can_delete`, deletes still land so expiring data drains the volume. pub fn set_read_only_persist( &mut self, can_delete: bool, persist: bool, ) -> Result<(), VolumeError> { if can_delete && !self.has_remote_file() { // deletes append tombstones to .idx; a read-only boot attached no writer self.attach_idx_writer_if_missing()?; } self.no_write_or_delete = !can_delete; if can_delete { self.no_write_can_delete = true; } else if !self.has_remote_file() { // downgrading a canDelete mark; remote volumes keep their derived flag self.no_write_can_delete = false; } if persist { self.save_vif()?; } Ok(()) } /// Attach an append-only .idx writer when missing (read-only boot). Runs /// before any flag flips so a failure cannot leave puts silently skipping /// the on-disk append. fn attach_idx_writer_if_missing(&mut self) -> Result<(), VolumeError> { let needs_idx_writer = self .nm .as_ref() .map(|nm| !nm.has_idx_writer()) .unwrap_or(false); if needs_idx_writer { let idx_path = self.file_name(".idx"); // Positioned writes: an append-mode handle cannot set_len on // Windows. let write_file = OpenOptions::new() .write(true) .create(true) .truncate(false) .open(&idx_path)?; let idx_size = trim_torn_idx_tail(&write_file, &idx_path)?; if let Some(ref mut nm) = self.nm { nm.set_idx_file(Box::new(write_file), idx_size); } } Ok(()) } /// Mark this volume as writable (allow writes and deletes). /// /// If the volume booted with .vif ReadOnly=true, `load_index` built the /// needle map without an .idx writer attached, so subsequent puts would /// silently skip the on-disk append and only mutate in-memory state — /// surviving until the next restart, then vanishing. Re-attach a writer /// here so writes persist again. pub fn set_writable(&mut self) -> Result<(), VolumeError> { if let Some(e) = self.unavailable_error() { return Err(e); } let was_no_write_or_delete = self.no_write_or_delete; let was_no_write_can_delete = self.no_write_can_delete; self.no_write_or_delete = false; // Remote-tiered volumes must stay no_write_can_delete regardless of marks. if !self.has_remote_file() { self.no_write_can_delete = false; } // Everything below keys off the flags above, so it runs with the volume // already marked writable. Any failure has to put them back: a volume // advertising writable whose needle map cannot reach .idx acknowledges // writes that are gone after a restart. if let Err(e) = self.publish_writable() { self.no_write_or_delete = was_no_write_or_delete; self.no_write_can_delete = was_no_write_can_delete; return Err(e); } self.reset_io_error_state(); Ok(()) } /// The steps that must all succeed before a volume can be left marked /// writable: swap out the read-only map, attach the .idx writer, persist the /// mark. Split out so set_writable has one rollback point rather than three. fn publish_writable(&mut self) -> Result<(), VolumeError> { self.reconcile_index_mode()?; self.attach_idx_writer_if_missing()?; self.save_vif() } /// Swap the read-only sorted map for the configured writable one once the /// current mode says the volume is no longer read-only. Mirrors Go's /// reopenIdxForWrite, and is the reason a volume that stops being read-only /// can accept writes at all: SortedFileNeedleMap::put always fails, so /// publishing a writable volume without this leaves every write appending to /// .dat and then failing to index it. A no-op unless the map is the sorted /// one and the flags have already moved. fn reconcile_index_mode(&mut self) -> Result<(), VolumeError> { let wants_sorted = self.use_sorted_index(); let has_sorted = matches!(self.nm, Some(NeedleMap::SortedFile(_))); if wants_sorted == has_sorted { return Ok(()); } // Both directions matter. Tiering DOWN has to trade the read-only // sorted map for a writable one before the volume is published as // writable. Tiering UP has to install the sorted map, or a volume // tiered while the server runs keeps its whole index in RAM and its // .idx descriptor pinned until the next restart — the cost this map // exists to avoid. // // load_index only publishes self.nm once the new map is built, so a // failure leaves the previous map in place and the caller can recover. self.load_index() } /// The tiered-storage VolumeInfo backing the .vif file. pub fn volume_info(&self) -> &PbVolumeInfo { &self.volume_info } /// Whether this volume is backed by a remote file, i.e. whether the .vif /// holds a remote reference. Derived rather than mirrored, so it can never /// disagree with the reference list it describes. pub fn has_remote_file(&self) -> bool { !self.volume_info.files.is_empty() } /// Edit the remote reference list and recompute everything derived from it. /// /// This is the only way to change `volume_info.files` from outside the /// module: the write/delete mode and the needle map follow from whether the /// volume is remote, so an edit that skipped the refresh would leave the /// volume claiming a mode its .vif contradicts. /// /// Not transactional: on error `f` has already been applied and the volume /// is left pinned read-only, which is the safe end of a half-finished tier /// transition. A caller that needs the old list back restores it with a /// second call. pub fn update_remote_files( &mut self, f: impl FnOnce(&mut Vec), ) -> Result<(), VolumeError> { f(&mut self.volume_info.files); self.refresh_remote_write_mode() } /// Recompute the Go-style write/delete mode from the current remote tier /// state, and bring the needle map in line with it — a volume that stops /// being remote also stops using the read-only sorted index. /// /// If the map cannot be rebuilt the volume is pinned read-only rather than /// published as writable with an index that rejects every put; a restart /// recovers it. fn refresh_remote_write_mode(&mut self) -> Result<(), VolumeError> { if self.has_remote_file() { self.no_write_can_delete = true; self.no_write_or_delete = false; } else if !self.volume_info.read_only_can_delete { // only clear the remoteness-derived flag, not an operator mark self.no_write_can_delete = false; } if let Err(e) = self.reconcile_index_mode() { self.no_write_or_delete = true; return Err(e); } Ok(()) } /// Open the local .dat as the data backend, dropping any remote backend, so reads /// are served from local disk. Mirrors Go's swapToLocalDatBackend after a tier-down. pub(crate) fn open_local_dat_backend(&mut self) -> Result<(), VolumeError> { let file = open_volume_file(OpenOptions::new().read(true).write(true), self.dat_path())?; self.remote_dat_file = None; self.dat_file = Some(file); Ok(()) } /// Path to .vif file. fn vif_path(&self) -> String { format!("{}.vif", self.data_file_name()) } /// Load volume info from .vif file. /// Supports both the protobuf-JSON format (Go-compatible) and legacy JSON. /// Returns true if a .vif file was found and successfully loaded. fn load_vif(&mut self) -> Result { let path = self.vif_path(); if let Ok(content) = fs::read_to_string(&path) { if content.trim().is_empty() { return Ok(false); } // Try protobuf-JSON (Go-compatible VolumeInfo via VifVolumeInfo) if let Ok(vif_info) = serde_json::from_str::(&content) { let pb_info = vif_info.to_pb(); if pb_info.read_only { if pb_info.read_only_can_delete { self.no_write_can_delete = true; } else { self.no_write_or_delete = true; } } self.volume_info = pb_info; self.refresh_remote_write_mode()?; if self.volume_info.version == 0 { self.volume_info.version = Version::current().0 as u32; } if !self.has_remote_file() && self.volume_info.bytes_offset == 0 { self.volume_info.bytes_offset = OFFSET_SIZE as u32; } if self.volume_info.bytes_offset != 0 && self.volume_info.bytes_offset != OFFSET_SIZE as u32 { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "bytes_offset mismatch in {}: found {}, expected {}", path, self.volume_info.bytes_offset, OFFSET_SIZE ), ))); } return Ok(true); } // Fall back to OldVersionVolumeInfo (Go's tryOldVersionVolumeInfo): // maps DestroyTime -> expire_at_sec if let Ok(old_info) = serde_json::from_str::(&content) { let vif_info = old_info.into_vif(); let pb_info = vif_info.to_pb(); if pb_info.read_only { self.no_write_or_delete = true; } self.volume_info = pb_info; self.refresh_remote_write_mode()?; if self.volume_info.version == 0 { self.volume_info.version = Version::current().0 as u32; } if !self.has_remote_file() && self.volume_info.bytes_offset == 0 { self.volume_info.bytes_offset = OFFSET_SIZE as u32; } if self.volume_info.bytes_offset != 0 && self.volume_info.bytes_offset != OFFSET_SIZE as u32 { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "bytes_offset mismatch in {}: found {}, expected {}", path, self.volume_info.bytes_offset, OFFSET_SIZE ), ))); } return Ok(true); } // Fall back to legacy format if let Ok(info) = serde_json::from_str::(&content) { if info.read_only { self.no_write_or_delete = true; } return Ok(true); } } Ok(false) } /// Save volume info to .vif file in protobuf-JSON format (Go-compatible). /// Matches Go's SaveVolumeInfo: checks writability before writing and propagates errors. fn save_vif(&mut self) -> Result<(), VolumeError> { let vif_path = self.vif_path(); // Match Go: if file exists but is not writable, return an error let path = std::path::Path::new(&vif_path); if path.exists() { let metadata = fs::metadata(path)?; if metadata.permissions().readonly() { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::PermissionDenied, format!("failed to check {} not writable", vif_path), ))); } } // remoteness-derived no_write_can_delete is not an operator mark; sync // volume_info so refresh_remote_write_mode sees a real mark let marked_can_delete = self.no_write_can_delete && !self.has_remote_file() && !self.no_write_or_delete; self.volume_info.read_only = self.no_write_or_delete || marked_can_delete; self.volume_info.read_only_can_delete = marked_can_delete; let mut vif = VifVolumeInfo::from_pb(&self.volume_info); // Match Go's SaveVolumeInfo: compute ExpireAtSec from TTL let expire_at_sec = self.expire_at_sec(); if expire_at_sec > 0 { vif.expire_at_sec = expire_at_sec; } let content = serde_json::to_string_pretty(&vif) .map_err(|e| VolumeError::Io(io::Error::other(e.to_string())))?; fs::write(&vif_path, content)?; Ok(()) } /// Save full VolumeInfo to .vif file (for tiered storage). /// Matches Go's SaveVolumeInfo which computes ExpireAtSec from TTL. pub fn save_volume_info(&mut self) -> Result<(), VolumeError> { let marked_can_delete = self.no_write_can_delete && !self.has_remote_file() && !self.no_write_or_delete; self.volume_info.read_only = self.no_write_or_delete || marked_can_delete; self.volume_info.read_only_can_delete = marked_can_delete; // Compute ExpireAtSec from TTL (matches Go's SaveVolumeInfo) let expire_at_sec = self.expire_at_sec(); if expire_at_sec > 0 { self.volume_info.expire_at_sec = expire_at_sec; } let vif = VifVolumeInfo::from_pb(&self.volume_info); let content = serde_json::to_string_pretty(&vif) .map_err(|e| VolumeError::Io(io::Error::other(e.to_string())))?; // fsync the .vif so a tiered volume's remote reference is durable before the // caller acts on it, e.g. deletes the remote object (matches Go util.WriteFile). let mut f = OpenOptions::new() .write(true) .create(true) .truncate(true) .open(self.vif_path())?; f.write_all(content.as_bytes())?; f.sync_all()?; Ok(()) } /// Get the remote storage backend name and key from this volume .vif. pub fn remote_storage_name_key(&self) -> (String, String) { if self.volume_info.files.is_empty() { return (String::new(), String::new()); } let rf = &self.volume_info.files[0]; let backend_name = if rf.backend_id.is_empty() { rf.backend_type.clone() } else { format!("{}.{}", rf.backend_type, rf.backend_id) }; (backend_name, rf.key.clone()) } /// Get the dat file path for this volume. pub fn dat_path(&self) -> String { self.file_name(".dat") } /// Get the directory this volume is stored in. pub fn dir(&self) -> &str { &self.dir } /// Get the directory this volume's index is stored in. pub fn dir_idx(&self) -> &str { &self.dir_idx } /// Throttle IO during compaction to avoid saturating disk. pub fn maybe_throttle_compaction(&self, bytes_written: u64) { if self.compaction_byte_per_second <= 0 || !self.is_compacting() { return; } // Simple throttle: sleep based on bytes written vs allowed rate let sleep_us = (bytes_written as f64 / self.compaction_byte_per_second as f64 * 1_000_000.0) as u64; if sleep_us > 0 { std::thread::sleep(std::time::Duration::from_micros(sleep_us)); } } /// Change the replication placement and rewrite the super block. pub fn set_replica_placement(&mut self, rp: ReplicaPlacement) -> Result<(), VolumeError> { self.super_block.replica_placement = rp; let bytes = self.super_block.to_bytes(); let dat_file = self .dat_file .as_mut() .ok_or_else(|| VolumeError::Io(io::Error::other("dat file not open")))?; dat_file.seek(SeekFrom::Start(0))?; dat_file.write_all(&bytes)?; dat_file.sync_all()?; Ok(()) } // ---- Binary search for incremental copy ---- /// Read a single index entry's offset from the .idx file by entry index. fn read_offset_from_index(&self, m: i64) -> Result { let idx_path = self.file_name(".idx"); let idx_file = File::open(&idx_path)?; let mut buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; let file_offset = m as u64 * NEEDLE_MAP_ENTRY_SIZE as u64; #[cfg(unix)] { use std::os::unix::fs::FileExt; idx_file.read_exact_at(&mut buf, file_offset)?; } #[cfg(not(unix))] { let mut f = idx_file; f.seek(SeekFrom::Start(file_offset))?; std::io::Read::read_exact(&mut f, &mut buf)?; } let (_key, offset, _size) = idx_entry_from_bytes(&buf); Ok(offset) } /// Read the append_at_ns timestamp from a needle at the given offset in the .dat file. /// Go reads the full needle body for ALL entries including tombstones to get the /// actual AppendAtNs timestamp, which is needed for correct binary search during /// incremental copy. fn read_append_at_ns(&self, offset: Offset) -> Result { let actual_offset = offset.to_actual_offset() as u64; let version = self.version(); let mut header_buf = [0u8; NEEDLE_HEADER_SIZE]; self.read_exact_at_backend(&mut header_buf, actual_offset)?; let (_cookie, _id, size) = Needle::parse_header(&header_buf); let actual_size = get_actual_size(size, version); if actual_size <= 0 { return Ok(0); } let mut buf = vec![0u8; actual_size as usize]; self.read_exact_at_backend(&mut buf, actual_offset)?; let mut n = Needle::default(); n.read_bytes_meta_only(&buf, offset.to_actual_offset(), size, version)?; Ok(n.append_at_ns) } /// Search right from position m to find the first non-deleted entry. fn read_right_ns(&self, m: i64, max: i64) -> Result<(i64, Offset, u64), VolumeError> { let mut index = m; loop { index += 1; if index >= max { return Ok((index, Offset::default(), 0)); } let offset = self.read_offset_from_index(index)?; if !offset.is_zero() { let ts = self.read_append_at_ns(offset)?; return Ok((index, offset, ts)); } } } /// Search left from position m to find the first non-deleted entry. fn read_left_ns(&self, m: i64) -> Result<(i64, Offset, u64), VolumeError> { let mut index = m; loop { index -= 1; if index < 0 { return Ok((index, Offset::default(), 0)); } let offset = self.read_offset_from_index(index)?; if !offset.is_zero() { let ts = self.read_append_at_ns(offset)?; return Ok((index, offset, ts)); } } } /// Binary search through the .idx file to find the first needle /// with append_at_ns > since_ns. Returns (offset, is_last). /// Matches Go's BinarySearchByAppendAtNs in volume_backup.go. pub fn binary_search_by_append_at_ns( &self, since_ns: u64, ) -> Result<(Offset, bool), VolumeError> { let file_size = self.idx_file_size() as i64; if file_size % NEEDLE_MAP_ENTRY_SIZE as i64 != 0 { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!("unexpected idx file size: {}", file_size), ))); } let entry_count = file_size / NEEDLE_MAP_ENTRY_SIZE as i64; let mut l: i64 = 0; let mut h: i64 = entry_count; while l < h { let m = (l + h) / 2; if m == entry_count { return Ok((Offset::default(), true)); } let offset = self.read_offset_from_index(m)?; if offset.is_zero() { let (left_index, _left_offset, left_ns) = self.read_left_ns(m)?; let (right_index, right_offset, right_ns) = self.read_right_ns(m, entry_count)?; if right_ns <= since_ns { l = right_index; if l == entry_count { return Ok((Offset::default(), true)); } else { continue; } } if since_ns < left_ns { h = left_index + 1; continue; } return Ok((right_offset, false)); } let m_ns = self.read_append_at_ns(offset)?; if m_ns <= since_ns { l = m + 1; } else { h = m; } } if l == entry_count { return Ok((Offset::default(), true)); } let offset = self.read_offset_from_index(l)?; Ok((offset, false)) } /// Write a raw needle blob at a specific offset in the .dat file. pub fn write_needle_blob( &mut self, offset: i64, needle_blob: &[u8], ) -> Result<(), VolumeError> { if self.is_read_only() { return Err(VolumeError::ReadOnly(self.id)); } let dat_file = self .dat_file .as_mut() .ok_or_else(|| VolumeError::Io(io::Error::other("dat file not open")))?; dat_file.seek(SeekFrom::Start(offset as u64))?; dat_file.write_all(needle_blob)?; Ok(()) } /// Write a needle blob and update the needle map index. /// Matches Go's Volume.WriteNeedleBlob which appends to dat and calls nm.Put. pub fn write_needle_blob_and_index( &mut self, needle_id: NeedleId, needle_blob: &[u8], size: Size, ) -> Result<(), VolumeError> { // nm.put on a read-only volume fails only after the blob is appended to .dat. if self.is_read_only() { return Err(VolumeError::ReadOnly(self.id)); } // Storage guard: negativity-only (Go parity). See parse_needle_at. if size.0 < 0 { return Err(VolumeError::Io(std::io::Error::new( std::io::ErrorKind::InvalidData, format!("invalid needle size {}", size.0), ))); } // size indexes the needle and places the v3 append timestamp, so a caller using // the payload-only DataSize corrupts both, silently until the needle is read back. if needle_blob.len() < NEEDLE_HEADER_SIZE { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "needle {} blob of {} bytes is shorter than a needle header", needle_id.0, needle_blob.len() ), ))); } let (_, _, header_size) = Needle::parse_header(needle_blob); if header_size != size { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "needle {} size {} does not match its blob header size {}", needle_id.0, size.0, header_size.0 ), ))); } // The blob is appended as is: its length must be the record this size takes in this volume's version. let actual_size = get_actual_size(size, self.version()); if needle_blob.len() as i64 != actual_size { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "needle {} blob of {} bytes does not match the {} bytes size {} takes in a version {} volume", needle_id.0, needle_blob.len(), actual_size, size.0, self.version().0 ), ))); } // Dedup check: if the same needle already exists with matching content, skip the write. // Matches Go's WriteNeedleBlob which reads existing needle and compares cookie+checksum+data. if let Some(nm) = &self.nm && let Some(nv) = nm.get(needle_id)? && nv.size == size { let version = self.version(); // Read existing needle from disk let mut old_needle = Needle::default(); let mut ro = ReadOption::default(); if self .read_needle_data_at_unlocked( &mut old_needle, nv.offset.to_actual_offset(), nv.size, &mut ro, ) .is_ok() { // Parse the incoming blob into a needle let mut new_needle = Needle::default(); if new_needle .read_bytes(needle_blob, nv.offset.to_actual_offset(), size, version) .is_ok() && old_needle.cookie == new_needle.cookie && old_needle.checksum == new_needle.checksum && old_needle.data == new_needle.data { return Ok(()); } } } // Check volume size limit let content_size = self.content_size(); if MAX_POSSIBLE_VOLUME_SIZE < content_size + needle_blob.len() as u64 { return Err(VolumeError::Io(io::Error::other(format!( "volume size limit {} exceeded! current size is {}", MAX_POSSIBLE_VOLUME_SIZE, content_size )))); } // Compute monotonic appendAtNs (matches Go: needle.GetAppendAtNs(v.lastAppendAtNs)) let append_at_ns = get_append_at_ns(self.last_append_at_ns); // Patch appendAtNs timestamp into V3 blobs (matches Go WriteNeedleBlob L64-77) let mut blob_buf; let blob_to_write = if self.version() == VERSION_3 { let ts_offset = NEEDLE_HEADER_SIZE + size.0 as usize + NEEDLE_CHECKSUM_SIZE; if ts_offset + TIMESTAMP_SIZE > needle_blob.len() { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "needle blob buffer too small: need {} bytes, have {}", ts_offset + TIMESTAMP_SIZE, needle_blob.len() ), ))); } blob_buf = needle_blob.to_vec(); blob_buf[ts_offset..ts_offset + TIMESTAMP_SIZE] .copy_from_slice(&append_at_ns.to_be_bytes()); &blob_buf[..] } else { needle_blob }; // Append blob at end of dat file let dat_size = self.dat_file_size()? as i64; self.write_needle_blob(dat_size, blob_to_write)?; // Update lastAppendAtNs (matches Go L352: v.lastAppendAtNs = appendAtNs) self.last_append_at_ns = append_at_ns; // Update needle map index let offset = Offset::from_actual_offset(dat_size); if let Some(ref mut nm) = self.nm { nm.put(needle_id, offset, size)?; } self.maybe_checkpoint_index(false); Ok(()) } pub fn needs_replication(&self) -> bool { self.super_block.replica_placement.get_copy_count() > 1 } /// Garbage ratio: deleted_size / content_size (matching Go's garbageLevel). /// content_size is the additive-only FileByteCounter. /// /// When DeletedCount > 0 but DeletedSize == 0 (e.g. .sdx converted back to /// normal .idx where deleted entry sizes are missing), falls back to /// computing deleted bytes as (datFileSize - contentSize - SuperBlockSize) /// and uses datFileSize as the denominator. pub fn garbage_level(&self) -> f64 { let content = self.content_size(); if content == 0 { return 0.0; } let mut deleted = self.deleted_size(); let mut file_size = content; if self.deleted_count() > 0 && deleted == 0 { // This happens for .sdx converted back to normal .idx // where deleted entry size is missing let dat_file_size = self.dat_file_size().unwrap_or(0); deleted = dat_file_size .saturating_sub(content) .saturating_sub(SUPER_BLOCK_SIZE as u64); file_size = dat_file_size; } if file_size == 0 { return 0.0; } deleted as f64 / file_size as f64 } pub fn dat_file_size(&self) -> io::Result { self.current_dat_file_size() } /// Get the modification time of the .dat file as Unix seconds. pub fn dat_file_mod_time(&self) -> u64 { if let Some(dat_file) = self.dat_file.as_ref() { dat_file .metadata() .ok() .and_then(|m| m.modified().ok()) .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok()) .map(|d| d.as_secs()) .unwrap_or(0) } else { self.remote_dat_file .as_ref() .map(|remote_dat_file| remote_dat_file.modified_time) .unwrap_or(0) } } pub fn idx_file_size(&self) -> u64 { self.nm.as_ref().map_or(0, |nm| nm.index_file_size()) } // ---- Compaction / Vacuum ---- /// Compact the volume by copying only live needles to new .cpd/.cpx files. /// This reads from the current .dat/.idx and writes to .cpd/.cpx. /// Call `commit_compact()` after to swap the files. pub fn compact_by_index( &mut self, _preallocate: u64, _max_bytes_per_second: i64, progress_fn: F, ) -> Result<(), VolumeError> where F: Fn(i64) -> bool, { match self.begin_compact_by_index()? { Some(job) => job.run(progress_fn), None => Ok(()), // already compacting } } /// Claim the compaction, record the `makeup_diff` watermark, and open the /// sources the copy reads, so the caller can run the copy after dropping /// its store guard. `None` means a compaction is already running. pub(crate) fn begin_compact_by_index(&mut self) -> Result, VolumeError> { let Some(claim) = CompactionClaim::try_claim(&self.is_compacting) else { return Ok(None); }; // Guard against nil needle map (matches Go's nil check) let Some(nm) = self.nm.as_ref() else { return Err(VolumeError::Io(io::Error::other(format!( "volume {} needle map is nil", self.id )))); }; if let Some(e) = self.unavailable_error() { return Err(e); } let idx_size = nm.index_file_size(); // The copy would stream the .dat from remote storage for a commit that refuses it. if self.has_remote_file() { return Err(VolumeError::Io(io::Error::other(format!( "volume {} is tiered to remote storage, cannot compact", self.id )))); } // Fresh opens, not `try_clone`: see `dat_scan_plan`. let src_dat = if self.dat_file.is_some() { NeedleStreamSource::Local(open_volume_file( OpenOptions::new().read(true), self.file_name(".dat"), )?) } else if let Some(remote) = self.remote_dat_file() { NeedleStreamSource::Remote(remote) } else { return Err(VolumeError::Io(io::Error::other("dat file not open"))); }; let src_idx = open_volume_file(OpenOptions::new().read(true), self.file_name(".idx"))?; // Record state before compaction for makeupDiff self.last_compact_index_offset = idx_size; self.last_compact_revision = self.super_block.compaction_revision; Ok(Some(CompactionJob { id: self.id, src_dat, src_idx, idx_size, cpd_path: self.file_name(".cpd"), cpx_path: self.file_name(".cpx"), version: self.version(), super_block: self.super_block.clone(), io_errors: self.io_errors.clone(), _claim: claim, })) } /// Commit a previously completed compaction: swap .cpd/.cpx to .dat/.idx and reload. /// Matches Go's isCompactionInProgress CompareAndSwap guard. pub fn commit_compact(&mut self) -> Result<(), VolumeError> { let Some(_claim) = CompactionClaim::try_claim(&self.is_compacting) else { return Ok(()); // already compacting, silently skip (matches Go) }; // The reload would read the remote object through the compacted .idx. if self.has_remote_file() { let _ = fs::remove_file(self.file_name(".cpd")); let _ = fs::remove_file(self.file_name(".cpx")); return Err(VolumeError::Io(io::Error::other(format!( "volume {} is tiered to remote storage, cannot commit compaction", self.id )))); } self.do_commit_compact() } fn do_commit_compact(&mut self) -> Result<(), VolumeError> { if let Err(e) = self.makeup_diff() { warn!("makeup_diff failed: {}", e); // Match Go: clean up .cpd/.cpx on makeup_diff failure let cpd = self.file_name(".cpd"); let cpx = self.file_name(".cpx"); let _ = fs::remove_file(&cpd); let _ = fs::remove_file(&cpx); return Err(e); } // Close current files if let Some(ref mut nm) = self.nm { nm.close(); } self.nm = None; if let Some(ref dat_file) = self.dat_file { let _ = dat_file.sync_all(); } self.dat_file = None; self.remote_dat_file = None; // makeup_diff has fsynced the .cpd/.cpx contents. Persist a durable .cpc // commit marker BEFORE the renames so the two-rename swap is atomic // across a crash: a marker on disk means the swap is decided and // reconcile rolls forward; no marker means roll back. Without it, a // crash between the two renames leaves a stale .idx that a later vacuum // compacts to empty. self.write_compact_commit_marker()?; self.apply_compact_swap()?; // Reload self.load(true, false, 0, self.version())?; Ok(()) } /// Write and fsync the .cpc marker, then fsync the directory so the marker /// survives a crash before apply_compact_swap. fn write_compact_commit_marker(&self) -> Result<(), VolumeError> { let marker_path = self.file_name(".cpc"); let f = OpenOptions::new() .write(true) .create(true) .truncate(true) .open(&marker_path)?; f.sync_all()?; drop(f); fsync_dir(&marker_path)?; Ok(()) } /// Perform the durable two-rename compaction commit. Idempotent: run both at /// the tail of commit and by reconcile rolling forward after a crash. It /// requires BOTH .cpd/.cpx to be present, so a stale or duplicate commit /// returns an error without deleting the live .dat/.idx. fn apply_compact_swap(&self) -> Result<(), VolumeError> { // Normal commit: both temp files must be present, or a stale/duplicate // commit could clobber the live .dat/.idx. if !Path::new(&self.file_name(".cpd")).exists() || !Path::new(&self.file_name(".cpx")).exists() { return Err(VolumeError::Io(io::Error::new( io::ErrorKind::NotFound, "compact files (.cpd/.cpx) not found", ))); } self.finish_compact_swap() } /// Renames whichever compaction temp file is still present (.cpd->.dat, /// .cpx->.idx), fsyncs, drops the stale .ldb/.rdb, then clears the .cpc /// marker. Tolerates a partial state: a crash after the .dat rename but /// before the .idx rename leaves only .cpx, which must still be applied -- /// not abandoned, which would pair a fresh .dat with a stale .idx. Existence /// is checked robustly so a transient error never silently skips the swap. fn finish_compact_swap(&self) -> Result<(), VolumeError> { let exists = |p: String| match fs::metadata(&p) { Ok(_) => true, Err(e) if e.kind() == io::ErrorKind::NotFound => false, Err(_) => true, }; let dat_path = self.file_name(".dat"); let idx_path = self.file_name(".idx"); let cpd_exists = exists(self.file_name(".cpd")); let cpx_exists = exists(self.file_name(".cpx")); if cpd_exists { #[cfg(windows)] { let _ = fs::remove_file(&dat_path); } fs::rename(self.file_name(".cpd"), &dat_path)?; } if cpx_exists { #[cfg(windows)] { let _ = fs::remove_file(&idx_path); } fs::rename(self.file_name(".cpx"), &idx_path)?; } if cpd_exists || cpx_exists { fsync_dir(&dat_path)?; if self.dir != self.dir_idx { fsync_dir(&idx_path)?; } let _ = fs::remove_dir_all(self.file_name(".ldb")); let _ = fs::remove_file(self.file_name(".rdb")); } // Clear the marker last and fsync the dir so a restart does not re-run a // completed swap. let marker_path = self.file_name(".cpc"); match fs::remove_file(&marker_path) { Ok(()) => {} Err(e) if e.kind() == io::ErrorKind::NotFound => {} Err(e) => return Err(e.into()), } fsync_dir(&marker_path)?; Ok(()) } /// Recover an interrupted compaction commit on load. When the .cpc marker is /// present the swap was decided, so roll FORWARD by finishing the renames; /// when it is absent any leftover .cpd/.cpx are an abandoned generation, so /// roll BACK by deleting them (and any stale .ldb beside a healthy .idx). pub fn reconcile_compact_state(&self) -> Result<(), VolumeError> { let cpc_path = self.file_name(".cpc"); if Path::new(&cpc_path).exists() { // Marker present: the swap was decided. Finish whichever rename is // still pending -- a crash may have completed only the .dat rename, // so the lone remaining .cpx must still be applied, not abandoned. // If neither temp file remains, finish_compact_swap clears the marker. tracing::info!( volume_id = self.id.0, "rolling forward interrupted compaction commit" ); return self.finish_compact_swap(); } // No marker: roll back any orphan compaction temp files. let mut rolled_back = false; for ext in &[".cpd", ".cpx"] { let p = self.file_name(ext); if Path::new(&p).exists() { tracing::info!( volume_id = self.id.0, "rolling back orphan compaction file {}", ext ); match fs::remove_file(&p) { Ok(()) => {} Err(e) if e.kind() == io::ErrorKind::NotFound => {} Err(e) => return Err(e.into()), } rolled_back = true; } } if rolled_back { let _ = fs::remove_dir_all(self.file_name(".ldb")); let _ = fs::remove_file(self.file_name(".rdb")); } Ok(()) } /// Clean up leftover compaction files (.cpd, .cpx). pub fn cleanup_compact(&self) -> Result<(), VolumeError> { // An in-flight copy is still writing .cpd/.cpx. if self.is_compacting() { return Err(self.compacting_error()); } // Refuse to unlink .cpd/.cpx while a .cpc marker exists: those temp files // are the only inputs reconcile can roll forward to, so removing them // mid-commit would strand a decided swap. if Path::new(&self.file_name(".cpc")).exists() { return Err(VolumeError::Io(io::Error::other(format!( "volume {}: refusing cleanup while commit marker present", self.id )))); } let cpd_path = self.file_name(".cpd"); let cpx_path = self.file_name(".cpx"); let cpldb_path = self.file_name(".cpldb"); let cpc_path = self.file_name(".cpc"); let e1 = fs::remove_file(&cpd_path); let e2 = fs::remove_file(&cpx_path); let e3 = fs::remove_dir_all(&cpldb_path); let e4 = fs::remove_file(&cpc_path); // Ignore NotFound errors for e in [e1, e2, e3, e4] { if let Err(e) = e && e.kind() != io::ErrorKind::NotFound { return Err(e.into()); } } Ok(()) } /// Read any new needles appended during compaction and append them to .cpd/.cpx fn makeup_diff(&mut self) -> Result<(), VolumeError> { let old_idx_size = self.nm.as_ref().map_or(0, |nm| nm.index_file_size()); if old_idx_size == 0 || old_idx_size <= self.last_compact_index_offset { return Ok(()); } let old_super_block = &self.super_block; if old_super_block.compaction_revision != self.last_compact_revision { return Err(VolumeError::Io(io::Error::other(format!( "current old dat file's compact revision {} is not the expected one {}", old_super_block.compaction_revision, self.last_compact_revision )))); } // Read the new .cpd file's super block and verify its compaction revision is old + 1 let cpd_path_check = self.file_name(".cpd"); let mut cpd_file_check = File::open(&cpd_path_check)?; let mut sb_buf = [0u8; SUPER_BLOCK_SIZE]; cpd_file_check.read_exact(&mut sb_buf)?; let new_super_block = SuperBlock::from_bytes(&sb_buf)?; let old_compact_revision = old_super_block.compaction_revision; let new_compact_revision = new_super_block.compaction_revision; if old_compact_revision + 1 != new_compact_revision { return Err(VolumeError::Io(io::Error::other(format!( "old dat file's compact revision {} + 1 does not equal new dat file's compact revision {}", old_compact_revision, new_compact_revision )))); } let old_idx_path = self.file_name(".idx"); let mut old_idx_file = File::open(&old_idx_path)?; // Read new entries from .idx let mut incremented_entries = std::collections::HashMap::new(); let offset = self.last_compact_index_offset; old_idx_file.seek(SeekFrom::Start(offset))?; let entry_count = (old_idx_size - offset) / NEEDLE_MAP_ENTRY_SIZE as u64; for _ in 0..entry_count { let mut buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; old_idx_file.read_exact(&mut buf)?; let (key, needle_offset, size) = crate::storage::types::idx_entry_from_bytes(&buf); incremented_entries.insert(key, (needle_offset, size)); } if incremented_entries.is_empty() { return Ok(()); } let cpd_path = self.file_name(".cpd"); let cpx_path = self.file_name(".cpx"); let mut dst_dat = OpenOptions::new().read(true).write(true).open(&cpd_path)?; let mut dst_idx = OpenOptions::new().append(true).open(&cpx_path)?; let mut dat_offset = dst_dat.seek(SeekFrom::End(0))?; let padding_rem = dat_offset % NEEDLE_PADDING_SIZE as u64; if padding_rem != 0 { dat_offset += NEEDLE_PADDING_SIZE as u64 - padding_rem; dst_dat.seek(SeekFrom::Start(dat_offset))?; } let version = self.version(); let old_dat_path = self.file_name(".dat"); let old_dat_file = File::open(&old_dat_path)?; for (key, (needle_offset, size)) in incremented_entries { if !needle_offset.is_zero() && !size.is_deleted() && size.0 > 0 { let actual_size = crate::storage::needle::needle::get_actual_size(size, version); let mut blob = vec![0u8; actual_size as usize]; read_exact_at( &old_dat_file, &mut blob, needle_offset.to_actual_offset() as u64, )?; dst_dat.write_all(&blob)?; let mut idx_entry_buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; crate::storage::types::idx_entry_to_bytes( &mut idx_entry_buf, key, Offset::from_actual_offset(dat_offset as i64), size, ); dst_idx.write_all(&idx_entry_buf)?; dat_offset += actual_size as u64; } else { let mut fake_del_needle = Needle { id: key, cookie: Cookie(0x12345678), append_at_ns: SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap() .as_nanos() as u64, ..Needle::default() }; let bytes = fake_del_needle.write_bytes(version); dst_dat.write_all(&bytes)?; // Record the tombstone's real .dat offset, like the normal delete path, // so a deletion left at the .dat tail stays visible to the integrity // check on reload. Offset 0 hid the trailing tombstone and falsely // flipped the volume read-only. let mut idx_entry_buf = [0u8; NEEDLE_MAP_ENTRY_SIZE]; crate::storage::types::idx_entry_to_bytes( &mut idx_entry_buf, key, Offset::from_actual_offset(dat_offset as i64), Size(crate::storage::types::TOMBSTONE_FILE_SIZE.into()), ); dst_idx.write_all(&idx_entry_buf)?; dat_offset += bytes.len() as u64; } } dst_dat.sync_all()?; dst_idx.sync_all()?; Ok(()) } // ---- Sync / Close ---- pub fn sync_to_disk(&mut self) -> io::Result<()> { if let Some(ref dat_file) = self.dat_file { dat_file.sync_all()?; } if let Some(ref nm) = self.nm { nm.sync()?; } Ok(()) } pub fn close(&mut self) { let dat_synced = if let Some(ref dat_file) = self.dat_file { dat_file.sync_all().is_ok() } else { true }; self.dat_file = None; self.remote_dat_file = None; // When the .dat flushed, checkpoint the index so the next load starts // from the recorded .idx size. When it did not, skip the checkpoint: // a durable index pointing past an unflushed .dat tail would make the // reload's max_needle_end check mark the volume read-only. Without the // checkpoint, META_IDX_SIZE stays at the last successful one and the // reload replays the uncheckpointed tail (redb flushes on drop). if let Some(ref mut nm) = self.nm { if dat_synced { nm.close(); } else { tracing::warn!( "volume {}: .dat sync failed on close, skipping index checkpoint", self.id.0 ); nm.close_without_checkpoint(); } } self.nm = None; } /// Move this volume's `.idx` (and `.sdx` when present) from its current /// index directory into `new_idx_dir`, then reload in place. Mirrors Go's /// `Volume::RelocateIndexTo`: it is a no-op when the index is already there /// or nothing is co-located to move, and is used to pull an index a decode /// or reconstruct left beside the data back into the configured `-dir.idx`. pub fn relocate_index_to(&mut self, new_idx_dir: &str) -> Result<(), VolumeError> { // Moving .idx would strand the .cpx an in-flight copy writes beside it. if self.is_compacting() { return Err(self.compacting_error()); } let _guard = self.data_file_access_control.write_lock(); if self.dir_idx == new_idx_dir { return Ok(()); } let old_base = volume_file_name(&self.dir_idx, &self.collection, self.id); let old_idx = format!("{old_base}.idx"); if !Path::new(&old_idx).exists() { return Ok(()); // nothing co-located to move } let new_base = volume_file_name(new_idx_dir, &self.collection, self.id); let new_idx = format!("{new_base}.idx"); // Close the index and data handles before moving the index file. let version = self.version(); self.close(); if let Err(e) = rename_or_copy(&old_idx, &new_idx) { // Reopen against the old dir so the volume is not left down; surface // a failed reopen since it leaves the volume unusable until reload. if let Err(reopen) = self.load(true, false, 0, version) { error!( "relocate volume {}: reopen after failed .idx move: {}", self.id, reopen ); } return Err(VolumeError::Io(io::Error::other(format!( "relocate index for volume {}: move .idx: {e}", self.id )))); } // The .sdx is a derived sorted index; move it when present, but a // failure is not fatal — drop the stale copy so a reload rebuilds it. let old_sdx = format!("{old_base}.sdx"); if Path::new(&old_sdx).exists() { let new_sdx = format!("{new_base}.sdx"); if let Err(e) = rename_or_copy(&old_sdx, &new_sdx) { warn!( "relocate volume {}: move .sdx: {} (will rebuild)", self.id, e ); let _ = fs::remove_file(&old_sdx); } } self.dir_idx = new_idx_dir.to_string(); self.load(true, false, 0, version) } /// Remove all volume files from disk. /// Destroy removes everything related to this volume. When keep_remote_data /// is true the cloud-tier object backing the volume is left intact — used /// by moves where another server is taking over the same .vif. pub fn destroy( &mut self, only_empty: bool, only_garbage: bool, keep_remote_data: bool, ) -> Result<(), VolumeError> { // Either enabled check may pass: a volume with no live data qualifies // whether it reads empty or as all garbage. Byte counters, not counts: // index rows and live tallies drift apart on reload. let empty_ok = only_empty && self.file_count() == 0; let garbage_ok = only_garbage && self.content_size() > 0 && self.deleted_size() >= self.content_size(); if (only_empty || only_garbage) && !empty_ok && !garbage_ok { return Err(VolumeError::NotEmpty); } if self.is_compacting() { return Err(self.compacting_error()); } let (storage_name, storage_key) = self.remote_storage_name_key(); if !keep_remote_data && self.has_remote_file() && !storage_name.is_empty() && !storage_key.is_empty() { let backend = crate::remote_storage::s3_tier::global_s3_tier_registry() .read() .unwrap() .get(&storage_name); if let Some(backend) = backend { if let Err(e) = backend.delete_file_blocking(&storage_key) { warn!( volume_id = self.id.0, storage_name, storage_key, error = %e, "failed to delete remote tier file during destroy" ); } } else { warn!( volume_id = self.id.0, storage_name, storage_key, "remote tier backend not found during destroy" ); } } // A regular volume and an EC volume for the same id share .vif. // When EC artefacts coexist on this disk (e.g. shards distributed onto // a source replica before it is deleted), keep the .vif so removing the // regular volume does not strip the EC volume's info file. let keep_vif = self.shares_vif_with_ec_volume(); self.close(); remove_volume_files(&self.data_file_name(), keep_vif); remove_volume_files(&self.index_file_name(), keep_vif); Ok(()) } /// Reports whether an EC volume for this id has a sealed .ecx on the same /// disk, in which case its .vif is the same file as the regular volume's /// and must outlive the regular volume's deletion. Mirrors the on-disk /// portion of Go's Volume.sharesVifWithEcVolume / HasEcxFileOnDisk. fn shares_vif_with_ec_volume(&self) -> bool { let has_ecx = |base: &str| -> bool { fs::metadata(format!("{}.ecx", base)) .map(|m| !m.is_dir() && m.len() > 0) .unwrap_or(false) }; if has_ecx(&volume_file_name(&self.dir_idx, &self.collection, self.id)) { return true; } self.dir != self.dir_idx && has_ecx(&volume_file_name(&self.dir, &self.collection, self.id)) } /// Matches Go's `checkReadWriteError` in `weed/storage/io_error.go`. fn check_read_write_error(&self, err: Option<&io::Error>) { self.io_errors.check_read_write_error(err); } pub fn get_io_error_state(&self) -> (Option, i32, bool) { self.io_errors.get_io_error_state() } pub fn should_quarantine(&self) -> bool { self.io_errors.should_quarantine() } pub fn mark_io_quarantined(&self) { self.io_errors.mark_io_quarantined(); } pub fn reset_io_error_state(&self) { self.io_errors.reset_io_error_state(); } #[cfg(test)] pub(crate) fn set_last_io_error_for_test(&self, err: Option<&str>) { self.io_errors.set_last_io_error_for_test(err); } #[cfg(test)] pub(crate) fn fail_next_fsync_for_test(&mut self, fail: bool) { self.fail_fsync_for_test = fail; } /// Test-only read of the redb META `.idx` size through the live handle. /// See `needle_map::test_support::live_meta_idx_size` for why durability /// tests read this live instead of copying the open `.rdb` (Windows /// mandatory file locking rejects reads of the locked file). #[cfg(test)] pub(crate) fn live_meta_idx_size_for_test(&self) -> Option { match self.nm.as_ref() { Some(NeedleMap::Redb(nm)) => nm.live_meta_idx_size(), _ => None, } } #[cfg(test)] pub(crate) fn fail_next_idx_sync_for_test(&mut self, fail: bool) { self.fail_idx_sync_for_test = fail; } #[cfg(test)] pub(crate) fn fail_next_truncate_for_test(&mut self, fail: bool) { self.fail_truncate_for_test = fail; } #[cfg(test)] pub(crate) fn fail_append_for_test(&mut self, ids: &[NeedleId]) { self.fail_append_for_test = ids.iter().copied().collect(); } /// (.dat syncs, .idx syncs) attempted since the volume was opened. #[cfg(test)] pub(crate) fn sync_counts_for_test(&self) -> (usize, usize) { ( self.dat_syncs_for_test.load(Ordering::Relaxed), self.idx_syncs_for_test.load(Ordering::Relaxed), ) } #[cfg(test)] pub(crate) fn set_last_modified_ts_for_test(&mut self, ts_seconds: u64) { self.last_modified_ts_seconds = ts_seconds; } #[cfg(test)] pub(crate) fn add_file_count_for_test(&self, delta: i64) { if let Some(nm) = self.nm.as_ref() { nm.add_file_count_for_test(delta); } } } // ============================================================================ // Helpers // ============================================================================ /// A copy of a run-wide failure for each entry it fails. fn run_error(e: &VolumeError) -> VolumeError { match e { VolumeError::Io(e) => VolumeError::Io(io::Error::new(e.kind(), e.to_string())), e => VolumeError::Io(io::Error::other(e.to_string())), } } /// Generate volume file base name: dir/collection_id or dir/id /// Byte offset just past the needle's on-disk record. Mirrors Go's /// needleDiskEnd. pub(crate) fn needle_disk_end(offset: Offset, size: Size, version: Version) -> i64 { offset.to_actual_offset() + get_actual_size(Size(size.raw() as i32), version) } fn size_mismatch_error(offset: i64, id: NeedleId, found: Size, expected: Size) -> VolumeError { VolumeError::Io(io::Error::new( io::ErrorKind::InvalidData, format!( "entry not found: offset {} found id {:?} size {}, expected size {}", offset, id, found.0, expected.0 ), )) } /// Drop a partial row from the end of `.idx` and return the remaining length. /// /// `.idx` is a run of fixed-size rows, and writers append at EOF: a short write /// leaves a partial row behind, and every row appended after it lands off /// alignment, so the next load parses the rest of the file as garbage. The /// partial row is unrecoverable either way — every loader already skips it — so /// removing it before anything can append is what keeps the file parseable. /// Go instead refuses to load a volume whose `.idx` is not a whole number of /// rows; trimming keeps it mountable, and the rows before the tear are intact. fn trim_torn_idx_tail(idx_file: &File, idx_path: &str) -> Result { let size = idx_file.metadata()?.len(); let aligned = size - size % NEEDLE_MAP_ENTRY_SIZE as u64; if aligned != size { warn!( idx = %idx_path, size, aligned, "dropping a partial row from the end of the index" ); idx_file.set_len(aligned)?; idx_file.sync_all()?; } Ok(aligned) } pub fn volume_file_name(dir: &str, collection: &str, id: VolumeId) -> String { if collection.is_empty() { format!("{}/{}", dir, id.0) } else { format!("{}/{}_{}", dir, collection, id.0) } } /// Move `src` to `dst`, falling back to copy+remove when the two live on /// different filesystems (a real `-dir.idx` split). Mirrors Go's /// `RenameOrCopyFile`: any rename error other than cross-device is fatal, and a /// failed copy or a source that cannot be removed rolls the copy back so a /// failure never leaves two divergent files. fn rename_or_copy(src: &str, dst: &str) -> io::Result<()> { match fs::rename(src, dst) { Ok(()) => return Ok(()), Err(e) if e.raw_os_error() != Some(libc::EXDEV) => return Err(e), Err(_) => {} } fs::copy(src, dst)?; // fsync the destination before dropping the source, matching Go's out.Sync(). if let Err(e) = OpenOptions::new() .write(true) .open(dst) .and_then(|f| f.sync_all()) { let _ = fs::remove_file(dst); return Err(e); } if let Err(e) = fs::remove_file(src) { let _ = fs::remove_file(dst); return Err(e); } Ok(()) } /// Generate a monotonically increasing append timestamp. fn get_append_at_ns(last: u64) -> u64 { let now = SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_nanos() as u64; if now <= last { last + 1 } else { now } } /// Remove all files associated with a volume. /// .dat/.idx removals log at info level so destructive calls are traceable. /// fsync the parent directory of `path` so a rename/create/unlink inside it is /// durable, propagating a sync failure so the commit path can abort rather than /// proceed with an undurable rename or marker. A path with no openable parent is /// tolerated; directory fsync is unsupported on Windows, so it is a no-op there /// (matching the Go fsyncDir helper, which skips it too). pub(crate) fn fsync_dir(path: &str) -> io::Result<()> { #[cfg(windows)] { let _ = path; Ok(()) } #[cfg(not(windows))] { if let Some(parent) = Path::new(path).parent() && let Ok(d) = File::open(parent) { return d.sync_all(); } Ok(()) } } pub(crate) fn remove_volume_files(base: &str, keep_vif: bool) { for ext in &[ ".dat", ".idx", ".vif", ".sdx", ".cpd", ".cpx", ".cpc", ".note", ".rdb", ".unavailable", ] { if *ext == ".vif" && keep_vif { continue; } let path = format!("{}{}", base, ext); let size = fs::metadata(&path).map(|m| m.len()).unwrap_or(0); let existed = fs::remove_file(&path).is_ok(); if existed && (*ext == ".dat" || *ext == ".idx") { tracing::info!("removed volume file {} (size={})", path, size); } } // leveldb uses a directory let _ = fs::remove_dir_all(format!("{}.ldb", base)); } // ============================================================================ // ScanVolumeFile — iterate all needles in a .dat file // ============================================================================ /// Callback for scanning needles in a volume file. pub trait VolumeFileVisitor { fn visit_super_block(&mut self, sb: &SuperBlock) -> Result<(), VolumeError>; fn read_needle_body(&self) -> bool; fn visit_needle(&mut self, n: &Needle, offset: i64) -> Result<(), VolumeError>; } /// Scan all needles in a volume's .dat file. pub fn scan_volume_file( dat_path: &str, visitor: &mut dyn VolumeFileVisitor, ) -> Result<(), VolumeError> { let mut file = File::open(dat_path)?; // Read super block let mut sb_buf = [0u8; SUPER_BLOCK_SIZE]; file.read_exact(&mut sb_buf)?; let sb = SuperBlock::from_bytes(&sb_buf)?; visitor.visit_super_block(&sb)?; let version = sb.version; let mut offset = sb.block_size() as i64; loop { // Read needle header let mut header = [0u8; NEEDLE_HEADER_SIZE]; file.seek(SeekFrom::Start(offset as u64))?; match file.read_exact(&mut header) { Ok(()) => {} Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => break, Err(e) => return Err(e.into()), } let (_cookie, _id, size) = Needle::parse_header(&header); if size.0 == 0 && _id.is_empty() { break; // end of valid data } // A negative size is a corrupt header, and body_length would advance the // walk backwards from it. The index rebuild this feeds salvages the // records before it, like Go's rebuild scanner stopping on io.EOF. if size.0 < 0 { break; } let body_length = needle::needle_body_length(size, version); let total_size = NEEDLE_HEADER_SIZE as i64 + body_length; // Skip full body parsing for deleted needles (tombstone or negative size) if size.is_deleted() || size.0 <= 0 { let mut n = Needle::default(); n.read_header(&header); visitor.visit_needle(&n, offset)?; } else if visitor.read_needle_body() { let mut buf = vec![0u8; total_size as usize]; file.seek(SeekFrom::Start(offset as u64))?; file.read_exact(&mut buf)?; let mut n = Needle::default(); n.read_bytes(&buf, offset, size, version)?; visitor.visit_needle(&n, offset)?; } else { let mut n = Needle::default(); n.read_header(&header); visitor.visit_needle(&n, offset)?; } offset += total_size; } Ok(()) } /// Reserve disk blocks for a file without changing its visible size. /// On Linux, uses `fallocate(FALLOC_FL_KEEP_SIZE)` to actually reserve blocks. /// On other platforms, this is a no-op. fn preallocate_file(file: &File, size: u64) { #[cfg(target_os = "linux")] { use std::os::unix::io::AsRawFd; let fd = file.as_raw_fd(); // FALLOC_FL_KEEP_SIZE = 1: allocate blocks without changing file size. // // SAFETY: `fd` is borrowed from the live `&File` the caller owns, so // it stays open for the call; the remaining arguments are plain // scalars; and failure is reported in the return value, which is // checked below before `last_os_error()` reads errno. let ret = unsafe { libc::fallocate(fd, 1, 0, size as libc::off_t) }; if ret == 0 { tracing::info!(bytes = size, "preallocated disk space"); } else { tracing::warn!( bytes = size, error = %io::Error::last_os_error(), "fallocate failed" ); } } #[cfg(not(target_os = "linux"))] { let _ = (file, size); tracing::debug!(bytes = size, "preallocation not supported on this platform"); } } // ============================================================================ // Tests // ============================================================================ /// An OS error the platform reports for failing storage media, which is /// what counts toward the I/O error streak. #[cfg(test)] fn media_error_for_test() -> io::Error { #[cfg(unix)] { io::Error::from_raw_os_error(libc::EIO) } #[cfg(windows)] { const ERROR_IO_DEVICE: i32 = 1117; io::Error::from_raw_os_error(ERROR_IO_DEVICE) } #[cfg(not(any(unix, windows)))] { io::Error::other("injected media error") } } #[cfg(test)] mod tests { use super::*; use crate::storage::needle::crc::CRC; use tempfile::TempDir; fn spawn_fake_s3_server(body: Vec) -> (String, tokio::sync::oneshot::Sender<()>) { use axum::Router; use axum::http::{HeaderMap, HeaderValue, StatusCode, header}; use axum::routing::any; let body = Arc::new(body); let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let addr = listener.local_addr().unwrap(); listener.set_nonblocking(true).unwrap(); let (shutdown_tx, shutdown_rx) = tokio::sync::oneshot::channel::<()>(); let (ready_tx, ready_rx) = std::sync::mpsc::channel::<()>(); std::thread::spawn(move || { let runtime = tokio::runtime::Builder::new_current_thread() .enable_all() .build() .unwrap(); runtime.block_on(async move { let app = Router::new().fallback(any(move |headers: HeaderMap| { let body = body.clone(); async move { let bytes = body.as_ref(); if let Some(range) = headers .get(header::RANGE) .and_then(|value| value.to_str().ok()) && let Some(spec) = range.strip_prefix("bytes=") { let (start, end) = spec.split_once('-').unwrap(); let start = start.parse::().unwrap(); let end = if end.is_empty() { bytes.len().saturating_sub(1) } else { end.parse::().unwrap() } .min(bytes.len().saturating_sub(1)); let chunk = bytes[start..=end].to_vec(); let mut response_headers = HeaderMap::new(); response_headers.insert( header::CONTENT_LENGTH, HeaderValue::from_str(&chunk.len().to_string()).unwrap(), ); response_headers.insert( header::CONTENT_RANGE, HeaderValue::from_str(&format!( "bytes {}-{}/{}", start, end, bytes.len() )) .unwrap(), ); return (StatusCode::PARTIAL_CONTENT, response_headers, chunk); } let mut response_headers = HeaderMap::new(); response_headers.insert( header::CONTENT_LENGTH, HeaderValue::from_str(&bytes.len().to_string()).unwrap(), ); (StatusCode::OK, response_headers, bytes.to_vec()) } })); let listener = tokio::net::TcpListener::from_std(listener).unwrap(); let _ = ready_tx.send(()); axum::serve(listener, app) .with_graceful_shutdown(async move { let _ = shutdown_rx.await; }) .await .unwrap(); }); }); // Wait for the server thread to be ready before returning. ready_rx.recv().unwrap(); (format!("http://{}", addr), shutdown_tx) } fn make_test_volume(dir: &str) -> Volume { Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap() } fn write_test_needle(v: &mut Volume, id: u64, data: &[u8]) -> u64 { let mut n = Needle { id: NeedleId(id), cookie: Cookie(0x12345678), data: data.to_vec(), data_size: data.len() as u32, flags: 0, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); n.append_at_ns } /// Run a plan to completion, keeping owned copies of every record. fn scan_all(plan: &DatScanPlan) -> Vec<(Vec, Vec, u64)> { let mut records = Vec::new(); plan.scan(|needle| { records.push(( needle.header.to_vec(), needle.body.to_vec(), needle.append_at_ns, )); ControlFlow::Continue(()) }) .unwrap(); records } #[test] fn test_data_file_access_control_blocks_writer_until_reader_releases() { let control = Arc::new(DataFileAccessControl::default()); let read_lease = control.read_lock(); let writer_control = control.clone(); let acquired = Arc::new(std::sync::atomic::AtomicBool::new(false)); let acquired_clone = acquired.clone(); let writer = std::thread::spawn(move || { let _write_lease = writer_control.write_lock(); acquired_clone.store(true, std::sync::atomic::Ordering::Relaxed); }); std::thread::sleep(std::time::Duration::from_millis(50)); assert!(!acquired.load(std::sync::atomic::Ordering::Relaxed)); drop(read_lease); writer.join().unwrap(); assert!(acquired.load(std::sync::atomic::Ordering::Relaxed)); } #[test] fn test_volume_file_name() { assert_eq!(volume_file_name("/data", "", VolumeId(1)), "/data/1"); assert_eq!( volume_file_name("/data", "pics", VolumeId(42)), "/data/pics_42" ); } #[test] fn test_volume_create_and_load() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let v = make_test_volume(dir); assert_eq!(v.version(), VERSION_3); assert_eq!(v.file_count(), 0); assert_eq!(v.content_size(), 0); // .dat and .idx files should exist assert!(Path::new(&v.file_name(".dat")).exists()); assert!(Path::new(&v.file_name(".idx")).exists()); } #[test] fn binary_search_reports_is_last_when_caller_is_caught_up() { // is_last drives the caught-up heartbeat; if it stops reporting true // for an up-to-date caller, the tail sender re-reads the whole volume. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut newest_ns = 0u64; for id in 1..=3u64 { let mut n = Needle { id: NeedleId(id), cookie: Cookie(0x12345678), data: vec![b'x'; 64], data_size: 64, flags: 0, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); newest_ns = n.append_at_ns; } assert!(newest_ns > 0, "needles must carry an append timestamp"); // Caught up: asking from the newest timestamp has nothing newer. let (_offset, is_last) = v.binary_search_by_append_at_ns(newest_ns).unwrap(); assert!( is_last, "a caller at the newest append_at_ns must be reported as caught up" ); // And from beyond the newest, likewise. let (_offset, is_last_future) = v .binary_search_by_append_at_ns(newest_ns + 1_000_000_000) .unwrap(); assert!( is_last_future, "a caller ahead of the newest needle must be reported as caught up" ); } #[test] fn binary_search_does_not_report_is_last_when_data_is_newer() { // Complement: a behind caller must NOT be caught up, or tailing loses data. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut first_ns = 0u64; for id in 1..=3u64 { let mut n = Needle { id: NeedleId(id), cookie: Cookie(0x12345678), data: vec![b'y'; 64], data_size: 64, flags: 0, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); if id == 1 { first_ns = n.append_at_ns; } } let (_offset, is_last) = v.binary_search_by_append_at_ns(first_ns).unwrap(); assert!( !is_last, "a caller behind the newest needle must NOT be reported as caught up" ); } #[test] fn binary_search_does_not_report_is_last_when_only_a_delete_is_newer() { // A delete is data the tail must ship. A caught-up caller before the // delete must be sent to scan from the tombstone, not handed a heartbeat. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut newest_ns = 0u64; for id in 1..=3u64 { let mut n = Needle { id: NeedleId(id), cookie: Cookie(0x12345678), data: vec![b'z'; 64], data_size: 64, flags: 0, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); newest_ns = n.append_at_ns; } let (_offset, is_last) = v.binary_search_by_append_at_ns(newest_ns).unwrap(); assert!(is_last, "precondition: the caller starts caught up"); v.delete_needle(&mut Needle { id: NeedleId(2), cookie: Cookie(0x12345678), ..Needle::default() }) .unwrap(); let (offset, is_last) = v.binary_search_by_append_at_ns(newest_ns).unwrap(); assert!( !is_last, "a caller older than a trailing delete must NOT be reported as caught up" ); // Scan and filter exactly as volume_tail_sender does: the tombstone, // and only the tombstone, is newer than the caller. let shipped: Vec = scan_all(&v.dat_scan_plan(offset.to_actual_offset() as u64).unwrap()) .into_iter() .map(|(_, _, append_at_ns)| append_at_ns) .filter(|&append_at_ns| append_at_ns > newest_ns) .collect(); assert_eq!(shipped.len(), 1, "the tail must ship the tombstone"); } #[test] fn binary_search_on_compacted_volume_still_reports_a_later_write() { // Compaction rewrites .idx in needle-id order, so append_at_ns is no // longer monotonic by row: an overwritten key can sit before an older // one. The caller's since_ns is the last row's timestamp, so such rows // were already in the files it copied. A write made afterwards is // appended as the final row, which the search cannot step past. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let write = |v: &mut Volume, id: u64, byte: u8| { let mut n = Needle { id: NeedleId(id), cookie: Cookie(0x12345678), data: vec![byte; 64], data_size: 64, flags: 0, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); n.append_at_ns }; write(&mut v, 1, b'c'); let key2_ns = write(&mut v, 2, b'c'); let key1_ns = write(&mut v, 1, b'd'); // genuine overwrite: different data assert!( key1_ns > key2_ns, "precondition: the overwrite must append a newer record, not dedup" ); v.compact_by_index(0, 0, |_| true).unwrap(); v.commit_compact().unwrap(); let (_offset, is_last) = v.binary_search_by_append_at_ns(key2_ns).unwrap(); assert!( is_last, "precondition: compaction ordered .idx by key, so key 2 is the final row" ); let key3_ns = write(&mut v, 3, b'c'); let (offset, is_last) = v.binary_search_by_append_at_ns(key2_ns).unwrap(); assert!( !is_last, "a write after compaction is the final row and must not be hidden" ); let shipped: Vec = scan_all(&v.dat_scan_plan(offset.to_actual_offset() as u64).unwrap()) .into_iter() .map(|(_, _, append_at_ns)| append_at_ns) .filter(|&append_at_ns| append_at_ns > key2_ns) .collect(); assert!( shipped.contains(&key3_ns), "the tail must ship the write made after compaction" ); } #[test] fn dat_scan_plan_visits_needles_and_tombstones_in_file_order() { // The tail ships exactly what the scan visits, so the scan must cover // the file record by record: the on-disk bytes, in file order, // tombstones included. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let written: Vec = (1..=3u64) .map(|id| write_test_needle(&mut v, id, b"scan")) .collect(); v.delete_needle(&mut Needle { id: NeedleId(2), cookie: Cookie(0x12345678), ..Needle::default() }) .unwrap(); let sb_size = v.super_block.block_size() as u64; let records = scan_all(&v.dat_scan_plan(sb_size).unwrap()); let dat = std::fs::read(v.file_name(".dat")).unwrap(); assert_eq!(records.len(), 4, "three writes and one tombstone"); let mut offset = sb_size as usize; for (header, body, _) in &records { assert_eq!(&dat[offset..offset + header.len()], header.as_slice()); offset += header.len(); assert_eq!(&dat[offset..offset + body.len()], body.as_slice()); offset += body.len(); } assert_eq!(offset, dat.len(), "the scan must reach the end of the file"); let ids: Vec = records .iter() .map(|(header, _, _)| Needle::parse_header(header).1) .collect(); assert_eq!( ids, vec![NeedleId(1), NeedleId(2), NeedleId(3), NeedleId(2)] ); let stamps: Vec = records.iter().map(|r| r.2).collect(); assert_eq!(&stamps[..3], written.as_slice()); assert!(stamps[3] > stamps[2], "the tombstone is the newest record"); } #[cfg(unix)] #[test] fn dat_scan_plan_outlives_a_vacuum_commit() { // The tail sender drops the store guard before scanning, so a vacuum // commit can land mid-scan. The commit renames .cpd over .dat; a plan // taken before it must keep reading the file its offset was resolved // against, not the compacted one. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"first"); write_test_needle(&mut v, 2, b"second"); write_test_needle(&mut v, 1, b"first, overwritten"); let sb_size = v.super_block.block_size() as u64; let before = scan_all(&v.dat_scan_plan(sb_size).unwrap()); let plan = v.dat_scan_plan(sb_size).unwrap(); let old_len = std::fs::metadata(v.file_name(".dat")).unwrap().len(); v.compact_by_index(0, 0, |_| true).unwrap(); v.commit_compact().unwrap(); let new_len = std::fs::metadata(v.file_name(".dat")).unwrap().len(); assert!( new_len < old_len, "precondition: the commit swapped in a smaller .dat" ); assert_eq!(scan_all(&plan), before); } #[cfg(unix)] #[test] fn dat_scan_plan_outlives_volume_destroy() { // Unmount or delete can land mid-scan too. The plan holds a handle, // not a path, so it finishes reading what was there. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"going"); write_test_needle(&mut v, 2, b"gone"); let sb_size = v.super_block.block_size() as u64; let before = scan_all(&v.dat_scan_plan(sb_size).unwrap()); let plan = v.dat_scan_plan(sb_size).unwrap(); let dat_path = v.file_name(".dat"); v.destroy(false, false, false).unwrap(); assert!( !Path::new(&dat_path).exists(), "precondition: destroy removed .dat" ); assert_eq!(scan_all(&plan), before); } #[test] fn dat_scan_plan_fails_when_the_snapshot_is_truncated() { // Unmount followed by a VolumeCopy of the same id reopens .dat with // truncate(true) on the inode a running plan holds. Every byte below // the captured end existed when the plan was taken, so a short read // there is an incomplete pass, not the end of the data: the stream // must fail rather than let volume.move take a partial tail as // complete. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"kept"); write_test_needle(&mut v, 2, b"cut off"); let sb_size = v.super_block.block_size() as u64; let first_record_len = { let records = scan_all(&v.dat_scan_plan(sb_size).unwrap()); assert_eq!(records.len(), 2, "precondition: two records on disk"); (records[0].0.len() + records[0].1.len()) as u64 }; let plan = v.dat_scan_plan(sb_size).unwrap(); let end = plan.end; // Truncate through the header of the second record. let second = sb_size + first_record_len; OpenOptions::new() .write(true) .open(v.file_name(".dat")) .unwrap() .set_len(second + NEEDLE_HEADER_SIZE as u64 / 2) .unwrap(); let mut visited = Vec::new(); let err = plan .scan(|n| { visited.push(n.append_at_ns); ControlFlow::Continue(()) }) .unwrap_err(); assert_eq!(visited.len(), 1, "the intact first record is still visited"); match err { VolumeError::Io(e) => { assert_eq!(e.kind(), io::ErrorKind::UnexpectedEof); let msg = e.to_string(); assert!(msg.contains("truncated"), "{msg}"); assert!(msg.contains(&format!("snapshot end {end}")), "{msg}"); } other => panic!("expected an I/O error, got {other:?}"), } } #[test] fn dat_scan_plan_stops_at_the_snapshot_end() { // The end bound is read under the guard, while no append can be in // flight. A record appended after the plan belongs to the next pass. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let first_ns = write_test_needle(&mut v, 1, b"before"); let plan = v.dat_scan_plan(v.super_block.block_size() as u64).unwrap(); write_test_needle(&mut v, 2, b"after"); let stamps: Vec = scan_all(&plan).into_iter().map(|r| r.2).collect(); assert_eq!(stamps, vec![first_ns]); } #[test] fn dat_scan_plan_stops_when_the_visitor_breaks() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for id in 1..=3u64 { write_test_needle(&mut v, id, b"brk"); } let mut visited = 0; v.dat_scan_plan(v.super_block.block_size() as u64) .unwrap() .scan(|_| { visited += 1; ControlFlow::Break(()) }) .unwrap(); assert_eq!(visited, 1); } #[test] fn dat_scan_plan_ends_the_pass_at_a_corrupt_header() { // A negative size is a corrupt header: the record length it implies // cannot advance the scan past it, so the pass fails. A size running // past the end bound, like one near i32::MAX, cannot be a complete // record and ends the pass after the records before it, without // reading or allocating the bogus body. for bad_size in [-1000, i32::MAX] { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"good"); let sb_size = v.super_block.block_size() as u64; let dat_path = v.file_name(".dat"); let start = sb_size as usize; let mut bad = std::fs::read(&dat_path).unwrap()[start..start + NEEDLE_HEADER_SIZE].to_vec(); Size(bad_size).to_bytes(&mut bad[COOKIE_SIZE + NEEDLE_ID_SIZE..NEEDLE_HEADER_SIZE]); // Bytes after the header, so the size check stops the walk, not EOF. bad.extend_from_slice(&[0u8; 64]); OpenOptions::new() .append(true) .open(&dat_path) .unwrap() .write_all(&bad) .unwrap(); let mut visited = 0; let result = v.dat_scan_plan(sb_size).unwrap().scan(|_| { visited += 1; ControlFlow::Continue(()) }); if bad_size < 0 { let err = result.unwrap_err(); assert!( matches!(&err, VolumeError::Io(e) if e.kind() == io::ErrorKind::InvalidData), "size {bad_size}: expected a corrupt-data error, got {err:?}" ); } else { result.unwrap(); } assert_eq!(visited, 1, "size {bad_size}: only the good record"); } } #[test] fn dat_scan_plan_fails_when_the_record_body_is_corrupt() { // A record can fit inside the captured snapshot and still fail needle // parsing. The tail must surface that failure instead of emitting a // raw record with a zero append timestamp and reporting a clean pass. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"good"); let sb_size = v.super_block.block_size() as u64; let plan = v.dat_scan_plan(sb_size).unwrap(); let mut dat = OpenOptions::new() .write(true) .open(v.file_name(".dat")) .unwrap(); dat.seek(SeekFrom::Start(sb_size + NEEDLE_HEADER_SIZE as u64)) .unwrap(); dat.write_all(&u32::MAX.to_be_bytes()).unwrap(); drop(dat); let mut visited = 0; let err = plan .scan(|_| { visited += 1; ControlFlow::Continue(()) }) .unwrap_err(); assert_eq!(visited, 0, "the corrupt record must not be emitted"); assert!( matches!(err, VolumeError::Needle(_)), "expected a needle parse error, got {err:?}" ); } fn append_corrupt_header(v: &Volume, size: i32) { let mut dat = OpenOptions::new() .append(true) .open(v.file_name(".dat")) .unwrap(); let mut corrupt = [0u8; NEEDLE_HEADER_SIZE]; NeedleId(99).to_bytes(&mut corrupt[4..12]); Size(size).to_bytes(&mut corrupt[12..16]); dat.write_all(&corrupt).unwrap(); } #[test] fn dat_scan_plan_fails_at_a_header_it_cannot_advance_past() { // A size so negative the record length is zero or less cannot be // advanced past; the pass must fail rather than end early and let a // truncated tail look complete. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"good"); append_corrupt_header(&v, -100); let plan = v.dat_scan_plan(v.super_block.block_size() as u64).unwrap(); let mut visited = 0; let err = plan .scan(|_| { visited += 1; ControlFlow::Continue(()) }) .unwrap_err(); assert_eq!( visited, 1, "the record before the corrupt header is visited" ); assert!( matches!(&err, VolumeError::Io(e) if e.kind() == io::ErrorKind::InvalidData), "expected a corrupt-data error, got {err:?}" ); } #[test] fn test_volume_write_read() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); // Write a needle let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x12345678), data: b"hello world".to_vec(), data_size: 11, flags: 0, ..Needle::default() }; let (offset, size, unchanged) = v.write_needle(&mut n, true, false).unwrap(); assert!(!unchanged); assert!(offset > 0); // after superblock assert!(size.0 > 0); assert_eq!(v.file_count(), 1); // Read it back let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; let count = v.read_needle(&mut read_n).unwrap(); assert_eq!(count, 11); assert_eq!(read_n.data, b"hello world"); assert_eq!(read_n.cookie, Cookie(0x12345678)); } /// A durable write goes down the same path and lands the same data; the /// flush is extra work, not different work. #[test] fn test_volume_write_needle_fsync() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x12345678), data: b"durable payload".to_vec(), data_size: 15, flags: 0, ..Needle::default() }; let (offset, _, unchanged) = v.write_needle(&mut n, true, true).unwrap(); assert!(!unchanged); assert!(offset > 0); let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; assert_eq!(v.read_needle(&mut read_n).unwrap(), 15); assert_eq!(read_n.data, b"durable payload"); // rewriting the same content still dedups, so there is nothing to flush let mut same = Needle { id: NeedleId(1), cookie: Cookie(0x12345678), data: b"durable payload".to_vec(), data_size: 15, flags: 0, ..Needle::default() }; let (_, _, unchanged) = v.write_needle(&mut same, true, true).unwrap(); assert!(unchanged); } /// A durable write whose flush fails must leave nothing behind: the append /// comes off the .dat and the mapping it would have replaced still stands, /// with the volume's own accounting untouched. #[test] fn test_write_needle_failed_fsync_keeps_prior_mapping() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut kept = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"first-copy".to_vec(), data_size: 10, ..Needle::default() }; v.write_needle(&mut kept, true, true).unwrap(); let prior = v.nm.as_ref().unwrap().get(NeedleId(1)).unwrap().unwrap(); let dat_len_before = std::fs::metadata(v.file_name(".dat")).unwrap().len(); let file_count_before = v.file_count(); let content_size_before = v.content_size(); v.fail_next_fsync_for_test(true); let mut replacement = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"second-copy".to_vec(), data_size: 11, ..Needle::default() }; v.write_needle(&mut replacement, true, true).unwrap_err(); v.fail_next_fsync_for_test(false); assert_eq!( std::fs::metadata(v.file_name(".dat")).unwrap().len(), dat_len_before, "the unflushed append should be off the .dat" ); let now = v.nm.as_ref().unwrap().get(NeedleId(1)).unwrap().unwrap(); assert_eq!( now.offset, prior.offset, "the mapping should never have moved" ); assert_eq!(now.size, prior.size); assert_eq!( v.file_count(), file_count_before, "a rejected write must not count towards the volume" ); assert_eq!(v.content_size(), content_size_before); let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; assert_eq!(v.read_needle(&mut read_n).unwrap(), 10); assert_eq!(read_n.data, b"first-copy"); } /// A durable write that dedups against an earlier non-durable one still has /// to flush the index. The row that earlier write left behind can be sitting /// in the page cache, so acking without flushing is the same false promise /// as skipping the flush on a fresh append. #[test] fn test_dedup_durable_write_flushes_the_index() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut first = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"same-content".to_vec(), data_size: 12, ..Needle::default() }; v.write_needle(&mut first, true, false).unwrap(); v.fail_next_idx_sync_for_test(true); let mut same = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"same-content".to_vec(), data_size: 12, ..Needle::default() }; let result = v.write_needle(&mut same, true, true); v.fail_next_idx_sync_for_test(false); assert!( result.is_err(), "a dedup hit must not be acked without flushing the index" ); assert!( v.is_read_only(), "and the failed index flush quarantines the volume, dedup or not" ); } /// A durable write whose index flush fails leaves the .dat record down and /// its row published but not guaranteed to come back. The volume stops /// taking writes rather than appending more past a record whose index may /// not survive a restart. #[test] fn test_write_needle_failed_idx_sync_quarantines_volume() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); v.fail_next_idx_sync_for_test(true); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"index-never-flushed".to_vec(), data_size: 19, ..Needle::default() }; v.write_needle(&mut n, true, true).unwrap_err(); v.fail_next_idx_sync_for_test(false); assert!( v.is_read_only(), "a volume whose index flush failed must stop taking writes" ); let mut later = Needle { id: NeedleId(2), cookie: Cookie(0xbb), data: b"should-be-refused".to_vec(), data_size: 17, ..Needle::default() }; assert!( matches!( v.write_needle(&mut later, true, false), Err(VolumeError::ReadOnly(_)) ), "later writes must not append past the record whose index is in doubt" ); } /// A failed fsync whose .dat rollback cannot complete leaves the tail /// unverified, so the volume fails closed: reads and writes are refused, /// the state is persisted, and a reload stays quarantined. #[test] fn test_failed_rollback_marks_volume_unavailable() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); v.fail_next_fsync_for_test(true); v.fail_next_truncate_for_test(true); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"never-landed".to_vec(), data_size: 12, ..Needle::default() }; v.write_needle(&mut n, true, true).unwrap_err(); v.fail_next_fsync_for_test(false); v.fail_next_truncate_for_test(false); assert!(v.is_read_only()); assert!(v.unavailable_error().is_some()); assert!( v.should_quarantine(), "an unavailable volume must stay out of heartbeats" ); assert!(Path::new(&v.file_name(".unavailable")).exists()); let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; assert!(matches!( v.read_needle(&mut read_n), Err(VolumeError::Unavailable(_)) )); let mut later = Needle { id: NeedleId(2), cookie: Cookie(0xbb), data: b"should-be-refused".to_vec(), data_size: 17, ..Needle::default() }; assert!(matches!( v.write_needle(&mut later, true, true), Err(VolumeError::Unavailable(_)) )); assert!( v.set_writable().is_err(), "a manual writable transition must not bypass quarantine" ); assert!(v.unavailable_error().is_some()); let reloaded = reload_volume(dir); assert!(reloaded.unavailable_error().is_some()); assert!(reloaded.is_read_only()); assert!(reloaded.should_quarantine()); let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; assert!(reloaded.read_needle(&mut read_n).is_err()); } /// Same for a needle the failed write introduced: it never becomes visible, /// rather than being published and then tombstoned back out. #[test] fn test_write_needle_failed_fsync_publishes_nothing() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let dat_len_before = std::fs::metadata(v.file_name(".dat")).unwrap().len(); let file_count_before = v.file_count(); v.fail_next_fsync_for_test(true); let mut fresh = Needle { id: NeedleId(7), cookie: Cookie(0x77), data: b"never-landed".to_vec(), data_size: 12, ..Needle::default() }; v.write_needle(&mut fresh, true, true).unwrap_err(); v.fail_next_fsync_for_test(false); assert_eq!( std::fs::metadata(v.file_name(".dat")).unwrap().len(), dat_len_before ); assert!( v.nm.as_ref().unwrap().get(NeedleId(7)).unwrap().is_none(), "a needle that never reached the disk must not be indexed at all" ); assert_eq!(v.file_count(), file_count_before); assert_eq!( v.deleted_count(), 0, "nothing was written, so nothing was deleted" ); let mut read_n = Needle { id: NeedleId(7), ..Needle::default() }; assert!(v.read_needle(&mut read_n).is_err()); } fn batch_needle(id: u64, cookie: u32, data: &[u8]) -> Needle { Needle { id: NeedleId(id), cookie: Cookie(cookie), data: data.to_vec(), data_size: data.len() as u32, ..Needle::default() } } fn dat_len(v: &Volume) -> u64 { std::fs::metadata(v.file_name(".dat")).unwrap().len() } /// A batch of durable writes shares one .dat sync and one .idx sync, /// where writing them one at a time syncs both files per needle. #[test] fn test_grouped_fsync_writes_share_one_sync() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut writes: Vec<_> = (1..=10u64) .map(|id| { ( batch_needle(id, 0xaa, format!("body-{id}").as_bytes()), true, ) }) .collect(); let results = v.write_needles_grouped(&mut writes); assert!(results.iter().all(|r| matches!(r, Ok((_, _, false))))); assert_eq!(v.sync_counts_for_test(), (1, 1)); for id in 1..=10u64 { let mut n = Needle { id: NeedleId(id), ..Needle::default() }; v.read_needle(&mut n).unwrap(); assert_eq!(n.data, format!("body-{id}").as_bytes()); } // A batch with no durable write syncs nothing, as before. let mut writes: Vec<_> = (11..=20u64) .map(|id| (batch_needle(id, 0xaa, b"lazy"), false)) .collect(); let results = v.write_needles_grouped(&mut writes); assert!(results.iter().all(|r| r.is_ok())); assert_eq!(v.sync_counts_for_test(), (1, 1)); // The per-needle path pays both syncs for every durable write. let tmp2 = TempDir::new().unwrap(); let mut one_by_one = make_test_volume(tmp2.path().to_str().unwrap()); for id in 1..=10u64 { let mut n = batch_needle(id, 0xaa, format!("body-{id}").as_bytes()); one_by_one.write_needle(&mut n, true, true).unwrap(); } assert_eq!(one_by_one.sync_counts_for_test(), (10, 10)); } /// A failed shared sync fails every entry of the run, durable or not, /// and leaves the volume as it was before the run: the .dat back at the /// run start, the clocks where they were, nothing published. #[test] fn test_grouped_failed_sync_rolls_back_the_run() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut kept = batch_needle(1, 0xaa, b"first-copy"); v.write_needle(&mut kept, true, true).unwrap(); let prior = v.nm.as_ref().unwrap().get(NeedleId(1)).unwrap().unwrap(); let dat_len_before = dat_len(&v); let last_append_before = v.last_append_at_ns; let last_modified_before = v.last_modified_ts_seconds; let file_count_before = v.file_count(); let mut writes = vec![ (batch_needle(1, 0xaa, b"second-copy"), false), (batch_needle(2, 0xbb, b"durable"), true), (batch_needle(3, 0xcc, b"lazy"), false), ]; for (n, _) in writes.iter_mut() { n.last_modified = last_modified_before + 1000; } v.fail_next_fsync_for_test(true); let results = v.write_needles_grouped(&mut writes); v.fail_next_fsync_for_test(false); assert!( results.iter().all(|r| matches!(r, Err(VolumeError::Io(_)))), "every entry of the run shares its failed sync: {results:?}" ); assert_eq!(dat_len(&v), dat_len_before, "the run is off the .dat"); assert_eq!(v.last_append_at_ns, last_append_before); assert_eq!(v.last_modified_ts_seconds, last_modified_before); let now = v.nm.as_ref().unwrap().get(NeedleId(1)).unwrap().unwrap(); assert_eq!((now.offset, now.size), (prior.offset, prior.size)); assert!(v.nm.as_ref().unwrap().get(NeedleId(2)).unwrap().is_none()); assert!(v.nm.as_ref().unwrap().get(NeedleId(3)).unwrap().is_none()); assert_eq!(v.file_count(), file_count_before); assert!( !v.is_read_only(), "a rolled-back run keeps the volume writable" ); let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; v.read_needle(&mut read_n).unwrap(); assert_eq!(read_n.data, b"first-copy"); // The same run goes through once the disk recovers. let results = v.write_needles_grouped(&mut writes); assert!(results.iter().all(|r| r.is_ok())); assert!(v.last_append_at_ns > last_append_before); } /// A repeated id starts a new run, so the second write sees the first /// one published: a different cookie is refused and the same content /// dedups, exactly as two sequential writes would. #[test] fn test_grouped_repeated_id_behaves_as_sequential_writes() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut writes = vec![ (batch_needle(1, 0xaa, b"one"), true), (batch_needle(1, 0xbb, b"imposter"), true), (batch_needle(2, 0xcc, b"two"), true), (batch_needle(2, 0xcc, b"two"), true), ]; let results = v.write_needles_grouped(&mut writes); assert!(matches!(results[0], Ok((_, _, false)))); assert!(matches!(results[1], Err(VolumeError::CookieMismatch(0xbb)))); assert!(matches!(results[2], Ok((_, _, false)))); assert!( matches!(results[3], Ok((0, _, true))), "the same content dedups against the write just before it" ); // Runs [1], [1, 2], [2]: one pair of syncs each. assert_eq!(v.sync_counts_for_test(), (3, 3)); let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; v.read_needle(&mut read_n).unwrap(); assert_eq!(read_n.data, b"one"); } /// A failed shared .idx sync fails every published entry and stops the /// volume taking writes, as it does for a single durable write. #[test] fn test_grouped_failed_idx_sync_quarantines_volume() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut writes = vec![ (batch_needle(1, 0xaa, b"durable"), true), (batch_needle(2, 0xbb, b"lazy"), false), ]; v.fail_next_idx_sync_for_test(true); let results = v.write_needles_grouped(&mut writes); v.fail_next_idx_sync_for_test(false); assert!(results.iter().all(|r| matches!(r, Err(VolumeError::Io(_))))); assert_eq!(v.sync_counts_for_test(), (1, 1)); assert!(v.is_read_only()); } /// A failed shared sync whose truncate also fails leaves an unverified /// tail, so the volume fails closed exactly as a single write does. #[test] fn test_grouped_failed_rollback_marks_volume_unavailable() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut writes = vec![ (batch_needle(1, 0xaa, b"never"), true), (batch_needle(2, 0xbb, b"landed"), false), ]; v.fail_next_fsync_for_test(true); v.fail_next_truncate_for_test(true); let results = v.write_needles_grouped(&mut writes); v.fail_next_fsync_for_test(false); v.fail_next_truncate_for_test(false); assert!(results.iter().all(|r| r.is_err())); assert!(v.unavailable_error().is_some()); assert!(v.is_read_only()); assert!(v.should_quarantine()); assert!(v.nm.as_ref().unwrap().get(NeedleId(1)).unwrap().is_none()); let mut later = vec![(batch_needle(3, 0xcc, b"refused"), true)]; let results = v.write_needles_grouped(&mut later); assert!(matches!(results[0], Err(VolumeError::Unavailable(_)))); } /// An .idx writer that tears its `tear_at`-th row: half of the row /// reaches the file, then the write fails. struct TornIdxWriter { file: File, writes: usize, tear_at: usize, fail_truncates: bool, } impl Write for TornIdxWriter { fn write(&mut self, buf: &[u8]) -> io::Result { self.writes += 1; if self.writes == self.tear_at { self.file.write_all(&buf[..buf.len() / 2])?; return Err(io::Error::other("injected torn .idx write")); } self.file.write(buf) } fn flush(&mut self) -> io::Result<()> { self.file.flush() } } impl Seek for TornIdxWriter { fn seek(&mut self, pos: SeekFrom) -> io::Result { self.file.seek(pos) } } impl crate::storage::needle_map::IdxFileWriter for TornIdxWriter { fn sync_all(&self) -> io::Result<()> { self.file.sync_all() } fn truncate_to(&mut self, len: u64) -> io::Result<()> { if self.fail_truncates { return Err(io::Error::other("injected trim failure")); } self.file.set_len(len) } } /// A durable entry whose index update fails stops the volume taking /// writes, as it does when sent on its own, so the entries after it in /// the run are refused instead of indexed behind a row that may be /// torn. Entries before it stay acked. #[test] fn test_grouped_failed_durable_index_refuses_rest_of_run() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut kept = batch_needle(4, 0xdd, b"kept"); v.write_needle(&mut kept, true, true).unwrap(); let mut other = batch_needle(5, 0xee, b"other"); v.write_needle(&mut other, true, true).unwrap(); let nm = v.nm.as_mut().unwrap(); let idx_len = nm.index_file_size(); let file = OpenOptions::new() .write(true) .open(format!("{dir}/1.idx")) .unwrap(); nm.set_idx_file( Box::new(TornIdxWriter { file, writes: 0, tear_at: 2, fail_truncates: false, }), idx_len, ); let mut writes = vec![ (batch_needle(1, 0xaa, b"before"), true), (batch_needle(2, 0xbb, b"torn"), true), (batch_needle(3, 0xcc, b"after"), true), (batch_needle(4, 0xdd, b"kept"), true), (batch_needle(5, 0xef, b"wrong cookie"), true), ]; let results = v.write_needles_grouped(&mut writes); // Two setup writes, then the run's one sync of each file. assert_eq!(v.sync_counts_for_test(), (3, 3)); assert!(v.is_read_only()); drop(v); let reopened = match Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) { Ok(v) => v, Err(e) => panic!("the volume does not reload: {e}"), }; for ((n, _), r) in writes.iter().zip(&results) { if r.is_ok() { let mut got = Needle { id: n.id, ..Needle::default() }; let read = reopened.read_needle(&mut got); assert!( read.is_ok() && got.data == n.data, "acked write {} lost on reload: {read:?}", n.id.0 ); } } assert!(matches!(results[0], Ok((_, _, false))), "{results:?}"); assert!(matches!(results[1], Err(VolumeError::Io(_))), "{results:?}"); for r in &results[2..] { assert!( matches!(r, Err(VolumeError::ReadOnly(VolumeId(1)))), "refused as it would be sent on its own: {results:?}" ); } } /// A torn .idx row is trimmed back, so the row a later write appends /// still lands aligned and survives a reload. #[test] fn test_failed_index_write_is_trimmed() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let nm = v.nm.as_mut().unwrap(); let idx_len = nm.index_file_size(); let file = OpenOptions::new() .write(true) .open(format!("{dir}/1.idx")) .unwrap(); nm.set_idx_file( Box::new(TornIdxWriter { file, writes: 0, tear_at: 1, fail_truncates: false, }), idx_len, ); let mut writes = vec![ (batch_needle(1, 0xaa, b"torn"), false), (batch_needle(2, 0xbb, b"after"), true), ]; let results = v.write_needles_grouped(&mut writes); assert!(matches!(results[0], Err(VolumeError::Io(_))), "{results:?}"); assert!(matches!(results[1], Ok((_, _, false))), "{results:?}"); drop(v); let reopened = match Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) { Ok(v) => v, Err(e) => panic!("the volume does not reload: {e}"), }; let mut got = Needle { id: NeedleId(2), ..Needle::default() }; reopened.read_needle(&mut got).unwrap(); assert_eq!(got.data, b"after"); } /// When the trim of a torn .idx row itself fails, no later row is /// appended after the torn bytes. #[test] fn test_untrimmed_torn_row_refuses_later_appends() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let nm = v.nm.as_mut().unwrap(); let idx_len = nm.index_file_size(); let file = OpenOptions::new() .write(true) .open(format!("{dir}/1.idx")) .unwrap(); nm.set_idx_file( Box::new(TornIdxWriter { file, writes: 0, tear_at: 1, fail_truncates: true, }), idx_len, ); let mut writes = vec![ (batch_needle(1, 0xaa, b"torn"), false), (batch_needle(2, 0xbb, b"after"), false), ]; let results = v.write_needles_grouped(&mut writes); assert!(matches!(results[0], Err(VolumeError::Io(_))), "{results:?}"); assert!(results[1].is_err(), "{results:?}"); // The second row was never appended behind the torn bytes. let size = std::fs::metadata(format!("{dir}/1.idx")).unwrap().len(); assert_eq!(size, idx_len + 8); } /// The I/O error streak after writing four durable needles, the ones in /// `failing` with a media error on their append, first one at a time and /// then as one grouped run. Also returns which grouped writes landed. #[cfg(any(unix, windows))] fn io_error_streaks(failing: &[u64]) -> (i32, i32, Vec) { let writes = || -> Vec<_> { (1..=4u64) .map(|id| { ( batch_needle(id, 0xaa, format!("body-{id}").as_bytes()), true, ) }) .collect() }; let failing: Vec<_> = failing.iter().map(|&id| NeedleId(id)).collect(); let tmp = TempDir::new().unwrap(); let mut one_by_one = make_test_volume(tmp.path().to_str().unwrap()); one_by_one.fail_append_for_test(&failing); for (mut n, fsync) in writes() { let _ = one_by_one.write_needle(&mut n, true, fsync); } let tmp2 = TempDir::new().unwrap(); let mut v = make_test_volume(tmp2.path().to_str().unwrap()); v.fail_append_for_test(&failing); let mut grouped = writes(); let results = v.write_needles_grouped(&mut grouped); assert!(!v.is_read_only(), "the failed appends were truncated back"); let landed = results .iter() .map(|r| matches!(r, Ok((_, _, false)))) .collect(); ( one_by_one.get_io_error_state().1, v.get_io_error_state().1, landed, ) } /// A run counts I/O errors as the same writes sent one at a time would: /// a success early in the run must not wipe out the streak that the /// failed appends after it built up, or the volume escapes quarantine. #[cfg(any(unix, windows))] #[test] fn test_grouped_run_keeps_the_io_error_streak_of_later_appends() { use crate::storage::io_error::IO_ERROR_TOLERANCE; let (one_by_one, grouped, landed) = io_error_streaks(&[2, 3, 4]); assert_eq!(landed, [true, false, false, false]); assert_eq!(one_by_one, IO_ERROR_TOLERANCE); assert_eq!(grouped, IO_ERROR_TOLERANCE); } /// The other half: a write that lands clears the errors of the appends /// queued before it, even when another append after it fails, or the /// run reaches a quarantine that the same writes one at a time do not. #[cfg(any(unix, windows))] #[test] fn test_grouped_run_clears_the_io_error_streak_of_earlier_appends() { let (one_by_one, grouped, landed) = io_error_streaks(&[1, 2, 4]); assert_eq!(landed, [false, false, true, false]); assert_eq!(one_by_one, 1); assert_eq!(grouped, 1); } /// An append whose partial bytes cannot be truncated back leaves the .dat /// tail unverified, so the volume fails closed rather than let a later /// append bury them mid-file. #[test] fn test_failed_append_rollback_marks_volume_unavailable() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut first = batch_needle(1, 0xaa, b"landed"); v.write_needle(&mut first, true, true).unwrap(); // A read-only .dat handle fails the append and the truncate-back alike. v.dat_file = Some(File::open(v.file_name(".dat")).unwrap()); let mut n = batch_needle(2, 0xbb, b"never-lands"); v.write_needle(&mut n, true, false).unwrap_err(); assert!(v.unavailable_error().is_some()); assert!(v.is_read_only()); assert!(v.should_quarantine()); assert!(v.nm.as_ref().unwrap().get(NeedleId(2)).unwrap().is_none()); let mut later = batch_needle(3, 0xcc, b"refused"); assert!(matches!( v.write_needle(&mut later, true, true), Err(VolumeError::Unavailable(_)) )); } #[test] fn test_volume_write_dedup() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"same data".to_vec(), data_size: 9, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); // Write same needle again — should be unchanged let mut n2 = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"same data".to_vec(), data_size: 9, ..Needle::default() }; n2.checksum = CRC::new(&n2.data); let (_, _, unchanged) = v.write_needle(&mut n2, true, false).unwrap(); assert!(unchanged); } #[test] fn test_volume_delete() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0xbb), data: b"delete me".to_vec(), data_size: 9, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); assert_eq!(v.file_count(), 1); let deleted_size = v .delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(0xbb), ..Needle::default() }) .unwrap(); assert!(deleted_size.0 > 0); // Additive-only: file_count stays at 1 after delete assert_eq!(v.file_count(), 1); assert_eq!(v.deleted_count(), 1); // Read should fail with Deleted let mut read_n = Needle { id: NeedleId(1), ..Needle::default() }; let err = v.read_needle(&mut read_n).unwrap_err(); assert!(matches!(err, VolumeError::Deleted)); } // Guard the Rust integrity-check tombstone path against the Go regression // where verifyDeletedNeedleIntegrity forwarded TombstoneFileSize into the // needle-size check, mismatched against the on-disk Size=0 header, and // sent every volume with a trailing deletion read-only on load. The Rust // check guards its size comparison with !size.is_deleted(); this test // keeps that guarantee from silently regressing. #[test] fn test_check_volume_data_integrity_with_deletion_tombstone() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = make_test_volume(dir); for i in 1..=3 { let data = format!("data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.delete_needle(&mut Needle { id: NeedleId(2), cookie: Cookie(2), ..Needle::default() }) .unwrap(); v.sync_to_disk().unwrap(); } let v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!( !v.is_no_write_or_delete(), "volume should not be read-only after reload with trailing deletion tombstone" ); } // Reproduce the delete-traffic TTL bug: deletes append a tombstone to the // .dat, which moves the file's mtime, and the loader read the TTL clock // back from that mtime. A volume taking delete traffic therefore had // is_expired() re-armed for another full TTL on every restart and was // never reclaimed. #[test] fn test_ttl_clock_survives_deletes() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let ttl = crate::storage::needle::ttl::TTL::read("5m").unwrap(); let last_write_ns = (SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap() .as_secs() - 2 * 60 * 60) * 1_000_000_000; let content_size = { let mut v = make_ttl_volume(dir, ttl); let mut written = Vec::new(); for i in 1..=3u64 { let data = format!("data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; let (offset, _, _) = v.write_needle(&mut n, true, false).unwrap(); written.push((offset, n.size)); } // More than one tombstone: the scan has to walk back over the whole // run of them to reach a write. for i in [2u64, 3] { v.delete_needle(&mut Needle { id: NeedleId(i), cookie: Cookie(i as u32), ..Needle::default() }) .unwrap(); } v.sync_to_disk().unwrap(); // Backdate the writes on disk so the last one sits well outside the // TTL, while the tombstones leave the .dat mtime at now. for (offset, size) in written { backdate_append_at_ns(&v.dat_path(), offset, size, last_write_ns); } v.content_size() }; let v = make_ttl_volume(dir, ttl); assert_eq!(v.last_modified_ts(), last_write_ns / 1_000_000_000); assert!( v.is_expired(content_size, 1024 * 1024), "a TTL volume whose last write is 2h old must be expired after a reload" ); } // The one layout where a .dat's order does not track its write order: // vacuum rewrites it by key, and an overwrite keeps its original, lower key. // Reading the position rather than the timestamps would recover the // highest-key needle's older write time and expire the volume before the // overwrite has lived out its TTL. #[test] fn test_ttl_clock_after_vacuum_takes_newest_write() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let ttl = crate::storage::needle::ttl::TTL::read("5m").unwrap(); let now = SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap() .as_secs(); let old_write_ns = (now - 2 * 60 * 60) * 1_000_000_000; let new_write_ns = (now - 60) * 1_000_000_000; let content_size = { let mut v = make_ttl_volume(dir, ttl); // Needle 1 is overwritten last but sorts first, so vacuum leaves it // at the head of the .dat with the newest timestamp of the three. for (id, append_at_ns) in [(2u64, old_write_ns), (3, old_write_ns), (1, new_write_ns)] { let data = format!("data {}", id); let mut n = Needle { id: NeedleId(id), cookie: Cookie(id as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; let (offset, _, _) = v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); backdate_append_at_ns(&v.dat_path(), offset, n.size, append_at_ns); } v.compact_by_index(0, 0, |_| true).unwrap(); v.commit_compact().unwrap(); v.content_size() }; let v = make_ttl_volume(dir, ttl); assert_eq!(v.last_modified_ts(), new_write_ns / 1_000_000_000); assert!( !v.is_expired(content_size, 1024 * 1024), "a volume overwritten a minute ago must not be expired after a vacuum and reload" ); } // Guard the destroy time an EC volume is reclaimed on: it was recomputed as // now+TTL every time the .vif was written, so a read-only mark, a tier // upload or an EC encode handed an already expiring volume another full TTL. #[test] fn test_expire_at_sec_counts_from_last_write() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let ttl = crate::storage::needle::ttl::TTL::read("5m").unwrap(); let now = SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap() .as_secs(); let mut v = make_ttl_volume(dir, ttl); // A volume with nothing written yet has no last write to count from, and // must not land in 1970 with its data due for destruction on sight. assert!(v.expire_at_sec() >= now); v.set_last_modified_ts_for_test(now - 3600); let want = now - 3600 + ttl.to_seconds(); for pass in 0..2 { v.save_volume_info().unwrap(); assert_eq!( v.volume_info.expire_at_sec, want, ".vif save {} moved the destroy time off the last write", pass ); } } fn make_ttl_volume(dir: &str, ttl: crate::storage::needle::ttl::TTL) -> Volume { Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec { ttl: Some(ttl), ..Default::default() }, ) .unwrap() } fn backdate_append_at_ns(dat_path: &str, offset: u64, size: Size, append_at_ns: u64) { let ts_offset = offset + NEEDLE_HEADER_SIZE as u64 + size.0 as u64 + NEEDLE_CHECKSUM_SIZE as u64; let mut f = OpenOptions::new().write(true).open(dat_path).unwrap(); f.seek(SeekFrom::Start(ts_offset)).unwrap(); f.write_all(&append_at_ns.to_be_bytes()).unwrap(); } fn write_three_needles(dir: &str) { let mut v = make_test_volume(dir); for i in 1..=3u64 { let data = format!("data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); } fn reload_volume(dir: &str) -> Volume { Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap() } // A torn shutdown can leave bytes in the .dat past the last indexed // needle. Appending after such a tail would place the next needle at an // offset the 8-byte-unit .idx encoding may not represent, so the load // check must quarantine the volume read-only, matching Go's // verifyNeedleIntegrity "actual N bytes expected M bytes" behavior. #[test] fn test_integrity_detects_unindexed_dat_tail() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); write_three_needles(dir); let dat_path = volume_file_name(dir, "", VolumeId(1)) + ".dat"; let mut f = OpenOptions::new().append(true).open(&dat_path).unwrap(); f.write_all(&[0xFFu8; 100]).unwrap(); f.sync_all().unwrap(); drop(f); let v = reload_volume(dir); assert!( v.is_no_write_or_delete(), "volume with unindexed .dat tail must load read-only" ); } // Go's tail check is v3-only, so it serves a v1/v2 volume with an // unindexed tail read-write. Checking it here flipped whole legacy disks // read-only on their first boot under this server. #[test] fn test_integrity_skips_dat_tail_check_before_v3() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec { version: VERSION_2, ..Default::default() }, ) .unwrap(); for i in 1..=3u64 { let data = format!("data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); } let dat_path = volume_file_name(dir, "", VolumeId(1)) + ".dat"; let mut f = OpenOptions::new().append(true).open(&dat_path).unwrap(); f.write_all(&[0xFFu8; 96]).unwrap(); f.sync_all().unwrap(); drop(f); let v = reload_volume(dir); assert_eq!(v.version(), VERSION_2, "volume should reload as v2"); assert!( !v.is_no_write_or_delete(), "v2 volume with unindexed .dat tail must stay writable, as in Go" ); } // Same torn tail, but with a deletion tombstone as the last indexed // record — the tombstone path must also verify the .dat ends at it. #[test] fn test_integrity_detects_tail_after_tombstone() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = make_test_volume(dir); let data = b"data 1".to_vec(); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: data.clone(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(1), ..Needle::default() }) .unwrap(); v.sync_to_disk().unwrap(); } let dat_path = volume_file_name(dir, "", VolumeId(1)) + ".dat"; let mut f = OpenOptions::new().append(true).open(&dat_path).unwrap(); f.write_all(&[0xFFu8; 64]).unwrap(); f.sync_all().unwrap(); drop(f); let v = reload_volume(dir); assert!( v.is_no_write_or_delete(), "volume with unindexed tail after tombstone must load read-only" ); } // A key-sorted .idx (legacy weed fix output) puts the highest-key needle // last by file position, not the .dat-tail needle. The check must find // the true tail entry via the max-offset scan instead of falsely flipping // a healthy volume read-only. #[test] fn test_integrity_key_sorted_idx_no_false_readonly() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); write_three_needles(dir); // Swap the last two .idx entries so the file-position-last entry // references a mid-file needle. let idx_path = volume_file_name(dir, "", VolumeId(1)) + ".idx"; let content = fs::read(&idx_path).unwrap(); assert_eq!(content.len(), 3 * NEEDLE_MAP_ENTRY_SIZE); let mut swapped = content.clone(); swapped[NEEDLE_MAP_ENTRY_SIZE..2 * NEEDLE_MAP_ENTRY_SIZE] .copy_from_slice(&content[2 * NEEDLE_MAP_ENTRY_SIZE..]); swapped[2 * NEEDLE_MAP_ENTRY_SIZE..] .copy_from_slice(&content[NEEDLE_MAP_ENTRY_SIZE..2 * NEEDLE_MAP_ENTRY_SIZE]); fs::write(&idx_path, swapped).unwrap(); let v = reload_volume(dir); assert!( !v.is_no_write_or_delete(), "healthy volume with key-sorted .idx must not load read-only" ); } // A .dat truncated mid-needle (crash during append) must quarantine. #[test] fn test_integrity_detects_truncated_dat_tail() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); write_three_needles(dir); let dat_path = volume_file_name(dir, "", VolumeId(1)) + ".dat"; let len = fs::metadata(&dat_path).unwrap().len(); let f = OpenOptions::new().write(true).open(&dat_path).unwrap(); f.set_len(len - 5).unwrap(); f.sync_all().unwrap(); drop(f); let v = reload_volume(dir); assert!( v.is_no_write_or_delete(), "volume with truncated .dat tail must load read-only" ); } #[test] fn test_scrub_empty_volume() { // Mirror of Go's TestScrubVolumeData "zero-size volume without index" // case (weed/storage/volume_checking_test.go): a freshly created / // pre-allocated volume has a superblock-only .dat and a zero-size .idx, // and must scrub clean instead of being flagged as corrupt. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let v = make_test_volume(dir); // .dat holds only the superblock; .idx is empty. assert_eq!(v.dat_file_size().unwrap(), SUPER_BLOCK_SIZE as u64); let (files_checked, broken) = v.scrub().unwrap(); assert_eq!(files_checked, 0); assert!( broken.is_empty(), "empty volume should scrub clean, got {:?}", broken ); // The index-only mode must agree. let (idx_checked, idx_broken) = v.scrub_index().unwrap(); assert_eq!(idx_checked, 0); assert!( idx_broken.is_empty(), "empty volume should scrub_index clean, got {:?}", idx_broken ); } #[test] fn test_scrub_overwritten_volume_scrubs_clean() { // An overwrite/delete appends a second .dat record + .idx row. Walking // the on-disk .idx (not the deduped map) makes total_read match the // physical .dat, so a healthy overwritten volume is NOT flagged broken. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for (id, body) in [(1u64, "first version"), (1, "second version"), (2, "other")] { let mut n = Needle { id: NeedleId(id), cookie: Cookie(id as u32), data: body.as_bytes().to_vec(), data_size: body.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); let (count, broken) = v.scrub().unwrap(); assert!( broken.is_empty(), "overwritten volume should scrub clean, got {:?}", broken ); assert_eq!(count, 3, "scrub must count every .idx row"); } #[test] fn test_scrub_ignores_offset0_tombstone() { // A remote-tier delete appends an offset-0 tombstone to the .idx with no // physical .dat bytes; it must not flag the volume (neither the size // reconcile nor the structural overlap check). let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let data = b"needle data".to_vec(); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: data.clone(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); // Append an offset-0 logical tombstone to the on-disk .idx. let mut f = std::fs::OpenOptions::new() .append(true) .open(v.file_name(".idx")) .unwrap(); crate::storage::idx::write_index_entry( &mut f, NeedleId(2), Offset::from_actual_offset(0), Size(-1), ) .unwrap(); f.sync_all().unwrap(); drop(f); let (count, broken) = v.scrub().unwrap(); assert!( broken.is_empty(), "offset-0 tombstone must not flag the volume, got {:?}", broken ); assert_eq!(count, 2, "both .idx rows are walked"); } /// The .dat offset a local delete's .idx row points at: the physical /// tombstone record. Mirrors the Go test helper localTombstoneOffset. fn local_tombstone_offset(v: &Volume, id: u64) -> Offset { let mut idx_file = File::open(v.file_name(".idx")).unwrap(); let mut found = Offset::default(); idx::walk_index_file(&mut idx_file, 0, |key, offset, size| { if key == NeedleId(id) && !offset.is_zero() && size.is_deleted() { found = offset; } Ok(()) }) .unwrap(); assert!( !found.is_zero(), "expected a local deletion tombstone for needle {} in .idx", id ); found } #[test] fn test_scrub_checks_local_deletion_tombstone() { // Mirror of Go's TestScrubVolumeDataChecksLocalDeletionTombstone: a // local delete's tombstone record is read and its needle id checked // against the .idx key. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"needle data"); v.delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(0x12345678), ..Needle::default() }) .unwrap(); // A later record keeps the tombstone mid-file rather than at the tail. write_test_needle(&mut v, 2, b"needle data"); v.sync_to_disk().unwrap(); let tombstone_offset = local_tombstone_offset(&v, 1); let (_count, broken) = v.scrub().unwrap(); assert!( broken.is_empty(), "healthy local deletion tombstone must pass scrub, got {:?}", broken ); let mut id_bytes = [0u8; NEEDLE_ID_SIZE]; NeedleId(99).to_bytes(&mut id_bytes); let mut dat = OpenOptions::new() .write(true) .open(v.file_name(".dat")) .unwrap(); dat.seek(SeekFrom::Start( tombstone_offset.to_actual_offset() as u64 + COOKIE_SIZE as u64, )) .unwrap(); dat.write_all(&id_bytes).unwrap(); dat.sync_all().unwrap(); let (_count, broken) = v.scrub().unwrap(); assert!( broken .iter() .any(|e| e.contains("does not match needle's Id")), "scrub should report the corrupted tombstone's Id, got {:?}", broken ); } #[test] fn test_scrub_checks_live_needle_id() { // Mirror of Go's TestScrubVolumeDataChecksLiveNeedleId: a live needle // whose stored id is damaged still reads clean — the data CRC does not // cover the header — so the scrub must catch it via the index key. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"needle data"); v.sync_to_disk().unwrap(); let mut idx_file = File::open(v.file_name(".idx")).unwrap(); let mut live_offset = Offset::default(); idx::walk_index_file(&mut idx_file, 0, |key, offset, size| { if key == NeedleId(1) && !offset.is_zero() && !size.is_deleted() { live_offset = offset; } Ok(()) }) .unwrap(); let (_count, broken) = v.scrub().unwrap(); assert!( broken.is_empty(), "healthy needle must pass, got {:?}", broken ); let mut id_bytes = [0u8; NEEDLE_ID_SIZE]; NeedleId(99).to_bytes(&mut id_bytes); let mut dat = OpenOptions::new() .write(true) .open(v.file_name(".dat")) .unwrap(); dat.seek(SeekFrom::Start( live_offset.to_actual_offset() as u64 + COOKIE_SIZE as u64, )) .unwrap(); dat.write_all(&id_bytes).unwrap(); dat.sync_all().unwrap(); let (_count, broken) = v.scrub().unwrap(); assert!( broken .iter() .any(|e| e.contains("does not match needle's Id")), "scrub should report the corrupted live needle's Id, got {:?}", broken ); } #[test] fn test_scrub_reports_truncated_local_deletion_tombstone() { // Mirror of Go's TestScrubVolumeDataReportsTruncatedLocalDeletionTombstone. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, b"needle data"); v.delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(0x12345678), ..Needle::default() }) .unwrap(); v.sync_to_disk().unwrap(); let tombstone_offset = local_tombstone_offset(&v, 1); let dat = OpenOptions::new() .write(true) .open(v.file_name(".dat")) .unwrap(); dat.set_len(tombstone_offset.to_actual_offset() as u64 + NEEDLE_HEADER_SIZE as u64) .unwrap(); dat.sync_all().unwrap(); let (_count, broken) = v.scrub().unwrap(); assert!( broken .iter() .any(|e| e.contains("failed to read needle 1 on volume 1")), "scrub should report the truncated tombstone read, got {:?}", broken ); } #[test] fn test_scrub_index_flags_zero_size_idx_with_data() { // A populated .dat with an empty .idx is corruption — the pre-allocated // exception only covers a superblock-only .dat. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let data = b"needle data".to_vec(); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: data.clone(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); assert!(v.dat_file_size().unwrap() > SUPER_BLOCK_SIZE as u64); // Truncate the .idx to zero while the .dat keeps its needle. std::fs::File::create(v.file_name(".idx")).unwrap(); let (count, broken) = v.scrub_index().unwrap(); assert_eq!(count, 0); assert!( broken.iter().any(|e| e.contains("zero-size IDX file")), "expected zero-size IDX error, got {:?}", broken ); } #[test] fn test_scrub_healthy_volume() { // Mirror of Go's TestScrubVolumeData "healthy volume" case: a volume // with live needles scrubs clean and the .dat size accounting matches. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=5 { let data = format!("needle data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); let (files_checked, broken) = v.scrub().unwrap(); assert_eq!(files_checked, 5); assert!( broken.is_empty(), "healthy volume should scrub clean, got {:?}", broken ); } #[test] fn test_volume_multiple_needles() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=10 { let data = format!("needle data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } assert_eq!(v.file_count(), 10); assert_eq!(v.max_file_key(), NeedleId(10)); // Read back needle 5 let mut n = Needle { id: NeedleId(5), ..Needle::default() }; v.read_needle(&mut n).unwrap(); assert_eq!(n.data, b"needle data 5"); } #[test] fn test_volume_reload_from_disk() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); // Write some needles { let mut v = make_test_volume(dir); for i in 1..=3 { let data = format!("data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); } // Reload and verify let v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert_eq!(v.file_count(), 3); let mut n = Needle { id: NeedleId(2), ..Needle::default() }; v.read_needle(&mut n).unwrap(); assert_eq!(std::str::from_utf8(&n.data).unwrap(), "data 2"); } #[test] fn test_redb_volume_close_then_reload_keeps_counters_exact() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let open = || { Volume::new( dir, dir, VolumeId(1), NeedleMapKind::Redb, &VolumeSpec::default(), ) .unwrap() }; { let mut v = open(); for i in 1..=3 { let data = format!("data {}", i); let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: data.as_bytes().to_vec(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } // Volume::close is the shutdown path (store -> disk location -> // volume). It must checkpoint the redb index, or the reload // replays rows the table already holds and inflates the counters. v.close(); } let v = open(); assert_eq!(v.file_count(), 3); assert_eq!(v.deleted_count(), 0); let mut n = Needle { id: NeedleId(2), ..Needle::default() }; v.read_needle(&mut n).unwrap(); assert_eq!(std::str::from_utf8(&n.data).unwrap(), "data 2"); } #[test] fn test_redb_volume_checkpoint_flushes_dat_before_index() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::Redb, &VolumeSpec::default(), ) .unwrap(); let write = |v: &mut Volume, i: u64| { let mut n = Needle { id: NeedleId(i), cookie: Cookie(1), data: b"x".to_vec(), data_size: 1, ..Needle::default() }; // fsync=false: the .dat append is not flushed by the write itself. v.write_needle(&mut n, true, false).unwrap(); }; for i in 1..1000 { write(&mut v, i); } // No checkpoint due yet, so META still holds the load-time .idx // size. Read live: copying the open .rdb fails on Windows, where // redb's file lock is mandatory (see live_meta_idx_size). assert_eq!(v.live_meta_idx_size_for_test(), Some(0)); // The 1000th write makes an index checkpoint due. A checkpoint makes // the index durable, so the volume has to flush the .dat first, and // when that flush fails nothing may be checkpointed: a durable index // row pointing past the end of an unflushed .dat loads read-only. v.fail_next_fsync_for_test(true); write(&mut v, 1000); assert_eq!( v.live_meta_idx_size_for_test(), Some(0), "skipped checkpoint must not record progress" ); v.fail_next_fsync_for_test(false); write(&mut v, 1001); assert_eq!( v.live_meta_idx_size_for_test(), Some(1001 * NEEDLE_MAP_ENTRY_SIZE as u64) ); } #[test] fn test_relocate_index_to_moves_index_and_serves_reads() { let root = TempDir::new().unwrap(); let data_dir = root.path().join("data"); let idx_dir = root.path().join("idx"); fs::create_dir_all(&data_dir).unwrap(); fs::create_dir_all(&idx_dir).unwrap(); let data = data_dir.to_str().unwrap(); let idx = idx_dir.to_str().unwrap(); // Create the volume with its index co-located in the data dir (the state // an EC reconstruct leaves), write a needle, and flush. let mut v = Volume::new( data, data, VolumeId(7), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); let payload = b"payload-across-relocate".to_vec(); let mut n = Needle { id: NeedleId(42), cookie: Cookie(0x55), data: payload.clone(), data_size: payload.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); let data_idx = format!("{data}/7.idx"); let idx_dir_idx = format!("{idx}/7.idx"); assert!( Path::new(&data_idx).exists(), "precondition: index co-located with the data" ); v.relocate_index_to(idx).unwrap(); assert!( Path::new(&idx_dir_idx).exists(), "index moved to the idx dir" ); assert!( !Path::new(&data_idx).exists(), "index gone from the data dir" ); assert_eq!(v.file_count(), 1); // The volume reloaded in place, so the needle still reads back. let mut got = Needle { id: NeedleId(42), ..Needle::default() }; v.read_needle(&mut got).unwrap(); assert_eq!(got.data, payload, "needle content survives the relocate"); // Relocating again is a no-op: the index is already where asked. v.relocate_index_to(idx).unwrap(); assert!(Path::new(&idx_dir_idx).exists()); } #[test] fn test_load_keeps_index_co_located_with_the_data() { let root = TempDir::new().unwrap(); let data_dir = root.path().join("data"); let idx_dir = root.path().join("idx"); fs::create_dir_all(&data_dir).unwrap(); fs::create_dir_all(&idx_dir).unwrap(); let data = data_dir.to_str().unwrap(); let idx = idx_dir.to_str().unwrap(); let mut v = Volume::new( data, data, VolumeId(7), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); let payload = b"payload-beside-the-data".to_vec(); let mut n = Needle { id: NeedleId(42), cookie: Cookie(0x55), data: payload.clone(), data_size: payload.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); drop(v); // --dir.idx now names an empty directory: the index already beside the // data keeps serving, and nothing lands in the new directory. let reopened = Volume::new( data, idx, VolumeId(7), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!( Path::new(&format!("{data}/7.idx")).exists(), "index stays with the data" ); assert!( !Path::new(&format!("{idx}/7.idx")).exists(), "nothing written to the new idx dir" ); let mut got = Needle { id: NeedleId(42), ..Needle::default() }; reopened.read_needle(&mut got).unwrap(); assert_eq!(got.data, payload); } #[test] fn test_relocate_index_to_noop_when_already_in_place() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: b"x".to_vec(), data_size: 1, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); // Data and index share a directory, so there is nothing to move. v.relocate_index_to(dir).unwrap(); assert!(Path::new(&format!("{dir}/1.idx")).exists()); let mut got = Needle { id: NeedleId(1), ..Needle::default() }; v.read_needle(&mut got).unwrap(); assert_eq!(got.data, b"x"); } #[test] fn test_volume_cookie_mismatch() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0xaa), data: b"original".to_vec(), data_size: 8, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); // Write with wrong cookie let mut n2 = Needle { id: NeedleId(1), cookie: Cookie(0xbb), data: b"overwrite".to_vec(), data_size: 9, ..Needle::default() }; let err = v.write_needle(&mut n2, true, false).unwrap_err(); assert!(matches!(err, VolumeError::CookieMismatch(_))); } // A size disagreeing with the blob's own header indexes the needle at the wrong // length and, on v3, stamps the append timestamp into the middle of the needle. #[test] fn test_write_needle_blob_rejects_size_mismatch() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x12345678), data: b"the merged payload".to_vec(), data_size: 18, ..Needle::default() }; n.checksum = CRC::new(&n.data); let (offset, _, _) = v.write_needle(&mut n, true, false).unwrap(); let blob = v.read_needle_blob(offset as i64, n.size).unwrap(); let dat_size_before = v.dat_file_size().unwrap(); // Size(n.data_size) is what append reports, and what a caller following the // payload-size convention would send. let err = v .write_needle_blob_and_index(NeedleId(2), &blob, Size(n.data_size as i32)) .unwrap_err(); assert!(matches!(err, VolumeError::Io(_)), "got {err:?}"); assert_eq!(v.dat_file_size().unwrap(), dat_size_before); v.write_needle_blob_and_index(NeedleId(2), &blob, n.size) .unwrap(); } // A blob shorter or longer than its record size leaves .dat off the record // grid: later writes index at truncated offsets, or a scan reads the leftover // bytes as the next record. #[test] fn test_write_needle_blob_rejects_length_mismatch() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x12345678), data: b"the merged payload".to_vec(), data_size: 18, ..Needle::default() }; n.checksum = CRC::new(&n.data); let (offset, _, _) = v.write_needle(&mut n, true, false).unwrap(); let blob = v.read_needle_blob(offset as i64, n.size).unwrap(); let dat_size_before = v.dat_file_size().unwrap(); let mut too_long = blob.clone(); too_long.push(0); let too_short = blob[..blob.len() - 1].to_vec(); let mut eight_long = blob.clone(); eight_long.extend_from_slice(&[0u8; 8]); for mutated in [&too_long, &too_short, &eight_long] { let err = v .write_needle_blob_and_index(NeedleId(2), mutated, n.size) .unwrap_err(); assert!(matches!(err, VolumeError::Io(_)), "got {err:?}"); assert_eq!(v.dat_file_size().unwrap(), dat_size_before); } // Later ordinary writes still read back correctly. let mut next = Needle { id: NeedleId(3), cookie: Cookie(2), data: b"next".to_vec(), data_size: 4, ..Needle::default() }; next.checksum = CRC::new(&next.data); v.write_needle(&mut next, true, false).unwrap(); let mut got = Needle { id: NeedleId(3), ..Needle::default() }; v.read_needle(&mut got).unwrap(); assert_eq!(got.data, b"next"); } #[test] fn test_read_blob_negative_does_not_panic() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let v = make_test_volume(dir); let res = v.read_needle_blob(0, Size(-100)); assert!(res.is_err(), "negative size must return Err, not panic"); match res.unwrap_err() { VolumeError::Io(e) => assert_eq!(e.kind(), std::io::ErrorKind::InvalidData), e => panic!("expected Io InvalidData, got {e:?}"), } } #[test] fn test_read_blob_zero_size_not_rejected_by_validation() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let v = make_test_volume(dir); // Size(0) must not be rejected by the negativity guard: the read may // Ok or fail on empty-volume IO, but never with our validation message. match v.read_needle_blob(0, Size(0)) { Ok(_) => {} Err(VolumeError::Io(e)) => { assert!( !e.to_string().contains("invalid needle size"), "Size(0) must pass validation, got {e}" ); } Err(e) => panic!("unexpected error kind for Size(0): {e:?}"), } } #[test] fn test_volume_destroy() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let dat_path; let idx_path; { let mut v = make_test_volume(dir); dat_path = v.file_name(".dat"); idx_path = v.file_name(".idx"); assert!(Path::new(&dat_path).exists()); v.destroy(false, false, false).unwrap(); } assert!(!Path::new(&dat_path).exists()); assert!(!Path::new(&idx_path).exists()); } #[test] fn test_get_append_at_ns() { let t1 = get_append_at_ns(0); assert!(t1 > 0); let t2 = get_append_at_ns(t1); assert!(t2 > t1); // If we pass a future timestamp, should return last+1 let future = u64::MAX - 1; let t3 = get_append_at_ns(future); assert_eq!(t3, future + 1); } #[test] fn test_volume_compact() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); // Write 3 needles for i in 1..=3u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: format!("data-{}", i).into_bytes(), data_size: format!("data-{}", i).len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } assert_eq!(v.file_count(), 3); // Delete needle 2 let mut del = Needle { id: NeedleId(2), cookie: Cookie(2), ..Needle::default() }; v.delete_needle(&mut del).unwrap(); // Additive-only: file_count stays at 3 after delete assert_eq!(v.file_count(), 3); assert_eq!(v.deleted_count(), 1); let dat_size_before = v.dat_file_size().unwrap(); // Compact v.compact_by_index(0, 0, |_| true).unwrap(); // Verify compact files exist assert!(Path::new(&v.file_name(".cpd")).exists()); assert!(Path::new(&v.file_name(".cpx")).exists()); // Commit: swap files and reload v.commit_compact().unwrap(); // After compaction: 2 live needles, 0 deleted assert_eq!(v.file_count(), 2); assert_eq!(v.deleted_count(), 0); // Dat should be smaller (deleted needle removed) let dat_size_after = v.dat_file_size().unwrap(); assert!( dat_size_after < dat_size_before, "dat should shrink after compact" ); // Read back live needles let mut n1 = Needle { id: NeedleId(1), ..Needle::default() }; v.read_needle(&mut n1).unwrap(); assert_eq!(n1.data, b"data-1"); let mut n3 = Needle { id: NeedleId(3), ..Needle::default() }; v.read_needle(&mut n3).unwrap(); assert_eq!(n3.data, b"data-3"); // Needle 2 should not exist let mut n2 = Needle { id: NeedleId(2), ..Needle::default() }; assert!(v.read_needle(&mut n2).is_err()); // Compact files should not exist after commit assert!(!Path::new(&v.file_name(".cpd")).exists()); assert!(!Path::new(&v.file_name(".cpx")).exists()); // Cleanup should be a no-op v.cleanup_compact().unwrap(); } /// Guards the copy-phase integrity check against regressing into /// double-subtracting skipped bytes: expected_live_bytes already excludes /// needles dropped as unreadable (they continue before the tally), so the /// check must compare it directly against the compacted .dat size. #[test] fn test_exceeds_expected_compacted_size() { assert!(!exceeds_expected_compacted_size(100, 100)); assert!(!exceeds_expected_compacted_size(100, 150)); assert!(exceeds_expected_compacted_size(100, 90)); } /// A write that lands on the live volume mid-copy must not trip the /// post-copy integrity check. The Rust port snapshots the index entries /// before the copy loop (equivalent to Go's frozen oldNm), so a concurrent /// write is invisible to the tally and the check stays quiet. The write /// is then replayed by makeup_diff during commit_compact. #[test] fn test_compact_by_index_tolerates_concurrent_write() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=8u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: format!("data-{}", i).into_bytes(), data_size: format!("data-{}", i).len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.compact_by_index(0, 0, |_| true).unwrap(); assert!(Path::new(&v.file_name(".cpd")).exists()); // A write arriving after the snapshot but before commit must survive // via makeup_diff, exactly like a concurrent write in the Go server. let mut late = Needle { id: NeedleId(99), cookie: Cookie(99), data: b"late-write".to_vec(), data_size: 10, ..Needle::default() }; v.write_needle(&mut late, true, false).unwrap(); v.commit_compact().unwrap(); let mut got = Needle { id: NeedleId(99), cookie: Cookie(99), ..Needle::default() }; v.read_needle(&mut got).unwrap(); assert_eq!(got.data, b"late-write"); } /// Mirrors Go's TestConcurrentWriteCrossesOffsetBoundary (issue #11410): /// a replayed write's index entry must encode all offset bytes even when /// old and new offsets sit in different 32 GiB ranges. Unix-only: Windows /// set_len eagerly allocates the 64 GiB extension. #[test] #[cfg(all(unix, feature = "5bytes"))] fn test_makeup_diff_replay_crosses_offset_boundary() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); write_test_needle(&mut v, 1, &[b'x'; 32]); v.dat_file.as_ref().unwrap().set_len(64u64 << 30).unwrap(); v.compact_by_index(0, 0, |_| true).unwrap(); let late_data = vec![b'x'; 113]; write_test_needle(&mut v, 342511246, &late_data); let mut before = Needle { id: NeedleId(342511246), ..Needle::default() }; v.read_needle(&mut before).unwrap(); assert_eq!(before.data, late_data); let expected_offset = fs::metadata(v.file_name(".cpd")).unwrap().len() as i64; v.commit_compact().unwrap(); let mut idx_file = File::open(v.file_name(".idx")).unwrap(); let mut actual_offset = 0i64; crate::storage::idx::walk_index_file(&mut idx_file, 0, |key, offset, _size| { if key == NeedleId(342511246) { actual_offset = offset.to_actual_offset(); } Ok(()) }) .unwrap(); assert_eq!(actual_offset, expected_offset); let mut after = Needle { id: NeedleId(342511246), ..Needle::default() }; v.read_needle(&mut after).unwrap(); assert_eq!(after.data, late_data); v.compact_by_index(0, 0, |_| true).unwrap(); v.commit_compact().unwrap(); let mut third = Needle { id: NeedleId(342511246), ..Needle::default() }; v.read_needle(&mut third).unwrap(); assert_eq!(third.data, late_data); } /// Vacuum compaction must tolerate an .idx entry whose offset points past /// the end of the .dat file. The bad /// entry is silently dropped from the resulting .cpx; healthy needles /// survive untouched. #[test] fn test_compact_by_index_drops_dangling_needle() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); // Write a handful of healthy needles to establish a baseline .dat/.idx. for i in 1..=5u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: format!("payload-{}", i).into_bytes(), data_size: format!("payload-{}", i).len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); let dat_size = v.dat_file_size().unwrap(); let bad_key = NeedleId(9999); let bad_offset = Offset::from_actual_offset((dat_size + 1024 * 1024) as i64); let bad_size = Size(2048); v.nm.as_mut() .expect("needle map present") .put(bad_key, bad_offset, bad_size) .unwrap(); v.nm.as_ref().unwrap().sync().unwrap(); // Vacuum must succeed in spite of the dangling entry. v.compact_by_index(0, 0, |_| true) .expect("compact_by_index should tolerate dangling entries"); // Walk the resulting .cpx and confirm the bad key was dropped while // every healthy key made it through. let cpx_path = v.file_name(".cpx"); let mut cpx = File::open(&cpx_path).unwrap(); let mut kept: Vec = Vec::new(); idx::walk_index_file(&mut cpx, 0, |key, _, size| { if !size.is_deleted() { kept.push(key.0); } Ok(()) }) .unwrap(); assert!( !kept.contains(&bad_key.0), "dangling key {} should have been dropped from .cpx, got {:?}", bad_key.0, kept ); for i in 1..=5u64 { assert!( kept.contains(&i), "healthy key {} missing from compacted .cpx, got {:?}", i, kept ); } } /// The needle map's max_needle_end accumulator must let volume.load /// detect an .idx whose entries point past the end of the .dat — the /// deeper-than-tail corruption shape that the existing /// last-10-entries scan cannot see. The check is populated by the load /// walk and read in volume.load() to flip the volume read-only. #[test] fn test_max_needle_end_detects_dangling_entry() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=4u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: format!("data-{}", i).into_bytes(), data_size: format!("data-{}", i).len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); let dat_size = v.dat_file_size().unwrap() as i64; let idx_path = v.file_name(".idx"); let version = v.version(); // Sanity: a fresh load walk over the healthy .idx puts max_needle_end // somewhere inside the .dat. let mut idx_reader = File::open(&idx_path).unwrap(); let healthy_nm = CompactNeedleMap::load_from_idx(&mut idx_reader, version).unwrap(); let healthy_end = healthy_nm.max_needle_end(); assert!( healthy_end > 0 && healthy_end <= dat_size, "healthy volume should have max_needle_end ({}) in [1, dat_size={}]", healthy_end, dat_size ); // Inject a dangling entry by appending a bogus 16/17-byte record // directly to the .idx, then reload. The load walk should observe // max_needle_end past dat_size — which is exactly the signal // volume.load uses to mark the volume read-only. let bad_offset = Offset::from_actual_offset(dat_size + 4 * 1024 * 1024); let mut idx_append = OpenOptions::new().append(true).open(&idx_path).unwrap(); idx::write_index_entry(&mut idx_append, NeedleId(9999), bad_offset, Size(1024)).unwrap(); idx_append.sync_all().unwrap(); let mut idx_reread = File::open(&idx_path).unwrap(); let bad_nm = CompactNeedleMap::load_from_idx(&mut idx_reread, version).unwrap(); let bad_end = bad_nm.max_needle_end(); assert!( bad_end > dat_size, "after dangling-entry inject max_needle_end ({}) should exceed dat_size ({})", bad_end, dat_size ); } #[test] fn test_stream_info_locates_needle_data() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); // Write a needle large enough to have meaningful data let data = vec![0xABu8; 2048]; let mut n = Needle { id: NeedleId(42), cookie: Cookie(0xDEADBEEF), data: data.clone(), data_size: data.len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); // Read stream info let mut read_n = Needle { id: NeedleId(42), cookie: Cookie(0xDEADBEEF), ..Needle::default() }; let mut plan = v.needle_read_plan(NeedleId(42), false).unwrap(); plan.read_meta(&mut read_n).unwrap(); let info = plan.into_stream_info(&read_n); assert_eq!(info.needle_id, NeedleId(42)); assert_eq!(info.data_size, data.len() as u32); assert!(info.data_file_offset > 0); } #[test] fn test_remote_vif_load_blocks_writes_but_allows_delete() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let dat_size_before_reload = { let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x1234), data: b"remote".to_vec(), data_size: 6, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); let vif = VifVolumeInfo { files: vec![VifRemoteFile { backend_type: "s3".to_string(), backend_id: "vif_rw_test".to_string(), key: "remote-key".to_string(), offset: 0, file_size: v.dat_file_size().unwrap(), modified_time: 123, extension: ".dat".to_string(), }], version: v.version().0 as u32, ..VifVolumeInfo::default() }; std::fs::write( format!("{}/1.vif", dir), serde_json::to_string_pretty(&vif).unwrap(), ) .unwrap(); // Register a dummy S3 backend so load_remote_dat_file can look it // up. This test never reads remote data, so a dead endpoint is fine. // Use a test-specific backend_id to avoid racing with other tests // that share the global registry. let tier_config = crate::remote_storage::s3_tier::S3TierConfig { access_key: "access".to_string(), secret_key: "secret".to_string(), region: "us-east-1".to_string(), bucket: "bucket-a".to_string(), endpoint: "http://127.0.0.1:1".to_string(), storage_class: "STANDARD".to_string(), force_path_style: true, }; crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap() .register( "s3.vif_rw_test".to_string(), crate::remote_storage::s3_tier::S3TierBackend::new(&tier_config), ); v.dat_file_size().unwrap() }; let mut v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!(v.is_read_only()); assert!(!v.no_write_or_delete); assert!(v.no_write_can_delete); let err = v .write_needle( &mut Needle { id: NeedleId(2), cookie: Cookie(0x5678), data: b"blocked".to_vec(), data_size: 7, ..Needle::default() }, true, false, ) .unwrap_err(); assert!(matches!(err, VolumeError::ReadOnly(_))); let deleted_size = v .delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(0x1234), ..Needle::default() }) .unwrap(); assert!(deleted_size.0 > 0); assert_eq!(v.dat_file_size().unwrap(), dat_size_before_reload); crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap() .remove("s3.vif_rw_test"); } /// Build a volume with `needles` needles, tier it to a fake remote backend, /// and reload it the way a restart would — so it comes back read-only with /// its index on disk. The local .dat is left in place, matching the state a /// completed tier-down download leaves behind. fn reload_as_tiered(dir: &str, backend_id: &str, needles: u64) -> Volume { { let mut v = make_test_volume(dir); for i in 1..=needles { let mut n = Needle { id: NeedleId(i), cookie: Cookie(0x1234), data: format!("needle-{i}").into_bytes(), data_size: format!("needle-{i}").len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } let vif = VifVolumeInfo { files: vec![VifRemoteFile { backend_type: "s3".to_string(), backend_id: backend_id.to_string(), key: "remote-key".to_string(), offset: 0, file_size: v.dat_file_size().unwrap(), modified_time: 123, extension: ".dat".to_string(), }], version: v.version().0 as u32, ..VifVolumeInfo::default() }; std::fs::write( format!("{}/1.vif", dir), serde_json::to_string_pretty(&vif).unwrap(), ) .unwrap(); let tier_config = crate::remote_storage::s3_tier::S3TierConfig { access_key: "access".to_string(), secret_key: "secret".to_string(), region: "us-east-1".to_string(), bucket: "bucket-a".to_string(), endpoint: "http://127.0.0.1:1".to_string(), storage_class: "STANDARD".to_string(), force_path_style: true, }; crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap() .register( format!("s3.{backend_id}"), crate::remote_storage::s3_tier::S3TierBackend::new(&tier_config), ); } Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap() } /// The remote reference and the derived write mode are the same fact, so a /// caller must not be able to move one without the other. Every edit goes /// through update_remote_files, which refreshes the mode on the way out. #[test] fn test_update_remote_files_refreshes_the_derived_write_mode() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let file_size = v.dat_file_size().unwrap(); assert!(!v.has_remote_file()); assert!(!v.is_no_write_can_delete()); assert!(!v.is_no_write_or_delete()); v.update_remote_files(|files| { files.push(PbRemoteFile { backend_type: "s3".to_string(), backend_id: "default".to_string(), key: "remote-key".to_string(), offset: 0, file_size, modified_time: 123, extension: ".dat".to_string(), }) }) .unwrap(); assert!(v.has_remote_file()); assert!( v.is_no_write_can_delete(), "a remote-backed volume only serves deletes" ); assert!(!v.is_no_write_or_delete()); v.update_remote_files(|files| { files.remove(0); }) .unwrap(); assert!(!v.has_remote_file()); assert!( !v.is_no_write_can_delete(), "dropping the last remote reference publishes the volume as writable" ); assert!(!v.is_no_write_or_delete()); } // Tier-down clears the remote mode and publishes the volume as writable. The // map it booted with is the read-only sorted one, whose put always fails, so // without a rebuild the first write appends to .dat and then cannot be // indexed — leaving bytes nothing references. /// A volume tiered while the server runs must install the sorted map right /// then. Reconciling only on the way down left it holding the whole index /// in RAM and its .idx descriptor pinned until the next restart — the cost /// the sorted map exists to avoid. #[test] fn test_tier_up_installs_the_sorted_needle_map() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=2u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(0x1234), data: format!("needle-{i}").into_bytes(), data_size: format!("needle-{i}").len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); assert!( !matches!(v.nm, Some(NeedleMap::SortedFile(_))), "a local volume starts with a writable in-memory map" ); // What the tier-up handler does once the .dat is uploaded: record the // remote reference and reconcile the mode. let file_size = v.dat_file_size().unwrap(); v.update_remote_files(|files| { files.push(PbRemoteFile { backend_type: "s3".to_string(), backend_id: "vif_tierup_test".to_string(), key: "remote-key".to_string(), offset: 0, file_size, modified_time: 123, extension: ".dat".to_string(), }) }) .unwrap(); assert!(v.has_remote_file()); assert!( matches!(v.nm, Some(NeedleMap::SortedFile(_))), "tier-up must install the sorted map without waiting for a restart" ); // The index still answers, now off .sdx. let nv = v.nm.as_ref() .unwrap() .get(NeedleId(1)) .unwrap() .expect("needle 1 still resolves through the sorted index"); assert!(!nv.size.is_deleted()); } #[test] fn test_tier_down_swaps_in_a_writable_needle_map() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = reload_as_tiered(dir, "vif_tierdown_test", 2); assert!(matches!(v.nm, Some(NeedleMap::SortedFile(_)))); // The tail of the tier-down handler, once the .dat is back on disk. v.update_remote_files(|files| { files.remove(0); }) .unwrap(); v.save_volume_info().unwrap(); v.open_local_dat_backend().unwrap(); assert!(!v.has_remote_file()); assert!( !v.is_read_only(), "tier-down should publish a writable volume" ); assert!( !matches!(v.nm, Some(NeedleMap::SortedFile(_))), "tier-down must swap the read-only map out before writes are allowed" ); let mut n = Needle { id: NeedleId(7), cookie: Cookie(0x5678), data: b"after-tier-down".to_vec(), data_size: 15, ..Needle::default() }; v.write_needle(&mut n, true, true).unwrap(); v.sync_to_disk().unwrap(); drop(v); // Reload: the needle must come back from .idx, not just have landed in // .dat as unreferenced bytes. let v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); let mut probe = Needle { id: NeedleId(7), ..Needle::default() }; v.read_needle(&mut probe).unwrap(); assert_eq!(probe.data, b"after-tier-down"); crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap() .remove("s3.vif_tierdown_test"); } // An .idx that cannot be read up to the recorded size must abort // compaction. Treating the short scan as the complete live set would // commit a volume missing every needle past the truncation. #[test] fn test_compaction_aborts_on_truncated_index() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = make_test_volume(dir); for i in 1..=4u64 { write_test_needle(&mut v, i, format!("needle-{i}").as_bytes()); } v.set_read_only_persist(false, true).unwrap(); v.sync_to_disk().unwrap(); } let mut v = make_test_volume(dir); let Some(NeedleMap::SortedFile(_)) = v.nm else { panic!("read-only volume should search the on-disk .sdx"); }; let idx = OpenOptions::new() .write(true) .open(v.file_name(".idx")) .unwrap(); idx.set_len(NEEDLE_MAP_ENTRY_SIZE as u64).unwrap(); drop(idx); let err = v .compact_by_index(0, 0, |_| true) .expect_err("compaction must not commit a partially scanned index"); assert!( matches!(err, VolumeError::Io(ref e) if e.kind() == io::ErrorKind::UnexpectedEof), "unexpected error: {err:?}" ); } // Building .sdx writes to the index directory, which a read-only volume's // may not allow. Before the sorted map that volume mounted and served reads // off an in-memory index; it must still do so rather than going offline. #[test] #[cfg(unix)] fn test_read_only_volume_mounts_when_the_index_dir_is_not_writable() { use std::os::unix::fs::PermissionsExt; // root ignores the directory mode, so there is nothing to simulate. // SAFETY: `geteuid` takes no arguments, reads no memory and cannot fail. if unsafe { libc::geteuid() } == 0 { return; } let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap().to_string(); { let mut v = make_test_volume(&dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x1234), data: b"still-readable".to_vec(), data_size: 14, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.set_read_only_persist(false, true).unwrap(); v.sync_to_disk().unwrap(); } let set_mode = |mode: u32| { let mut perms = std::fs::metadata(tmp.path()).unwrap().permissions(); perms.set_mode(mode); std::fs::set_permissions(tmp.path(), perms).unwrap(); }; set_mode(0o555); let loaded = Volume::new( &dir, &dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ); set_mode(0o755); // restore before any assertion, so cleanup works let v = loaded.expect("a read-only volume must mount without writing its index dir"); assert!( !matches!(v.nm, Some(NeedleMap::SortedFile(_))), "the .sdx could not be built, so the index should have fallen back to memory" ); let mut probe = Needle { id: NeedleId(1), ..Needle::default() }; v.read_needle(&mut probe).unwrap(); assert_eq!(probe.data, b"still-readable"); } // Compaction copies the .idx prefix index_file_size() reports. A read-only // volume's map has no writer, so that must still be the loaded size, or the // copy is empty and the commit drops every needle. #[cfg(unix)] fn check_read_only_compaction_keeps_needles(index_dir_writable: bool) { use std::os::unix::fs::PermissionsExt; let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap().to_string(); { let mut v = make_test_volume(&dir); for i in 1..=3u64 { write_test_needle(&mut v, i, format!("data-{i}").as_bytes()); } v.set_read_only_persist(false, true).unwrap(); v.sync_to_disk().unwrap(); } let idx_len = fs::metadata(format!("{dir}/1.idx")).unwrap().len(); let set_mode = |mode: u32| { let mut perms = std::fs::metadata(tmp.path()).unwrap().permissions(); perms.set_mode(mode); std::fs::set_permissions(tmp.path(), perms).unwrap(); }; if !index_dir_writable { set_mode(0o555); } let loaded = Volume::new( &dir, &dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ); set_mode(0o755); let mut v = loaded.unwrap(); assert_eq!( matches!(v.nm, Some(NeedleMap::SortedFile(_))), index_dir_writable ); assert_eq!(v.idx_file_size(), idx_len); v.compact_by_index(0, 0, |_| true).unwrap(); v.commit_compact().unwrap(); for i in 1..=3u64 { let mut n = Needle { id: NeedleId(i), ..Needle::default() }; v.read_needle(&mut n).unwrap(); assert_eq!(n.data, format!("data-{i}").as_bytes()); } } #[test] #[cfg(unix)] fn test_compacting_a_read_only_volume_keeps_its_needles_sorted_index() { check_read_only_compaction_keeps_needles(true); } // The .sdx could not be built, so the index fell back to memory. #[test] #[cfg(unix)] fn test_compacting_a_read_only_volume_keeps_its_needles_in_memory_fallback() { // root ignores the directory mode, so there is nothing to simulate. // SAFETY: `geteuid` takes no arguments, reads no memory and cannot fail. if unsafe { libc::geteuid() } == 0 { return; } check_read_only_compaction_keeps_needles(false); } // set_writable clears the read-only flags before it can know the .idx writer // will attach. If attaching fails the flags have to go back: a volume that // advertises writable while its map has no writer takes puts into memory and // loses them at the next restart. #[test] #[cfg(unix)] fn test_set_writable_rolls_back_when_the_idx_writer_cannot_attach() { use std::os::unix::fs::PermissionsExt; // root ignores the directory mode, so there is nothing to simulate. // SAFETY: `geteuid` takes no arguments, reads no memory and cannot fail. if unsafe { libc::geteuid() } == 0 { return; } let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap().to_string(); { let mut v = make_test_volume(&dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x1234), data: b"before".to_vec(), data_size: 6, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.set_read_only_persist(false, true).unwrap(); v.sync_to_disk().unwrap(); } // A read-only mount, both halves of it: nothing new can be created in the // directory, so .sdx generation fails and the index falls back to memory, // and the .idx itself cannot be opened for write, so no writer attaches. let set_mode = |path: &std::path::Path, mode: u32| { let mut perms = std::fs::metadata(path).unwrap().permissions(); perms.set_mode(mode); std::fs::set_permissions(path, perms).unwrap(); }; let idx_path = tmp.path().join("1.idx"); set_mode(&idx_path, 0o444); set_mode(tmp.path(), 0o555); let loaded = Volume::new( &dir, &dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ); let marked = loaded.map(|mut v| { let r = v.set_writable(); ( v.no_write_or_delete, v.is_read_only(), v.nm.as_ref().unwrap().has_idx_writer(), r, ) }); // Restore before any assertion, so cleanup works. set_mode(tmp.path(), 0o755); set_mode(&idx_path, 0o644); let (no_write_or_delete, read_only, has_writer, result) = marked.unwrap(); assert!( result.is_err(), "set_writable cannot succeed without an .idx writer" ); assert!(!has_writer, "the writer is what failed to attach"); assert!( no_write_or_delete && read_only, "a failed mark must leave the volume read-only, not writable with an index it cannot append to" ); } // .idx is a run of fixed-size rows and writers append at EOF, so a partial // row left by a short write puts every row appended after it off alignment // and the next load parses the rest as garbage. The tail has to go before // anything writable attaches. #[test] fn test_writable_load_trims_a_torn_idx_tail() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap().to_string(); { let mut v = make_test_volume(&dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x1234), data: b"first".to_vec(), data_size: 5, ..Needle::default() }; v.write_needle(&mut n, true, true).unwrap(); v.sync_to_disk().unwrap(); } let idx_path = tmp.path().join("1.idx"); let whole = std::fs::metadata(&idx_path).unwrap().len(); { use std::io::Write as _; let mut f = OpenOptions::new().append(true).open(&idx_path).unwrap(); f.write_all(&[0xcd; 5]).unwrap(); } let mut v = Volume::new( &dir, &dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert_eq!( std::fs::metadata(&idx_path).unwrap().len(), whole, "the partial row should be gone before any writer attaches" ); let mut n = Needle { id: NeedleId(2), cookie: Cookie(0x5678), data: b"second".to_vec(), data_size: 6, ..Needle::default() }; v.write_needle(&mut n, true, true).unwrap(); v.sync_to_disk().unwrap(); drop(v); // Both rows have to survive the round trip; a misaligned append loses // the second one and garbles whatever follows it. let v = Volume::new( &dir, &dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); for (id, want) in [(1u64, &b"first"[..]), (2u64, &b"second"[..])] { let mut probe = Needle { id: NeedleId(id), ..Needle::default() }; v.read_needle(&mut probe).unwrap(); assert_eq!(probe.data, want); } } // A delete-capable read-only volume — every tiered one — takes the in-memory // loader's read-write branch, which fails on the same unwritable directory // that refused the .sdx. It has to end up read-only rather than offline. #[test] #[cfg(unix)] fn test_delete_capable_volume_falls_all_the_way_back_to_read_only() { use std::os::unix::fs::PermissionsExt; // root ignores the directory mode, so there is nothing to simulate. // SAFETY: `geteuid` takes no arguments, reads no memory and cannot fail. if unsafe { libc::geteuid() } == 0 { return; } let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap().to_string(); { let mut v = make_test_volume(&dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(0x1234), data: b"still-readable".to_vec(), data_size: 14, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.set_read_only_persist(true, true).unwrap(); v.sync_to_disk().unwrap(); } let set_mode = |path: &std::path::Path, mode: u32| { let mut perms = std::fs::metadata(path).unwrap().permissions(); perms.set_mode(mode); std::fs::set_permissions(path, perms).unwrap(); }; let idx_path = tmp.path().join("1.idx"); set_mode(&idx_path, 0o444); set_mode(tmp.path(), 0o555); let loaded = Volume::new( &dir, &dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ); set_mode(tmp.path(), 0o755); set_mode(&idx_path, 0o644); let v = loaded.expect("a delete-capable volume must mount without a writable index dir"); assert!( v.no_write_or_delete, "with no writer for tombstones, deletes have to be refused outright" ); let mut probe = Needle { id: NeedleId(1), ..Needle::default() }; v.read_needle(&mut probe).unwrap(); assert_eq!(probe.data, b"still-readable"); } // Issue #10937: a volume server holding hundreds of thousands of cloud-tiered // volumes ran out of descriptors because every one of them pinned its index // for the life of the process. A tiered volume must search the on-disk .sdx // and hold nothing open while it sits idle. #[test] fn test_remote_volume_index_is_on_disk_and_holds_no_descriptors() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = make_test_volume(dir); for i in 1..=4u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(0x1234), data: format!("needle-{i}").into_bytes(), data_size: format!("needle-{i}").len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } // A writable volume does pin its .idx, which is also what proves the // descriptor probe below is looking at something real. if let Some(count) = crate::storage::needle_map::file_pool::open_index_fds(tmp.path()) { assert!(count > 0, "a writable volume should hold its .idx open"); } let vif = VifVolumeInfo { files: vec![VifRemoteFile { backend_type: "s3".to_string(), backend_id: "vif_fd_test".to_string(), key: "remote-key".to_string(), offset: 0, file_size: v.dat_file_size().unwrap(), modified_time: 123, extension: ".dat".to_string(), }], version: v.version().0 as u32, ..VifVolumeInfo::default() }; std::fs::write( format!("{}/1.vif", dir), serde_json::to_string_pretty(&vif).unwrap(), ) .unwrap(); let tier_config = crate::remote_storage::s3_tier::S3TierConfig { access_key: "access".to_string(), secret_key: "secret".to_string(), region: "us-east-1".to_string(), bucket: "bucket-a".to_string(), endpoint: "http://127.0.0.1:1".to_string(), storage_class: "STANDARD".to_string(), force_path_style: true, }; crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap() .register( "s3.vif_fd_test".to_string(), crate::remote_storage::s3_tier::S3TierBackend::new(&tier_config), ); } let mut v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!(v.has_remote_file()); let Some(NeedleMap::SortedFile(ref nm)) = v.nm else { panic!( "tiered volume should search the on-disk .sdx, got {:?}", v.nm.is_some() ); }; let idx_path = nm.index_file_name().to_string(); let sdx_path = nm.db_file_name().to_string(); assert!(Path::new(&sdx_path).exists(), "load should build the .sdx"); let drop_pooled = || { crate::storage::needle_map::file_pool::pooled_index_files().discard(&idx_path); crate::storage::needle_map::file_pool::pooled_index_files().discard(&sdx_path); }; if crate::storage::needle_map::file_pool::open_index_fds(tmp.path()).is_some() { drop_pooled(); assert_eq!( crate::storage::needle_map::file_pool::open_index_fds(tmp.path()), Some(0), "a loaded tiered volume must hold no .idx/.sdx descriptor" ); } // Lookups still resolve, straight off .sdx. assert!( !v.nm .as_ref() .unwrap() .get(NeedleId(3)) .unwrap() .unwrap() .size .is_deleted() ); assert!(v.nm.as_ref().unwrap().get(NeedleId(9)).unwrap().is_none()); // Deletes are still allowed on a tiered volume and land in .idx. let idx_before = std::fs::metadata(&idx_path).unwrap().len(); let deleted = v .delete_needle(&mut Needle { id: NeedleId(3), cookie: Cookie(0x1234), ..Needle::default() }) .unwrap(); assert!(deleted.0 > 0); assert_eq!( std::fs::metadata(&idx_path).unwrap().len(), idx_before + NEEDLE_MAP_ENTRY_SIZE as u64, "the tombstone must be appended to the .idx tail" ); assert!( v.nm.as_ref() .unwrap() .get(NeedleId(3)) .unwrap() .unwrap() .size .is_deleted() ); if crate::storage::needle_map::file_pool::open_index_fds(tmp.path()).is_some() { drop_pooled(); assert_eq!( crate::storage::needle_map::file_pool::open_index_fds(tmp.path()), Some(0), "reads and deletes must give their borrowed handles back" ); } crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap() .remove("s3.vif_fd_test"); } #[test] fn test_set_writable_keeps_remote_delete_only_mode() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let file_size = v.dat_file_size().unwrap(); v.update_remote_files(|files| { files.push(PbRemoteFile { backend_type: "s3".to_string(), backend_id: "default".to_string(), key: "remote-key".to_string(), offset: 0, file_size, modified_time: 123, extension: ".dat".to_string(), }) }) .unwrap(); v.set_writable().unwrap(); assert!(v.is_read_only()); assert!(!v.no_write_or_delete); assert!(v.no_write_can_delete); } // A volume booted with .vif ReadOnly=true used to come back stuck — // load_index_inmemory built the CompactNeedleMap without an .idx writer // attached, and set_writable only flipped the flag and rewrote .vif. // The next put silently skipped the .idx append, so the write landed in // memory only and was lost on the next restart. #[test] fn test_set_writable_reattaches_idx_writer_after_persisted_readonly() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: b"initial".to_vec(), data_size: 7, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.set_read_only_persist(false, true).unwrap(); v.sync_to_disk().unwrap(); } let mut v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!( v.no_write_or_delete, "reloaded volume should be read-only from .vif" ); assert!( matches!(v.nm, Some(NeedleMap::SortedFile(_))), "read-only load should search the on-disk .sdx" ); v.set_writable().unwrap(); assert!(!v.is_read_only()); assert!( !matches!(v.nm, Some(NeedleMap::SortedFile(_))), "set_writable must swap out the read-only map, whose put always fails" ); assert!( v.nm.as_ref().unwrap().has_idx_writer(), "set_writable must reattach the .idx writer or post-restart writes vanish" ); let mut n = Needle { id: NeedleId(2), cookie: Cookie(2), data: b"after-mark-writable".to_vec(), data_size: 19, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); // Reload one more time — the .idx must contain the post-mark-writable // entry, not just have it in memory. drop(v); let v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); let mut probe = Needle { id: NeedleId(2), ..Needle::default() }; v.read_needle(&mut probe).unwrap(); assert_eq!( std::str::from_utf8(&probe.data).unwrap(), "after-mark-writable" ); } // readOnlyCanDelete rejects writes, keeps accepting deletes, and survives // a restart. #[test] fn test_read_only_can_delete_persists_and_keeps_deletes_working() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = make_test_volume(dir); for id in 1..=2u64 { let mut n = Needle { id: NeedleId(id), cookie: Cookie(id as u32), data: b"payload".to_vec(), data_size: 7, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.set_read_only_persist(true, true).unwrap(); assert!(v.no_write_can_delete); assert!(!v.no_write_or_delete); assert!(v.is_read_only()); let err = v .write_needle( &mut Needle { id: NeedleId(3), cookie: Cookie(3), data: b"blocked".to_vec(), data_size: 7, ..Needle::default() }, true, false, ) .unwrap_err(); assert!(matches!(err, VolumeError::ReadOnly(_))); let deleted = v .delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(1), ..Needle::default() }) .unwrap(); assert!(deleted.0 > 0, "deletes must still land"); v.sync_to_disk().unwrap(); } let mut v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!(v.no_write_can_delete, "state must survive a restart"); assert!(!v.no_write_or_delete); assert!( v.nm.as_ref().unwrap().has_idx_writer(), "canDelete boot must attach an .idx writer for delete tombstones" ); let err = v .write_needle( &mut Needle { id: NeedleId(4), cookie: Cookie(4), data: b"blocked".to_vec(), data_size: 7, ..Needle::default() }, true, false, ) .unwrap_err(); assert!(matches!(err, VolumeError::ReadOnly(_))); let deleted = v .delete_needle(&mut Needle { id: NeedleId(2), cookie: Cookie(2), ..Needle::default() }) .unwrap(); assert!(deleted.0 > 0, "deletes must still land after restart"); // downgrading to plain readonly clears the canDelete flag v.set_read_only_persist(false, true).unwrap(); assert!(v.no_write_or_delete); assert!(!v.no_write_can_delete); // -writable clears the state again. v.set_writable().unwrap(); assert!(!v.is_read_only()); let mut n = Needle { id: NeedleId(5), cookie: Cookie(5), data: b"writable-again".to_vec(), data_size: 14, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } // Upgrading a volume that booted plain persisted-readonly to canDelete // must attach the missing .idx writer, or delete tombstones cannot append. #[test] fn test_read_only_can_delete_upgrade_after_readonly_boot() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: b"payload".to_vec(), data_size: 7, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.set_read_only_persist(false, true).unwrap(); v.sync_to_disk().unwrap(); } let mut v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!(v.no_write_or_delete); let err = v .delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(1), ..Needle::default() }) .unwrap_err(); assert!( matches!(err, VolumeError::ReadOnly(_)), "plain readonly must reject deletes" ); v.set_read_only_persist(true, true).unwrap(); assert!(!v.no_write_or_delete); assert!(v.no_write_can_delete); assert!( v.nm.as_ref().unwrap().has_idx_writer(), "upgrade to canDelete must attach the .idx writer" ); let deleted = v .delete_needle(&mut Needle { id: NeedleId(1), cookie: Cookie(1), ..Needle::default() }) .unwrap(); assert!(deleted.0 > 0, "deletes must land once canDelete is set"); } #[test] fn test_load_vif_defaults_local_version_and_bytes_offset() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let _v = make_test_volume(dir); let vif = VifVolumeInfo::default(); std::fs::write( format!("{}/1.vif", dir), serde_json::to_string_pretty(&vif).unwrap(), ) .unwrap(); } let v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert_eq!(v.volume_info.version, Version::current().0 as u32); assert_eq!(v.volume_info.bytes_offset, OFFSET_SIZE as u32); assert_eq!(v.version(), Version::current()); } #[test] fn test_version_superblock_overrides_vif_version() { // Go behavior: after reading the superblock, volumeInfo.Version is set // to SuperBlock.Version, overriding whatever was in the .vif file. let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let _v = make_test_volume(dir); // Write a .vif with version=2, but the .dat superblock is version=3 let vif = VifVolumeInfo { version: VERSION_2.0 as u32, bytes_offset: OFFSET_SIZE as u32, ..VifVolumeInfo::default() }; std::fs::write( format!("{}/1.vif", dir), serde_json::to_string_pretty(&vif).unwrap(), ) .unwrap(); } let v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); // Superblock version (3) overrides the .vif version (2) assert_eq!(v.volume_info.version, VERSION_3.0 as u32); assert_eq!(v.version(), VERSION_3); } #[test] fn test_load_vif_rejects_bytes_offset_mismatch() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); { let _v = make_test_volume(dir); let vif = VifVolumeInfo { version: Version::current().0 as u32, bytes_offset: (OFFSET_SIZE as u32) + 1, ..VifVolumeInfo::default() }; std::fs::write( format!("{}/1.vif", dir), serde_json::to_string_pretty(&vif).unwrap(), ) .unwrap(); } let result = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ); match result { Ok(_) => panic!("expected bytes_offset mismatch to fail"), Err(VolumeError::Io(io_err)) => { assert_eq!(io_err.kind(), io::ErrorKind::InvalidData); assert!(io_err.to_string().contains("bytes_offset mismatch")); } Err(other) => panic!("unexpected error: {other:?}"), } } #[test] fn test_remote_only_volume_load_reads_from_tier_backend() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let dat_bytes = { let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(7), cookie: Cookie(0x7788), data: b"remote-only".to_vec(), data_size: 11, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); v.sync_to_disk().unwrap(); std::fs::read(v.file_name(".dat")).unwrap() }; let dat_path = format!("{}/1.dat", dir); std::fs::remove_file(&dat_path).unwrap(); let (endpoint, shutdown_tx) = spawn_fake_s3_server(dat_bytes.clone()); // Use a test-specific backend_id to avoid racing with other tests // that share the global registry. Never call clear() — only // register/remove our own entries. let tier_config = crate::remote_storage::s3_tier::S3TierConfig { access_key: "access".to_string(), secret_key: "secret".to_string(), region: "us-east-1".to_string(), bucket: "bucket-a".to_string(), endpoint, storage_class: "STANDARD".to_string(), force_path_style: true, }; { let mut registry = crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap(); registry.register( "s3.remote_only_rw".to_string(), crate::remote_storage::s3_tier::S3TierBackend::new(&tier_config), ); } let vif = VifVolumeInfo { files: vec![VifRemoteFile { backend_type: "s3".to_string(), backend_id: "remote_only_rw".to_string(), key: "remote-key".to_string(), offset: 0, file_size: dat_bytes.len() as u64, modified_time: 123, extension: ".dat".to_string(), }], version: Version::current().0 as u32, bytes_offset: OFFSET_SIZE as u32, dat_file_size: dat_bytes.len() as i64, ..VifVolumeInfo::default() }; std::fs::write( format!("{}/1.vif", dir), serde_json::to_string_pretty(&vif).unwrap(), ) .unwrap(); let v = Volume::new( dir, dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); assert!(v.has_remote_file()); assert!(v.dat_file.is_none()); assert!(v.remote_dat_file.is_some()); let mut n = Needle { id: NeedleId(7), ..Needle::default() }; let size = v.read_needle(&mut n).unwrap(); assert_eq!(size, 11); assert_eq!(n.data, b"remote-only"); let mut meta = Needle { id: NeedleId(7), ..Needle::default() }; let mut plan = v.needle_read_plan(NeedleId(7), false).unwrap(); plan.read_meta(&mut meta).unwrap(); let info = plan.into_stream_info(&meta); assert!(matches!(info.source, NeedleStreamSource::Remote(_))); let mut streamed = vec![0u8; info.data_size as usize]; info.source .read_exact_at(&mut streamed, info.data_file_offset) .unwrap(); assert_eq!(streamed, b"remote-only"); assert_eq!(meta.data_size, 11); let _ = shutdown_tx.send(()); crate::remote_storage::s3_tier::global_s3_tier_registry() .write() .unwrap() .remove("s3.remote_only_rw"); } /// Volume destroy removes .vif alongside the primary data files. #[test] fn test_destroy_removes_vif() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: b"test".to_vec(), data_size: 4, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); // Write a .vif file (as EC encode would) let vif_path = format!("{}/1.vif", dir); std::fs::write(&vif_path, r#"{"version":3}"#).unwrap(); assert!(std::path::Path::new(&vif_path).exists()); // .dat and .idx should exist let dat_path = format!("{}/1.dat", dir); let idx_path = format!("{}/1.idx", dir); assert!(std::path::Path::new(&dat_path).exists()); assert!(std::path::Path::new(&idx_path).exists()); // Destroy the volume v.destroy(false, false, false).unwrap(); // .dat and .idx should be gone assert!( !std::path::Path::new(&dat_path).exists(), ".dat should be removed" ); assert!( !std::path::Path::new(&idx_path).exists(), ".idx should be removed" ); assert!( !std::path::Path::new(&vif_path).exists(), ".vif should be removed" ); } /// Volume destroy with separate idx directory must clean up both dirs and .vif. #[test] fn test_destroy_with_separate_idx_dir() { let dat_tmp = TempDir::new().unwrap(); let idx_tmp = TempDir::new().unwrap(); let dat_dir = dat_tmp.path().to_str().unwrap(); let idx_dir = idx_tmp.path().to_str().unwrap(); let mut v = Volume::new( dat_dir, idx_dir, VolumeId(1), NeedleMapKind::InMemory, &VolumeSpec::default(), ) .unwrap(); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: b"hello".to_vec(), data_size: 5, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); // Write .vif in data dir (as EC encode would) let vif_path = format!("{}/1.vif", dat_dir); std::fs::write(&vif_path, r#"{"version":3}"#).unwrap(); let dat_path = format!("{}/1.dat", dat_dir); let idx_path = format!("{}/1.idx", idx_dir); assert!(std::path::Path::new(&dat_path).exists()); assert!(std::path::Path::new(&idx_path).exists()); v.destroy(false, false, false).unwrap(); assert!( !std::path::Path::new(&dat_path).exists(), ".dat removed from data dir" ); assert!( !std::path::Path::new(&idx_path).exists(), ".idx removed from idx dir" ); assert!( !std::path::Path::new(&vif_path).exists(), ".vif removed from data dir" ); } /// When an EC volume for the same id has a sealed .ecx on the same disk, the /// .vif is shared with it and must survive the regular volume's deletion. #[test] fn test_destroy_keeps_vif_when_ec_coexists() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); let mut n = Needle { id: NeedleId(1), cookie: Cookie(1), data: b"test".to_vec(), data_size: 4, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); let vif_path = format!("{}/1.vif", dir); std::fs::write(&vif_path, r#"{"version":3}"#).unwrap(); // A sealed .ecx marks a coexisting EC volume for the same id. let ecx_path = format!("{}/1.ecx", dir); std::fs::write(&ecx_path, b"ec-index").unwrap(); v.destroy(false, false, false).unwrap(); let dat_path = format!("{}/1.dat", dir); let idx_path = format!("{}/1.idx", dir); assert!(!std::path::Path::new(&dat_path).exists(), ".dat removed"); assert!(!std::path::Path::new(&idx_path).exists(), ".idx removed"); assert!( std::path::Path::new(&vif_path).exists(), ".vif kept: shared with the coexisting EC volume" ); assert!( std::path::Path::new(&ecx_path).exists(), ".ecx is an EC sidecar, never touched here" ); } /// A crash after the .idx/.dat were consumed but before the .cpx->.idx /// rename committed leaves only .cpd + .cpx + .cpc. reconcile_compact_state /// must roll the swap FORWARD and produce a loadable, writable volume /// holding the compacted needle count. #[test] fn test_reconcile_roll_forward_marker_only() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=6u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: format!("data-{}", i).into_bytes(), data_size: format!("data-{}", i).len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } for id in [2u64, 5u64] { let mut del = Needle { id: NeedleId(id), cookie: Cookie(id as u32), ..Needle::default() }; v.delete_needle(&mut del).unwrap(); } let expected_live = v.file_count() - v.deleted_count(); v.compact_by_index(0, 0, |_| true).unwrap(); v.close(); let cpd = v.file_name(".cpd"); let cpx = v.file_name(".cpx"); let cpc = v.file_name(".cpc"); let dat = v.file_name(".dat"); let idx = v.file_name(".idx"); assert!(Path::new(&cpd).exists()); assert!(Path::new(&cpx).exists()); // Simulate the mid-commit crash: original .dat/.idx are gone and only // the compacted temp files plus the commit marker survive. fs::remove_file(&dat).unwrap(); fs::remove_file(&idx).unwrap(); let _ = fs::remove_dir_all(v.file_name(".ldb")); fs::write(&cpc, b"").unwrap(); v.reconcile_compact_state().unwrap(); assert!(!Path::new(&cpd).exists(), ".cpd consumed by roll-forward"); assert!(!Path::new(&cpx).exists(), ".cpx consumed by roll-forward"); assert!(!Path::new(&cpc).exists(), ".cpc cleared after swap"); assert!(Path::new(&dat).exists(), ".dat restored by roll-forward"); assert!(Path::new(&idx).exists(), ".idx restored by roll-forward"); // The rolled-forward files must load as a writable volume with the // compacted needle count. let reloaded = make_test_volume(dir); assert!(!reloaded.is_read_only(), "rolled-forward volume read-only"); assert_eq!( reloaded.file_count(), expected_live, "rolled-forward volume needle count" ); } /// With no .cpc marker, leftover .cpd/.cpx are an abandoned generation; /// reconcile must roll BACK by deleting them and leave the live .dat/.idx. #[test] fn test_reconcile_roll_back_no_marker() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=4u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: format!("data-{}", i).into_bytes(), data_size: format!("data-{}", i).len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.compact_by_index(0, 0, |_| true).unwrap(); let cpd = v.file_name(".cpd"); let cpx = v.file_name(".cpx"); let dat = v.file_name(".dat"); let idx = v.file_name(".idx"); assert!(Path::new(&cpd).exists()); assert!(Path::new(&cpx).exists()); // No .cpc marker exists. v.reconcile_compact_state().unwrap(); assert!(!Path::new(&cpd).exists(), ".cpd rolled back"); assert!(!Path::new(&cpx).exists(), ".cpx rolled back"); assert!(Path::new(&dat).exists(), "live .dat kept"); assert!(Path::new(&idx).exists(), "live .idx kept"); } /// apply_compact_swap must abort without touching the live .dat/.idx when /// the .cpd/.cpx temp files are missing (a stale or duplicate commit). #[test] fn test_apply_compact_swap_missing_temp_files_preserves_live() { let tmp = TempDir::new().unwrap(); let dir = tmp.path().to_str().unwrap(); let mut v = make_test_volume(dir); for i in 1..=3u64 { let mut n = Needle { id: NeedleId(i), cookie: Cookie(i as u32), data: format!("data-{}", i).into_bytes(), data_size: format!("data-{}", i).len() as u32, ..Needle::default() }; v.write_needle(&mut n, true, false).unwrap(); } v.sync_to_disk().unwrap(); let dat = v.file_name(".dat"); let idx = v.file_name(".idx"); let dat_len_before = fs::metadata(&dat).unwrap().len(); // No .cpd/.cpx present: the swap must refuse. assert!( v.apply_compact_swap().is_err(), "swap should error when .cpd/.cpx are missing" ); assert!(Path::new(&dat).exists(), "live .dat preserved"); assert!(Path::new(&idx).exists(), "live .idx preserved"); assert_eq!( fs::metadata(&dat).unwrap().len(), dat_len_before, "live .dat unchanged" ); } }