1use anyhow::Context as _;
5use bytes::Bytes;
6use prost::Message as _;
7use sui_inverted_index::ScanDirection;
8use sui_rpc::proto::sui::rpc::v2::LedgerPosition;
9
10mod proto;
11
12use proto::sui::rpc::cursor::v1 as grpc;
13
14#[derive(Clone, Debug, Eq, PartialEq)]
16pub struct CursorToken {
17 pub kind: CursorKind,
18 pub position: Position,
19}
20
21#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
27pub struct LedgerPoint {
28 pub checkpoint: u64,
29 pub transaction_index: u64,
30 pub event_index: u32,
31}
32
33impl LedgerPoint {
34 pub const GENESIS: Self = Self {
36 checkpoint: 0,
37 transaction_index: 0,
38 event_index: 0,
39 };
40
41 pub fn checkpoint_start(checkpoint: u64) -> Self {
43 Self {
44 checkpoint,
45 ..Self::GENESIS
46 }
47 }
48
49 pub fn transaction(checkpoint: u64, transaction_index: u64) -> Self {
52 Self {
53 checkpoint,
54 transaction_index,
55 event_index: 0,
56 }
57 }
58
59 pub fn event(checkpoint: u64, transaction_index: u64, event_index: u32) -> Self {
61 Self {
62 checkpoint,
63 transaction_index,
64 event_index,
65 }
66 }
67
68 pub fn to_ledger_position(self, position: &Position) -> LedgerPosition {
71 let proto = LedgerPosition::default().with_checkpoint(self.checkpoint);
72 match position {
73 Position::Checkpoints { .. } => proto,
74 Position::Transactions { .. } => proto.with_transaction_index(self.transaction_index),
75 Position::Events { .. } => proto
76 .with_transaction_index(self.transaction_index)
77 .with_event_index(self.event_index),
78 }
79 }
80}
81
82#[derive(Clone, Copy, Debug, Eq, PartialEq)]
87pub enum Position {
88 Checkpoints {
89 checkpoint: u64,
90 },
91 Transactions {
92 tx_seq: u64,
93 public_position: LedgerPoint,
94 },
95 Events {
96 tx_seq: u64,
97 event_index: u32,
98 public_position: LedgerPoint,
99 },
100}
101
102impl Position {
103 pub fn public_position(&self) -> LedgerPoint {
106 match *self {
107 Position::Checkpoints { checkpoint } => LedgerPoint::checkpoint_start(checkpoint),
108 Position::Transactions {
109 public_position, ..
110 }
111 | Position::Events {
112 public_position, ..
113 } => public_position,
114 }
115 }
116
117 pub fn item_resume(&self, direction: ScanDirection) -> LedgerPoint {
122 let key = self.public_position();
123 if !direction.is_ascending() {
124 return key;
125 }
126 match self {
129 Position::Checkpoints { .. } => {
130 LedgerPoint::checkpoint_start(key.checkpoint.saturating_add(1))
131 }
132 Position::Transactions { .. } => {
133 LedgerPoint::transaction(key.checkpoint, key.transaction_index.saturating_add(1))
134 }
135 Position::Events { .. } => LedgerPoint::event(
136 key.checkpoint,
137 key.transaction_index,
138 key.event_index.saturating_add(1),
139 ),
140 }
141 }
142}
143
144#[derive(Clone, Copy, Debug, Eq, PartialEq)]
147pub enum CursorKind {
148 Item,
149 Boundary,
150}
151
152impl CursorToken {
153 pub fn item(position: Position) -> Self {
154 Self {
155 kind: CursorKind::Item,
156 position,
157 }
158 }
159
160 pub fn boundary(position: Position) -> Self {
161 Self {
162 kind: CursorKind::Boundary,
163 position,
164 }
165 }
166
167 pub fn encode(&self) -> Bytes {
168 grpc::CursorToken::from(self).encode_to_vec().into()
169 }
170
171 pub fn decode(bytes: &[u8]) -> anyhow::Result<Self> {
172 Self::try_from(grpc::CursorToken::decode(bytes)?)
173 }
174}
175
176impl CursorKind {
177 fn to_proto(self) -> grpc::CursorKind {
178 match self {
179 CursorKind::Item => grpc::CursorKind::Item,
180 CursorKind::Boundary => grpc::CursorKind::Boundary,
181 }
182 }
183
184 fn from_proto(value: grpc::CursorKind) -> Option<Self> {
185 match value {
186 grpc::CursorKind::Item => Some(CursorKind::Item),
187 grpc::CursorKind::Boundary => Some(CursorKind::Boundary),
188 grpc::CursorKind::Unspecified => None,
189 }
190 }
191}
192
193impl From<LedgerPoint> for grpc::PublicPosition {
194 fn from(point: LedgerPoint) -> Self {
195 Self {
196 checkpoint: point.checkpoint,
197 transaction_index: point.transaction_index,
198 event_index: point.event_index,
199 }
200 }
201}
202
203impl From<grpc::PublicPosition> for LedgerPoint {
204 fn from(position: grpc::PublicPosition) -> Self {
205 Self {
206 checkpoint: position.checkpoint,
207 transaction_index: position.transaction_index,
208 event_index: position.event_index,
209 }
210 }
211}
212
213impl From<&CursorToken> for grpc::CursorToken {
214 fn from(cursor: &CursorToken) -> Self {
215 let (position, public_position) = match cursor.position {
216 Position::Checkpoints { checkpoint } => (
217 grpc::cursor_token::Position::Checkpoints(grpc::CheckpointsPosition {
218 checkpoint: Some(checkpoint),
219 }),
220 None,
221 ),
222 Position::Transactions {
223 tx_seq,
224 public_position,
225 } => (
226 grpc::cursor_token::Position::Transactions(grpc::TransactionsPosition {
227 tx_seq: Some(tx_seq),
228 }),
229 Some(LedgerPoint::transaction(
231 public_position.checkpoint,
232 public_position.transaction_index,
233 )),
234 ),
235 Position::Events {
236 tx_seq,
237 event_index,
238 public_position,
239 } => (
240 grpc::cursor_token::Position::Events(grpc::EventsPosition {
241 tx_seq: Some(tx_seq),
242 event_index: Some(event_index),
243 }),
244 Some(public_position),
245 ),
246 };
247 Self {
248 kind: cursor.kind.to_proto() as i32,
249 public_position: public_position.map(Into::into),
250 position: Some(position),
251 }
252 }
253}
254
255impl TryFrom<grpc::CursorToken> for CursorToken {
260 type Error = anyhow::Error;
261
262 fn try_from(proto: grpc::CursorToken) -> anyhow::Result<Self> {
263 let kind = grpc::CursorKind::try_from(proto.kind)
264 .ok()
265 .and_then(CursorKind::from_proto)
266 .with_context(|| format!("unknown cursor kind: {}", proto.kind))?;
267 let public_position = || -> anyhow::Result<LedgerPoint> {
268 proto
269 .public_position
270 .map(Into::into)
271 .context("cursor missing public_position")
272 };
273 let position = match proto.position.context("cursor missing position")? {
274 grpc::cursor_token::Position::Checkpoints(position) => Position::Checkpoints {
275 checkpoint: position.checkpoint.context("cursor missing checkpoint")?,
276 },
277 grpc::cursor_token::Position::Transactions(position) => {
278 let tx_seq = position.tx_seq.context("cursor missing tx_seq")?;
279 let point = public_position()?;
280 Position::Transactions {
281 tx_seq,
282 public_position: LedgerPoint::transaction(
283 point.checkpoint,
284 point.transaction_index,
285 ),
286 }
287 }
288 grpc::cursor_token::Position::Events(position) => Position::Events {
289 tx_seq: position.tx_seq.context("cursor missing tx_seq")?,
290 event_index: position.event_index.context("cursor missing event_index")?,
291 public_position: public_position()?,
292 },
293 };
294 Ok(Self { kind, position })
295 }
296}
297
298#[cfg(test)]
299mod tests {
300 use super::*;
301
302 const PUBLIC: LedgerPoint = LedgerPoint {
303 checkpoint: 11,
304 transaction_index: 2,
305 event_index: 13,
306 };
307
308 fn token_bytes(
309 public_position: Option<grpc::PublicPosition>,
310 position: grpc::cursor_token::Position,
311 ) -> Vec<u8> {
312 grpc::CursorToken {
313 kind: grpc::CursorKind::Item as i32,
314 public_position,
315 position: Some(position),
316 }
317 .encode_to_vec()
318 }
319
320 #[test]
321 fn roundtrips_all_position_variants() {
322 for token in [
323 CursorToken::item(Position::Checkpoints { checkpoint: 7 }),
324 CursorToken::boundary(Position::Transactions {
325 tx_seq: 10,
326 public_position: LedgerPoint::transaction(9, 4),
327 }),
328 CursorToken::item(Position::Events {
329 tx_seq: 12,
330 event_index: 13,
331 public_position: PUBLIC,
332 }),
333 CursorToken::boundary(Position::Events {
335 tx_seq: 0,
336 event_index: 0,
337 public_position: LedgerPoint::GENESIS,
338 }),
339 ] {
340 let bytes = token.encode();
341 let decoded = CursorToken::decode(&bytes).unwrap();
342 assert_eq!(decoded, token);
343 assert_eq!(decoded.encode(), bytes, "re-encoding keeps the bytes");
344 }
345 }
346
347 #[test]
350 fn decodes_cursors_carrying_a_checkpoint_label() {
351 let cases: [(&[u8], CursorToken, &[u8]); 2] = [
352 (
353 &[
356 0x28, 0x01, 0x3a, 0x04, 0x08, 0x2a, 0x10, 0x07, 0x4a, 0x04, 0x08, 0x2a, 0x10,
357 0x03,
358 ],
359 CursorToken::item(Position::Transactions {
360 tx_seq: 7,
361 public_position: LedgerPoint::transaction(42, 3),
362 }),
363 &[
364 0x28, 0x01, 0x3a, 0x02, 0x10, 0x07, 0x4a, 0x04, 0x08, 0x2a, 0x10, 0x03,
365 ],
366 ),
367 (
368 &[
371 0x28, 0x01, 0x42, 0x06, 0x08, 0x2a, 0x10, 0x07, 0x18, 0x01, 0x4a, 0x06, 0x08,
372 0x2a, 0x10, 0x03, 0x18, 0x01,
373 ],
374 CursorToken::item(Position::Events {
375 tx_seq: 7,
376 event_index: 1,
377 public_position: LedgerPoint::event(42, 3, 1),
378 }),
379 &[
380 0x28, 0x01, 0x42, 0x04, 0x10, 0x07, 0x18, 0x01, 0x4a, 0x06, 0x08, 0x2a, 0x10,
381 0x03, 0x18, 0x01,
382 ],
383 ),
384 ];
385 for (labelled, expected, unlabelled) in cases {
386 let token = CursorToken::decode(labelled).unwrap();
387 assert_eq!(token, expected);
388 assert_eq!(token.encode().as_ref(), unlabelled);
389 }
390 }
391
392 #[test]
395 fn transaction_cursors_drop_a_public_event_index() {
396 for (kind, token) in [
397 (0x01, CursorToken::item as fn(Position) -> CursorToken),
398 (0x02, CursorToken::boundary),
399 ] {
400 let forged: &[u8] = &[
403 0x28, kind, 0x3a, 0x02, 0x10, 0x2a, 0x4a, 0x06, 0x08, 0x07, 0x10, 0x03, 0x18, 0x09,
404 ];
405 let projected: &[u8] = &[
407 0x28, kind, 0x3a, 0x02, 0x10, 0x2a, 0x4a, 0x04, 0x08, 0x07, 0x10, 0x03,
408 ];
409 let decoded = CursorToken::decode(forged).unwrap();
410 assert_eq!(
411 decoded,
412 token(Position::Transactions {
413 tx_seq: 42,
414 public_position: LedgerPoint::transaction(7, 3),
415 })
416 );
417 assert_eq!(decoded.encode().as_ref(), projected);
418 let minted = token(Position::Transactions {
419 tx_seq: 42,
420 public_position: LedgerPoint::event(7, 3, 9),
421 });
422 assert_eq!(minted.encode().as_ref(), projected);
423 }
424
425 let event = CursorToken::item(Position::Events {
426 tx_seq: 42,
427 event_index: 9,
428 public_position: LedgerPoint::event(7, 3, 9),
429 });
430 assert_eq!(CursorToken::decode(&event.encode()).unwrap(), event);
431 }
432
433 #[test]
434 fn rejects_transaction_and_event_cursors_without_a_public_position() {
435 let transactions = token_bytes(
436 None,
437 grpc::cursor_token::Position::Transactions(grpc::TransactionsPosition {
438 tx_seq: Some(10),
439 }),
440 );
441 assert!(CursorToken::decode(&transactions).is_err());
442
443 let events = token_bytes(
444 None,
445 grpc::cursor_token::Position::Events(grpc::EventsPosition {
446 tx_seq: Some(10),
447 event_index: Some(3),
448 }),
449 );
450 assert!(CursorToken::decode(&events).is_err());
451 }
452
453 #[test]
455 fn checkpoint_cursors_ignore_a_public_position() {
456 let bytes = token_bytes(
457 Some(PUBLIC.into()),
458 grpc::cursor_token::Position::Checkpoints(grpc::CheckpointsPosition {
459 checkpoint: Some(5),
460 }),
461 );
462 let token = CursorToken::decode(&bytes).unwrap();
463 assert_eq!(
464 token,
465 CursorToken::item(Position::Checkpoints { checkpoint: 5 })
466 );
467 }
468
469 #[test]
471 fn rejects_tokens_in_the_reserved_schema() {
472 let bytes = [0x08, 0x02, 0x10, 0x01, 0x18, 0x2a, 0x20, 0x07];
474 assert!(CursorToken::decode(&bytes).is_err());
475 }
476
477 #[test]
478 fn rejects_unspecified_kind() {
479 let bytes = grpc::CursorToken {
480 kind: grpc::CursorKind::Unspecified as i32,
481 public_position: Some(PUBLIC.into()),
482 position: Some(grpc::cursor_token::Position::Transactions(
483 grpc::TransactionsPosition { tx_seq: Some(2) },
484 )),
485 }
486 .encode_to_vec();
487
488 assert!(CursorToken::decode(&bytes).is_err());
489 }
490
491 #[test]
492 fn rejects_missing_position() {
493 let bytes = grpc::CursorToken {
494 kind: grpc::CursorKind::Item as i32,
495 public_position: Some(grpc::PublicPosition::default()),
496 position: None,
497 }
498 .encode_to_vec();
499
500 assert!(CursorToken::decode(&bytes).is_err());
501 }
502
503 #[test]
504 fn rejects_missing_inner_fields() {
505 let events = token_bytes(
506 Some(PUBLIC.into()),
507 grpc::cursor_token::Position::Events(grpc::EventsPosition {
508 tx_seq: Some(2),
509 event_index: None,
510 }),
511 );
512 assert!(CursorToken::decode(&events).is_err());
513
514 let checkpoints = token_bytes(
515 None,
516 grpc::cursor_token::Position::Checkpoints(grpc::CheckpointsPosition {
517 checkpoint: None,
518 }),
519 );
520 assert!(CursorToken::decode(&checkpoints).is_err());
521 }
522
523 #[test]
524 fn item_resume_is_above_the_key_ascending_and_the_key_descending() {
525 for (item, key, above) in [
526 (
527 Position::Checkpoints { checkpoint: 4 },
528 LedgerPoint::checkpoint_start(4),
529 LedgerPoint::checkpoint_start(5),
530 ),
531 (
532 Position::Transactions {
533 tx_seq: 9,
534 public_position: LedgerPoint::transaction(4, 2),
535 },
536 LedgerPoint::transaction(4, 2),
537 LedgerPoint::transaction(4, 3),
538 ),
539 (
540 Position::Events {
541 tx_seq: 9,
542 event_index: 1,
543 public_position: LedgerPoint::event(4, 2, 1),
544 },
545 LedgerPoint::event(4, 2, 1),
546 LedgerPoint::event(4, 2, 2),
547 ),
548 ] {
549 assert_eq!(item.item_resume(ScanDirection::Ascending), above);
550 assert_eq!(item.item_resume(ScanDirection::Descending), key);
551 }
552 }
553
554 #[test]
556 fn to_ledger_position_sets_only_the_lane_coordinates() {
557 let point = LedgerPoint::event(4, 2, 1);
558 let checkpoint = point.to_ledger_position(&Position::Checkpoints { checkpoint: 0 });
559 assert_eq!(
560 (
561 checkpoint.checkpoint,
562 checkpoint.transaction_index,
563 checkpoint.event_index
564 ),
565 (Some(4), None, None)
566 );
567 let transaction = point.to_ledger_position(&Position::Transactions {
568 tx_seq: 0,
569 public_position: LedgerPoint::GENESIS,
570 });
571 assert_eq!(
572 (
573 transaction.checkpoint,
574 transaction.transaction_index,
575 transaction.event_index
576 ),
577 (Some(4), Some(2), None)
578 );
579 let event = point.to_ledger_position(&Position::Events {
580 tx_seq: 0,
581 event_index: 0,
582 public_position: LedgerPoint::GENESIS,
583 });
584 assert_eq!(
585 (event.checkpoint, event.transaction_index, event.event_index),
586 (Some(4), Some(2), Some(1))
587 );
588 }
589}