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}