1use std::collections::{HashSet, VecDeque};
4
5use crate::errors::{ForeignSessionError, GapFillError, ProtocolError};
6use crate::msp::{ViewGapParams, ViewPageDirection, ViewPageParams};
7
8const PAGE_LIMIT: u32 = 200;
9
10#[derive(Debug, Clone, PartialEq, Eq)]
16pub struct GapEvent<T> {
17 session_id: String,
18 view_cursor: String,
19 value: T,
20}
21
22impl<T> GapEvent<T> {
23 #[must_use]
25 pub fn new(session_id: impl Into<String>, view_cursor: impl Into<String>, value: T) -> Self {
26 Self {
27 session_id: session_id.into(),
28 view_cursor: view_cursor.into(),
29 value,
30 }
31 }
32
33 #[must_use]
35 pub fn session_id(&self) -> &str {
36 &self.session_id
37 }
38
39 #[must_use]
41 pub fn view_cursor(&self) -> &str {
42 &self.view_cursor
43 }
44
45 #[must_use]
47 pub const fn value(&self) -> &T {
48 &self.value
49 }
50}
51
52#[derive(Debug, Clone, PartialEq, Eq)]
54#[non_exhaustive]
55pub enum PageCursor {
56 More(String),
58 End,
60}
61
62#[derive(Debug, Clone, PartialEq, Eq)]
64pub struct GapPage<T> {
65 events: Vec<GapEvent<T>>,
66 next_cursor: PageCursor,
67}
68
69impl<T> GapPage<T> {
70 #[must_use]
72 pub const fn new(events: Vec<GapEvent<T>>, next_cursor: PageCursor) -> Self {
73 Self {
74 events,
75 next_cursor,
76 }
77 }
78
79 #[must_use]
81 pub fn events(&self) -> &[GapEvent<T>] {
82 &self.events
83 }
84
85 #[must_use]
87 pub const fn next_cursor(&self) -> &PageCursor {
88 &self.next_cursor
89 }
90}
91
92#[derive(Debug, Clone, PartialEq, Eq)]
94#[non_exhaustive]
95pub enum ApplyOutcome {
96 Applied,
98 Buffered,
101 IgnoredOverlap {
104 view_cursor: String,
106 },
107}
108
109#[derive(Debug, Clone, PartialEq, Eq)]
111#[non_exhaustive]
112pub enum GapAdvance {
113 Request(ViewPageParams),
116 Current {
119 filled_through: String,
123 },
124}
125
126#[derive(Debug)]
133pub struct GapFill<T> {
134 session_id: String,
135 pending_gap: Option<ViewGapParams>,
136 walking: bool,
137 page_cursor: Option<String>,
138 request_target: Option<String>,
141 paged: Vec<GapEvent<T>>,
142 buffered: Vec<GapEvent<T>>,
143 paged_cursors: HashSet<String>,
144 buffered_cursors: HashSet<String>,
145 overlap_receipts: HashSet<String>,
146 overlap_receipt_order: VecDeque<String>,
147 seen_targets: HashSet<String>,
150}
151
152impl<T> GapFill<T> {
153 #[must_use]
155 pub fn new(session_id: impl Into<String>) -> Self {
156 Self {
157 session_id: session_id.into(),
158 pending_gap: None,
159 walking: false,
160 page_cursor: None,
161 request_target: None,
162 paged: Vec::new(),
163 buffered: Vec::new(),
164 paged_cursors: HashSet::new(),
165 buffered_cursors: HashSet::new(),
166 overlap_receipts: HashSet::new(),
167 overlap_receipt_order: VecDeque::new(),
168 seen_targets: HashSet::new(),
169 }
170 }
171
172 #[must_use]
174 pub const fn is_current(&self) -> bool {
175 self.pending_gap.is_none()
176 }
177
178 #[must_use]
181 pub const fn pending_gap(&self) -> Option<&ViewGapParams> {
182 self.pending_gap.as_ref()
183 }
184
185 pub(crate) fn held(&self) -> usize {
187 self.buffered.len()
188 }
189
190 pub fn begin_gap(
192 &mut self,
193 gap: ViewGapParams,
194 ) -> Result<Option<ViewPageParams>, GapFillError> {
195 if gap.session_id != self.session_id {
196 return Err(self.foreign_session(gap.session_id, &gap.after, &gap.next));
197 }
198
199 if let Some(pending) = self.pending_gap.as_mut() {
200 if self.seen_targets.insert(gap.next.clone()) {
201 pending.next = gap.next;
202 }
203 if self.walking {
204 return Ok(None);
205 }
206 } else {
207 self.page_cursor = Some(gap.after.clone());
208 self.seen_targets.clear();
209 self.seen_targets.insert(gap.next.clone());
210 self.pending_gap = Some(gap);
211 }
212
213 self.walking = true;
214 Ok(self.page_request())
215 }
216
217 #[must_use]
224 pub fn reattach(&mut self) -> Option<ViewPageParams> {
225 self.pending_gap.as_ref()?;
226 if self.walking {
227 return None;
228 }
229 self.walking = true;
230 self.page_request()
231 }
232
233 pub fn apply(
235 &mut self,
236 event: GapEvent<T>,
237 mut apply: impl FnMut(T),
238 ) -> Result<ApplyOutcome, GapFillError> {
239 if event.session_id != self.session_id {
240 let (after, next) = self
241 .pending_gap
242 .as_ref()
243 .map_or(("", ""), |gap| (gap.after.as_str(), gap.next.as_str()));
244 return Err(self.foreign_session(event.session_id, after, next));
245 }
246 if self.overlap_receipts.contains(&event.view_cursor) {
247 return Ok(ApplyOutcome::IgnoredOverlap {
248 view_cursor: event.view_cursor,
249 });
250 }
251 if self.pending_gap.is_some() {
254 if !self.buffered_cursors.insert(event.view_cursor.clone()) {
255 return Ok(ApplyOutcome::IgnoredOverlap {
256 view_cursor: event.view_cursor,
257 });
258 }
259 self.buffered.push(event);
260 return Ok(ApplyOutcome::Buffered);
261 }
262 apply(event.value);
263 Ok(ApplyOutcome::Applied)
264 }
265
266 pub fn accept_page(
268 &mut self,
269 page: GapPage<T>,
270 mut apply: impl FnMut(T),
271 ) -> Result<GapAdvance, GapFillError> {
272 let Some(pending) = self.pending_gap.as_ref() else {
273 return Err(GapFillError::PageFailed {
274 after: String::new(),
275 next: String::new(),
276 source: Box::new(ProtocolError::Other {
277 message: "view/page arrived with no pending gap".to_owned(),
278 line: None,
279 }),
280 });
281 };
282 let after = pending.after.clone();
283 let target = pending.next.clone();
284 let cursor = self.page_cursor.clone().unwrap_or_else(|| after.clone());
285 let page_was_empty = page.events.is_empty();
286
287 let mut reached = false;
288 let mut last_cursor = None;
289 for event in page.events {
290 if event.session_id != self.session_id {
291 let error = self.foreign_session(event.session_id, &after, &target);
292 self.fail_and_hold();
293 return Err(error);
294 }
295 if event.view_cursor == target {
296 reached = true;
297 }
298 last_cursor = Some(event.view_cursor.clone());
299 if self.overlap_receipts.contains(&event.view_cursor)
300 || !self.paged_cursors.insert(event.view_cursor.clone())
301 {
302 continue;
303 }
304 self.paged.push(event);
305 }
306
307 match page.next_cursor {
308 PageCursor::End
318 if reached || self.request_target.as_deref() == Some(target.as_str()) =>
319 {
320 Ok(self.finish(target, &mut apply))
321 }
322 PageCursor::End => {
323 let next_cursor = last_cursor.unwrap_or(cursor);
324 self.page_cursor = Some(next_cursor.clone());
325 Ok(GapAdvance::Request(self.page_request_at(next_cursor)))
326 }
327 PageCursor::More(next_cursor) => {
328 if page_was_empty || next_cursor == cursor {
329 let error = GapFillError::PageStalled {
330 after,
331 next: target,
332 cursor,
333 };
334 self.fail_and_hold();
335 return Err(error);
336 }
337 if reached {
338 Ok(self.finish(target, &mut apply))
339 } else {
340 self.page_cursor = Some(next_cursor.clone());
341 Ok(GapAdvance::Request(self.page_request_at(next_cursor)))
342 }
343 }
344 }
345 }
346
347 fn finish(&mut self, target: String, apply: &mut impl FnMut(T)) -> GapAdvance {
348 self.pending_gap = None;
349 self.walking = false;
350 self.page_cursor = None;
351 self.request_target = None;
352 self.drain_success(apply);
353 self.seen_targets.clear();
354 GapAdvance::Current {
355 filled_through: target,
356 }
357 }
358
359 fn fail_and_hold(&mut self) {
360 self.walking = false;
361 }
362
363 fn drain_success(&mut self, apply: &mut impl FnMut(T)) {
364 let paged = std::mem::take(&mut self.paged);
365 let buffered = std::mem::take(&mut self.buffered);
366 let paged_cursors = std::mem::take(&mut self.paged_cursors);
367 for event in paged {
368 self.record_overlap_receipt(event.view_cursor);
369 apply(event.value);
370 }
371 for event in buffered {
372 if paged_cursors.contains(&event.view_cursor) {
373 continue;
374 }
375 self.record_overlap_receipt(event.view_cursor);
376 apply(event.value);
377 }
378 self.buffered_cursors.clear();
379 }
380
381 fn record_overlap_receipt(&mut self, cursor: String) {
382 if !self.overlap_receipts.insert(cursor.clone()) {
383 return;
384 }
385 self.overlap_receipt_order.push_back(cursor);
386 if self.overlap_receipt_order.len() > PAGE_LIMIT as usize
389 && let Some(oldest) = self.overlap_receipt_order.pop_front()
390 {
391 self.overlap_receipts.remove(&oldest);
392 }
393 }
394
395 fn page_request(&mut self) -> Option<ViewPageParams> {
396 let cursor = self.page_cursor.clone()?;
397 Some(self.page_request_at(cursor))
398 }
399
400 fn page_request_at(&mut self, cursor: String) -> ViewPageParams {
401 self.request_target = self.pending_gap.as_ref().map(|gap| gap.next.clone());
402 ViewPageParams {
403 session_id: self.session_id.clone(),
404 cursor: Some(cursor),
405 anchor: None,
406 direction: Some(ViewPageDirection::Forward),
407 limit: PAGE_LIMIT,
408 }
409 }
410
411 fn foreign_session(&self, actual: String, after: &str, next: &str) -> GapFillError {
412 GapFillError::PageFailed {
413 after: after.to_owned(),
414 next: next.to_owned(),
415 source: Box::new(ForeignSessionError {
416 expected: self.session_id.clone(),
417 actual,
418 }),
419 }
420 }
421}