sui_rpc/client/ledger_streams/types.rs
1use std::fmt;
2use std::num::NonZeroUsize;
3use std::sync::Arc;
4use std::time::Duration;
5
6use super::observability::LedgerStreamEvent;
7use super::observability::LedgerStreamObserver;
8use super::observability::ListEvent;
9use super::observability::ListObserver;
10use crate::proto::sui::rpc::v2::Checkpoint;
11use crate::proto::sui::rpc::v2::Event;
12use crate::proto::sui::rpc::v2::EventFilter;
13use crate::proto::sui::rpc::v2::ExecutedTransaction;
14use crate::proto::sui::rpc::v2::TransactionFilter;
15use prost::bytes::Bytes;
16use prost_types::FieldMask;
17
18/// A point in ledger order, as coordinates `(checkpoint, transaction_index, event_index)`: the
19/// boundary immediately before the item with that key. Transaction positions leave
20/// `event_index` at 0.
21///
22/// Ordering is lexicographic and never contradicts ledger order, so sorting, `max`, and `<` are
23/// safe. `==` compares coordinates: equal coordinates name the same point, but different
24/// coordinates can name one point too. For example, the point after the last of checkpoint
25/// `c`'s `n` transactions is `(c, n)` on that transaction's frame and `(c + 1, 0)` on a following
26/// progress frame.
27#[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq, PartialOrd, Ord)]
28pub struct Position {
29 /// Checkpoint sequence number.
30 pub checkpoint: u64,
31 /// Zero-based index of a transaction within `checkpoint`.
32 pub transaction_index: u64,
33 /// Zero-based index of an event within its transaction's event list.
34 pub event_index: u32,
35}
36
37/// How a stream follows the ledger.
38#[non_exhaustive]
39#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
40pub enum Delivery {
41 /// Follows the tip through SubscriptionService, repairing gaps through List.
42 #[default]
43 Subscribe,
44 /// Follows the ledger via the List APIs, useful on endpoints without SubscriptionService.
45 Poll,
46}
47
48/// Starting position for a checkpoint stream.
49#[non_exhaustive]
50#[derive(Clone, Debug, Default, PartialEq, Eq)]
51pub enum CheckpointStreamStart {
52 /// Begins at the chain tip (live for `Subscribe`, indexed for `Poll`) and emits an initial
53 /// progress frame before subsequent items.
54 #[default]
55 Tip,
56 /// Starts at and includes the checkpoint with this sequence number.
57 Checkpoint(u64),
58}
59
60/// Starting position for a transaction stream.
61#[non_exhaustive]
62#[derive(Clone, Debug, Default, PartialEq, Eq)]
63pub enum TransactionStreamStart {
64 /// Begins at the chain tip (live for `Subscribe`, indexed for `Poll`) and emits an initial
65 /// progress frame before subsequent items.
66 #[default]
67 Tip,
68 /// Starts at and includes transactions from this checkpoint.
69 Checkpoint(u64),
70 /// Starts strictly after this server-validated opaque cursor. The stream lists one match after
71 /// `cursor` to learn a position, delivers that List frame, and continues from it as
72 /// [`Self::ResumeAt`] does, one List request later. A server that rejects `cursor`, as sui 1.84
73 /// and later do for a cursor minted without a position, ends the stream with its error; a List
74 /// frame without `cursor_position` ends it with `DataLoss`.
75 #[deprecated(
76 note = "resume with `ResumeAt`, passing a frame's `cursor` and `position`, which saves a \
77 List request"
78 )]
79 Resume(Bytes),
80 /// Resumes from a previous frame: starts at `position`, which the server-validated opaque
81 /// `cursor` also names. Pass a frame's [`TransactionStreamFrame::cursor`] and
82 /// [`TransactionStreamFrame::position`] unchanged.
83 ResumeAt {
84 /// The frame's opaque cursor.
85 cursor: Bytes,
86 /// The frame's resume point; the stream sends it as the request's start fields.
87 position: Position,
88 },
89}
90
91/// Starting position for an event stream.
92#[non_exhaustive]
93#[derive(Clone, Debug, Default, PartialEq, Eq)]
94pub enum EventStreamStart {
95 /// Begins at the chain tip (live for `Subscribe`, indexed for `Poll`) and emits an initial
96 /// progress frame before subsequent items.
97 #[default]
98 Tip,
99 /// Starts at and includes events from this checkpoint.
100 Checkpoint(u64),
101 /// Starts strictly after this server-validated opaque cursor. The stream lists one match after
102 /// `cursor` to learn a position, delivers that List frame, and continues from it as
103 /// [`Self::ResumeAt`] does, one List request later. A server that rejects `cursor`, as sui 1.84
104 /// and later do for a cursor minted without a position, ends the stream with its error; a List
105 /// frame without `cursor_position` ends it with `DataLoss`.
106 #[deprecated(
107 note = "resume with `ResumeAt`, passing a frame's `cursor` and `position`, which saves a \
108 List request"
109 )]
110 Resume(Bytes),
111 /// Resumes from a previous frame: starts at `position`, which the server-validated opaque
112 /// `cursor` also names. Pass a frame's [`EventStreamFrame::cursor`] and
113 /// [`EventStreamFrame::position`] unchanged.
114 ResumeAt {
115 /// The frame's opaque cursor.
116 cursor: Bytes,
117 /// The frame's resume point; the stream sends it as the request's start fields.
118 position: Position,
119 },
120}
121
122/// Request for a resumable checkpoint stream.
123#[non_exhaustive]
124#[derive(Clone, Debug, Default, PartialEq)]
125pub struct CheckpointStreamRequest {
126 /// Projection applied to both List and Subscribe requests.
127 pub read_mask: Option<FieldMask>,
128 /// Transaction filter applied to checkpoints.
129 pub filter: Option<TransactionFilter>,
130 /// Logical starting position.
131 pub start: CheckpointStreamStart,
132 /// How the stream follows the ledger.
133 pub delivery: Delivery,
134}
135
136impl CheckpointStreamRequest {
137 /// Creates a request with the default start and delivery.
138 pub fn new() -> Self {
139 Self::default()
140 }
141
142 /// Sets the response projection.
143 pub fn with_read_mask(mut self, read_mask: impl Into<FieldMask>) -> Self {
144 self.read_mask = Some(read_mask.into());
145 self
146 }
147
148 /// Sets the transaction filter.
149 pub fn with_filter(mut self, filter: impl Into<TransactionFilter>) -> Self {
150 self.filter = Some(filter.into());
151 self
152 }
153
154 /// Sets the logical starting position.
155 pub fn with_start(mut self, start: impl Into<CheckpointStreamStart>) -> Self {
156 self.start = start.into();
157 self
158 }
159
160 /// Sets how the stream follows the ledger.
161 pub fn with_delivery(mut self, delivery: impl Into<Delivery>) -> Self {
162 self.delivery = delivery.into();
163 self
164 }
165}
166
167/// Request for a resumable transaction stream.
168#[non_exhaustive]
169#[derive(Clone, Debug, Default, PartialEq)]
170pub struct TransactionStreamRequest {
171 /// Projection applied to both List and Subscribe requests.
172 pub read_mask: Option<FieldMask>,
173 /// Filter applied to transactions.
174 pub filter: Option<TransactionFilter>,
175 /// Logical starting position.
176 pub start: TransactionStreamStart,
177 /// How the stream follows the ledger.
178 pub delivery: Delivery,
179}
180
181impl TransactionStreamRequest {
182 /// Creates a request with the default start and delivery.
183 pub fn new() -> Self {
184 Self::default()
185 }
186
187 /// Sets the response projection.
188 pub fn with_read_mask(mut self, read_mask: impl Into<FieldMask>) -> Self {
189 self.read_mask = Some(read_mask.into());
190 self
191 }
192
193 /// Sets the transaction filter.
194 pub fn with_filter(mut self, filter: impl Into<TransactionFilter>) -> Self {
195 self.filter = Some(filter.into());
196 self
197 }
198
199 /// Sets the logical starting position.
200 pub fn with_start(mut self, start: impl Into<TransactionStreamStart>) -> Self {
201 self.start = start.into();
202 self
203 }
204
205 /// Sets how the stream follows the ledger.
206 pub fn with_delivery(mut self, delivery: impl Into<Delivery>) -> Self {
207 self.delivery = delivery.into();
208 self
209 }
210}
211
212/// Request for a resumable event stream.
213#[non_exhaustive]
214#[derive(Clone, Debug, Default, PartialEq)]
215pub struct EventStreamRequest {
216 /// Projection applied to both List and Subscribe requests.
217 pub read_mask: Option<FieldMask>,
218 /// Filter applied to events.
219 pub filter: Option<EventFilter>,
220 /// Logical starting position.
221 pub start: EventStreamStart,
222 /// How the stream follows the ledger.
223 pub delivery: Delivery,
224}
225
226impl EventStreamRequest {
227 /// Creates a request with the default start and delivery.
228 pub fn new() -> Self {
229 Self::default()
230 }
231
232 /// Sets the response projection.
233 pub fn with_read_mask(mut self, read_mask: impl Into<FieldMask>) -> Self {
234 self.read_mask = Some(read_mask.into());
235 self
236 }
237
238 /// Sets the event filter.
239 pub fn with_filter(mut self, filter: impl Into<EventFilter>) -> Self {
240 self.filter = Some(filter.into());
241 self
242 }
243
244 /// Sets the logical starting position.
245 pub fn with_start(mut self, start: impl Into<EventStreamStart>) -> Self {
246 self.start = start.into();
247 self
248 }
249
250 /// Sets how the stream follows the ledger.
251 pub fn with_delivery(mut self, delivery: impl Into<Delivery>) -> Self {
252 self.delivery = delivery.into();
253 self
254 }
255}
256
257/// A checkpoint frame with an optional payload and inclusive restart cursor.
258///
259/// Process `checkpoint` before persisting `cursor`. To resume after this checkpoint,
260/// start the next stream from `CheckpointStreamStart::Checkpoint(cursor + 1)`.
261#[non_exhaustive]
262#[derive(Clone, Debug)]
263pub struct CheckpointStreamFrame {
264 /// The checkpoint payload, or `None` for a progress-only frame.
265 pub checkpoint: Option<Checkpoint>,
266 /// The inclusive checkpoint cursor represented by this frame.
267 pub cursor: u64,
268}
269
270/// A transaction frame with an optional payload and its exclusive restart point.
271///
272/// Process `transaction` before persisting `cursor` and `position`, then resume with
273/// `TransactionStreamStart::ResumeAt { cursor, position }`.
274#[non_exhaustive]
275#[derive(Clone, Debug)]
276pub struct TransactionStreamFrame {
277 /// The executed transaction payload, or `None` for a progress-only frame.
278 pub transaction: Option<ExecutedTransaction>,
279 /// The server's opaque resume cursor as of this frame, passed through verbatim. Never compare
280 /// cursors; compare `position` instead.
281 pub cursor: Bytes,
282 /// The resume point `cursor` names: every matching transaction before it has been delivered.
283 /// On a frame with a transaction, it is that transaction's
284 /// `(checkpoint, transaction_index + 1)`. See [`Position`] for how positions compare.
285 pub position: Position,
286 /// Checkpoint coverage reported with this frame, when known, for progress observability.
287 pub covered_checkpoint: Option<u64>,
288}
289
290/// An event frame with an optional payload and its exclusive restart point.
291///
292/// Process `event` before persisting `cursor` and `position`, then resume with
293/// `EventStreamStart::ResumeAt { cursor, position }`.
294#[non_exhaustive]
295#[derive(Clone, Debug)]
296pub struct EventStreamFrame {
297 /// The event payload, or `None` for a progress-only frame.
298 pub event: Option<Event>,
299 /// The server's opaque resume cursor as of this frame, passed through verbatim. Never compare
300 /// cursors; compare `position` instead.
301 pub cursor: Bytes,
302 /// The resume point `cursor` names: every matching event before it has been delivered. On a
303 /// frame with an event, it is that event's `(checkpoint, transaction_index, event_index + 1)`.
304 /// See [`Position`] for how positions compare.
305 pub position: Position,
306 /// Checkpoint coverage reported with this frame, when known, for progress observability.
307 pub covered_checkpoint: Option<u64>,
308}
309
310/// Polling, retry, buffering, and observability controls for `stream_*` operations.
311///
312/// Client-level timeouts bound individual RPCs, not the total duration of the stream.
313/// Finite `list_*` operations use the retry and observer controls in [`ListConfig`].
314#[non_exhaustive]
315#[derive(Clone)]
316pub struct LedgerStreamConfig {
317 /// Delay between polls when using `Poll` delivery. Must be non-zero.
318 pub ledger_tip_poll_interval: Duration,
319 /// Maximum items per internally built List request.
320 pub list_page_limit: Option<u32>,
321 /// Delay before the first transient retry.
322 pub base_retry_delay: Duration,
323 /// Maximum exponential portion of a retry delay.
324 pub max_retry_delay: Duration,
325 /// Maximum random jitter added to a retry delay.
326 pub retry_jitter: Duration,
327 /// Maximum number of consecutive retries of a transient failure before the stream yields the
328 /// failure as its terminal error. The count restarts each time the stream makes progress, so
329 /// it bounds how long a stream keeps retrying one outage, not how many retries it makes in
330 /// total. `Some(0)` never retries. `None`, the default, retries indefinitely.
331 pub max_consecutive_retries: Option<u32>,
332 /// Maximum number of live subscription items buffered during gap replay before reconnecting.
333 pub max_buffered_live_items: NonZeroUsize,
334 observer: Option<LedgerStreamObserver>,
335}
336
337impl fmt::Debug for LedgerStreamConfig {
338 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
339 formatter
340 .debug_struct("LedgerStreamConfig")
341 .field("ledger_tip_poll_interval", &self.ledger_tip_poll_interval)
342 .field("list_page_limit", &self.list_page_limit)
343 .field("base_retry_delay", &self.base_retry_delay)
344 .field("max_retry_delay", &self.max_retry_delay)
345 .field("retry_jitter", &self.retry_jitter)
346 .field("max_consecutive_retries", &self.max_consecutive_retries)
347 .field("max_buffered_live_items", &self.max_buffered_live_items)
348 .field("observer_configured", &self.observer.is_some())
349 .finish()
350 }
351}
352
353impl Default for LedgerStreamConfig {
354 fn default() -> Self {
355 Self {
356 ledger_tip_poll_interval: Duration::from_secs(1),
357 list_page_limit: None,
358 base_retry_delay: Duration::from_millis(250),
359 max_retry_delay: Duration::from_secs(30),
360 retry_jitter: Duration::from_millis(500),
361 max_consecutive_retries: None,
362 max_buffered_live_items: NonZeroUsize::new(1_024).expect("non-zero constant"),
363 observer: None,
364 }
365 }
366}
367
368impl LedgerStreamConfig {
369 /// Installs the synchronous stream observer, replacing any prior callback.
370 ///
371 /// The callback must return quickly and not block; its panic propagates to the polling task.
372 pub fn with_observer(
373 mut self,
374 observer: impl Fn(LedgerStreamEvent) + Send + Sync + 'static,
375 ) -> Self {
376 self.observer = Some(Arc::new(observer));
377 self
378 }
379
380 pub(super) fn observer(&self) -> Option<LedgerStreamObserver> {
381 self.observer.clone()
382 }
383}
384
385/// Retry and observability controls for finite `list_*` operations.
386#[non_exhaustive]
387#[derive(Clone)]
388pub struct ListConfig {
389 /// Delay before the first transient retry.
390 pub base_retry_delay: Duration,
391 /// Maximum exponential portion of a retry delay.
392 pub max_retry_delay: Duration,
393 /// Maximum random jitter added to a retry delay.
394 pub retry_jitter: Duration,
395 /// Maximum number of consecutive retries of a transient failure before the stream yields the
396 /// failure as its terminal error. The count restarts each time the stream makes progress.
397 /// `Some(0)` never retries, and `None` retries indefinitely. Defaults to
398 /// [`Self::DEFAULT_MAX_CONSECUTIVE_RETRIES`].
399 pub max_consecutive_retries: Option<u32>,
400 observer: Option<ListObserver>,
401}
402
403impl fmt::Debug for ListConfig {
404 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
405 formatter
406 .debug_struct("ListConfig")
407 .field("base_retry_delay", &self.base_retry_delay)
408 .field("max_retry_delay", &self.max_retry_delay)
409 .field("retry_jitter", &self.retry_jitter)
410 .field("max_consecutive_retries", &self.max_consecutive_retries)
411 .field("observer_configured", &self.observer.is_some())
412 .finish()
413 }
414}
415
416impl Default for ListConfig {
417 fn default() -> Self {
418 let stream_defaults = LedgerStreamConfig::default();
419 Self {
420 base_retry_delay: stream_defaults.base_retry_delay,
421 max_retry_delay: stream_defaults.max_retry_delay,
422 retry_jitter: stream_defaults.retry_jitter,
423 max_consecutive_retries: Some(Self::DEFAULT_MAX_CONSECUTIVE_RETRIES),
424 observer: None,
425 }
426 }
427}
428
429impl ListConfig {
430 /// The default [`Self::max_consecutive_retries`]. A `list_*` call is a finite read that a
431 /// caller is usually waiting on, so by default it gives up on an outage after about two
432 /// seconds of backoff instead of waiting for the outage to end. That still covers a replica
433 /// that is a few checkpoints behind.
434 pub const DEFAULT_MAX_CONSECUTIVE_RETRIES: u32 = 3;
435
436 /// Installs the synchronous List observer, replacing any prior callback.
437 ///
438 /// The callback must return quickly and not block; its panic propagates to the polling task.
439 pub fn with_observer(mut self, observer: impl Fn(ListEvent) + Send + Sync + 'static) -> Self {
440 self.observer = Some(Arc::new(observer));
441 self
442 }
443
444 pub(super) fn into_stream_config(self) -> LedgerStreamConfig {
445 let observer: Option<LedgerStreamObserver> = self.observer.map(|list_observer| {
446 Arc::new(move |event: LedgerStreamEvent| {
447 if let Some(list_event) = ListEvent::from_stream_event(event) {
448 list_observer(list_event);
449 }
450 }) as LedgerStreamObserver
451 });
452
453 LedgerStreamConfig {
454 base_retry_delay: self.base_retry_delay,
455 max_retry_delay: self.max_retry_delay,
456 retry_jitter: self.retry_jitter,
457 max_consecutive_retries: self.max_consecutive_retries,
458 observer,
459 ..LedgerStreamConfig::default()
460 }
461 }
462}