rostra-client-db 0.1.4

Embedded database and projections for a Rostra client
Documentation
//! Bounded, read-only traversal of the authored-time social-post index.

use rostra_core::event::content_kind::SocialPost;
use rostra_core::id::RostraId;
use rostra_core::{ShortEventId, Timestamp};

use crate::social::EventPaginationCursor;

/// Independent limits and early filters for one read snapshot.
#[derive(Clone, Copy, Debug)]
pub struct SocialPostScanRequest {
    /// Inclusive upper key; use the previous page's continuation unchanged.
    pub cursor: Option<EventPaginationCursor>,
    /// Inclusive lower authored timestamp, or the beginning of time.
    pub authored_from: Option<Timestamp>,
    /// Inclusive upper authored timestamp, or the end of time.
    pub authored_through: Option<Timestamp>,
    /// Optional exact author filter, applied before content decoding.
    pub author: Option<RostraId>,
    /// Maximum index rows examined, including hidden and filtered rows.
    pub max_rows: usize,
    /// Maximum cumulative raw CBOR bytes submitted to content deserialization.
    pub max_content_bytes: usize,
    /// Maximum returned records; one supports caller-side output budgeting.
    pub max_records: usize,
}

/// A surviving locally retained post, without unbounded reply-count metadata.
#[derive(Clone, Debug)]
pub struct SocialPostScanRow {
    /// Author-provided timestamp used by the index.
    pub ts: Timestamp,
    /// Full author identity.
    pub author: RostraId,
    /// Event identity in the local social-post index.
    pub event_id: ShortEventId,
    /// Complete decoded content, never truncated for matching.
    pub content: SocialPost,
}

/// Why a bounded scan stopped.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SocialPostScanStop {
    /// No remaining index keys in the requested range in this snapshot.
    Exhausted,
    /// The index-row allowance was reached, without probing another row.
    RowBudget,
    /// The output-count allowance was reached, without probing another row.
    RecordBudget,
    /// The next eligible payload exceeds the remaining byte allowance.
    ContentByteBudget,
    /// One eligible payload exceeds the entire byte allowance.
    ContentTooLarge,
}

/// Results, honest work counters, and continuation from one read snapshot.
#[derive(Clone, Debug)]
pub struct SocialPostScanPage {
    /// Eligible records in descending `(authored timestamp, event ID)` order.
    pub rows: Vec<SocialPostScanRow>,
    /// Inclusive upper boundary of the unprocessed range, possibly absent as a
    /// stored key. A budget stop can require an empty final call to prove
    /// exhaustion. An indivisible oversized record remains at its exact key.
    pub next_cursor: Option<EventPaginationCursor>,
    /// Exhaustion or the specific limiting resource.
    pub stop: SocialPostScanStop,
    /// Actual index rows examined, including a byte-blocked candidate.
    pub rows_scanned: usize,
    /// Raw CBOR bytes submitted to the decoder, including invalid content.
    pub content_bytes_decoded: usize,
    /// Content deserialization attempts, including invalid content.
    pub contents_decoded: usize,
}

/// Compute an inclusive boundary without reading an uncharged lookahead row.
pub(crate) fn predecessor(cursor: EventPaginationCursor) -> Option<EventPaginationCursor> {
    let id = u128::from_be_bytes(cursor.event_id.to_bytes());
    if let Some(id) = id.checked_sub(1) {
        Some(EventPaginationCursor {
            ts: cursor.ts,
            event_id: ShortEventId::from_bytes(id.to_be_bytes()),
        })
    } else {
        cursor
            .ts
            .as_u64()
            .checked_sub(1)
            .map(|ts| EventPaginationCursor {
                ts: ts.into(),
                event_id: ShortEventId::MAX,
            })
    }
}