Skip to main content

muse_code_sdk/
gap.rs

1//! Reattach and delivery-gap recovery.
2
3use 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/// A lossless view event plus the generated base fields gap recovery needs.
11///
12/// `T` stays intact because the generated `UnframedViewNotificationParams`
13/// contains only the common envelope fields. Deserializing a page into that
14/// type would discard event-specific item and turn data before the fold sees it.
15#[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    /// Wraps one event with the session and view cursor it was delivered under.
24    #[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    /// The session the event names.
34    #[must_use]
35    pub fn session_id(&self) -> &str {
36        &self.session_id
37    }
38
39    /// The event's opaque view cursor.
40    #[must_use]
41    pub fn view_cursor(&self) -> &str {
42        &self.view_cursor
43    }
44
45    /// The whole event.
46    #[must_use]
47    pub const fn value(&self) -> &T {
48        &self.value
49    }
50}
51
52/// The required nullable `nextCursor` member of one raw `view/page` result.
53#[derive(Debug, Clone, PartialEq, Eq)]
54#[non_exhaustive]
55pub enum PageCursor {
56    /// More events follow; request the next page from this cursor.
57    More(String),
58    /// The page reached the end of the view.
59    End,
60}
61
62/// One lossless page supplied by the connection layer.
63#[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    /// A page of events in view order, and the page's `nextCursor`.
71    #[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    /// The page's events, in view order.
80    #[must_use]
81    pub fn events(&self) -> &[GapEvent<T>] {
82        &self.events
83    }
84
85    /// Whether more pages follow, and from which cursor.
86    #[must_use]
87    pub const fn next_cursor(&self) -> &PageCursor {
88        &self.next_cursor
89    }
90}
91
92/// What happened to one live event at the public apply boundary.
93#[derive(Debug, Clone, PartialEq, Eq)]
94#[non_exhaustive]
95pub enum ApplyOutcome {
96    /// No gap is pending, so the event went straight to the callback.
97    Applied,
98    /// A gap is pending, so the event waits behind it and reaches the callback
99    /// once the gap fills.
100    Buffered,
101    /// The event repeats one a page already delivered, or one already held
102    /// behind the gap, so it was dropped.
103    IgnoredOverlap {
104        /// The dropped event's view cursor.
105        view_cursor: String,
106    },
107}
108
109/// The next step after accepting a page.
110#[derive(Debug, Clone, PartialEq, Eq)]
111#[non_exhaustive]
112pub enum GapAdvance {
113    /// Send this `view/page` request and pass its answer to
114    /// [`GapFill::accept_page`].
115    Request(ViewPageParams),
116    /// The gap is closed: the paged events were delivered in order, followed
117    /// by the live events held behind the gap.
118    Current {
119        /// The gap's `next` cursor. When the view ended before it (a streamed
120        /// fragment, which pages never serve), the fill stops at the end of the
121        /// view and those fragments are not recovered.
122        filled_through: String,
123    },
124}
125
126/// Synchronous splice-fill state for one session.
127///
128/// The facade's `Session` (its gap route) owns the `view/page` round trips
129/// and calls [`Self::accept_page`] with the raw, lossless page. Every
130/// delivered value reaches the same callback used by [`Self::apply`], so paged
131/// and live events share one downstream path.
132#[derive(Debug)]
133pub struct GapFill<T> {
134    session_id: String,
135    pending_gap: Option<ViewGapParams>,
136    walking: bool,
137    page_cursor: Option<String>,
138    // The target the in-flight page request was sent toward. An end-of-view
139    // answer finishes only that range, never a target extended since.
140    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    // Cursors are opaque; equality with a target already seen is the only
148    // safe way to recognize a delayed older bracket during this fill.
149    seen_targets: HashSet<String>,
150}
151
152impl<T> GapFill<T> {
153    /// Empty fill state for one session, with no gap pending.
154    #[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    /// Whether no gap is pending.
173    #[must_use]
174    pub const fn is_current(&self) -> bool {
175        self.pending_gap.is_none()
176    }
177
178    /// The pending gap, with its `next` cursor extended by any later gap that
179    /// arrived during the fill.
180    #[must_use]
181    pub const fn pending_gap(&self) -> Option<&ViewGapParams> {
182        self.pending_gap.as_ref()
183    }
184
185    /// Live events held behind the pending hole, awaiting the splice.
186    pub(crate) fn held(&self) -> usize {
187        self.buffered.len()
188    }
189
190    /// Record a delivery gap and start, or extend, its single forward walk.
191    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    /// Reissue the page after a failed walk on a replacement transport.
218    ///
219    /// An already in-flight request returns `None` so reattach cannot create a
220    /// redelivery race. This deliberately does not construct `session/resume`
221    /// or reconcile commands; those are owned by the facade and pending-command
222    /// layers.
223    #[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    /// Feed one live event through the same application boundary used by a fill.
234    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        // A failed walk still owns a pending hole. Keep later live facts
252        // behind its eventual retry instead of applying newer before older.
253        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    /// Accept one raw page, advancing or atomically splicing it into the fold.
267    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            // The server's end of the view finishes the fill even before the
309            // target: `view/page` serves durable events only, so a hole whose
310            // `next` is an ephemeral fragment cursor (an `item/delta` mid-stream)
311            // ends here, and its fragments are unrecoverable by design (the
312            // TypeScript and Python fillers do the same).
313            // It finishes only the range this request was sent toward: if a
314            // later `view/gap` extended the target mid-walk, page on toward it
315            // from the last served cursor, or re-ask the current cursor when the
316            // end page was empty (the TypeScript `gapFilled` refusal).
317            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        // One page covers the only page/live overlap window. Older receipts
387        // expire in FIFO order instead of accumulating for the session lifetime.
388        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            // The gap-filler pages the full overlap window: no caller
409            // cap, so the server budget alone binds.
410            max_bytes: None,
411        }
412    }
413
414    fn foreign_session(&self, actual: String, after: &str, next: &str) -> GapFillError {
415        GapFillError::PageFailed {
416            after: after.to_owned(),
417            next: next.to_owned(),
418            source: Box::new(ForeignSessionError {
419                expected: self.session_id.clone(),
420                actual,
421            }),
422        }
423    }
424}