rostra-client-db 0.1.4

Embedded database and projections for a Rostra client
Documentation
use std::ops::Bound;

use rostra_core::ShortEventId;
use rostra_core::event::{EventContentUnsized, EventExt as _, EventKind, content_kind};
use rostra_core::id::ToShort as _;

use crate::social::EventPaginationCursor;
use crate::social_post_scan::predecessor;
use crate::{
    Database, DbError, DbResult, SocialPostScanPage, SocialPostScanRequest, SocialPostScanRow,
    SocialPostScanStop, content_store, events, events_content_state, social_posts_by_time,
    social_posts_replaced_by,
};

impl Database {
    /// Scan locally retained social posts in reverse authored-time order.
    ///
    /// Limits count examined index rows and raw CBOR bytes submitted to the
    /// decoder, not accepted matches. Author/time filtering precedes decoding.
    /// Replaced, unavailable and invalid posts are omitted just as in the
    /// reverse timeline; all local authors (including self) are eligible.
    /// Reply counts, replacement ancestry, attachments, private messages
    /// and network reads are never accessed. There is no caller predicate:
    /// matching and output policy belong to the caller.
    ///
    /// Each examined row requires only fixed-size index/envelope/state reads
    /// and one replaced-by existence probe. Content is borrowed from
    /// storage and its declared and stored lengths checked before owned
    /// deserialization. The byte allowance is not an OS I/O, database
    /// page-cache, decoder heap or CPU-time limit. Callers must bound their
    /// requests, concurrency and output retention.
    ///
    /// A continuation is an inclusive range boundary, not necessarily an
    /// existing key. Budget stops do not read ahead to establish
    /// exhaustion. Oversized or byte-blocked candidates remain unconsumed
    /// at their exact key and count as examined, but not decoded. Zero
    /// row/result limits return immediately with the initial boundary; a
    /// reversed time range is exhausted. Every call uses a fresh snapshot,
    /// so concurrent edits/deletions can change later pages. Callers must
    /// bind cursors to their account and filters.
    ///
    /// Storage and stored-record decoding errors propagate as errors; invalid
    /// social-post CBOR is skipped and charged as a decode attempt.
    pub async fn scan_social_posts_rev(
        &self,
        request: SocialPostScanRequest,
    ) -> DbResult<SocialPostScanPage> {
        self.read_with(|tx| {
            let lower = EventPaginationCursor {
                ts: request
                    .authored_from
                    .unwrap_or(rostra_core::Timestamp::ZERO),
                event_id: ShortEventId::ZERO,
            };
            let upper =
                request
                    .cursor
                    .unwrap_or(EventPaginationCursor::MAX)
                    .min(EventPaginationCursor {
                        ts: request
                            .authored_through
                            .unwrap_or(rostra_core::Timestamp::MAX),
                        event_id: ShortEventId::MAX,
                    });
            let mut page = SocialPostScanPage {
                rows: Vec::new(),
                next_cursor: (lower <= upper).then_some(upper),
                stop: SocialPostScanStop::Exhausted,
                rows_scanned: 0,
                content_bytes_decoded: 0,
                contents_decoded: 0,
            };
            if lower > upper {
                return Ok(page);
            }
            let index = tx.open_table(&social_posts_by_time::TABLE)?;
            let events = tx.open_table(&events::TABLE)?;
            let states = tx.open_table(&events_content_state::TABLE)?;
            let replaced = tx.open_table(&social_posts_replaced_by::TABLE)?;
            let store = tx.open_table(&content_store::TABLE)?;
            let encode = |key: EventPaginationCursor| {
                bincode::encode_to_vec((key.ts, key.event_id), redb_bincode::BINCODE_CONFIG)
                    .map_err(|_| scan_invariant_error())
            };
            let lower_key = encode(lower)?;
            let upper_key = encode(upper)?;
            let mut entries = index
                .as_raw()
                .range::<&[u8]>((
                    Bound::Included(lower_key.as_slice()),
                    Bound::Included(upper_key.as_slice()),
                ))?
                .rev();
            loop {
                if page.next_cursor.is_none() {
                    page.stop = SocialPostScanStop::Exhausted;
                    break;
                }
                if page.rows.len() == request.max_records {
                    page.stop = SocialPostScanStop::RecordBudget;
                    break;
                }
                if page.rows_scanned == request.max_rows {
                    page.stop = SocialPostScanStop::RowBudget;
                    break;
                }
                let Some(entry) = entries.next() else {
                    page.next_cursor = None;
                    page.stop = SocialPostScanStop::Exhausted;
                    break;
                };
                let (key, _) = entry?;
                let ((ts, event_id), consumed) =
                    bincode::decode_from_slice(key.value(), redb_bincode::BINCODE_CONFIG)?;
                if consumed != key.value().len() {
                    return Err(scan_invariant_error());
                }
                let cursor = EventPaginationCursor { ts, event_id };
                page.rows_scanned += 1;
                page.next_cursor = predecessor(cursor).filter(|cursor| *cursor >= lower);
                let Some(event) = events
                    .get(&event_id)?
                    .map(|row| row.value_try())
                    .transpose()?
                else {
                    continue;
                };
                if event.kind() != EventKind::SOCIAL_POST
                    || event.timestamp() != ts
                    || event.event().compute_id().to_short() != event_id
                {
                    return Err(scan_invariant_error());
                }
                let author = event.author();
                if request.author.is_some_and(|wanted| wanted != author) {
                    continue;
                }
                if Self::is_social_post_replaced_tx(author, event_id, &replaced)?
                    || states
                        .get(&event_id)?
                        .map(|row| row.value_try())
                        .transpose()?
                        .is_some()
                {
                    continue;
                }
                let content_key = encode_content_hash_key(event.content_hash());
                let Some(raw) = store.as_raw().get(content_key.as_slice())? else {
                    continue;
                };
                let len = event.content_len() as usize;
                let blocked = if len > request.max_content_bytes {
                    Some(SocialPostScanStop::ContentTooLarge)
                } else if len > request.max_content_bytes - page.content_bytes_decoded {
                    Some(SocialPostScanStop::ContentByteBudget)
                } else {
                    None
                };
                if let Some(stop) = blocked {
                    page.next_cursor = Some(cursor);
                    page.stop = stop;
                    break;
                }
                // ContentStoreRecord's single Cow field uses the borrowed
                // EventContentUnsized encoding; no owned payload is needed here.
                let (content, consumed) =
                    bincode::borrow_decode_from_slice::<&EventContentUnsized, _>(
                        raw.value(),
                        redb_bincode::BINCODE_CONFIG,
                    )?;
                if consumed != raw.value().len() {
                    return Err(bincode::error::DecodeError::Other(
                        "Trailing bytes after encoded value",
                    )
                    .into());
                }
                if content.as_slice().len() != len {
                    return Err(scan_invariant_error());
                }
                page.content_bytes_decoded += content.as_slice().len();
                page.contents_decoded += 1;
                let decoded = content.deserialize_cbor::<content_kind::SocialPost>();
                let Ok(content) = decoded else {
                    continue;
                };
                page.rows.push(SocialPostScanRow {
                    ts,
                    author,
                    event_id,
                    content,
                });
            }
            Ok(page)
        })
        .await
    }
}

pub(crate) fn encode_content_hash_key(hash: rostra_core::ContentHash) -> [u8; 32] {
    let mut encoded = [0; 32];
    let written = bincode::encode_into_slice(hash, &mut encoded, redb_bincode::BINCODE_CONFIG)
        .expect("fixed-size content hash must fit its database key buffer");
    assert_eq!(written, encoded.len());
    encoded
}

fn scan_invariant_error() -> DbError {
    bincode::error::DecodeError::Other("Social-post scan data does not match its retained event")
        .into()
}