Skip to main content

jmap_websocket/server/
hub.rs

1//! [`PushHub`]: an in-memory [`PushSource`] with `pushState` replay.
2
3use std::collections::{BTreeMap, VecDeque};
4use std::fmt;
5use std::sync::atomic::{AtomicU64, Ordering};
6use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
7use std::time::{SystemTime, UNIX_EPOCH};
8
9use futures::StreamExt as _;
10use futures::stream::BoxStream;
11use jmap_types::{Id, State, StateChange};
12use tokio::sync::watch;
13
14use super::PushSource;
15use crate::{WebSocketPushEnable, WsStateChange};
16
17/// The `changed` map of a StateChange (RFC 8620 §7.1).
18type Changed = BTreeMap<Id, BTreeMap<String, State>>;
19
20/// Distinguishes hubs made in the same clock tick.
21static HUB_COUNTER: AtomicU64 = AtomicU64::new(0);
22
23/// A fan-out of state changes to every connection of one principal, with
24/// RFC 8887 §4.3.5.1 `pushState` tokens and replay.
25///
26/// The deployment calls [`publish`](Self::publish) after every write and
27/// gives each connection a clone as its [`PushSource`]. Keep one hub per
28/// principal (or per set of accounts a caller sees): a hub does no
29/// access filtering, and its `pushState` "encodes the entire server state
30/// visible to the user".
31///
32/// The hub keeps the last `capacity` changes. A `pushState` it issued is
33/// answered with the changes since then, merged into one notification;
34/// if some were already dropped, with the latest state of every type the
35/// hub has seen (a superset: a client's `/changes` call for a type that
36/// did not change returns nothing). A token it did not issue (another
37/// hub, or a hub from before a restart) replays nothing, and the client
38/// resyncs with `/changes`. Tokens are opaque strings.
39///
40/// Each wake of a slow connection merges all changes since its last
41/// notification into one, keeping the latest state per type; `extra`
42/// members of merged changes are dropped.
43///
44/// ```
45/// use std::collections::BTreeMap;
46/// use jmap_websocket::server::PushHub;
47/// use jmap_websocket::jmap_types::{Id, State, StateChange};
48///
49/// let hub = PushHub::new(256);
50/// let mut types = BTreeMap::new();
51/// types.insert("Email".to_owned(), State::from("e2"));
52/// let mut changed = BTreeMap::new();
53/// changed.insert(Id::from("a1"), types);
54/// hub.publish(StateChange::new(changed));
55/// assert!(!hub.push_state().is_empty());
56/// ```
57#[derive(Clone)]
58pub struct PushHub {
59    inner: Arc<Inner>,
60}
61
62struct Inner {
63    epoch: String,
64    capacity: usize,
65    log: Mutex<Log>,
66    wake: watch::Sender<u64>,
67}
68
69#[derive(Default)]
70struct Log {
71    seq: u64,
72    entries: VecDeque<(u64, Changed)>,
73    latest: Changed,
74}
75
76impl fmt::Debug for PushHub {
77    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
78        f.debug_struct("PushHub")
79            .field("capacity", &self.inner.capacity)
80            .field("push_state", &self.push_state())
81            .finish_non_exhaustive()
82    }
83}
84
85impl PushHub {
86    /// A hub that keeps the last `capacity` changes for replay (at least
87    /// one).
88    pub fn new(capacity: usize) -> Self {
89        let nanos = SystemTime::now()
90            .duration_since(UNIX_EPOCH)
91            .map_or(0, |d| d.as_nanos() as u64);
92        let n = HUB_COUNTER.fetch_add(1, Ordering::Relaxed);
93        let (wake, _) = watch::channel(0);
94        Self {
95            inner: Arc::new(Inner {
96                epoch: format!("{:x}", nanos ^ n.rotate_left(48)),
97                capacity: capacity.max(1),
98                log: Mutex::new(Log::default()),
99                wake,
100            }),
101        }
102    }
103
104    /// Record a state change and wake every subscribed connection.
105    /// A change with no accounts is ignored; `extra` members are not kept.
106    pub fn publish(&self, change: StateChange) {
107        if change.changed.values().all(BTreeMap::is_empty) {
108            return;
109        }
110        let seq = {
111            let mut log = self.lock();
112            log.seq += 1;
113            let seq = log.seq;
114            for (account, types) in &change.changed {
115                let entry = log.latest.entry(account.clone()).or_default();
116                for (name, state) in types {
117                    entry.insert(name.clone(), state.clone());
118                }
119            }
120            log.entries.push_back((seq, change.changed));
121            while log.entries.len() > self.inner.capacity {
122                log.entries.pop_front();
123            }
124            seq
125        };
126        self.inner.wake.send_replace(seq);
127    }
128
129    /// The `pushState` token for everything published so far.
130    pub fn push_state(&self) -> String {
131        self.token(self.lock().seq)
132    }
133
134    fn lock(&self) -> MutexGuard<'_, Log> {
135        // A panic while holding the lock leaves the log consistent: every
136        // mutation above is a single push or insert.
137        self.inner
138            .log
139            .lock()
140            .unwrap_or_else(PoisonError::into_inner)
141    }
142
143    fn token(&self, seq: u64) -> String {
144        format!("{}.{seq}", self.inner.epoch)
145    }
146
147    /// The sequence number a token of this hub names, if it is one.
148    fn parse_token(&self, token: &str) -> Option<u64> {
149        let (epoch, seq) = token.split_once('.')?;
150        if epoch != self.inner.epoch {
151            return None;
152        }
153        seq.parse().ok()
154    }
155
156    /// The changes after `since`, merged, and the sequence they bring the
157    /// reader to; `None` when there are none.
158    fn changes_since(&self, since: u64) -> Option<(WsStateChange, u64)> {
159        let log = self.lock();
160        if log.seq <= since {
161            return None;
162        }
163        let complete = log
164            .entries
165            .front()
166            .is_some_and(|(first, _)| *first <= since + 1);
167        let merged = if complete {
168            let mut merged: Changed = BTreeMap::new();
169            for (_, changed) in log.entries.iter().filter(|(seq, _)| *seq > since) {
170                for (account, types) in changed {
171                    let entry = merged.entry(account.clone()).or_default();
172                    for (name, state) in types {
173                        entry.insert(name.clone(), state.clone());
174                    }
175                }
176            }
177            merged
178        } else {
179            log.latest.clone()
180        };
181        let seq = log.seq;
182        drop(log);
183        Some((
184            WsStateChange::new(StateChange::new(merged), Some(self.token(seq))),
185            seq,
186        ))
187    }
188}
189
190impl PushSource for PushHub {
191    fn subscribe(&mut self, enable: &WebSocketPushEnable) -> BoxStream<'static, WsStateChange> {
192        let mut wake = self.inner.wake.subscribe();
193        wake.mark_unchanged();
194        let current = self.lock().seq;
195        let start = enable
196            .push_state
197            .as_deref()
198            .and_then(|t| self.parse_token(t))
199            .filter(|seq| *seq <= current)
200            .unwrap_or(current);
201        let hub = self.clone();
202        futures::stream::unfold((hub, wake, start), |(hub, mut wake, since)| async move {
203            loop {
204                if let Some((change, seq)) = hub.changes_since(since) {
205                    return Some((change, (hub, wake, seq)));
206                }
207                if wake.changed().await.is_err() {
208                    return None;
209                }
210            }
211        })
212        .boxed()
213    }
214}