sui_rpc/client/ledger_streams/adapter/
progress.rs1use 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#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub(in crate::client::ledger_streams) enum KeyGranularity {
11 Checkpoint,
13 Transaction,
15 Event,
17}
18
19#[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 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 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 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 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 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 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
125pub(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#[derive(Clone, Debug, PartialEq, Eq)]
135pub(in crate::client::ledger_streams) struct Progress<C> {
136 pub(in crate::client::ledger_streams) position: Position,
138 pub(in crate::client::ledger_streams) cursor: C,
140 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 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
202pub(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
208pub(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 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 pub(in crate::client::ledger_streams) fn leading_boundary(&self) -> Position {
241 self.item_key().unwrap_or(self.progress.position)
242 }
243}
244
245pub(in crate::client::ledger_streams) struct RecoveryGap<C> {
247 pub(in crate::client::ledger_streams) start: Position,
248 pub(in crate::client::ledger_streams) after: C,
250 pub(in crate::client::ledger_streams) end: Position,
251 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}