data_bucket 0.7.13

DataBucket is container for WorkTable's data
//! Bounded append-only retention segments over the generation protocol.
//! Payload pages are opaque Metadata pages, not WorkTable data-page images.
//! A caller supplies naming, record framing, single-writer fencing and GC.
use super::*;
use alloc::vec::Vec;
use eko::thread::Mutex;

pub const STREAM_PAGE_BYTES: usize = crate::PAGE_SIZE;
pub const STREAM_MAX_PAGES: usize = 4096;
const SLOT: usize = 128;
const MAGIC: &[u8; 8] = b"DBSTR001";

#[derive(Default)]
pub struct StreamCatalog {
    pages: Mutex<Vec<SystemPageRecord>>,
}
pub struct PreparedStreamCatalog {
    pages: Vec<SystemPageRecord>,
    bytes: Vec<u8>,
}
impl PreparedSystemCatalog for PreparedStreamCatalog {
    fn checkpoint(&self) -> &[u8] {
        &self.bytes
    }
}

fn table(pages: &[SystemPageRecord]) -> SystemTableRecord {
    let generation = pages.last().map_or(0, |p| p.generation);
    SystemTableRecord {
        table_id: TableId(1),
        name: CatalogName::new("append-stream").expect("bounded name"),
        schema_version: 1,
        data_space_id: SpaceId(1),
        page_stride: STREAM_PAGE_BYTES as u32,
        row_count: 0,
        live_row_bytes: 0,
        allocated_data_pages: 0,
        live_data_pages: 0,
        primary_index_entries: 0,
        secondary_index_entries: 0,
        tombstones: 0,
        applied_generation: generation,
        durable_generation: generation,
    }
}

fn prepared(pages: Vec<SystemPageRecord>) -> Result<PreparedStreamCatalog, CatalogError> {
    if pages.len() > STREAM_MAX_PAGES {
        return Err(CatalogError::InvalidMutation);
    }
    let mut bytes = alloc::vec![0; SLOT * (pages.len() + 1)];
    bytes[..8].copy_from_slice(MAGIC);
    bytes[8..16].copy_from_slice(&(pages.len() as u64).to_le_bytes());
    for (index, page) in pages.iter().enumerate() {
        if usize::from(page.page_id) != index + 1
            || page.table_id != TableId(1)
            || page.space_id != SpaceId(1)
            || page.page_kind != PageKind::Metadata
            || page.encoded_length == 0
            || page.encoded_length as usize > STREAM_PAGE_BYTES
            || page.encoded_length != page.decoded_length
            || page.generation == 0
        {
            return Err(CatalogError::InvalidMutation);
        }
        let row = &mut bytes[SLOT * (index + 1)..SLOT * (index + 2)];
        row[..8].copy_from_slice(&page.generation.to_le_bytes());
        row[8..40].copy_from_slice(&page.object);
        row[40..48].copy_from_slice(&page.object_offset.to_le_bytes());
        row[48..52].copy_from_slice(&page.encoded_length.to_le_bytes());
        row[52..84].copy_from_slice(&page.checksum);
        row[84..88].copy_from_slice(&page.live_rows.to_le_bytes());
        row[88..92].copy_from_slice(&page.live_bytes.to_le_bytes());
    }
    Ok(PreparedStreamCatalog { pages, bytes })
}

impl StreamCatalog {
    fn lock_pages(
        &self,
    ) -> Result<impl core::ops::DerefMut<Target = Vec<SystemPageRecord>> + '_, CatalogError> {
        Ok(self.pages.lock())
    }
}

