Skip to main content

sui_rpc/client/ledger_streams/
facade.rs

1use futures::Stream;
2
3use super::super::Client;
4use super::super::Result;
5use super::adapter::CheckpointAdapter;
6use super::adapter::EventAdapter;
7use super::adapter::SubscriptionAdapter;
8use super::adapter::TransactionAdapter;
9use super::list::ListDriver;
10use super::stream::Driver;
11use super::stream::Start;
12use super::types::CheckpointStreamFrame;
13use super::types::CheckpointStreamRequest;
14use super::types::CheckpointStreamStart;
15use super::types::EventStreamFrame;
16use super::types::EventStreamRequest;
17use super::types::EventStreamStart;
18use super::types::LedgerStreamConfig;
19use super::types::ListConfig;
20use super::types::TransactionStreamFrame;
21use super::types::TransactionStreamRequest;
22use super::types::TransactionStreamStart;
23use crate::proto::sui::rpc::v2::ListCheckpointsRequest;
24use crate::proto::sui::rpc::v2::ListCheckpointsResponse;
25use crate::proto::sui::rpc::v2::ListEventsRequest;
26use crate::proto::sui::rpc::v2::ListEventsResponse;
27use crate::proto::sui::rpc::v2::ListTransactionsRequest;
28use crate::proto::sui::rpc::v2::ListTransactionsResponse;
29use crate::proto::sui::rpc::v2::SubscribeCheckpointsRequest;
30use crate::proto::sui::rpc::v2::SubscribeEventsRequest;
31use crate::proto::sui::rpc::v2::SubscribeTransactionsRequest;
32
33impl Client {
34    /// Paginates `ListCheckpoints` requests into a stream of raw response pages.
35    ///
36    /// Automatically follows `ItemLimit` and `ScanLimit` pagination until reaching the
37    /// request's end bound or the ledger tip, continuing each page from the last frame's
38    /// `Watermark.cursor_position` and `Watermark.cursor`. Every frame must carry
39    /// `cursor_position`.
40    pub fn list_checkpoints(
41        &self,
42        request: ListCheckpointsRequest,
43    ) -> impl Stream<Item = Result<ListCheckpointsResponse>> + Send + 'static {
44        self.list_checkpoints_with_config(request, ListConfig::default())
45    }
46    /// Performs [`Client::list_checkpoints`] using `config`.
47    pub fn list_checkpoints_with_config(
48        &self,
49        request: ListCheckpointsRequest,
50        config: ListConfig,
51    ) -> impl Stream<Item = Result<ListCheckpointsResponse>> + Send + 'static {
52        list_stream(ListDriver::<CheckpointAdapter>::new(
53            self.clone(),
54            request,
55            config.into_stream_config(),
56        ))
57    }
58
59    /// Streams checkpoints indefinitely, automatically retrying transient errors.
60    ///
61    /// To resume after a previous checkpoint, pass `cursor + 1` to
62    /// [`CheckpointStreamStart::Checkpoint`].
63    ///
64    /// For a finite read that stops at a bound, use [`Client::list_checkpoints`].
65    pub fn stream_checkpoints(
66        &self,
67        request: CheckpointStreamRequest,
68    ) -> impl Stream<Item = Result<CheckpointStreamFrame>> + Send + 'static {
69        self.stream_checkpoints_with_config(request, LedgerStreamConfig::default())
70    }
71
72    /// Performs [`Client::stream_checkpoints`] using `config`.
73    pub fn stream_checkpoints_with_config(
74        &self,
75        request: CheckpointStreamRequest,
76        config: LedgerStreamConfig,
77    ) -> impl Stream<Item = Result<CheckpointStreamFrame>> + Send + 'static {
78        let subscribe_payload = SubscribeCheckpointsRequest {
79            read_mask: request.read_mask.clone(),
80            filter: request.filter.clone(),
81        };
82        let list_template = ListCheckpointsRequest {
83            read_mask: request.read_mask,
84            filter: request.filter,
85            start_checkpoint: None,
86            end_checkpoint: None,
87            options: None,
88        };
89        let start = match request.start {
90            CheckpointStreamStart::Tip => Start::Tip,
91            CheckpointStreamStart::Checkpoint(checkpoint) => Start::Checkpoint(checkpoint),
92        };
93        resumable_stream(Driver::<CheckpointAdapter>::new_stream(
94            self.clone(),
95            subscribe_payload,
96            list_template,
97            start,
98            request.delivery,
99            config,
100        ))
101    }
102
103    /// Paginates `ListTransactions` requests into a stream of raw response pages.
104    ///
105    /// Automatically follows `ItemLimit` and `ScanLimit` pagination until reaching the
106    /// request's end bound or the ledger tip, continuing each page from the last frame's
107    /// `Watermark.cursor_position` and `Watermark.cursor`. Every frame must carry
108    /// `cursor_position`.
109    pub fn list_transactions(
110        &self,
111        request: ListTransactionsRequest,
112    ) -> impl Stream<Item = Result<ListTransactionsResponse>> + Send + 'static {
113        self.list_transactions_with_config(request, ListConfig::default())
114    }
115    /// Performs [`Client::list_transactions`] using `config`.
116    pub fn list_transactions_with_config(
117        &self,
118        request: ListTransactionsRequest,
119        config: ListConfig,
120    ) -> impl Stream<Item = Result<ListTransactionsResponse>> + Send + 'static {
121        list_stream(ListDriver::<TransactionAdapter>::new(
122            self.clone(),
123            request,
124            config.into_stream_config(),
125        ))
126    }
127
128    /// Streams transactions indefinitely, automatically retrying transient errors.
129    ///
130    /// To resume from a previous frame, pass `frame.cursor` and `frame.position` to
131    /// [`TransactionStreamStart::ResumeAt`].
132    ///
133    /// For a finite read that stops at a bound, use [`Client::list_transactions`].
134    pub fn stream_transactions(
135        &self,
136        request: TransactionStreamRequest,
137    ) -> impl Stream<Item = Result<TransactionStreamFrame>> + Send + 'static {
138        self.stream_transactions_with_config(request, LedgerStreamConfig::default())
139    }
140
141    /// Performs [`Client::stream_transactions`] using `config`.
142    pub fn stream_transactions_with_config(
143        &self,
144        request: TransactionStreamRequest,
145        config: LedgerStreamConfig,
146    ) -> impl Stream<Item = Result<TransactionStreamFrame>> + Send + 'static {
147        let subscribe_payload = SubscribeTransactionsRequest {
148            read_mask: request.read_mask.clone(),
149            filter: request.filter.clone(),
150        };
151        let list_template = ListTransactionsRequest {
152            read_mask: request.read_mask,
153            filter: request.filter,
154            start_checkpoint: None,
155            end_checkpoint: None,
156            options: None,
157            start_transaction_index: None,
158            end_transaction_index: None,
159        };
160        #[allow(deprecated)]
161        let start = match request.start {
162            TransactionStreamStart::Tip => Start::Tip,
163            TransactionStreamStart::Checkpoint(checkpoint) => Start::Checkpoint(checkpoint),
164            TransactionStreamStart::Resume(cursor) => Start::AfterCursor(cursor),
165            TransactionStreamStart::ResumeAt { cursor, position } => {
166                Start::After { cursor, position }
167            }
168        };
169        resumable_stream(Driver::<TransactionAdapter>::new_stream(
170            self.clone(),
171            subscribe_payload,
172            list_template,
173            start,
174            request.delivery,
175            config,
176        ))
177    }
178
179    /// Paginates `ListEvents` requests into a stream of raw response pages.
180    ///
181    /// Automatically follows `ItemLimit` and `ScanLimit` pagination until reaching the
182    /// request's end bound or the ledger tip, continuing each page from the last frame's
183    /// `Watermark.cursor_position` and `Watermark.cursor`. Every frame must carry
184    /// `cursor_position`.
185    pub fn list_events(
186        &self,
187        request: ListEventsRequest,
188    ) -> impl Stream<Item = Result<ListEventsResponse>> + Send + 'static {
189        self.list_events_with_config(request, ListConfig::default())
190    }
191    /// Performs [`Client::list_events`] using `config`.
192    pub fn list_events_with_config(
193        &self,
194        request: ListEventsRequest,
195        config: ListConfig,
196    ) -> impl Stream<Item = Result<ListEventsResponse>> + Send + 'static {
197        list_stream(ListDriver::<EventAdapter>::new(
198            self.clone(),
199            request,
200            config.into_stream_config(),
201        ))
202    }
203
204    /// Streams events indefinitely, automatically retrying transient errors.
205    ///
206    /// To resume from a previous frame, pass `frame.cursor` and `frame.position` to
207    /// [`EventStreamStart::ResumeAt`].
208    ///
209    /// For a finite read that stops at a bound, use [`Client::list_events`].
210    pub fn stream_events(
211        &self,
212        request: EventStreamRequest,
213    ) -> impl Stream<Item = Result<EventStreamFrame>> + Send + 'static {
214        self.stream_events_with_config(request, LedgerStreamConfig::default())
215    }
216
217    /// Performs [`Client::stream_events`] using `config`.
218    pub fn stream_events_with_config(
219        &self,
220        request: EventStreamRequest,
221        config: LedgerStreamConfig,
222    ) -> impl Stream<Item = Result<EventStreamFrame>> + Send + 'static {
223        let subscribe_payload = SubscribeEventsRequest {
224            read_mask: request.read_mask.clone(),
225            filter: request.filter.clone(),
226        };
227        let list_template = ListEventsRequest {
228            read_mask: request.read_mask,
229            filter: request.filter,
230            start_checkpoint: None,
231            end_checkpoint: None,
232            options: None,
233            start_transaction_index: None,
234            start_event_index: None,
235            end_transaction_index: None,
236            end_event_index: None,
237        };
238        #[allow(deprecated)]
239        let start = match request.start {
240            EventStreamStart::Tip => Start::Tip,
241            EventStreamStart::Checkpoint(checkpoint) => Start::Checkpoint(checkpoint),
242            EventStreamStart::Resume(cursor) => Start::AfterCursor(cursor),
243            EventStreamStart::ResumeAt { cursor, position } => Start::After { cursor, position },
244        };
245        resumable_stream(Driver::<EventAdapter>::new_stream(
246            self.clone(),
247            subscribe_payload,
248            list_template,
249            start,
250            request.delivery,
251            config,
252        ))
253    }
254}
255
256fn list_stream<A: SubscriptionAdapter>(
257    driver: ListDriver<A>,
258) -> impl Stream<Item = Result<A::ListResponse>> + Send + 'static {
259    futures::stream::unfold(driver, |mut driver| async move {
260        driver.next().await.map(|item| (item, driver))
261    })
262}
263
264fn resumable_stream<A: SubscriptionAdapter>(
265    driver: Driver<A>,
266) -> impl Stream<Item = Result<A::Output>> + Send + 'static {
267    futures::stream::unfold(driver, |mut driver| async move {
268        driver.next().await.map(|item| (item, driver))
269    })
270}