Skip to main content

sui_rpc/client/ledger_streams/
subscription.rs

1use std::collections::VecDeque;
2
3use tonic::Status;
4use tonic::codegen::BoxStream;
5
6use super::super::Result;
7use super::adapter::LedgerFrame;
8use super::adapter::ListScanDirection;
9use super::adapter::Progress;
10use super::adapter::SubscriptionAdapter;
11use super::list::ListMachine;
12use super::observability::LedgerStreamEvent;
13use super::observability::LedgerStreamObservability;
14use super::observability::LedgerStreamStage;
15use super::types::LedgerStreamConfig;
16
17pub(super) struct LiveSubscription<A: SubscriptionAdapter> {
18    pub(super) stream: BoxStream<A::SubscribeResponse>,
19    /// The subscription's furthest position and coverage, which its frames must not contradict.
20    pub(super) furthest: Progress<A::Cursor>,
21}
22
23pub(super) enum BufferedSubscriptionState<A: SubscriptionAdapter> {
24    Active(LiveSubscription<A>),
25    Failed(Status),
26    DroppedAtBufferLimit,
27}
28
29/// Lists the interval between committed progress and a new subscription's first frame while
30/// buffering that subscription's frames.
31pub(super) struct GapReplay<A: SubscriptionAdapter> {
32    pub(super) list_machine: ListMachine<A>,
33    pub(super) subscription_state: BufferedSubscriptionState<A>,
34    /// Item frames retain payloads; adjacent progress-only frames coalesce once per contiguous run.
35    buffered_subscription_frames: VecDeque<LedgerFrame<A::Item, A::Cursor>>,
36    /// Number of payload-bearing frames currently buffered, bounded by `max_buffered_live_items`
37    /// (empty progress-only frames do not count toward this limit).
38    buffered_subscription_items: usize,
39    observability: LedgerStreamObservability,
40}
41
42impl<A: SubscriptionAdapter> GapReplay<A> {
43    /// Starts buffering `live` with its first frame, which the replay ends before.
44    pub(super) fn new(
45        list_machine: ListMachine<A>,
46        live: LiveSubscription<A>,
47        first: LedgerFrame<A::Item, A::Cursor>,
48        config: &LedgerStreamConfig,
49    ) -> Self {
50        let observability = list_machine.observability.clone();
51        let mut gap = Self {
52            list_machine,
53            subscription_state: BufferedSubscriptionState::Active(live),
54            buffered_subscription_frames: VecDeque::new(),
55            buffered_subscription_items: 0,
56            observability,
57        };
58        gap.retain_frame(first, config);
59        gap
60    }
61
62    /// Buffers a frame of the active subscription, dropping the subscription once the buffer holds
63    /// `max_buffered_live_items` items.
64    fn retain_frame(
65        &mut self,
66        frame: LedgerFrame<A::Item, A::Cursor>,
67        config: &LedgerStreamConfig,
68    ) {
69        if frame.item.is_none()
70            && let Some(deferred_tail) = self.buffered_subscription_frames.back_mut()
71            && deferred_tail.item.is_none()
72        {
73            deferred_tail.progress = frame.progress;
74            return;
75        }
76
77        if frame.item.is_some() {
78            self.buffered_subscription_items = self.buffered_subscription_items.saturating_add(1);
79        }
80        self.buffered_subscription_frames.push_back(frame);
81        if self.buffered_subscription_items >= config.max_buffered_live_items.get() {
82            self.subscription_state = BufferedSubscriptionState::DroppedAtBufferLimit;
83            let buffered_items = self.buffered_subscription_items;
84            let limit = config.max_buffered_live_items.get();
85            self.observability
86                .emit(|| LedgerStreamEvent::SubscriptionBufferLimitReached {
87                    family: A::FAMILY,
88                    buffered_items,
89                    limit,
90                });
91        }
92    }
93
94    /// Returns whether a valid buffered frame advanced subscription progress, controlling retry
95    /// backoff reset.
96    pub(super) fn buffer_subscription_result(
97        &mut self,
98        result: Option<Result<A::SubscribeResponse>>,
99        item_required: bool,
100        config: &LedgerStreamConfig,
101    ) -> bool {
102        let BufferedSubscriptionState::Active(live) = &mut self.subscription_state else {
103            return false;
104        };
105        let frame = match result {
106            Some(Ok(response)) => match A::parse_live(response, item_required) {
107                Ok(frame) => frame,
108                Err(status) => {
109                    self.subscription_state = BufferedSubscriptionState::Failed(status);
110                    return false;
111                }
112            },
113            Some(Err(status)) => {
114                self.observability
115                    .emit(|| LedgerStreamEvent::SubscriptionStreamInterrupted {
116                        family: A::FAMILY,
117                        stage: LedgerStreamStage::GapRecovery,
118                        status: status.clone(),
119                    });
120                self.subscription_state = BufferedSubscriptionState::Failed(status);
121                return false;
122            }
123            None => {
124                let status = Status::unavailable("subscription stream ended unexpectedly");
125                self.observability
126                    .emit(|| LedgerStreamEvent::SubscriptionStreamInterrupted {
127                        family: A::FAMILY,
128                        stage: LedgerStreamStage::GapRecovery,
129                        status: status.clone(),
130                    });
131                self.subscription_state = BufferedSubscriptionState::Failed(status);
132                return false;
133            }
134        };
135
136        match live.furthest.advance(
137            &frame.progress,
138            ListScanDirection::Ascending,
139            frame.item.is_some(),
140            "subscription",
141        ) {
142            Err(status) => {
143                self.subscription_state = BufferedSubscriptionState::Failed(status);
144                false
145            }
146            Ok((false, false)) => false,
147            Ok(_) => {
148                self.retain_frame(frame, config);
149                true
150            }
151        }
152    }
153
154    pub(super) fn into_buffered_subscription_drain(self) -> BufferedSubscriptionDrain<A> {
155        BufferedSubscriptionDrain {
156            subscription_state: self.subscription_state,
157            buffered_subscription_frames: self.buffered_subscription_frames,
158        }
159    }
160}
161
162pub(super) struct BufferedSubscriptionDrain<A: SubscriptionAdapter> {
163    pub(super) subscription_state: BufferedSubscriptionState<A>,
164    pub(super) buffered_subscription_frames: VecDeque<LedgerFrame<A::Item, A::Cursor>>,
165}