Skip to main content

jmap_server/
scoped_state.rs

1//! [`ScopedState`]: shared in-memory backend state that can open a
2//! draft-ietf-jmap-conditional-02 [`SetScope`] (docs/design/conditional.md
3//! §7).
4//!
5//! **Demonstration quality.** This is what the in-repo memory reference
6//! backends use to implement [`ConditionalBackend::begin_set`]: one gate
7//! per backend (or shared between several), a whole-store clone as the
8//! undo log, and final-state checks run at commit. It is correct, but it
9//! serializes every scoped method behind one lock and copies the whole
10//! store per atomic call. A production backend uses its storage engine's
11//! transactions instead.
12//!
13//! [`ConditionalBackend::begin_set`]: crate::ConditionalBackend::begin_set
14
15use std::fmt;
16use std::future::ready;
17use std::ops::{Deref, DerefMut};
18use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
19
20use tokio::sync::OwnedMutexGuard;
21
22use crate::conditional::{
23    CommitError, CommitFuture, DeferredFailure, RollbackFuture, SetMode, SetScope, SetScopeId,
24    SetScopeRequest, current_set_scope,
25};
26
27/// The lock a [`ScopedState`] waits on while another task's [`SetScope`]
28/// is open.
29///
30/// Each [`ScopedState::new`] makes its own gate. Backends that call each
31/// other inside one method (a binding crate over two stores, the testjig)
32/// share one through [`ScopedState::with_gate`]: with separate gates, two
33/// scopes opened in opposite orders deadlock. A task running in the scope
34/// that holds the gate passes it, on every state that shares it.
35pub struct ScopeGate {
36    /// Held by the open scope for its whole life.
37    lock: Arc<tokio::sync::Mutex<()>>,
38    /// The open scope and its mode, while one is open.
39    owner: Mutex<Option<(SetScopeId, SetMode)>>,
40}
41
42impl ScopeGate {
43    /// A gate with no scope open.
44    pub fn new() -> Arc<Self> {
45        Arc::new(Self {
46            lock: Arc::new(tokio::sync::Mutex::new(())),
47            owner: Mutex::new(None),
48        })
49    }
50
51    /// The open scope and its mode, if any.
52    fn owner(&self) -> Option<(SetScopeId, SetMode)> {
53        *self.owner.lock().unwrap_or_else(PoisonError::into_inner)
54    }
55
56    fn set_owner(&self, owner: Option<(SetScopeId, SetMode)>) {
57        *self.owner.lock().unwrap_or_else(PoisonError::into_inner) = owner;
58    }
59
60    /// The mode of the open scope, when the running task is in it.
61    fn owned_by_current(&self) -> Option<SetMode> {
62        let current = current_set_scope()?;
63        self.owner()
64            .and_then(|(id, mode)| (id == current).then_some(mode))
65    }
66}
67
68impl fmt::Debug for ScopeGate {
69    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70        f.debug_struct("ScopeGate")
71            .field("owner", &self.owner())
72            .finish_non_exhaustive()
73    }
74}
75
76/// Access to a [`ScopedState`]'s value, from [`ScopedState::lock`] or
77/// [`ScopedState::lock_unscoped`].
78///
79/// A `std::sync::MutexGuard` underneath: do not hold it across an
80/// `.await`.
81pub struct ScopedGuard<'a, T>(MutexGuard<'a, T>);
82
83impl<T> Deref for ScopedGuard<'_, T> {
84    type Target = T;
85
86    fn deref(&self) -> &T {
87        &self.0
88    }
89}
90
91impl<T> DerefMut for ScopedGuard<'_, T> {
92    fn deref_mut(&mut self) -> &mut T {
93        &mut self.0
94    }
95}
96
97impl<T: fmt::Debug> fmt::Debug for ScopedGuard<'_, T> {
98    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
99        self.0.fmt(f)
100    }
101}
102
103/// A final-state check run when an atomic scope commits: given the state
104/// before the scope opened and the state it would commit, the changes that
105/// break a cross-object constraint (§4.2). Empty means commit.
106type Validate<T> = Box<dyn FnOnce(&T, &T) -> Vec<DeferredFailure> + Send>;
107
108/// A memory backend's state behind a mutex, gated by a [`ScopeGate`] so a
109/// conditional-02 [`SetScope`] can isolate it and roll it back
110/// (docs/design/conditional.md §7).
111///
112/// **Demonstration quality.** It is correct, but it serializes every scoped
113/// method behind one gate and clones the whole value per atomic call. A
114/// production backend uses its storage engine's transactions instead.
115///
116/// Replaces `Arc<Mutex<Inner>>`. Cloning shares the state and the gate.
117///
118/// - [`lock`](Self::lock) is for async backend methods, reads included: it
119///   waits while another task's scope is open, so no caller sees a change
120///   an atomic method may still undo. A task in the open scope passes.
121/// - [`lock_unscoped`](Self::lock_unscoped) is for sync code and seeding
122///   helpers; it never waits on the gate.
123/// - [`open`](Self::open) is how `begin_set` opens a scope.
124///
125/// With no scope ever opened, as in a deployment that does not opt in to
126/// conditional-02, the gate is always free and `lock` is a plain mutex
127/// lock.
128pub struct ScopedState<T> {
129    value: Arc<Mutex<T>>,
130    gate: Arc<ScopeGate>,
131}
132
133impl<T> Clone for ScopedState<T> {
134    fn clone(&self) -> Self {
135        Self {
136            value: Arc::clone(&self.value),
137            gate: Arc::clone(&self.gate),
138        }
139    }
140}
141
142impl<T: Default> Default for ScopedState<T> {
143    fn default() -> Self {
144        Self::new(T::default())
145    }
146}
147
148impl<T: fmt::Debug> fmt::Debug for ScopedState<T> {
149    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
150        f.debug_struct("ScopedState")
151            .field("value", &self.value)
152            .field("gate", &self.gate)
153            .finish()
154    }
155}
156
157impl<T> ScopedState<T> {
158    /// `value`, behind a gate of its own.
159    pub fn new(value: T) -> Self {
160        Self::with_gate(value, ScopeGate::new())
161    }
162
163    /// `value`, behind `gate`, which other states may share.
164    pub fn with_gate(value: T, gate: Arc<ScopeGate>) -> Self {
165        Self {
166            value: Arc::new(Mutex::new(value)),
167            gate,
168        }
169    }
170
171    /// The gate, to share with another state through
172    /// [`with_gate`](Self::with_gate).
173    pub fn gate(&self) -> &Arc<ScopeGate> {
174        &self.gate
175    }
176
177    /// Lock the value for an async backend method.
178    ///
179    /// Waits while a scope opened by another task holds the gate; passes
180    /// at once when the running task is in the open scope
181    /// ([`current_set_scope`]), or no scope is open. A poisoned mutex is
182    /// taken anyway: the value is plain data.
183    pub async fn lock(&self) -> ScopedGuard<'_, T> {
184        if self.gate.owned_by_current().is_none() {
185            // Wait for any open scope to end, and take the value before
186            // releasing the gate: released first, a scope could open and
187            // snapshot in between, and this guard's writes would then land
188            // inside that scope (and be lost if it rolls back). Taken
189            // first, a scope opening next waits for this guard to snapshot.
190            let _gate = self.gate.lock.lock().await;
191            return self.lock_unscoped();
192        }
193        self.lock_unscoped()
194    }
195
196    /// Lock the value without waiting on the gate, for sync code and
197    /// seeding helpers that never run alongside a scoped method.
198    pub fn lock_unscoped(&self) -> ScopedGuard<'_, T> {
199        ScopedGuard(self.value.lock().unwrap_or_else(PoisonError::into_inner))
200    }
201
202    /// Whether the running task is in an open atomic scope on this
203    /// state's gate.
204    ///
205    /// Per-object methods skip their cross-object checks (unique names,
206    /// cycles, single default, quotas) when it is true: the scope's
207    /// `validate` runs them against the final state at commit, so a swap
208    /// that passes through a conflict still commits (§4.2).
209    pub fn deferring(&self) -> bool {
210        self.gate.owned_by_current() == Some(SetMode::Atomic)
211    }
212}
213
214impl<T: Clone + Send + 'static> ScopedState<T> {
215    /// Open the [`SetScope`] for `request`, for
216    /// [`ConditionalBackend::begin_set`](crate::ConditionalBackend::begin_set).
217    ///
218    /// Waits for the gate and records `request.scope` as its owner, so
219    /// calls made in that scope pass [`lock`](Self::lock) and every other
220    /// task waits until the scope ends. If `request.scope` already holds
221    /// the gate (a second state sharing it, opened for the same method),
222    /// it does not wait.
223    ///
224    /// [`SetMode::Atomic`] snapshots the value. Rollback, or dropping the
225    /// scope, restores the snapshot, so the state string and change log
226    /// held in `T` are as before (§4.2). Commit first runs
227    /// `validate(&before, &after)`; any failures it returns restore the
228    /// snapshot and reject the commit with [`CommitError::Rejected`].
229    ///
230    /// [`SetMode::Isolated`] takes no snapshot and never calls `validate`:
231    /// each change stands on its own (§6.1), and the dispatcher writes
232    /// nothing before the handler runs. Ending the scope only releases
233    /// the gate.
234    pub async fn open<V>(&self, request: SetScopeRequest<'_>, validate: V) -> Box<dyn SetScope>
235    where
236        V: FnOnce(&T, &T) -> Vec<DeferredFailure> + Send + 'static,
237    {
238        let held = self.gate.owner().is_some_and(|(id, _)| id == request.scope);
239        let permit = if held {
240            None
241        } else {
242            let permit = Arc::clone(&self.gate.lock).lock_owned().await;
243            self.gate.set_owner(Some((request.scope, request.mode)));
244            Some(permit)
245        };
246        let atomic = request.mode == SetMode::Atomic;
247        let snapshot = atomic.then(|| self.lock_unscoped().clone());
248        Box::new(StateScope {
249            value: Arc::clone(&self.value),
250            gate: Arc::clone(&self.gate),
251            permit,
252            snapshot,
253            validate: atomic.then(|| Box::new(validate) as Validate<T>),
254        })
255    }
256}
257
258/// The [`SetScope`] [`ScopedState::open`] returns.
259struct StateScope<T> {
260    value: Arc<Mutex<T>>,
261    gate: Arc<ScopeGate>,
262    /// The gate, when this scope took it (not when another state of the
263    /// same scope did).
264    permit: Option<OwnedMutexGuard<()>>,
265    /// The value before the scope, for an atomic scope not yet ended.
266    snapshot: Option<T>,
267    validate: Option<Validate<T>>,
268}
269
270impl<T> StateScope<T> {
271    /// Put the snapshot back, if there is one.
272    fn restore(&mut self) {
273        if let Some(before) = self.snapshot.take() {
274            *self.value.lock().unwrap_or_else(PoisonError::into_inner) = before;
275        }
276    }
277}
278
279impl<T: Send + 'static> SetScope for StateScope<T> {
280    fn commit(mut self: Box<Self>) -> CommitFuture {
281        let failures = match (self.snapshot.as_ref(), self.validate.take()) {
282            (Some(before), Some(validate)) => {
283                let after = self.value.lock().unwrap_or_else(PoisonError::into_inner);
284                validate(before, &after)
285            }
286            _ => Vec::new(),
287        };
288        let result = if failures.is_empty() {
289            self.snapshot = None;
290            Ok(())
291        } else {
292            self.restore();
293            Err(CommitError::Rejected(failures))
294        };
295        drop(self);
296        Box::pin(ready(result))
297    }
298
299    fn rollback(self: Box<Self>) -> RollbackFuture {
300        // Drop restores the snapshot and releases the gate.
301        drop(self);
302        Box::pin(ready(()))
303    }
304}
305
306impl<T> Drop for StateScope<T> {
307    fn drop(&mut self) {
308        // A scope not committed rolls back (the SetScope contract), before
309        // the gate is released below so no waiter sees the undone writes.
310        self.restore();
311        if let Some(permit) = self.permit.take() {
312            self.gate.set_owner(None);
313            drop(permit);
314        }
315    }
316}
317
318#[cfg(test)]
319mod tests {
320    use std::collections::BTreeMap;
321    use std::future::Future;
322    use std::pin::pin;
323    use std::task::{Context, Poll, Waker};
324
325    use jmap_types::{Id, SetError};
326    use serde_json::Value;
327
328    use super::*;
329    use crate::SetErrorType;
330    use crate::conditional::{SetOp, in_set_scope};
331
332    /// A memory store with a state counter and change log, like the
333    /// memory backends' `Inner`.
334    #[derive(Debug, Clone, Default, PartialEq)]
335    struct Store {
336        names: BTreeMap<String, String>,
337        state: u64,
338        log: Vec<String>,
339    }
340
341    impl Store {
342        fn write(&mut self, id: &str, name: &str) {
343            self.names.insert(id.to_owned(), name.to_owned());
344            self.state += 1;
345            self.log.push(id.to_owned());
346        }
347    }
348
349    fn seeded() -> ScopedState<Store> {
350        let state = ScopedState::<Store>::default();
351        state.lock_unscoped().write("a", "one");
352        state
353    }
354
355    /// `fut`'s output, which must be ready on the first poll: the call
356    /// did not wait.
357    fn now<F: Future>(fut: F) -> F::Output {
358        let mut cx = Context::from_waker(Waker::noop());
359        match pin!(fut).poll(&mut cx) {
360            Poll::Ready(out) => out,
361            Poll::Pending => panic!("waited, but nothing should block"),
362        }
363    }
364
365    /// Whether `fut` would wait on its first poll.
366    fn waits<F: Future>(fut: F) -> bool {
367        let mut cx = Context::from_waker(Waker::noop());
368        pin!(fut).poll(&mut cx).is_pending()
369    }
370
371    fn request(mode: SetMode) -> SetScopeRequest<'static> {
372        SetScopeRequest::new("Probe/set", "Probe", None, mode, &Value::Null)
373    }
374
375    fn no_checks(_: &Store, _: &Store) -> Vec<DeferredFailure> {
376        Vec::new()
377    }
378
379    #[test]
380    fn lock_never_waits_with_no_scope_open() {
381        let state = seeded();
382        assert_eq!(now(state.lock()).names["a"], "one");
383        // Nor once a scope has come and gone.
384        let scope = now(state.open(request(SetMode::Atomic), no_checks));
385        now(scope.commit()).unwrap();
386        now(state.lock()).write("b", "two");
387        assert_eq!(state.lock_unscoped().names.len(), 2);
388    }
389
390    #[tokio::test]
391    async fn unscoped_read_and_write_wait_for_another_tasks_scope() {
392        let state = seeded();
393        let req = request(SetMode::Atomic);
394        let scope = state.open(req, no_checks).await;
395        in_set_scope(req.scope, async { state.lock().await.write("a", "scoped") }).await;
396
397        let reader = state.clone();
398        let read = tokio::spawn(async move { reader.lock().await.names["a"].clone() });
399        let writer = state.clone();
400        let write = tokio::spawn(async move { writer.lock().await.write("b", "outside") });
401        for _ in 0..10 {
402            tokio::task::yield_now().await;
403        }
404        assert!(!read.is_finished(), "a read must not see the open scope");
405        assert!(!write.is_finished(), "a write must wait for the open scope");
406
407        scope.rollback().await;
408        // The reader never saw "scoped"; the writer landed after rollback.
409        assert_eq!(read.await.unwrap(), "one");
410        write.await.unwrap();
411        let after = state.lock_unscoped();
412        assert_eq!(after.names["a"], "one");
413        assert_eq!(after.names["b"], "outside");
414        assert_eq!(after.log, ["a", "b"]);
415    }
416
417    /// Unscoped writes racing scopes that roll back are never lost: an
418    /// unscoped `lock` holds the gate until it has the value, so no scope
419    /// can snapshot between the two and restore over the write.
420    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
421    async fn unscoped_writes_racing_rolled_back_scopes_are_kept() {
422        const WRITES: u64 = 2000;
423        let state = ScopedState::new(0_u64);
424        let writers: Vec<_> = (0..2)
425            .map(|_| {
426                let state = state.clone();
427                tokio::spawn(async move {
428                    for _ in 0..WRITES {
429                        *state.lock().await += 1;
430                        tokio::task::yield_now().await;
431                    }
432                })
433            })
434            .collect();
435        let scoper = {
436            let state = state.clone();
437            tokio::spawn(async move {
438                for _ in 0..WRITES {
439                    let req = request(SetMode::Atomic);
440                    let scope = state.open(req, |_: &u64, _: &u64| Vec::new()).await;
441                    in_set_scope(req.scope, async { *state.lock().await += 1_000_000 }).await;
442                    scope.rollback().await;
443                }
444            })
445        };
446        for w in writers {
447            w.await.unwrap();
448        }
449        scoper.await.unwrap();
450        assert_eq!(*state.lock_unscoped(), 2 * WRITES);
451    }
452
453    #[test]
454    fn scope_owner_reenters_without_waiting() {
455        let state = seeded();
456        let req = request(SetMode::Isolated);
457        let _scope = now(state.open(req, no_checks));
458        let len = now(in_set_scope(req.scope, async {
459            state.lock().await.write("b", "two");
460            state.lock().await.write("c", "three");
461            state.lock().await.names.len()
462        }));
463        assert_eq!(len, 3);
464        // Outside the scope, the same lock waits.
465        assert!(waits(state.lock()));
466    }
467
468    #[test]
469    fn states_sharing_a_gate_do_not_deadlock() {
470        let a = seeded();
471        let b = ScopedState::with_gate(Store::default(), Arc::clone(a.gate()));
472        let req = request(SetMode::Atomic);
473        let scope_a = now(a.open(req, no_checks));
474        // Opening the second state for the same scope does not wait on
475        // the gate the first already holds.
476        let scope_b = now(b.open(req, no_checks));
477        now(in_set_scope(req.scope, async {
478            a.lock().await.write("a", "changed");
479            b.lock().await.write("x", "new");
480            a.lock().await.write("a", "again");
481        }));
482        assert!(waits(b.lock()), "b is gated by a's scope");
483
484        // b's scope rolls back b only and keeps the gate held.
485        now(scope_b.rollback());
486        assert_eq!(*b.lock_unscoped(), Store::default());
487        assert!(waits(a.lock()));
488        now(scope_a.commit()).unwrap();
489        assert_eq!(now(a.lock()).names["a"], "again");
490        assert_eq!(*now(b.lock()), Store::default());
491    }
492
493    #[test]
494    fn rollback_restores_state_and_change_log() {
495        let state = seeded();
496        let before = state.lock_unscoped().clone();
497        let req = request(SetMode::Atomic);
498        let scope = now(state.open(req, no_checks));
499        now(in_set_scope(req.scope, async {
500            let mut s = state.lock().await;
501            s.write("a", "renamed");
502            s.write("b", "created");
503        }));
504        assert_eq!(state.lock_unscoped().state, 3);
505        now(scope.rollback());
506        assert_eq!(*state.lock_unscoped(), before);
507        assert_eq!(before.state, 1);
508        assert_eq!(before.log, ["a"]);
509    }
510
511    #[test]
512    fn dropping_a_scope_rolls_back_and_frees_the_gate() {
513        let state = seeded();
514        let before = state.lock_unscoped().clone();
515        let req = request(SetMode::Atomic);
516        let scope = now(state.open(req, no_checks));
517        now(in_set_scope(req.scope, async {
518            state.lock().await.write("b", "two")
519        }));
520        drop(scope);
521        assert_eq!(*now(state.lock()), before);
522    }
523
524    #[test]
525    fn commit_keeps_changes_validated_against_the_final_state() {
526        let state = seeded();
527        let req = request(SetMode::Atomic);
528        let scope = now(state.open(req, |before: &Store, after: &Store| {
529            assert_eq!(before.names["a"], "one");
530            assert_eq!(after.names["a"], "two");
531            Vec::new()
532        }));
533        now(in_set_scope(req.scope, async {
534            state.lock().await.write("a", "two")
535        }));
536        now(scope.commit()).unwrap();
537        let after = state.lock_unscoped();
538        assert_eq!((after.names["a"].as_str(), after.state), ("two", 2));
539    }
540
541    #[test]
542    fn rejected_commit_restores_and_reports_the_failures() {
543        let state = seeded();
544        let before = state.lock_unscoped().clone();
545        let req = request(SetMode::Atomic);
546        // Final-state uniqueness: no two objects share a name.
547        let scope = now(state.open(req, |_: &Store, after: &Store| {
548            let mut seen = BTreeMap::new();
549            after
550                .names
551                .iter()
552                .filter(|(_, name)| seen.insert(name.as_str(), ()).is_some())
553                .map(|(id, _)| {
554                    DeferredFailure::new(
555                        SetOp::Update(Id::new_validated(id).unwrap()),
556                        SetError::new(SetErrorType::AlreadyExists),
557                    )
558                })
559                .collect()
560        }));
561        now(in_set_scope(req.scope, async {
562            state.lock().await.write("b", "one")
563        }));
564        let Err(CommitError::Rejected(failures)) = now(scope.commit()) else {
565            panic!("a duplicate name must reject the commit");
566        };
567        assert_eq!(failures.len(), 1);
568        assert_eq!(
569            failures[0].op,
570            SetOp::Update(Id::new_validated("b").unwrap())
571        );
572        assert_eq!(
573            *now(state.lock()),
574            before,
575            "rejected: rolled back, gate free"
576        );
577    }
578
579    #[test]
580    fn isolated_scope_keeps_its_writes_and_skips_validate() {
581        let state = seeded();
582        let req = request(SetMode::Isolated);
583        let scope = now(
584            state.open(req, |_: &Store, _: &Store| -> Vec<DeferredFailure> {
585                panic!("an isolated scope has no final-state check")
586            }),
587        );
588        now(in_set_scope(req.scope, async {
589            assert!(!state.deferring());
590            state.lock().await.write("b", "two");
591        }));
592        now(scope.commit()).unwrap();
593        assert_eq!(now(state.lock()).names.len(), 2);
594
595        // Rolling back an isolated scope keeps what it wrote: each change
596        // stood on its own (§6.1).
597        let req = request(SetMode::Isolated);
598        let scope = now(state.open(req, no_checks));
599        now(in_set_scope(req.scope, async {
600            state.lock().await.write("c", "three")
601        }));
602        now(scope.rollback());
603        assert_eq!(now(state.lock()).names.len(), 3);
604    }
605
606    #[test]
607    fn deferring_only_inside_the_running_atomic_scope() {
608        let state = seeded();
609        assert!(!state.deferring());
610        let req = request(SetMode::Atomic);
611        let scope = now(state.open(req, no_checks));
612        assert!(!state.deferring(), "not in the scope");
613        assert!(now(in_set_scope(req.scope, async { state.deferring() })));
614        let other = SetScopeId::next();
615        assert!(!now(in_set_scope(other, async { state.deferring() })));
616        drop(scope);
617        assert!(!now(in_set_scope(req.scope, async { state.deferring() })));
618    }
619}