sui_rpc_api/ledger_history/row_placement.rs
1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Placing scan frontiers in public ledger coordinates.
5//!
6//! Every list and subscription frame carries its resume point as a [`LedgerPoint`]
7//! (`Watermark.cursor_position`). Cursors name the same boundaries by `tx_seq`, which stays
8//! private, and carry the public position of their coordinate ([`Position::public_position`]),
9//! so a server places any cursor without a read. A scan frontier is placed by the index row
10//! (checkpoint and position in it) of one transaction the scan already reads: [`RowPlacement`]
11//! says which one, and how its row places the boundary. Checkpoint boundaries, the request's own
12//! fields, and items need no read.
13//!
14//! [`Position::public_position`]: crate::ledger_history::cursor::Position::public_position
15
16use sui_inverted_index::ScanDirection;
17
18use crate::ledger_history::cursor::LedgerPoint;
19use crate::ledger_history::query_options::IntraTxCoordinate;
20
21/// Which transaction's index row places a transaction- or event-lane boundary, and how. A scan
22/// boundary is placed by the transaction on its covered side: ascending, the last transaction
23/// before it (or the transaction it lies inside); descending, the transaction right after it. That
24/// transaction lies in the scanned, indexed part of the ledger whenever the scan reached the
25/// boundary, including a boundary at the indexed tip.
26#[derive(Clone, Copy, Debug, Eq, PartialEq)]
27pub struct RowPlacement {
28 /// The transaction whose row places the boundary.
29 pub tx_seq: u64,
30 /// Whether the boundary lies right after that transaction rather than before one of its
31 /// events.
32 after_transaction: bool,
33 event_index: u32,
34}
35
36impl RowPlacement {
37 /// The placement of the transaction-lane boundary right before `tx_seq`, or `None` for the
38 /// ascending boundary at genesis, which is [`LedgerPoint::GENESIS`]. It is the event-lane
39 /// boundary before the transaction's first event.
40 pub fn transaction_boundary(tx_seq: u64, direction: ScanDirection) -> Option<Self> {
41 Self::event_boundary(IntraTxCoordinate::start_of_tx(tx_seq), direction)
42 }
43
44 /// The placement of the event-lane boundary right before `position`, or `None` for the
45 /// ascending boundary at genesis, which is [`LedgerPoint::GENESIS`].
46 pub fn event_boundary(position: IntraTxCoordinate, direction: ScanDirection) -> Option<Self> {
47 if direction.is_ascending() && position.index == 0 {
48 position.tx_seq.checked_sub(1).map(|tx_seq| Self {
49 tx_seq,
50 after_transaction: true,
51 event_index: 0,
52 })
53 } else {
54 Some(Self {
55 tx_seq: position.tx_seq,
56 after_transaction: false,
57 event_index: position.index,
58 })
59 }
60 }
61
62 /// The boundary, given the checkpoint of [`Self::tx_seq`] and its index in that checkpoint.
63 /// A boundary right after a checkpoint's last transaction keeps that checkpoint, with a
64 /// transaction index past its end.
65 pub fn point(self, checkpoint: u64, transaction_index: u64) -> LedgerPoint {
66 if self.after_transaction {
67 LedgerPoint::transaction(checkpoint, transaction_index + 1)
68 } else {
69 LedgerPoint::event(checkpoint, transaction_index, self.event_index)
70 }
71 }
72}
73
74#[cfg(test)]
75mod tests {
76 use super::*;
77
78 #[test]
79 fn row_placement_reads_the_covered_side() {
80 // Ascending, a transaction boundary is placed after the transaction before it.
81 let placement = RowPlacement::transaction_boundary(10, ScanDirection::Ascending).unwrap();
82 assert_eq!(placement.tx_seq, 9);
83 assert_eq!(placement.point(3, 4), LedgerPoint::transaction(3, 5));
84 assert_eq!(
85 RowPlacement::transaction_boundary(0, ScanDirection::Ascending),
86 None
87 );
88
89 // Descending, before the transaction at the boundary.
90 let placement = RowPlacement::transaction_boundary(10, ScanDirection::Descending).unwrap();
91 assert_eq!(placement.tx_seq, 10);
92 assert_eq!(placement.point(3, 4), LedgerPoint::transaction(3, 4));
93
94 // An event boundary inside a transaction is placed by that transaction either way.
95 let inside = IntraTxCoordinate {
96 tx_seq: 10,
97 index: 2,
98 };
99 for direction in [ScanDirection::Ascending, ScanDirection::Descending] {
100 let placement = RowPlacement::event_boundary(inside, direction).unwrap();
101 assert_eq!(placement.tx_seq, 10);
102 assert_eq!(placement.point(3, 4), LedgerPoint::event(3, 4, 2));
103 }
104
105 // At a transaction's start, ascending reads the transaction before it.
106 let start = IntraTxCoordinate::start_of_tx(10);
107 let placement = RowPlacement::event_boundary(start, ScanDirection::Ascending).unwrap();
108 assert_eq!(placement.tx_seq, 9);
109 assert_eq!(placement.point(3, 4), LedgerPoint::event(3, 5, 0));
110 let placement = RowPlacement::event_boundary(start, ScanDirection::Descending).unwrap();
111 assert_eq!(placement.tx_seq, 10);
112 assert_eq!(placement.point(3, 4), LedgerPoint::event(3, 4, 0));
113 assert_eq!(
114 RowPlacement::event_boundary(
115 IntraTxCoordinate::start_of_tx(0),
116 ScanDirection::Ascending
117 ),
118 None
119 );
120 }
121}