Skip to main content

sui_rpc/client/ledger_streams/adapter/
progress.rs

1use tonic::Status;
2
3use super::super::super::Result;
4use super::super::types::Position;
5use super::ListScanDirection;
6use crate::proto::sui::rpc::v2::LedgerPosition;
7
8/// The fields of an item key, which also bound the fields of positions in its family.
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub(in crate::client::ledger_streams) enum KeyGranularity {
11    /// Keys are `(checkpoint)`.
12    Checkpoint,
13    /// Keys are `(checkpoint, transaction_index)`.
14    Transaction,
15    /// Keys are `(checkpoint, transaction_index, event_index)`.
16    Event,
17}
18
19/// Checkpoint range fields that bound one end of a List request at a position.
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub(in crate::client::ledger_streams) struct BoundFields {
22    pub(in crate::client::ledger_streams) checkpoint: u64,
23    pub(in crate::client::ledger_streams) transaction_index: Option<u64>,
24    pub(in crate::client::ledger_streams) event_index: Option<u32>,
25}
26
27impl Position {
28    /// The boundary before the first item of `checkpoint`.
29    pub(in crate::client::ledger_streams) fn checkpoint_start(checkpoint: u64) -> Self {
30        Self {
31            checkpoint,
32            transaction_index: 0,
33            event_index: 0,
34        }
35    }
36
37    /// Request fields that start a scan at this position: `start_checkpoint`, plus
38    /// `start_transaction_index` when either index is nonzero and `start_event_index` when the
39    /// event index is nonzero.
40    pub(in crate::client::ledger_streams) fn start_fields(self) -> BoundFields {
41        let has_index = self.transaction_index != 0 || self.event_index != 0;
42        BoundFields {
43            checkpoint: self.checkpoint,
44            transaction_index: has_index.then_some(self.transaction_index),
45            event_index: (self.event_index != 0).then_some(self.event_index),
46        }
47    }
48
49    /// Request fields that end a scan at this position: `end_checkpoint` alone at a checkpoint
50    /// start; otherwise `end_checkpoint = checkpoint + 1` plus the end indexes.
51    pub(in crate::client::ledger_streams) fn end_fields(self) -> Result<BoundFields> {
52        if self.transaction_index == 0 && self.event_index == 0 {
53            return Ok(BoundFields {
54                checkpoint: self.checkpoint,
55                transaction_index: None,
56                event_index: None,
57            });
58        }
59        let checkpoint = self.checkpoint.checked_add(1).ok_or_else(|| {
60            Status::out_of_range("ledger position cannot be converted to an exclusive end bound")
61        })?;
62        Ok(BoundFields {
63            checkpoint,
64            transaction_index: Some(self.transaction_index),
65            event_index: (self.event_index != 0).then_some(self.event_index),
66        })
67    }
68}
69
70impl KeyGranularity {
71    /// Reads a wire position, with unset fields as 0, ignoring fields finer than this
72    /// granularity.
73    pub(in crate::client::ledger_streams) fn position(self, position: &LedgerPosition) -> Position {
74        self.normalize(Position {
75            checkpoint: position.checkpoint_opt().unwrap_or(0),
76            transaction_index: position.transaction_index_opt().unwrap_or(0),
77            event_index: position.event_index_opt().unwrap_or(0),
78        })
79    }
80
81    /// Zeroes the fields of `position` finer than this granularity.
82    pub(in crate::client::ledger_streams) fn normalize(self, position: Position) -> Position {
83        match self {
84            Self::Checkpoint => Position::checkpoint_start(position.checkpoint),
85            Self::Transaction => Position {
86                event_index: 0,
87                ..position
88            },
89            Self::Event => position,
90        }
91    }
92
93    /// The key of the item an ascending item frame at `position` carries: `position` with its
94    /// finest index decremented. Exact, because item frames never carry their position into the
95    /// next transaction or checkpoint. `None` when that index is 0, which no item frame names.
96    pub(in crate::client::ledger_streams) fn ascending_item_key(
97        self,
98        position: Position,
99    ) -> Option<Position> {
100        match self {
101            Self::Checkpoint => position
102                .checkpoint
103                .checked_sub(1)
104                .map(Position::checkpoint_start),
105            Self::Transaction => {
106                position
107                    .transaction_index
108                    .checked_sub(1)
109                    .map(|transaction_index| Position {
110                        transaction_index,
111                        ..position
112                    })
113            }
114            Self::Event => position
115                .event_index
116                .checked_sub(1)
117                .map(|event_index| Position {
118                    event_index,
119                    ..position
120                }),
121        }
122    }
123}
124
125/// The error for a frame whose watermark lacks `cursor_position`.
126pub(in crate::client::ledger_streams) fn missing_cursor_position(source: &str) -> Status {
127    Status::data_loss(format!(
128        "{source} watermark is missing its cursor_position; servers that predate cursor \
129         positions do not send it"
130    ))
131}
132
133/// A frame's resume point plus the checkpoint coverage reported with it.
134#[derive(Clone, Debug, PartialEq, Eq)]
135pub(in crate::client::ledger_streams) struct Progress<C> {
136    /// Every match before this position has been delivered (ascending).
137    pub(in crate::client::ledger_streams) position: Position,
138    /// Opaque cursor naming `position`, passed back to servers unchanged and never compared.
139    pub(in crate::client::ledger_streams) cursor: C,
140    /// Inclusive checkpoint the scan reported fully covered, when reported.
141    pub(in crate::client::ledger_streams) checkpoint: Option<u64>,
142}
143
144impl<C: Clone> Progress<C> {
145    pub(in crate::client::ledger_streams) fn inherit_checkpoint_coverage(
146        &mut self,
147        previous: &Self,
148    ) {
149        if self.checkpoint.is_none() {
150            self.checkpoint = previous.checkpoint;
151        }
152    }
153
154    /// Folds `next`, a later frame of the same `source` scan or subscription in `direction`, into
155    /// `self`, the furthest progress seen. Returns whether `next` advanced
156    /// `(position, coverage)`.
157    ///
158    /// A frame without an item whose position lies behind `self`'s makes no progress rather than
159    /// failing: different positions can name one boundary, such as `(cp, tx_count)` and
160    /// `(cp + 1, 0)`. An item frame's position must lie beyond `self`'s, and coverage must not
161    /// regress or disappear.
162    pub(in crate::client::ledger_streams) fn advance(
163        &mut self,
164        next: &Self,
165        direction: ListScanDirection,
166        item_present: bool,
167        source: &str,
168    ) -> Result<(bool, bool)> {
169        let coverage_regressed = match (self.checkpoint, next.checkpoint) {
170            (Some(_), None) => {
171                return Err(Status::data_loss(format!(
172                    "{source} checkpoint coverage became unavailable"
173                )));
174            }
175            (Some(current), Some(next)) => match direction {
176                ListScanDirection::Ascending => next < current,
177                ListScanDirection::Descending => next > current,
178            },
179            (None, _) => false,
180        };
181        if coverage_regressed {
182            return Err(Status::data_loss(format!(
183                "{source} checkpoint coverage regressed"
184            )));
185        }
186        let position_advanced = direction.beyond(next.position, self.position);
187        if item_present && !position_advanced {
188            return Err(Status::data_loss(format!(
189                "{source} item did not advance its cursor_position"
190            )));
191        }
192        let coverage_advanced = next.checkpoint != self.checkpoint;
193        if position_advanced {
194            self.position = next.position;
195            self.cursor = next.cursor.clone();
196        }
197        self.checkpoint = next.checkpoint;
198        Ok((position_advanced, coverage_advanced))
199    }
200}
201
202/// An item with its ledger key.
203pub(in crate::client::ledger_streams) struct KeyedItem<I> {
204    pub(in crate::client::ledger_streams) key: Position,
205    pub(in crate::client::ledger_streams) payload: I,
206}
207
208/// One frame of an ascending scan or subscription: an optional item and its progress.
209pub(in crate::client::ledger_streams) struct LedgerFrame<I, C> {
210    pub(in crate::client::ledger_streams) item: Option<KeyedItem<I>>,
211    pub(in crate::client::ledger_streams) progress: Progress<C>,
212}
213
214impl<I, C> LedgerFrame<I, C> {
215    /// Keys `item` from the frame's ascending position.
216    pub(in crate::client::ledger_streams) fn new(
217        item: Option<I>,
218        progress: Progress<C>,
219        granularity: KeyGranularity,
220    ) -> Result<Self> {
221        let item = item
222            .map(|payload| {
223                granularity
224                    .ascending_item_key(progress.position)
225                    .map(|key| KeyedItem { key, payload })
226                    .ok_or_else(|| {
227                        Status::data_loss("item frame cursor_position does not follow an item")
228                    })
229            })
230            .transpose()?;
231        Ok(Self { item, progress })
232    }
233
234    pub(in crate::client::ledger_streams) fn item_key(&self) -> Option<Position> {
235        self.item.as_ref().map(|item| item.key)
236    }
237
238    /// The boundary before this frame's content: its item's key, or its position when it carries
239    /// no item.
240    pub(in crate::client::ledger_streams) fn leading_boundary(&self) -> Position {
241        self.item_key().unwrap_or(self.progress.position)
242    }
243}
244
245/// Historical List interval `[start, end)` between committed progress and a new subscription.
246pub(in crate::client::ledger_streams) struct RecoveryGap<C> {
247    pub(in crate::client::ledger_streams) start: Position,
248    /// Cursor naming `start`, sent as `options.after`.
249    pub(in crate::client::ledger_streams) after: C,
250    pub(in crate::client::ledger_streams) end: Position,
251    /// Cursor naming `end`, sent as `options.before`.
252    pub(in crate::client::ledger_streams) before: C,
253}
254
255#[cfg(test)]
256mod tests {
257    use super::*;
258
259    fn position(checkpoint: u64, transaction_index: u64, event_index: u32) -> Position {
260        Position {
261            checkpoint,
262            transaction_index,
263            event_index,
264        }
265    }
266
267    #[test]
268    fn start_fields_set_indexes_only_when_nonzero() {
269        assert_eq!(
270            position(7, 0, 0).start_fields(),
271            BoundFields {
272                checkpoint: 7,
273                transaction_index: None,
274                event_index: None,
275            }
276        );
277        assert_eq!(
278            position(7, 3, 0).start_fields(),
279            BoundFields {
280                checkpoint: 7,
281                transaction_index: Some(3),
282                event_index: None,
283            }
284        );
285        assert_eq!(
286            position(7, 0, 2).start_fields(),
287            BoundFields {
288                checkpoint: 7,
289                transaction_index: Some(0),
290                event_index: Some(2),
291            }
292        );
293    }
294
295    #[test]
296    fn end_fields_end_inside_the_next_checkpoint_range_unless_at_a_checkpoint_start() {
297        assert_eq!(
298            position(7, 0, 0).end_fields().unwrap(),
299            BoundFields {
300                checkpoint: 7,
301                transaction_index: None,
302                event_index: None,
303            }
304        );
305        assert_eq!(
306            position(7, 3, 0).end_fields().unwrap(),
307            BoundFields {
308                checkpoint: 8,
309                transaction_index: Some(3),
310                event_index: None,
311            }
312        );
313        assert_eq!(
314            position(7, 3, 2).end_fields().unwrap(),
315            BoundFields {
316                checkpoint: 8,
317                transaction_index: Some(3),
318                event_index: Some(2),
319            }
320        );
321        assert_eq!(
322            position(u64::MAX, 1, 0).end_fields().unwrap_err().code(),
323            tonic::Code::OutOfRange
324        );
325    }
326
327    #[test]
328    fn ascending_item_keys_decrement_the_finest_index() {
329        assert_eq!(
330            KeyGranularity::Checkpoint.ascending_item_key(position(8, 0, 0)),
331            Some(position(7, 0, 0))
332        );
333        assert_eq!(
334            KeyGranularity::Transaction.ascending_item_key(position(8, 3, 0)),
335            Some(position(8, 2, 0))
336        );
337        assert_eq!(
338            KeyGranularity::Event.ascending_item_key(position(8, 3, 2)),
339            Some(position(8, 3, 1))
340        );
341        assert_eq!(
342            KeyGranularity::Transaction.ascending_item_key(position(8, 0, 0)),
343            None
344        );
345        assert_eq!(
346            KeyGranularity::Event.ascending_item_key(position(8, 3, 0)),
347            None
348        );
349    }
350
351    #[test]
352    fn positions_ignore_fields_finer_than_their_granularity() {
353        let ledger_position = LedgerPosition::default()
354            .with_checkpoint(4)
355            .with_transaction_index(5)
356            .with_event_index(6);
357        assert_eq!(
358            KeyGranularity::Checkpoint.position(&ledger_position),
359            position(4, 0, 0)
360        );
361        assert_eq!(
362            KeyGranularity::Transaction.position(&ledger_position),
363            position(4, 5, 0)
364        );
365        assert_eq!(
366            KeyGranularity::Event.position(&ledger_position),
367            position(4, 5, 6)
368        );
369        assert_eq!(
370            KeyGranularity::Event.position(&LedgerPosition::default()),
371            Position::default()
372        );
373    }
374}