impl SystemCatalog for StreamCatalog {
    type Prepared = PreparedStreamCatalog;
    fn prepare(
        &self,
        _: &CatalogWritePermit,
        mutations: &[CatalogMutation],
    ) -> Result<Self::Prepared, CatalogError> {
        let mut pages = self.lock_pages()?.clone();
        for mutation in mutations {
            match mutation {
                CatalogMutation::Upsert(CatalogRecord::Table(row))
                    if row.table_id == TableId(1) => {}
                CatalogMutation::Upsert(CatalogRecord::Page(row))
                    if usize::from(row.page_id) == pages.len() + 1 =>
                {
                    pages.push(row.clone())
                }
                _ => return Err(CatalogError::InvalidMutation),
            }
        }
        prepared(pages)
    }
    fn prepare_restore(
        &self,
        _: &CatalogWritePermit,
        bytes: &[u8],
    ) -> Result<Self::Prepared, CatalogError> {
        if bytes.len() < SLOT || bytes.get(..8) != Some(MAGIC) {
            return Err(CatalogError::Codec);
        }
        let count = u64::from_le_bytes(bytes[8..16].try_into().map_err(|_| CatalogError::Codec)?);
        let count = usize::try_from(count).map_err(|_| CatalogError::Codec)?;
        if count > STREAM_MAX_PAGES || bytes.len() != SLOT * (count + 1) {
            return Err(CatalogError::Codec);
        }
        let mut pages = Vec::with_capacity(count);
        for index in 0..count {
            let row = &bytes[SLOT * (index + 1)..SLOT * (index + 2)];
            let length =
                u32::from_le_bytes(row[48..52].try_into().map_err(|_| CatalogError::Codec)?);
            pages.push(SystemPageRecord {
                table_id: TableId(1),
                space_id: SpaceId(1),
                page_id: ((index + 1) as u32).into(),
                page_kind: PageKind::Metadata,
                generation: u64::from_le_bytes(
                    row[..8].try_into().map_err(|_| CatalogError::Codec)?,
                ),
                object: row[8..40].try_into().map_err(|_| CatalogError::Codec)?,
                object_offset: u64::from_le_bytes(
                    row[40..48].try_into().map_err(|_| CatalogError::Codec)?,
                ),
                encoded_length: length,
                decoded_length: length,
                checksum: row[52..84].try_into().map_err(|_| CatalogError::Codec)?,
                live_rows: u32::from_le_bytes(
                    row[84..88].try_into().map_err(|_| CatalogError::Codec)?,
                ),
                live_bytes: u32::from_le_bytes(
                    row[88..92].try_into().map_err(|_| CatalogError::Codec)?,
                ),
            });
        }
        let restored = prepared(pages)?;
        if restored.bytes != bytes {
            return Err(CatalogError::Codec);
        }
        Ok(restored)
    }
    fn publish(&self, _: &CatalogWritePermit, prepared: Self::Prepared) {
        *self.lock_pages().expect("stream catalog lock") = prepared.pages;
    }
    fn record(&self, key: &CatalogKey) -> Option<CatalogRecord> {
        let pages = self.lock_pages().ok()?;
        if *key == CatalogRecord::table_key(TableId(1)) {
            return Some(CatalogRecord::Table(table(&pages)));
        }
        pages
            .iter()
            .find(|p| CatalogRecord::Page((*p).clone()).key() == *key)
            .cloned()
            .map(CatalogRecord::Page)
    }
    fn records(&self, kind: CatalogRecordKind) -> Vec<CatalogRecord> {
        let pages = self.lock_pages().expect("stream catalog lock");
        match kind {
            CatalogRecordKind::Table => alloc::vec![CatalogRecord::Table(table(&pages))],
            CatalogRecordKind::Page => pages.iter().cloned().map(CatalogRecord::Page).collect(),
            _ => Vec::new(),
        }
    }
}

