Skip to main content

wse_client/
delivery.rs

1//! The delivery, as the TypeScript client's `core/delivery.ts`: each topic's
2//! subscription (requested, active, denied) and continuity (continuous,
3//! resync required, resyncing), what the consumer committed it applied, and
4//! in the recover-or-resync mode ([`Delivery`]) the barrier.
5//!
6//! A topic that is not continuous -- from a cold start, after every
7//! reconnect, after a break -- holds its messages. Once the server took it,
8//! an [`Event::Resync`] asks the application to bring the topic's state up
9//! to date; [`Client::resynced`] then hands on what was held (the
10//! application applies a repeat safely). A topic that lost messages to the
11//! holding limit, or broke off again while it resynced, is asked for once
12//! more instead of passing for complete.
13//!
14//! The checkpoint is what the application committed it applied: per stream
15//! it moves only through what was applied without a hole. It is bound to the
16//! realm, the user, the consumer and the schema, and one of anything else is
17//! refused aloud. A recovery starts from it, so a message that came but was
18//! not applied comes again.
19//!
20//! The gate sees what the application hears in the order the application
21//! hears it: a [`Handler`] where the session hands it out, the [`Events`]
22//! stream where it is read.
23//!
24//! [`Client::resynced`]: crate::Client::resynced
25//! [`Events`]: crate::Events
26
27use std::collections::{BTreeMap, BTreeSet, HashMap, VecDeque};
28use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
29
30use crate::error::Error;
31use crate::events::Incoming;
32use crate::handler::{CheckpointRejected, Event, Handler, MaybeSend, Resync, TopicContinuity};
33use crate::message::{Message, OwnedMessage, Position};
34
35const DEFAULT_MAX_HELD: usize = 10_000;
36/// Commits held beyond a hole, per stream; more are not tracked.
37const MAX_AHEAD: usize = 10_000;
38/// Reasons that concern what came before the topic's subscription: the
39/// state the application is loading covers them.
40const BEFORE_SUBSCRIPTION: [&str; 2] = ["not_recovered", "epoch_changed"];
41
42/// The recover-or-resync delivery, for an application where every fact
43/// counts: a topic that is not continuous (a cold start, every reconnect, a
44/// break) holds its messages until the application brought its state up to
45/// date ([`Event::Resync`], then [`Client::resynced`]); the checkpoint is
46/// what it committed it applied, and recovery starts from it.
47///
48/// [`Client::resynced`]: crate::Client::resynced
49#[derive(Clone, PartialEq, Eq)]
50#[non_exhaustive]
51pub struct Delivery {
52    /// The one consumer that commits, by a stable name.
53    pub consumer: String,
54    /// The application's data schema: a checkpoint of another is refused.
55    pub schema: Option<String>,
56    /// The server's realm (by default the URL as given): a checkpoint of
57    /// another is refused.
58    pub realm: Option<String>,
59    /// The checkpoint the application saved last
60    /// ([`Client::checkpoint`](crate::Client::checkpoint)).
61    pub checkpoint: Option<String>,
62    /// Messages a topic holds while it resyncs (0: 10,000); more starts the
63    /// resync over.
64    pub max_held: usize,
65}
66
67// The checkpoint names the user: left out of a print.
68impl std::fmt::Debug for Delivery {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        f.debug_struct("Delivery")
71            .field("consumer", &self.consumer)
72            .field("schema", &self.schema)
73            .field("realm", &self.realm)
74            .field(
75                "checkpoint",
76                &format_args!(
77                    "{}",
78                    if self.checkpoint.is_some() {
79                        "Some(<redacted>)"
80                    } else {
81                        "None"
82                    }
83                ),
84            )
85            .field("max_held", &self.max_held)
86            .finish()
87    }
88}
89
90impl Delivery {
91    pub fn new(consumer: impl Into<String>) -> Self {
92        Self {
93            consumer: consumer.into(),
94            schema: None,
95            realm: None,
96            checkpoint: None,
97            max_held: 0,
98        }
99    }
100}
101
102/// Whether the server took a topic.
103#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
104pub enum Subscription {
105    Requested,
106    Active,
107    Denied,
108}
109
110/// Whether a topic's messages run without a break.
111#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
112pub enum Continuity {
113    Continuous,
114    /// Its messages broke off (or none came yet): the application's state of
115    /// it is to be brought up to date.
116    ResyncRequired,
117    /// A resync round asks the application for it.
118    Resyncing,
119}
120
121/// A topic held: whether the server took it, and whether its messages run
122/// without a break.
123#[derive(Clone, Debug, PartialEq, Eq)]
124#[non_exhaustive]
125pub struct TopicState {
126    pub topic: String,
127    pub subscription: Subscription,
128    pub continuity: Continuity,
129    /// Why it is not continuous: `cold_start`, `reconnected`, `requested`,
130    /// `overflow`, or the reason of the gap.
131    pub reason: Option<String>,
132}
133
134/// Where a consumer stands in one stream of a topic: the last offset it
135/// committed it applied.
136#[derive(Clone, Debug, PartialEq, Eq)]
137#[non_exhaustive]
138pub struct StreamPosition {
139    pub topic: String,
140    pub epoch: u32,
141    pub offset: u64,
142}
143
144#[derive(Clone, Copy, PartialEq, Eq)]
145enum Mode {
146    BestEffort,
147    RecoverOrResync,
148}
149
150#[derive(Clone)]
151struct State {
152    subscription: Subscription,
153    continuity: Continuity,
154    reason: Option<String>,
155    /// The resync round it is in.
156    round: Option<u64>,
157}
158
159/// What a consumer applied of one stream: everything before `next`, and
160/// some beyond.
161#[derive(Default)]
162struct Progress {
163    next: u64,
164    ahead: BTreeSet<u64>,
165}
166
167impl Progress {
168    fn from(next: u64) -> Self {
169        Self {
170            next,
171            ahead: BTreeSet::new(),
172        }
173    }
174
175    /// The last offset applied, when any is.
176    fn last(&self) -> Option<u64> {
177        self.next.checked_sub(1)
178    }
179}
180
181#[derive(Default)]
182struct Held {
183    messages: Vec<OwnedMessage>,
184    /// Messages were lost to the limit.
185    incomplete: bool,
186}
187
188#[derive(serde::Serialize, serde::Deserialize)]
189struct Saved {
190    v: u32,
191    realm: Option<String>,
192    user: Option<String>,
193    consumer: Option<String>,
194    schema: Option<String>,
195    topics: BTreeMap<String, BTreeMap<String, u64>>,
196}
197
198/// The delivery's state: what the application heard, held and committed.
199pub(crate) struct Gate {
200    mode: Mode,
201    consumer: Option<String>,
202    schema: Option<String>,
203    realm: Option<String>,
204    max_held: usize,
205    /// The saved checkpoint, until the first connection says whose it is.
206    pending: Option<String>,
207    /// The user of the last connection in the order the application hears
208    /// the events, once there was one: what came before the events show
209    /// another user is still the last one's.
210    user: Option<Option<String>>,
211    /// The user generation: a new one starts where the events show another
212    /// user. Each message handed out carries it, and a commit counts only in
213    /// the generation it was handed out in.
214    generation: u32,
215    states: BTreeMap<String, State>,
216    held: HashMap<String, Held>,
217    progress: HashMap<String, BTreeMap<u32, Progress>>,
218    /// The last offset received of each stream.
219    received: HashMap<String, BTreeMap<u32, u64>>,
220    /// Topics that broke off while they resynced, and why.
221    again: HashMap<String, String>,
222    next_round: u64,
223    /// What the gate made outside what the application hears (held messages
224    /// handed on, a refused checkpoint, what an event leads to), handed out
225    /// before what comes next.
226    out: VecDeque<Incoming>,
227}
228
229/// The gate, shared by the client's handles and where the application hears.
230pub(crate) type Shared = Arc<Mutex<Gate>>;
231
232/// The gate, whatever a thread that panicked holding it left.
233pub(crate) fn lock(gate: &Shared) -> MutexGuard<'_, Gate> {
234    gate.lock().unwrap_or_else(PoisonError::into_inner)
235}
236
237impl Gate {
238    pub(crate) fn new(
239        config: Option<Delivery>,
240        realm: &str,
241        topics: &[String],
242    ) -> Result<Self, Error> {
243        let mut gate = match config {
244            None => Self::with(Mode::BestEffort, None, None, None, DEFAULT_MAX_HELD, None),
245            Some(config) => {
246                if config.consumer.is_empty() {
247                    return Err(Error::Config(
248                        "recover-or-resync needs a consumer name".to_owned(),
249                    ));
250                }
251                let max_held = if config.max_held == 0 {
252                    DEFAULT_MAX_HELD
253                } else {
254                    config.max_held
255                };
256                Self::with(
257                    Mode::RecoverOrResync,
258                    Some(config.consumer),
259                    config.schema,
260                    Some(config.realm.unwrap_or_else(|| realm.to_owned())),
261                    max_held,
262                    config.checkpoint,
263                )
264            }
265        };
266        gate.track(topics);
267        Ok(gate)
268    }
269
270    fn with(
271        mode: Mode,
272        consumer: Option<String>,
273        schema: Option<String>,
274        realm: Option<String>,
275        max_held: usize,
276        pending: Option<String>,
277    ) -> Self {
278        Self {
279            mode,
280            consumer,
281            schema,
282            realm,
283            max_held,
284            pending,
285            user: None,
286            generation: 0,
287            states: BTreeMap::new(),
288            held: HashMap::new(),
289            progress: HashMap::new(),
290            received: HashMap::new(),
291            again: HashMap::new(),
292            next_round: 1,
293            out: VecDeque::new(),
294        }
295    }
296
297    fn barrier(&self) -> bool {
298        self.mode == Mode::RecoverOrResync
299    }
300
301    pub(crate) fn topic_states(&self) -> Vec<TopicState> {
302        self.states
303            .iter()
304            .map(|(topic, state)| TopicState {
305                topic: topic.clone(),
306                subscription: state.subscription,
307                continuity: state.continuity,
308                reason: state.reason.clone(),
309            })
310            .collect()
311    }
312
313    /// Each of `topics` held and continuous: a send that requires them may go.
314    /// One of `topics` the client holds is not continuous: a kept send that
315    /// requires them waits (one the client let go of holds nothing back).
316    pub(crate) fn holds_back(&self, topics: &[String]) -> bool {
317        topics.iter().any(|topic| {
318            self.states
319                .get(topic)
320                .is_some_and(|state| state.continuity != Continuity::Continuous)
321        })
322    }
323
324    pub(crate) fn continuous(&self, topics: &[String]) -> bool {
325        topics.iter().all(|topic| {
326            self.states
327                .get(topic)
328                .is_some_and(|state| state.continuity == Continuity::Continuous)
329        })
330    }
331
332    /// `event` goes to the application with what the gate makes: something
333    /// outside the connection said it (the offline queue's file).
334    pub(crate) fn tell(&mut self, event: Event) {
335        self.out.push_back(Incoming::Event(event));
336    }
337
338    /// What the gate made outside what the application hears, next.
339    pub(crate) fn take_out(&mut self) -> Option<Incoming> {
340        self.out.pop_front()
341    }
342
343    // -- topics --------------------------------------------------------------
344
345    pub(crate) fn track(&mut self, topics: &[String]) {
346        for topic in topics {
347            if topic.is_empty() || self.states.contains_key(topic) {
348                continue;
349            }
350            let state = if self.barrier() {
351                self.held.insert(topic.clone(), Held::default());
352                State {
353                    subscription: Subscription::Requested,
354                    continuity: Continuity::ResyncRequired,
355                    reason: Some("cold_start".to_owned()),
356                    round: None,
357                }
358            } else {
359                State {
360                    subscription: Subscription::Requested,
361                    continuity: Continuity::Continuous,
362                    reason: None,
363                    round: None,
364                }
365            };
366            self.states.insert(topic.clone(), state);
367        }
368    }
369
370    pub(crate) fn untrack(&mut self, topics: &[String]) {
371        for topic in topics {
372            self.states.remove(topic);
373            self.held.remove(topic);
374            self.progress.remove(topic);
375            self.received.remove(topic);
376            self.again.remove(topic);
377        }
378    }
379
380    // -- what the application hears ------------------------------------------
381
382    /// A message: the generation to hand it on with now, or None when the
383    /// barrier holds it (a copy of it).
384    pub(crate) fn message(&mut self, message: &Message<'_>) -> Option<u32> {
385        match self.admit(message.topic(), message.position()) {
386            Admit::Pass => Some(self.generation),
387            Admit::Hold => {
388                let mut owned = message.to_owned();
389                owned.generation = self.generation;
390                self.hold(owned);
391                None
392            }
393        }
394    }
395
396    /// [`message`](Self::message) for one already owned: itself stamped, or
397    /// None when held.
398    pub(crate) fn owned(&mut self, mut message: OwnedMessage) -> Option<OwnedMessage> {
399        message.generation = self.generation;
400        match self.admit(message.topic(), message.position()) {
401            Admit::Pass => Some(message),
402            Admit::Hold => {
403                self.hold(message);
404                None
405            }
406        }
407    }
408
409    fn admit(&mut self, topic: Option<&str>, position: Option<Position>) -> Admit {
410        let Some(topic) = topic else {
411            return Admit::Pass;
412        };
413        if let Some(at) = position {
414            match self.received.get_mut(topic) {
415                Some(streams) => {
416                    let last = streams.entry(at.epoch).or_insert(at.offset);
417                    *last = (*last).max(at.offset);
418                }
419                None => {
420                    self.received
421                        .insert(topic.to_owned(), BTreeMap::from([(at.epoch, at.offset)]));
422                }
423            }
424        }
425        let Some(state) = self.states.get(topic) else {
426            return Admit::Pass;
427        };
428        if self.barrier() && state.continuity != Continuity::Continuous {
429            return Admit::Hold;
430        }
431        if let Some(at) = position {
432            self.handed_on(topic, at);
433        }
434        Admit::Pass
435    }
436
437    fn hold(&mut self, message: OwnedMessage) {
438        let Some(topic) = message.topic() else {
439            return;
440        };
441        let held = self.held.entry(topic.to_owned()).or_default();
442        if held.messages.len() < self.max_held {
443            held.messages.push(message);
444        } else {
445            held.incomplete = true;
446        }
447    }
448
449    /// An event the application hears; what follows from it goes out after
450    /// it.
451    pub(crate) fn event(&mut self, event: &Event) {
452        match event {
453            Event::Connected(connected) => self.user_is(connected.user_id.as_deref()),
454            Event::Subscribed(subscribed) => {
455                for topic in &subscribed.topics {
456                    self.set_subscription(topic, Subscription::Active);
457                }
458                for topic in &subscribed.failed {
459                    self.set_subscription(topic, Subscription::Denied);
460                }
461                self.start_resyncs();
462            }
463            Event::Disconnected(_) | Event::Paused(_) => self.connection_lost(),
464            Event::Gap(gap) => self.broke_off(&gap.topic, gap.reason.as_str()),
465            _ => {}
466        }
467    }
468
469    fn set_subscription(&mut self, topic: &str, subscription: Subscription) {
470        if let Some(state) = self.states.get_mut(topic) {
471            state.subscription = subscription;
472        }
473    }
474
475    /// A message handed on: a stream first seen starts its checkpoint just
476    /// before it.
477    fn handed_on(&mut self, topic: &str, at: Position) {
478        match self.progress.get_mut(topic) {
479            Some(streams) => {
480                streams
481                    .entry(at.epoch)
482                    .or_insert_with(|| Progress::from(at.offset));
483            }
484            None => {
485                self.progress.insert(
486                    topic.to_owned(),
487                    BTreeMap::from([(at.epoch, Progress::from(at.offset))]),
488                );
489            }
490        }
491    }
492
493    fn connection_lost(&mut self) {
494        let barrier = self.barrier();
495        let mut changes = Vec::new();
496        for (topic, state) in &mut self.states {
497            state.subscription = Subscription::Requested;
498            state.round = None;
499            self.again.remove(topic);
500            let before = state.continuity;
501            if barrier {
502                self.held.insert(topic.clone(), Held::default());
503                if state.continuity != Continuity::ResyncRequired {
504                    state.continuity = Continuity::ResyncRequired;
505                    state.reason = Some("reconnected".to_owned());
506                }
507            } else if state.continuity == Continuity::Resyncing {
508                state.continuity = Continuity::ResyncRequired;
509            }
510            if state.continuity != before {
511                changes.push(continuity_event(topic, state));
512            }
513        }
514        self.out.extend(changes);
515    }
516
517    fn broke_off(&mut self, topic: &str, reason: &str) {
518        let Some(continuity) = self.states.get(topic).map(|s| s.continuity) else {
519            return;
520        };
521        match continuity {
522            Continuity::Resyncing => {
523                // What came before the subscription is in the state being
524                // loaded; a message lost since may not be.
525                if !BEFORE_SUBSCRIPTION.contains(&reason) {
526                    self.again.insert(topic.to_owned(), reason.to_owned());
527                }
528            }
529            Continuity::ResyncRequired => {}
530            Continuity::Continuous => {
531                if self.barrier() {
532                    self.held.insert(topic.to_owned(), Held::default());
533                }
534                self.set_continuity(topic, Continuity::ResyncRequired, Some(reason));
535                self.start_resyncs();
536            }
537        }
538    }
539
540    /// The topics the server took that wait for a resync, in one round.
541    fn start_resyncs(&mut self) {
542        if !self.barrier() {
543            return;
544        }
545        let topics: Vec<String> = self
546            .states
547            .iter()
548            .filter(|(_, s)| {
549                s.subscription == Subscription::Active && s.continuity == Continuity::ResyncRequired
550            })
551            .map(|(topic, _)| topic.clone())
552            .collect();
553        if topics.is_empty() {
554            return;
555        }
556        let round = self.next_round;
557        self.next_round += 1;
558        let mut reasons = Vec::with_capacity(topics.len());
559        let mut committed = Vec::new();
560        for topic in &topics {
561            let state = self.states.get_mut(topic).expect("listed");
562            state.continuity = Continuity::Resyncing;
563            state.round = Some(round);
564            reasons.push(
565                state
566                    .reason
567                    .clone()
568                    .unwrap_or_else(|| "requested".to_owned()),
569            );
570            self.out.push_back(continuity_event(topic, state));
571            for (epoch, progress) in self.progress.get(topic).into_iter().flatten() {
572                if let Some(offset) = progress.last() {
573                    committed.push(StreamPosition {
574                        topic: topic.clone(),
575                        epoch: *epoch,
576                        offset,
577                    });
578                }
579            }
580        }
581        self.out.push_back(Incoming::Event(Event::Resync(Resync {
582            round,
583            topics,
584            reasons,
585            committed,
586        })));
587    }
588
589    // -- what the application says -------------------------------------------
590
591    /// The application brought the topics of `round` up to date: what they
592    /// held goes on, or a topic that lost some is asked for again.
593    pub(crate) fn resynced(&mut self, round: u64) {
594        let topics: Vec<String> = self
595            .states
596            .iter()
597            .filter(|(_, s)| s.round == Some(round) && s.continuity == Continuity::Resyncing)
598            .map(|(topic, _)| topic.clone())
599            .collect();
600        for topic in &topics {
601            let held = self.held.remove(topic).unwrap_or_default();
602            let broke = if held.incomplete {
603                Some("overflow".to_owned())
604            } else {
605                self.again.remove(topic)
606            };
607            self.again.remove(topic);
608            if let Some(reason) = broke {
609                self.held.insert(topic.clone(), Held::default());
610                if let Some(state) = self.states.get_mut(topic) {
611                    state.round = None;
612                }
613                self.set_continuity(topic, Continuity::ResyncRequired, Some(&reason));
614                continue;
615            }
616            self.restart(topic, &held.messages);
617            if let Some(state) = self.states.get_mut(topic) {
618                state.round = None;
619            }
620            self.set_continuity(topic, Continuity::Continuous, None);
621            for message in held.messages {
622                if let Some(at) = message.position() {
623                    self.handed_on(topic, at);
624                }
625                self.out.push_back(Incoming::Message(message));
626            }
627        }
628        self.start_resyncs();
629    }
630
631    /// The state the application loaded covers each stream up to the first
632    /// message handed on after it, or up to what was received when none is.
633    fn restart(&mut self, topic: &str, onward: &[OwnedMessage]) {
634        let mut streams: BTreeMap<u32, Progress> = self
635            .received
636            .get(topic)
637            .into_iter()
638            .flatten()
639            .map(|(epoch, offset)| (*epoch, Progress::from(offset + 1)))
640            .collect();
641        let mut first = BTreeSet::new();
642        for message in onward {
643            if let Some(at) = message.position()
644                && first.insert(at.epoch)
645            {
646                streams.insert(at.epoch, Progress::from(at.offset));
647            }
648        }
649        self.progress.insert(topic.to_owned(), streams);
650    }
651
652    /// The application asks for `topics` to be brought up to date. Best
653    /// effort: it did so itself, and they read continuous again.
654    pub(crate) fn resync(&mut self, topics: &[String]) {
655        for topic in topics {
656            let Some(state) = self.states.get(topic) else {
657                continue;
658            };
659            if !self.barrier() {
660                if state.continuity != Continuity::Continuous {
661                    self.set_continuity(topic, Continuity::Continuous, None);
662                }
663                continue;
664            }
665            self.held.insert(topic.clone(), Held::default());
666            if let Some(state) = self.states.get_mut(topic) {
667                state.round = None;
668            }
669            if self.states[topic].continuity != Continuity::ResyncRequired {
670                self.set_continuity(topic, Continuity::ResyncRequired, Some("requested"));
671            }
672        }
673        self.start_resyncs();
674    }
675
676    /// The consumer applied the message at `epoch`, `offset` of `topic`,
677    /// handed out in `generation`: one of an earlier user counts for nobody.
678    pub(crate) fn commit(&mut self, topic: &str, epoch: u32, offset: u64, generation: u32) {
679        if generation != self.generation {
680            return;
681        }
682        let Some(progress) = self
683            .progress
684            .get_mut(topic)
685            .and_then(|streams| streams.get_mut(&epoch))
686        else {
687            return;
688        };
689        if offset < progress.next {
690            return;
691        }
692        if offset == progress.next {
693            progress.next += 1;
694            while progress.ahead.remove(&progress.next) {
695                progress.next += 1;
696            }
697        } else if progress.ahead.len() < MAX_AHEAD {
698            progress.ahead.insert(offset);
699        }
700    }
701
702    /// The checkpoint, to save with the application's own state.
703    pub(crate) fn checkpoint(&self) -> String {
704        // A stream nothing of which was applied is left out, and a topic
705        // with none.
706        let topics = self
707            .progress
708            .iter()
709            .filter_map(|(topic, streams)| {
710                let applied: BTreeMap<String, u64> = streams
711                    .iter()
712                    .filter_map(|(epoch, progress)| {
713                        Some((format!("{epoch:08x}"), progress.last()?))
714                    })
715                    .collect();
716                (!applied.is_empty()).then(|| (topic.clone(), applied))
717            })
718            .collect();
719        serde_json::to_string(&Saved {
720            v: 1,
721            realm: self.realm.clone(),
722            user: self.user.clone().flatten(),
723            consumer: self.consumer.clone(),
724            schema: self.schema.clone(),
725            topics,
726        })
727        .unwrap_or_default()
728    }
729
730    /// recover-or-resync: where each topic's recovery starts, for a
731    /// connection of `user` about to subscribe (None in best effort). The
732    /// saved checkpoint is taken here, once a connection named its user.
733    pub(crate) fn committed(
734        &mut self,
735        user: Option<&str>,
736    ) -> Option<BTreeMap<String, Vec<Position>>> {
737        if !self.barrier() {
738            return None;
739        }
740        match &self.user {
741            // The first connection: nothing was heard before it.
742            None => self.user_is(user),
743            // Another user's: nothing of what the last one applied. The
744            // change itself comes where the events show it, after what the
745            // last user still has to hear.
746            Some(last) if last.as_deref() != user => return Some(BTreeMap::new()),
747            Some(_) => {}
748        }
749        self.take_saved();
750        Some(
751            self.progress
752                .iter()
753                .filter(|(topic, _)| self.states.contains_key(*topic))
754                .map(|(topic, streams)| {
755                    (
756                        topic.clone(),
757                        streams
758                            .iter()
759                            .filter_map(|(epoch, progress)| {
760                                Some(Position {
761                                    epoch: *epoch,
762                                    offset: progress.last()?,
763                                })
764                            })
765                            .collect(),
766                    )
767                })
768                .collect(),
769        )
770    }
771
772    /// A connection of `user`, where the events show it: what another user
773    /// applied, or holds, is not this one's.
774    fn user_is(&mut self, user: Option<&str>) {
775        let user = user.map(str::to_owned);
776        if self.user.as_ref().is_some_and(|last| *last != user) {
777            self.progress.clear();
778            self.received.clear();
779            self.again.clear();
780            for held in self.held.values_mut() {
781                *held = Held::default();
782            }
783            self.generation = self.generation.wrapping_add(1);
784        }
785        self.user = Some(user);
786    }
787
788    fn take_saved(&mut self) {
789        let Some(text) = self.pending.take() else {
790            return;
791        };
792        let Ok(saved) = serde_json::from_str::<Saved>(&text) else {
793            self.reject("malformed");
794            return;
795        };
796        let mismatch = if saved.v != 1 {
797            Some("version")
798        } else if saved.realm != self.realm {
799            Some("realm")
800        } else if saved.user != self.user.clone().flatten() {
801            Some("user")
802        } else if saved.consumer != self.consumer {
803            Some("consumer")
804        } else if saved.schema != self.schema {
805            Some("schema")
806        } else {
807            None
808        };
809        if let Some(reason) = mismatch {
810            self.reject(reason);
811            return;
812        }
813        for (topic, streams) in saved.topics {
814            if !self.states.contains_key(&topic) || self.progress.contains_key(&topic) {
815                continue;
816            }
817            let streams: BTreeMap<u32, Progress> = streams
818                .into_iter()
819                .filter_map(|(epoch, last)| {
820                    let epoch = u32::from_str_radix(&epoch, 16).ok()?;
821                    Some((epoch, Progress::from(last.checked_add(1)?)))
822                })
823                .collect();
824            if !streams.is_empty() {
825                self.progress.insert(topic, streams);
826            }
827        }
828    }
829
830    fn reject(&mut self, reason: &str) {
831        tracing::warn!(
832            "[WSE] the saved checkpoint is not taken: its {reason} is not this client's"
833        );
834        self.out
835            .push_back(Incoming::Event(Event::CheckpointRejected(
836                CheckpointRejected {
837                    reason: reason.to_owned(),
838                },
839            )));
840    }
841
842    fn set_continuity(&mut self, topic: &str, continuity: Continuity, reason: Option<&str>) {
843        let Some(state) = self.states.get_mut(topic) else {
844            return;
845        };
846        if state.continuity == continuity && state.reason.as_deref() == reason {
847            return;
848        }
849        state.continuity = continuity;
850        state.reason = reason.map(str::to_owned);
851        let event = continuity_event(topic, state);
852        self.out.push_back(event);
853    }
854}
855
856enum Admit {
857    Pass,
858    Hold,
859}
860
861fn continuity_event(topic: &str, state: &State) -> Incoming {
862    Incoming::Event(Event::Continuity(TopicContinuity {
863        topic: topic.to_owned(),
864        continuity: state.continuity,
865        reason: state.reason.clone(),
866    }))
867}
868
869/// The application's handler behind the gate, for a client made with one:
870/// what the session hands out passes the gate in the order the handler hears
871/// it. Not `before` the handler (the [`Events`](crate::Events) stream's
872/// queue, read behind the gate) everything passes as it is.
873pub(crate) struct Delivered<H> {
874    pub(crate) inner: H,
875    gate: Shared,
876    before: bool,
877}
878
879impl<H: Handler> Delivered<H> {
880    pub(crate) fn new(inner: H, gate: Shared, before: bool) -> Self {
881        Self {
882            inner,
883            gate,
884            before,
885        }
886    }
887
888    /// `inner` with a gate of its own that it does not stand behind.
889    #[cfg(test)]
890    pub(crate) fn passing(inner: H) -> Self {
891        let gate = Gate::new(None, "ws://x", &[]).expect("best effort");
892        Self::new(inner, Arc::new(Mutex::new(gate)), false)
893    }
894
895    /// The delivery's gate, wherever it stands.
896    pub(crate) fn gate(&self) -> &Shared {
897        &self.gate
898    }
899
900    /// What the gate made outside the session's hand-out (held messages
901    /// handed on, a refused checkpoint, what an event led to), to the handler
902    /// now, the gate let go while it runs.
903    pub(crate) fn drain(&mut self) {
904        if !self.before {
905            return;
906        }
907        loop {
908            let next = lock(&self.gate).take_out();
909            match next {
910                Some(Incoming::Message(message)) => self.inner.message(&message.as_message()),
911                Some(Incoming::Event(event)) => self.inner.event(event),
912                Some(Incoming::Binary(data)) => self.inner.binary(&data),
913                None => return,
914            }
915        }
916    }
917}
918
919impl<H: Handler> Handler for Delivered<H> {
920    fn message(&mut self, message: &Message<'_>) {
921        if !self.before {
922            self.inner.message(message);
923            return;
924        }
925        // The gate is let go before the handler runs: it may commit.
926        let generation = lock(&self.gate).message(message);
927        match generation {
928            Some(generation) if generation == message.generation => self.inner.message(message),
929            Some(generation) => {
930                let mut stamped = message.clone();
931                stamped.generation = generation;
932                self.inner.message(&stamped);
933            }
934            None => {}
935        }
936        self.drain();
937    }
938
939    fn event(&mut self, event: Event) {
940        if self.before {
941            lock(&self.gate).event(&event);
942        }
943        self.inner.event(event);
944        self.drain();
945    }
946
947    fn binary(&mut self, data: &[u8]) {
948        self.inner.binary(data);
949    }
950
951    fn ready(&mut self) -> impl std::future::Future<Output = ()> + MaybeSend {
952        self.inner.ready()
953    }
954}
955
956#[cfg(test)]
957mod tests {
958    use super::*;
959    use crate::handler::{Connected, Disconnected, Subscribed};
960
961    fn message(topic: &str, epoch: u32, offset: u64) -> OwnedMessage {
962        OwnedMessage::for_test("m", Some(topic), Some(Position { epoch, offset }))
963    }
964
965    fn connected(user: &str) -> Event {
966        Event::Connected(Connected {
967            connection_id: "c".into(),
968            user_id: Some(user.into()),
969            reconnected: false,
970            recovery: true,
971        })
972    }
973
974    fn disconnected() -> Event {
975        Event::Disconnected(Disconnected {
976            code: Some(1006),
977            reason: "gone".into(),
978            retry_in: std::time::Duration::ZERO,
979            attempt: 1,
980        })
981    }
982
983    fn subscribed(topics: &[&str]) -> Event {
984        Event::Subscribed(Subscribed {
985            topics: topics.iter().map(|t| (*t).to_owned()).collect(),
986            failed: Vec::new(),
987            recovery: Vec::new(),
988        })
989    }
990
991    fn out(gate: &mut Gate) -> Vec<Incoming> {
992        std::iter::from_fn(|| gate.take_out()).collect()
993    }
994
995    fn round_of(items: &[Incoming]) -> u64 {
996        items
997            .iter()
998            .find_map(|i| match i {
999                Incoming::Event(Event::Resync(r)) => Some(r.round),
1000                _ => None,
1001            })
1002            .expect("a resync round")
1003    }
1004
1005    fn board() -> Gate {
1006        Gate::new(
1007            Some(Delivery::new("board")),
1008            "ws://x/wse",
1009            &["t".to_owned()],
1010        )
1011        .unwrap()
1012    }
1013
1014    /// A connection of `user` that took topic t and resynced it.
1015    fn resynced(gate: &mut Gate, user: &str) {
1016        gate.committed(Some(user));
1017        gate.event(&connected(user));
1018        gate.event(&subscribed(&["t"]));
1019        let round = round_of(&out(gate));
1020        gate.resynced(round);
1021        out(gate);
1022    }
1023
1024    #[test]
1025    fn a_checkpoint_is_never_another_users() {
1026        let mut gate = board();
1027        resynced(&mut gate, "alice");
1028        let alices = gate.owned(message("t", 1, 99)).expect("handed on");
1029        gate.commit("t", 1, 99, alices.generation);
1030        assert_eq!(
1031            gate.committed(Some("alice")).unwrap()["t"],
1032            [Position {
1033                epoch: 1,
1034                offset: 99
1035            }]
1036        );
1037
1038        // The next connection is Bob's: it recovers nothing of what Alice
1039        // applied.
1040        gate.event(&disconnected());
1041        let positions = gate.committed(Some("bob")).unwrap();
1042        assert!(
1043            positions.get("t").is_none_or(Vec::is_empty),
1044            "{positions:?}"
1045        );
1046        // Where the events show his connection, the checkpoint is his, and
1047        // Alice's message applied late counts for nobody.
1048        gate.event(&connected("bob"));
1049        gate.commit("t", 1, 99, alices.generation);
1050        gate.commit("t", 1, 100, alices.generation);
1051        let saved: serde_json::Value = serde_json::from_str(&gate.checkpoint()).unwrap();
1052        assert_eq!(saved["user"], "bob");
1053        assert_eq!(saved["topics"], serde_json::json!({}));
1054    }
1055
1056    #[test]
1057    fn a_cold_start_holds_the_topic_until_the_application_resynced_it() {
1058        let mut gate = board();
1059        gate.committed(Some("ann"));
1060        gate.event(&connected("ann"));
1061        assert!(
1062            gate.owned(message("t", 1, 5)).is_none(),
1063            "held before the server took it"
1064        );
1065        gate.event(&subscribed(&["t"]));
1066        let items = out(&mut gate);
1067        let round = round_of(&items);
1068        assert!(
1069            gate.owned(message("t", 1, 6)).is_none(),
1070            "held while it resyncs"
1071        );
1072        gate.resynced(round);
1073        let released: Vec<Position> = out(&mut gate)
1074            .into_iter()
1075            .filter_map(|i| match i {
1076                Incoming::Message(m) => m.position(),
1077                _ => None,
1078            })
1079            .collect();
1080        assert_eq!(
1081            released,
1082            [
1083                Position {
1084                    epoch: 1,
1085                    offset: 5
1086                },
1087                Position {
1088                    epoch: 1,
1089                    offset: 6
1090                }
1091            ]
1092        );
1093        assert!(gate.owned(message("t", 1, 7)).is_some(), "continuous now");
1094    }
1095
1096    #[test]
1097    fn a_break_while_it_resyncs_asks_for_the_topic_again() {
1098        let mut gate = board();
1099        gate.committed(Some("ann"));
1100        gate.event(&connected("ann"));
1101        gate.event(&subscribed(&["t"]));
1102        let round = round_of(&out(&mut gate));
1103        gate.event(&Event::Gap(crate::handler::Gap {
1104            topic: "t".into(),
1105            epoch: 1,
1106            first: Some(3),
1107            last: Some(4),
1108            reason: crate::handler::GapReason::Timeout,
1109        }));
1110        gate.resynced(round);
1111        let items = out(&mut gate);
1112        assert!(
1113            items.iter().any(
1114                |i| matches!(i, Incoming::Event(Event::Resync(r)) if r.reasons == ["timeout"])
1115            ),
1116            "{items:?}"
1117        );
1118    }
1119
1120    /// The checkpoints every client reads alike: the positions taken, or
1121    /// why one is refused (the TypeScript and Python clients read the file
1122    /// too).
1123    #[test]
1124    fn the_shared_checkpoint_vectors() {
1125        let doc: serde_json::Value =
1126            serde_json::from_str(include_str!("../tests/vectors/checkpoint.json")).unwrap();
1127        let scope = &doc["scope"];
1128        let topics: Vec<String> = scope["topics"]
1129            .as_array()
1130            .unwrap()
1131            .iter()
1132            .map(|t| t.as_str().unwrap().to_owned())
1133            .collect();
1134        let user = scope["user"].as_str();
1135        let gate_with = |saved: &str| {
1136            let mut delivery = Delivery::new(scope["consumer"].as_str().unwrap());
1137            delivery.schema = scope["schema"].as_str().map(str::to_owned);
1138            delivery.checkpoint = Some(saved.to_owned());
1139            Gate::new(Some(delivery), scope["realm"].as_str().unwrap(), &topics).unwrap()
1140        };
1141        let rejected = |gate: &mut Gate| -> Vec<String> {
1142            out(gate)
1143                .into_iter()
1144                .filter_map(|i| match i {
1145                    Incoming::Event(Event::CheckpointRejected(c)) => Some(c.reason),
1146                    _ => None,
1147                })
1148                .collect()
1149        };
1150        for case in doc["taken"].as_array().unwrap() {
1151            let mut gate = gate_with(case["saved"].as_str().unwrap());
1152            let positions: BTreeMap<String, BTreeMap<String, u64>> = gate
1153                .committed(user)
1154                .unwrap()
1155                .into_iter()
1156                .filter(|(_, at)| !at.is_empty())
1157                .map(|(topic, at)| {
1158                    let streams = at
1159                        .into_iter()
1160                        .map(|p| (format!("{:08x}", p.epoch), p.offset));
1161                    (topic, streams.collect())
1162                })
1163                .collect();
1164            assert_eq!(
1165                serde_json::to_value(positions).unwrap(),
1166                case["positions"],
1167                "{}",
1168                case["name"]
1169            );
1170            assert!(rejected(&mut gate).is_empty(), "{}", case["name"]);
1171        }
1172        for case in doc["refused"].as_array().unwrap() {
1173            let mut gate = gate_with(case["saved"].as_str().unwrap());
1174            let positions = gate.committed(user).unwrap();
1175            assert!(
1176                positions.values().all(Vec::is_empty),
1177                "{}: {positions:?}",
1178                case["name"]
1179            );
1180            assert_eq!(
1181                rejected(&mut gate),
1182                [case["reason"].as_str().unwrap()],
1183                "{}",
1184                case["name"]
1185            );
1186        }
1187    }
1188
1189    #[test]
1190    fn best_effort_holds_nothing_and_counts_commits() {
1191        let mut gate = Gate::new(None, "ws://x/wse", &["t".to_owned()]).unwrap();
1192        gate.event(&connected("ann"));
1193        gate.event(&subscribed(&["t"]));
1194        let m = gate.owned(message("t", 1, 1)).expect("never held");
1195        gate.commit("t", 1, 1, m.generation);
1196        let saved: serde_json::Value = serde_json::from_str(&gate.checkpoint()).unwrap();
1197        assert_eq!(saved["topics"]["t"]["00000001"], 1, "{saved}");
1198        assert!(out(&mut gate).is_empty());
1199    }
1200}