Skip to main content

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}