/// One physical retention segment. Never exposes a mutable domain or delete.
pub struct AppendStream<S> {
    domain: StorageDomain<StreamCatalog, S>,
}
impl<S: PageStore> AppendStream<S> {
    pub fn open(
        id: StorageDomainId,
        epoch: WriterEpoch,
        store: S,
    ) -> Result<Self, DomainError<S::Error>> {
        Ok(Self {
            domain: StorageDomain::open(id, epoch, StreamCatalog::default(), store)?,
        })
    }
    pub fn generation(&self) -> Generation {
        self.domain.generation()
    }
    pub fn store(&self) -> &S {
        self.domain.store()
    }
    pub fn page_count(&self) -> usize {
        self.domain.catalog().records(CatalogRecordKind::Page).len()
    }
    pub fn remaining_pages(&self) -> usize {
        STREAM_MAX_PAGES - self.page_count()
    }
    pub fn read(&self, page: u32) -> Result<Option<Vec<u8>>, DomainError<S::Error>> {
        self.domain.read_page(self.address(page))
    }
    fn address(&self, page: u32) -> PageAddress {
        PageAddress {
            domain: self.domain.id(),
            table_id: TableId(1),
            space_id: SpaceId(1),
            page_id: page.into(),
            page_kind: PageKind::Metadata,
        }
    }
    /// Every supplied image is sealed, including a partially filled last page.
    pub fn append(
        &mut self,
        images: Vec<Vec<u8>>,
    ) -> Result<CommittedGeneration, DomainError<S::Error>> {
        if images.is_empty()
            || images.len() > self.remaining_pages()
            || images
                .iter()
                .any(|p| p.is_empty() || p.len() > STREAM_PAGE_BYTES)
        {
            return Err(DomainError::Catalog(CatalogError::InvalidMutation));
        }
        let first = self.page_count() + 1;
        let mut builder = self.domain.begin_generation()?;
        for (index, image) in images.into_iter().enumerate() {
            let length = image.len() as u32;
            builder.put_page(self.address((first + index) as u32), image, 0, length);
        }
        self.domain.commit_generation(builder.finish())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn malformed_catalog_is_rejected() {
        let catalog = StreamCatalog::default();
        let permit = CatalogWritePermit { _private: () };
        assert!(catalog.prepare_restore(&permit, b"DBSTR000").is_err());
        let empty = prepared(Vec::new()).unwrap();
        assert!(catalog.prepare_restore(&permit, &empty.bytes).is_ok());
    }
    #[test]
    fn slots_do_not_move_and_overwrite_is_rejected() {
        let row = SystemPageRecord {
            table_id: TableId(1),
            space_id: SpaceId(1),
            page_id: 1u32.into(),
            page_kind: PageKind::Metadata,
            generation: 1,
            object: [7; 32],
            object_offset: 0,
            encoded_length: 1,
            decoded_length: 1,
            checksum: [8; 32],
            live_rows: 0,
            live_bytes: 1,
        };
        let one = prepared(alloc::vec![row.clone()]).unwrap();
        let mut next = row.clone();
        next.page_id = 2u32.into();
        next.generation = 2;
        let two = prepared(alloc::vec![row.clone(), next]).unwrap();
        assert_eq!(&one.bytes[SLOT..], &two.bytes[SLOT..2 * SLOT]);
        let catalog = StreamCatalog::default();
        let permit = CatalogWritePermit { _private: () };
        catalog.publish(&permit, one);
        assert!(catalog
            .prepare(
                &permit,
                &[CatalogMutation::Upsert(CatalogRecord::Page(row))]
            )
            .is_err());
    }

    struct MemoryS3 {
        objects: Mutex<BTreeMap<alloc::string::String, (Vec<u8>, alloc::string::String)>>,
    }
    impl super::super::s3::S3Transport for MemoryS3 {
        fn send(
            &self,
            method: &str,
            url: &str,
            headers: &[(&str, &str)],
            body: &[u8],
        ) -> Result<super::super::s3::S3Response, super::super::s3::S3StoreError> {
            use super::super::s3::{S3Response, S3StoreError};
            let key = alloc::string::String::from(
                url::Url::parse(url)
                    .map_err(|_| S3StoreError::InvalidConfig)?
                    .path(),
            );
            let mut objects = self.objects.lock();
            let header = |name| headers.iter().find(|(k, _)| *k == name).map(|(_, v)| *v);
            if method == "PUT" {
                if header("if-none-match").is_some() && objects.contains_key(&key)
                    || header("if-match").is_some_and(|etag| {
                        objects.get(&key).map(|(_, e)| e.as_str()) != Some(etag)
                    })
                {
                    return Ok(S3Response {
                        status: 412,
                        etag: None,
                        body: Vec::new(),
                    });
                }
                let etag = alloc::format!("{}", blake3::hash(body));
                objects.insert(key, (body.to_vec(), etag));
                return Ok(S3Response {
                    status: 200,
                    etag: None,
                    body: Vec::new(),
                });
            }
            let Some((bytes, etag)) = objects.get(&key) else {
                return Ok(S3Response {
                    status: 404,
                    etag: None,
                    body: Vec::new(),
                });
            };
            if let Some(range) = header("range") {
                let (start, end) = range
                    .strip_prefix("bytes=")
                    .unwrap()
                    .split_once('-')
                    .unwrap();
                let start: usize = start.parse().unwrap();
                let end: usize = end.parse().unwrap();
                return Ok(S3Response {
                    status: 206,
                    etag: Some(etag.clone()),
                    body: bytes[start..=end].to_vec(),
                });
            }
            Ok(S3Response {
                status: 200,
                etag: Some(etag.clone()),
                body: bytes.clone(),
            })
        }
    }
    fn config() -> super::super::s3::S3Config {
        super::super::s3::S3Config {
            bucket_name: "stream-test".into(),
            endpoint: "https://objects.invalid".into(),
            access_key: "fixture".into(),
            secret_key: "fixture".into(),
            session_token: None,
            region: "auto".into(),
            prefix: Some("test".into()),
            virtual_host_style: false,
        }
    }
    #[test]
    fn actual_put_bodies_restart_ranges_and_retirement() {
        use super::super::s3::S3PageStore;
        let transport = alloc::sync::Arc::new(MemoryS3 {
            objects: Mutex::new(BTreeMap::new()),
        });
        let id = StorageDomainId([1; 16]);
        let store = S3PageStore::with_transport(config(), transport.clone()).unwrap();
        let mut stream = AppendStream::open(id, 1, store).unwrap();
        stream.append(alloc::vec![alloc::vec![1; 5]]).unwrap();
        assert_eq!(stream.store().put_totals(), (4, 509));
        let sealed = transport
            .objects
            .lock()
            .iter()
            .find(|(key, _)| key.contains("/segments/"))
            .map(|(key, value)| (key.clone(), value.clone()))
            .unwrap();
        stream.append(alloc::vec![alloc::vec![2; 7]]).unwrap();
        assert_eq!(stream.store().put_totals(), (8, 1148));
        assert_eq!(
            transport.objects.lock().get(&sealed.0),
            Some(&sealed.1)
        );
        let store = S3PageStore::with_transport(config(), transport.clone()).unwrap();
        let mut reopened = AppendStream::open(id, 1, store).unwrap();
        assert_eq!(reopened.read(1).unwrap(), Some(alloc::vec![1; 5]));
        reopened.append(alloc::vec![alloc::vec![3; 9]]).unwrap();
        assert_eq!(reopened.store().put_totals(), (4, 769));
        reopened.store().retire(id).unwrap();
        assert!(reopened.append(alloc::vec![alloc::vec![4]]).is_err());
        let store = S3PageStore::with_transport(config(), transport).unwrap();
        assert!(AppendStream::open(id, 1, store).is_err());
    }
}