Skip to main content

rostra_client_db/
social_post_scan.rs

1//! Bounded, read-only traversal of the authored-time social-post index.
2
3use rostra_core::event::content_kind::SocialPost;
4use rostra_core::id::RostraId;
5use rostra_core::{ShortEventId, Timestamp};
6
7use crate::social::EventPaginationCursor;
8
9/// Independent limits and early filters for one read snapshot.
10#[derive(Clone, Copy, Debug)]
11pub struct SocialPostScanRequest {
12    /// Inclusive upper key; use the previous page's continuation unchanged.
13    pub cursor: Option<EventPaginationCursor>,
14    /// Inclusive lower authored timestamp, or the beginning of time.
15    pub authored_from: Option<Timestamp>,
16    /// Inclusive upper authored timestamp, or the end of time.
17    pub authored_through: Option<Timestamp>,
18    /// Optional exact author filter, applied before content decoding.
19    pub author: Option<RostraId>,
20    /// Maximum index rows examined, including hidden and filtered rows.
21    pub max_rows: usize,
22    /// Maximum cumulative raw CBOR bytes submitted to content deserialization.
23    pub max_content_bytes: usize,
24    /// Maximum returned records; one supports caller-side output budgeting.
25    pub max_records: usize,
26}
27
28/// A surviving locally retained post, without unbounded reply-count metadata.
29#[derive(Clone, Debug)]
30pub struct SocialPostScanRow {
31    /// Author-provided timestamp used by the index.
32    pub ts: Timestamp,
33    /// Full author identity.
34    pub author: RostraId,
35    /// Event identity in the local social-post index.
36    pub event_id: ShortEventId,
37    /// Complete decoded content, never truncated for matching.
38    pub content: SocialPost,
39}
40
41/// Why a bounded scan stopped.
42#[derive(Clone, Copy, Debug, PartialEq, Eq)]
43pub enum SocialPostScanStop {
44    /// No remaining index keys in the requested range in this snapshot.
45    Exhausted,
46    /// The index-row allowance was reached, without probing another row.
47    RowBudget,
48    /// The output-count allowance was reached, without probing another row.
49    RecordBudget,
50    /// The next eligible payload exceeds the remaining byte allowance.
51    ContentByteBudget,
52    /// One eligible payload exceeds the entire byte allowance.
53    ContentTooLarge,
54}
55
56/// Results, honest work counters, and continuation from one read snapshot.
57#[derive(Clone, Debug)]
58pub struct SocialPostScanPage {
59    /// Eligible records in descending `(authored timestamp, event ID)` order.
60    pub rows: Vec<SocialPostScanRow>,
61    /// Inclusive upper boundary of the unprocessed range, possibly absent as a
62    /// stored key. A budget stop can require an empty final call to prove
63    /// exhaustion. An indivisible oversized record remains at its exact key.
64    pub next_cursor: Option<EventPaginationCursor>,
65    /// Exhaustion or the specific limiting resource.
66    pub stop: SocialPostScanStop,
67    /// Actual index rows examined, including a byte-blocked candidate.
68    pub rows_scanned: usize,
69    /// Raw CBOR bytes submitted to the decoder, including invalid content.
70    pub content_bytes_decoded: usize,
71    /// Content deserialization attempts, including invalid content.
72    pub contents_decoded: usize,
73}
74
75/// Compute an inclusive boundary without reading an uncharged lookahead row.
76pub(crate) fn predecessor(cursor: EventPaginationCursor) -> Option<EventPaginationCursor> {
77    let id = u128::from_be_bytes(cursor.event_id.to_bytes());
78    if let Some(id) = id.checked_sub(1) {
79        Some(EventPaginationCursor {
80            ts: cursor.ts,
81            event_id: ShortEventId::from_bytes(id.to_be_bytes()),
82        })
83    } else {
84        cursor
85            .ts
86            .as_u64()
87            .checked_sub(1)
88            .map(|ts| EventPaginationCursor {
89                ts: ts.into(),
90                event_id: ShortEventId::MAX,
91            })
92    }
93}