Skip to main content

rostra_client_db/
social_post_materialization.rs

1use std::num::NonZeroUsize;
2
3use bincode::{Decode, Encode};
4use redb::ReadableTable as _;
5use rostra_core::event::{EventExt as _, EventKind, content_kind};
6use rostra_core::{ExternalEventId, ShortEventId, Timestamp};
7use serde::{Deserialize, Serialize};
8use snafu::OptionExt as _;
9
10use crate::event::ContentStoreRecord;
11use crate::{
12    Database, DbResult, EventContentState, OverflowSnafu, WriteTransactionCtx, content_store,
13    events, events_content_state, social_post_materializations, social_posts_replaced_by,
14};
15
16/// Maximum number of materialization rows resolved by one scan.
17pub const SOCIAL_POST_MATERIALIZATION_SCAN_MAX: usize = 4_096;
18
19/// Opaque durable position in one database lineage's SocialPost materialization
20/// feed.
21///
22/// Persist this value only after durably handling every item in its page, then
23/// pass it back to resume. A cursor belongs to the database lineage that issued
24/// it. A faithful backup carrying the same feed prefix retains its meaning;
25/// divergent copies and unrelated databases do not. Restoring a database older
26/// than the cursor fails as out of range.
27#[derive(
28    Clone, Copy, Debug, Decode, Deserialize, Encode, Eq, Ord, PartialEq, PartialOrd, Serialize,
29)]
30#[serde(transparent)]
31pub struct SocialPostMaterializationCursor(u64);
32
33/// Current high-level state of one logged ordinary SocialPost materialization.
34#[derive(Clone, Debug, Eq, PartialEq)]
35pub enum SocialPostMaterialization {
36    /// The materialized post remains current and its validated content is
37    /// available.
38    Present {
39        /// Immutable author and event identity.
40        post_id: ExternalEventId,
41        /// Author-provided creation timestamp.
42        authored_at: Timestamp,
43        /// Currently available validated post content.
44        content: Box<content_kind::SocialPost>,
45    },
46    /// The post was later deleted, pruned, or replaced.
47    Removed {
48        /// Immutable author and event identity of the original occurrence.
49        post_id: ExternalEventId,
50    },
51}
52
53/// One bounded snapshot page from the ordinary SocialPost materialization feed.
54#[derive(Clone, Debug, Eq, PartialEq)]
55pub struct SocialPostMaterializationPage {
56    /// Occurrences resolved against current state in the page's read snapshot.
57    pub items: Vec<SocialPostMaterialization>,
58    /// Position acknowledging every occurrence before this cursor.
59    pub scanned_through: SocialPostMaterializationCursor,
60    /// Whether the same read snapshot contained no later occurrence.
61    pub exhausted: bool,
62}
63
64impl Database {
65    pub(crate) fn append_social_post_materialization_tx(
66        event_id: ShortEventId,
67        tx: &WriteTransactionCtx,
68    ) -> DbResult<()> {
69        if !tx.materialization_emission_enabled() {
70            return Ok(());
71        }
72
73        let mut table = tx.open_table(&social_post_materializations::TABLE)?;
74        let next = {
75            let last = table.as_raw().last()?;
76            Self::social_post_materialization_next_sequence(
77                last.as_ref().map(|entry| entry.0.value()),
78            )?
79        };
80        if next == u64::MAX {
81            return OverflowSnafu.fail();
82        }
83        table.insert(&next, &event_id)?;
84        Ok(())
85    }
86
87    /// Gets a cursor at the current tip of the SocialPost materialization feed.
88    ///
89    /// The cursor denotes the next sequence in one read snapshot. Establishing
90    /// that snapshot is the consumer-enablement linearization point: every
91    /// occurrence visible before the tip is acknowledged by the cursor, while
92    /// an occurrence committed after the snapshot has a sequence at or after
93    /// the cursor and remains discoverable by a later scan. A commit concurrent
94    /// with this call may fall on either side of that boundary.
95    ///
96    /// This reads only the feed's last key; it does not enumerate or resolve
97    /// feed rows. An empty feed returns the sequence-zero cursor.
98    ///
99    /// # Errors
100    ///
101    /// Returns an error on storage, key decode, or sequence overflow.
102    pub async fn get_social_post_materialization_tip(
103        &self,
104    ) -> DbResult<SocialPostMaterializationCursor> {
105        self.read_with(|tx| {
106            let feed = tx.open_table(&social_post_materializations::TABLE)?;
107            let last = feed.as_raw().last()?;
108            let next = Self::social_post_materialization_next_sequence(
109                last.as_ref().map(|entry| entry.0.value()),
110            )?;
111            Ok(SocialPostMaterializationCursor(next))
112        })
113        .await
114    }
115
116    /// Scans ordinary SocialPost materializations in commit order.
117    ///
118    /// `after` is an opaque position acknowledging every earlier occurrence.
119    /// `None` starts at this database lineage's cutover position zero. The
120    /// schema upgrade does not backfill posts materialized by older code.
121    ///
122    /// Each logged identity is resolved against one current-state read
123    /// snapshot. Later deletion, pruning, or replacement yields
124    /// [`SocialPostMaterialization::Removed`]; a currently available post
125    /// yields [`SocialPostMaterialization::Present`]. Log rows remain
126    /// append-only either way. `limit` bounds rows resolved, and the
127    /// implementation performs at most one additional key lookahead to
128    /// determine snapshot-relative exhaustion.
129    ///
130    /// A replaced post is still required to have a coherent lifecycle. If that
131    /// lifecycle claims the content remains processed, retained bytes must be
132    /// present and decodable. Corruption takes precedence over `Removed`.
133    ///
134    /// # Errors
135    ///
136    /// Returns no page or acknowledgment on storage, decode, cursor, density,
137    /// or current-state invariant errors.
138    pub async fn scan_social_post_materializations(
139        &self,
140        after: Option<SocialPostMaterializationCursor>,
141        limit: NonZeroUsize,
142    ) -> DbResult<SocialPostMaterializationPage> {
143        if SOCIAL_POST_MATERIALIZATION_SCAN_MAX < limit.get() {
144            return Err(crate::DbError::SocialPostMaterializationScanLimitTooHigh {
145                requested: limit.get(),
146                maximum: SOCIAL_POST_MATERIALIZATION_SCAN_MAX,
147            });
148        }
149        self.read_with(|tx| {
150            let feed = tx.open_table(&social_post_materializations::TABLE)?;
151            let last = feed.as_raw().last()?;
152            let durable_next = Self::social_post_materialization_next_sequence(
153                last.as_ref().map(|entry| entry.0.value()),
154            )?;
155            let mut expected = after.map_or(0, |cursor| cursor.0);
156            if durable_next < expected {
157                return crate::SocialPostMaterializationCursorOutOfRangeSnafu {
158                    position: expected,
159                    durable_next,
160                }
161                .fail();
162            }
163
164            let events_table = tx.open_table(&events::TABLE)?;
165            let states = tx.open_table(&events_content_state::TABLE)?;
166            let content = tx.open_table(&content_store::TABLE)?;
167            let replacements = tx.open_table(&social_posts_replaced_by::TABLE)?;
168            let mut range = feed.range(expected..)?;
169            let mut items = Vec::with_capacity(limit.get());
170
171            for _ in 0..limit.get() {
172                let Some(entry) = range.next() else {
173                    return Ok(SocialPostMaterializationPage {
174                        items,
175                        scanned_through: SocialPostMaterializationCursor(expected),
176                        exhausted: true,
177                    });
178                };
179                let (sequence, event_id) = entry?;
180                let actual = sequence.value_try()?;
181                if actual != expected {
182                    return crate::SocialPostMaterializationLogGapSnafu { expected, actual }.fail();
183                }
184                let event_id = event_id.value_try()?;
185                items.push(Self::resolve_social_post_materialization_tx(
186                    event_id,
187                    &events_table,
188                    &states,
189                    &content,
190                    &replacements,
191                )?);
192                expected = expected.checked_add(1).context(OverflowSnafu)?;
193            }
194
195            let exhausted = match range.next().transpose()? {
196                None => true,
197                Some((sequence, _)) => {
198                    let actual = sequence.value_try()?;
199                    if actual != expected {
200                        return crate::SocialPostMaterializationLogGapSnafu { expected, actual }
201                            .fail();
202                    }
203                    false
204                }
205            };
206            Ok(SocialPostMaterializationPage {
207                items,
208                scanned_through: SocialPostMaterializationCursor(expected),
209                exhausted,
210            })
211        })
212        .await
213    }
214
215    fn social_post_materialization_next_sequence(last_key: Option<&[u8]>) -> DbResult<u64> {
216        let Some(last_key) = last_key else {
217            return Ok(0);
218        };
219        let (last, consumed) =
220            bincode::decode_from_slice::<u64, _>(last_key, redb_bincode::BINCODE_CONFIG)?;
221        if consumed != last_key.len() {
222            return Err(
223                bincode::error::DecodeError::Other("Trailing bytes after encoded value").into(),
224            );
225        }
226        last.checked_add(1).context(OverflowSnafu)
227    }
228
229    fn resolve_social_post_materialization_tx(
230        event_id: ShortEventId,
231        events_table: &impl events::ReadableTable,
232        states: &impl events_content_state::ReadableTable,
233        content: &impl content_store::ReadableTable,
234        replacements: &impl social_posts_replaced_by::ReadableTable,
235    ) -> DbResult<SocialPostMaterialization> {
236        let event = events_table
237            .get(&event_id)?
238            .map(|entry| entry.value_try())
239            .transpose()?
240            .context(crate::MissingSocialPostMaterializationEventSnafu { event_id })?;
241        if event.kind() != EventKind::SOCIAL_POST {
242            return crate::InvalidSocialPostMaterializationKindSnafu {
243                event_id,
244                kind: event.kind(),
245            }
246            .fail();
247        }
248        let post_id = ExternalEventId::new(event.author(), event_id);
249
250        match Self::get_event_content_state_tx(event_id, states)? {
251            Some(EventContentState::Deleted { .. } | EventContentState::Pruned) => {
252                return Ok(SocialPostMaterialization::Removed { post_id });
253            }
254            Some(EventContentState::Missing { .. }) => {
255                return crate::MissingSocialPostMaterializationStateSnafu { event_id }.fail();
256            }
257            Some(EventContentState::Invalid) => {
258                return crate::InvalidSocialPostMaterializationStateSnafu { event_id }.fail();
259            }
260            None => {}
261        }
262
263        let ContentStoreRecord(raw) = content
264            .get(&event.content_hash())?
265            .map(|entry| entry.value_try())
266            .transpose()?
267            .context(crate::MissingSocialPostMaterializationContentSnafu { event_id })?;
268        let content = raw
269            .deserialize_cbor::<content_kind::SocialPost>()
270            .map_err(
271                |source| crate::DbError::InvalidSocialPostMaterializationContent {
272                    event_id,
273                    source: Box::new(source),
274                },
275            )?;
276        if Self::is_social_post_replaced_tx(event.author(), event_id, replacements)? {
277            return Ok(SocialPostMaterialization::Removed { post_id });
278        }
279        Ok(SocialPostMaterialization::Present {
280            post_id,
281            authored_at: event.timestamp(),
282            content: Box::new(content),
283        })
284    }
285}