sui_rpc/client/ledger_streams/adapter/
mod.rs1use std::future::Future;
2use std::pin::Pin;
3
4use prost::Message;
5use prost::bytes::Bytes;
6use tonic::Request;
7use tonic::Status;
8use tonic::codegen::BoxStream;
9
10use super::super::Client;
11use super::super::Result;
12use super::observability::LedgerStreamFamily;
13use crate::proto::sui::rpc::v2::Ordering;
14use crate::proto::sui::rpc::v2::QueryEnd;
15use crate::proto::sui::rpc::v2::QueryOptions;
16use crate::proto::sui::rpc::v2::Watermark;
17
18mod checkpoint;
19mod event;
20mod progress;
21mod transaction;
22
23pub(super) use super::types::Position;
24pub(super) use checkpoint::CheckpointAdapter;
25pub(super) use event::EventAdapter;
26pub(super) use progress::BoundFields;
27pub(super) use progress::KeyGranularity;
28pub(super) use progress::LedgerFrame;
29pub(super) use progress::Progress;
30pub(super) use progress::RecoveryGap;
31pub(super) use progress::missing_cursor_position;
32pub(super) use transaction::TransactionAdapter;
33
34pub(super) type RpcFuture<T> = Pin<Box<dyn Future<Output = Result<BoxStream<T>>> + Send + 'static>>;
35
36pub(super) trait SubscriptionAdapter: Send + Sync + 'static {
38 const FAMILY: LedgerStreamFamily;
39 const GRANULARITY: KeyGranularity;
41
42 type Item: Send + 'static;
43 type Cursor: Clone + Send + 'static;
45 type Output: Send + 'static;
46 type ListRequest: Clone + Send + Sync + 'static;
47 type ListResponse: Send + 'static;
48 type SubscribeRequest: Clone + Send + 'static;
49 type SubscribeResponse: Message + Send + 'static;
50
51 fn options(request: &Self::ListRequest) -> Option<&QueryOptions>;
53 fn options_mut(request: &mut Self::ListRequest) -> &mut QueryOptions;
55 fn start_checkpoint(request: &Self::ListRequest) -> Option<u64>;
57 fn end_checkpoint(request: &Self::ListRequest) -> Option<u64>;
59 fn set_start_fields(request: &mut Self::ListRequest, fields: BoundFields);
61 fn set_end_fields(request: &mut Self::ListRequest, fields: BoundFields);
63 fn validate_checkpoint_bound(
65 _request: &Self::ListRequest,
66 _direction: ListScanDirection,
67 _checkpoint: Option<u64>,
68 ) -> Result<()> {
69 Ok(())
70 }
71 fn cursor_bytes(cursor: &Self::Cursor) -> Option<Bytes>;
73 fn list_cursor(cursor: Bytes) -> Self::Cursor;
75 fn extract_metadata(
77 response: &Self::ListResponse,
78 ) -> (bool, Option<&Watermark>, Option<&QueryEnd>);
79 fn into_list_item(response: Self::ListResponse) -> Option<Self::Item>;
81 fn item_required(_request: &Self::SubscribeRequest) -> bool {
83 false
84 }
85 fn parse_live(
87 response: Self::SubscribeResponse,
88 item_required: bool,
89 ) -> Result<LedgerFrame<Self::Item, Self::Cursor>>;
90 fn into_output(item: Option<Self::Item>, progress: Progress<Self::Cursor>) -> Self::Output;
92 fn dispatch_list(
93 client: Client,
94 request: Request<Self::ListRequest>,
95 ) -> RpcFuture<Self::ListResponse>;
96 fn dispatch_subscribe(
97 client: Client,
98 request: Request<Self::SubscribeRequest>,
99 ) -> RpcFuture<Self::SubscribeResponse>;
100}
101
102pub(super) fn set_start<A: SubscriptionAdapter>(
105 request: &mut A::ListRequest,
106 position: Position,
107 cursor: Option<Bytes>,
108) {
109 A::set_start_fields(request, position.start_fields());
110 A::options_mut(request).after = cursor;
111}
112
113pub(super) fn set_end<A: SubscriptionAdapter>(
116 request: &mut A::ListRequest,
117 position: Position,
118 cursor: Option<Bytes>,
119) -> Result<()> {
120 A::set_end_fields(request, position.end_fields()?);
121 A::options_mut(request).before = cursor;
122 Ok(())
123}
124
125fn parse_opaque_live_frame<I>(
127 item: Option<I>,
128 watermark: Option<Watermark>,
129 granularity: KeyGranularity,
130) -> Result<LedgerFrame<I, Bytes>> {
131 let watermark = watermark
132 .ok_or_else(|| Status::data_loss("subscription frame is missing its watermark"))?;
133 let position = watermark
134 .cursor_position
135 .as_ref()
136 .map(|position| granularity.position(position))
137 .ok_or_else(|| missing_cursor_position("subscription"))?;
138 let cursor = watermark
139 .cursor
140 .ok_or_else(|| Status::data_loss("subscription watermark is missing its cursor"))?;
141 let progress = Progress {
142 position,
143 cursor,
144 checkpoint: watermark.checkpoint,
145 };
146 LedgerFrame::new(item, progress, granularity)
147}
148
149#[derive(Clone, Copy, Debug, PartialEq, Eq)]
150pub(super) enum ListScanDirection {
151 Ascending,
152 Descending,
153}
154
155impl ListScanDirection {
156 pub(super) fn from_request<A: SubscriptionAdapter>(request: &A::ListRequest) -> Result<Self> {
157 match A::options(request).and_then(|options| options.ordering) {
158 None => Ok(Self::Ascending),
159 Some(ordering) => match Ordering::try_from(ordering) {
160 Ok(Ordering::Ascending) => Ok(Self::Ascending),
161 Ok(Ordering::Descending) => Ok(Self::Descending),
162 Err(_) => Err(Status::invalid_argument("List ordering is unknown")),
163 },
164 }
165 }
166
167 pub(super) fn beyond(self, next: Position, previous: Position) -> bool {
169 match self {
170 Self::Ascending => next > previous,
171 Self::Descending => next < previous,
172 }
173 }
174
175 pub(super) fn set_resume<A: SubscriptionAdapter>(
178 self,
179 request: &mut A::ListRequest,
180 progress: &Progress<Bytes>,
181 ) -> Result<()> {
182 match self {
183 Self::Ascending => {
184 set_start::<A>(request, progress.position, Some(progress.cursor.clone()));
185 Ok(())
186 }
187 Self::Descending => {
188 set_end::<A>(request, progress.position, Some(progress.cursor.clone()))
189 }
190 }
191 }
192
193 pub(super) fn has_resume_cursor(self, options: &QueryOptions) -> bool {
195 match self {
196 Self::Ascending => options.after.is_some(),
197 Self::Descending => options.before.is_some(),
198 }
199 }
200}