sui_rpc/client/ledger_streams/
subscription.rs1use 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 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
29pub(super) struct GapReplay<A: SubscriptionAdapter> {
32 pub(super) list_machine: ListMachine<A>,
33 pub(super) subscription_state: BufferedSubscriptionState<A>,
34 buffered_subscription_frames: VecDeque<LedgerFrame<A::Item, A::Cursor>>,
36 buffered_subscription_items: usize,
39 observability: LedgerStreamObservability,
40}
41
42impl<A: SubscriptionAdapter> GapReplay<A> {
43 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 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 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}