use std::collections::{HashMap, HashSet};
use std::sync::{Arc, OnceLock};
use parking_lot::RwLock;
use crate::error::{Error, Result};
use crate::file::VectorBasePtrs;
use crate::file::catalog_io::FrameLocator;
use crate::file::segment_io::{SegmentRegistry, verify_payload_wire_bytes};
use crate::format::FrameId;
use crate::format::SegmentId;
use crate::format::VectorId;
use crate::format::catalog::{CatalogSnapshot, FrameDesc, PayloadEncoding, VectorDesc};
use crate::format::segment::SegmentType;
#[allow(
dead_code,
reason = "non-mmap fields consumed by Stage 4 read paths; Stage 2 ships only publish + pin"
)]
pub struct Snapshot {
pub(crate) generation: u64,
pub(crate) toc_offset: u64,
pub(crate) mmap: Option<Arc<memmap2::Mmap>>,
pub(crate) catalog: Arc<CatalogSnapshot>,
pub(crate) frame_locators: Arc<HashMap<FrameId, FrameLocator>>,
pub(crate) segment_registry: Arc<SegmentRegistry>,
pub(crate) vector_by_id: Arc<HashMap<VectorId, VectorDesc>>,
pub(crate) vector_base_ptrs: OnceLock<Arc<VectorBasePtrs>>,
pub(crate) verified_payload_segments: Arc<RwLock<HashSet<SegmentId>>>,
}
impl Snapshot {
#[must_use]
pub fn generation(&self) -> u64 {
self.generation
}
#[must_use]
pub fn toc_offset(&self) -> u64 {
self.toc_offset
}
#[must_use]
pub fn mmap(&self) -> Option<&memmap2::Mmap> {
self.mmap.as_deref()
}
#[must_use]
pub fn catalog(&self) -> &CatalogSnapshot {
&self.catalog
}
pub fn frame_full(&self, frame_id: FrameId) -> Result<FrameDesc> {
if let Ok(idx) = self
.catalog
.frames
.binary_search_by_key(&frame_id.0, |f| f.frame_id.0)
{
return Ok(self.catalog.frames[idx].clone());
}
let locator =
self.frame_locators.get(&frame_id).copied().ok_or_else(|| {
Error::Format(format!("frame_full: unknown frame_id {}", frame_id.0))
})?;
let mmap = self
.mmap
.as_ref()
.ok_or_else(|| Error::Integrity("frame_full: snapshot has no pinned mmap".into()))?;
let payload = crate::file::mmap_segment_payload(
mmap,
locator.catalog_segment,
SegmentType::FrameCatalog,
)?;
let end = locator
.payload_offset
.checked_add(locator.payload_len)
.ok_or_else(|| Error::Integrity("frame_full: locator offset overflow".into()))?;
if end > payload.len() {
return Err(Error::Integrity(format!(
"frame_full: locator out of range (payload len {}, locator end {end})",
payload.len()
)));
}
let bytes = &payload[locator.payload_offset..end];
let (desc, _): (FrameDesc, _) =
bincode::serde::decode_from_slice(bytes, crate::format::bincode_config())
.map_err(|e| Error::Serde(e.to_string()))?;
if desc.frame_id != frame_id {
return Err(Error::Integrity(format!(
"frame_full: locator pointed at frame_id {} but expected {}",
desc.frame_id.0, frame_id.0
)));
}
Ok(desc)
}
pub fn read_payload(&self, frame_id: FrameId) -> Result<Vec<u8>> {
let frame = self.frame_full(frame_id)?;
if frame.payload_encoding != PayloadEncoding::Raw {
return Err(Error::Unsupported(
"compressed frame payloads are not implemented in v0.1-alpha".into(),
));
}
let payload_ref = frame
.payload_ref
.ok_or_else(|| Error::Format("frame has no materialized payload".into()))?;
let segment = self
.segment_registry
.by_id
.get(&payload_ref.segment_id)
.copied()
.ok_or_else(|| {
Error::Integrity(format!(
"read_payload: data segment {} not in snapshot's registry",
payload_ref.segment_id.0
))
})?;
let mmap = self
.mmap
.as_ref()
.ok_or_else(|| Error::Integrity("read_payload: snapshot has no pinned mmap".into()))?;
let segment_payload =
crate::file::mmap_segment_payload(mmap, segment, SegmentType::Payload)?;
verify_payload_wire_bytes(
segment.segment_id,
&segment.checksum,
segment_payload,
&self.verified_payload_segments,
)?;
let start = segment.offset as usize;
let compression_code = u16::from_le_bytes([mmap[start + 24], mmap[start + 25]]);
crate::format::segment::Compression::try_from(compression_code)?.ensure_decodable()?;
let payload = if compression_code == crate::format::segment::Compression::Zstd as u16 {
let end = payload_ref
.bytes_offset
.checked_add(payload_ref.bytes_length)
.ok_or_else(|| Error::Format("payload ref range overflow".into()))?;
let decompressed = zstd::decode_all(segment_payload).map_err(|err| {
Error::Format(format!("zstd decode failed in snapshot read: {err}"))
})?;
if end > decompressed.len() as u64 {
return Err(Error::Integrity(
"payload ref exceeds segment uncompressed length".into(),
));
}
decompressed[payload_ref.bytes_offset as usize..end as usize].to_vec()
} else {
let end = payload_ref
.bytes_offset
.checked_add(payload_ref.bytes_length)
.ok_or_else(|| Error::Format("payload ref range overflow".into()))?;
if end > segment_payload.len() as u64 {
return Err(Error::Integrity(
"payload ref exceeds segment length".into(),
));
}
segment_payload[payload_ref.bytes_offset as usize..end as usize].to_vec()
};
Ok(payload)
}
pub fn read_raw_text(&self, frame_id: FrameId) -> Result<String> {
let bytes = self.read_payload(frame_id)?;
String::from_utf8(bytes).map_err(|err| {
Error::Format(format!(
"read_raw_text: frame {} payload is not valid UTF-8: {err}",
frame_id.0
))
})
}
#[allow(dead_code, reason = "constructor scaffolding for Stage 4 reuse")]
pub(crate) fn empty() -> Self {
Self {
generation: 0,
toc_offset: 0,
mmap: None,
catalog: Arc::new(CatalogSnapshot::default()),
frame_locators: Arc::new(HashMap::new()),
segment_registry: Arc::new(SegmentRegistry::default()),
vector_by_id: Arc::new(HashMap::new()),
vector_base_ptrs: OnceLock::new(),
verified_payload_segments: Arc::new(RwLock::new(HashSet::new())),
}
}
}
impl std::fmt::Debug for Snapshot {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Snapshot")
.field("generation", &self.generation)
.field("toc_offset", &self.toc_offset)
.field("has_mmap", &self.mmap.is_some())
.field("frames", &self.catalog.frames.len())
.field("frame_stubs", &self.catalog.frame_stubs.len())
.field("vectors", &self.catalog.vectors.len())
.finish()
}
}