Skip to main content

coven_sync/
sequence_reload_operation.rs

1//! An explicit reload retains its selected bodies and common target (§16.5, E6).
2use super::*;
3use crate::sequence_sync::OperationState;
4use coven_database::operation_kind;
5use coven_database::{NewOperation, OperationRecord};
6use serde::{Deserialize, Serialize};
7
8#[derive(Serialize, Deserialize)]
9enum ReloadWork {
10    Loading { target: u64, selections: Vec<Selection> },
11    Installed,
12}
13
14#[derive(Serialize, Deserialize)]
15enum Selection {
16    Stored(#[serde(with = "announcement")] (Slot, SnapshotAnnouncement)),
17    Current(#[serde(with = "crate::pending_encoding::audience")] Audience),
18}
19
20impl OperationState for ReloadWork {}
21
22/// The newest usable announcement of each readable audience (§16.2).
23fn selections(history: &History, member: &MemberIdentity) -> Vec<Selection> {
24    history
25        .state
26        .readable_audiences(&member.member())
27        .into_iter()
28        .map(|audience| {
29            match history.announcements.iter().rev().find(|(_, announcement)| {
30                announcement.snapshot.audience == audience && history.usable(announcement)
31            }) {
32                Some((slot, announcement)) => Selection::Stored((*slot, announcement.clone())),
33                None => Selection::Current(audience),
34            }
35        })
36        .collect()
37}
38
39impl SequenceSync {
40    /// Reload readable audiences from selected snapshots and retained slots,
41    /// preserving waiting writes. Repeated calls resume the same journal (§16.5).
42    pub async fn reload_from_snapshot(&self) -> Result<(), SyncError> {
43        let mut session = self.session.lock().await;
44        if let crate::SequenceStatus::Stopped(_) = self.state.status() {
45            return self.state.check();
46        }
47        let member = self.member.read()?.ok_or(coven_storage::StorageFailure::MemberKeysMissing)?;
48        let mut ring = self.ring(&mut session, &member).await?;
49        let record = match self.database.first_operation(operation_kind::SEQUENCE_RELOAD).await? {
50            Some(record) => {
51                self.retry_operation(record.id).await?;
52                record
53            }
54            None => {
55                self.read_forward(&mut session, &mut ring, &member).await?;
56                self.settle_open(&mut session, &mut ring, &member).await?;
57                // An explicit reload chooses the newest applicable announcements
58                // (§16.2).
59                let selections = selections(&session.history, &member);
60                if !selections.iter().any(|selection| matches!(selection, Selection::Stored(_))) {
61                    return Err(coven_storage::StorageFailure::NotFound
62                        .with_source("no usable snapshot is announced for a readable audience")
63                        .into());
64                }
65                let data = serde_json::to_vec(&ReloadWork::Loading {
66                    target: session.through,
67                    selections,
68                })?;
69                let kind = operation_kind::SEQUENCE_RELOAD.to_owned();
70                let started_by = "reload_from_snapshot".to_owned();
71                let id = self
72                    .database
73                    .start_operation(NewOperation {
74                        kind: kind.clone(),
75                        data: data.clone(),
76                        started_by: started_by.clone(),
77                        pauses_writes: false,
78                    })
79                    .await?;
80                OperationRecord { id, kind, last_step: 0, data, started_by }
81            }
82        };
83        Box::pin(self.run_reload(&mut session, &mut ring, &member, record)).await
84    }
85
86    /// Finish a retained reload before advancing its applied prefix or claiming.
87    pub(crate) async fn resume_reload(
88        &self,
89        session: &mut Session,
90        ring: &mut StoreKeyring,
91        member: &MemberIdentity,
92    ) -> Result<(), SyncError> {
93        if let Some(record) = self.database.first_operation(operation_kind::SEQUENCE_RELOAD).await?
94        {
95            // Reload staging lives on the heap; ordinary readers and their
96            // callers need not reserve its future on every stack frame.
97            Box::pin(self.run_reload(session, ring, member, record)).await?;
98        }
99        Ok(())
100    }
101
102    async fn run_reload(
103        &self,
104        session: &mut Session,
105        ring: &mut StoreKeyring,
106        member: &MemberIdentity,
107        record: OperationRecord,
108    ) -> Result<(), SyncError> {
109        if !self.operation_ready(&record, ring).await? {
110            return Err(SyncError::ReloadPending(record.id));
111        }
112        let id = record.id;
113        let scope = self.waits.begin_attempt(id);
114        if let Err(error) = coven_database::in_commit_scope(
115            scope,
116            self.advance_reload(session, ring, member, record),
117        )
118        .await
119        {
120            // A reload whose selection retention deleted has ended (§16.5).
121            if self.database.operation(id).await?.is_some() {
122                self.record_operation_error(
123                    id,
124                    crate::OperationKind::ReloadFromSnapshot,
125                    crate::sequence_sync::OperationFailure::Returned(&error),
126                    ring,
127                )
128                .await?;
129            }
130            return Err(error);
131        }
132        self.waits.operation_advanced(id);
133        Ok(())
134    }
135
136    async fn advance_reload(
137        &self,
138        session: &mut Session,
139        ring: &mut StoreKeyring,
140        member: &MemberIdentity,
141        record: OperationRecord,
142    ) -> Result<(), SyncError> {
143        let work: ReloadWork = serde_json::from_slice(&record.data)?;
144        loop {
145            let ReloadWork::Loading { target, selections: chosen } = &work else {
146                // Cancellation may have followed the database commit before its
147                // in-memory installation. Reconstruct committed state on resume:
148                // both reads first, so a failed or cancelled one leaves the
149                // session's history and applied prefix as they were.
150                let originals = self.database.original_slots().await?;
151                let through = self.database.applied_slot().await?;
152                let history = History::restore(&originals, self.store(), ring, member)?;
153                session.history = history;
154                session.through = through;
155                session.floor = None;
156                self.database.finish_operation(record.id).await?;
157                return Ok(());
158            };
159            let floor = self.read_floor(session.floor.as_ref(), ring, member).await?;
160            let first = chosen
161                .iter()
162                .map(|selection| match selection {
163                    Selection::Stored((_, announcement)) => announcement.covers,
164                    Selection::Current(_) => session.through,
165                })
166                .min()
167                .expect("readable store audience");
168            // Retention deletes what a selection needs only once a newer
169            // snapshot has passed grace. The reload then ends with the error,
170            // and the next call selects afresh (§16.5).
171            if let Some(floor) =
172                floor.as_ref().filter(|floor| floor.header.first.get() > first.saturating_add(1))
173            {
174                self.database.finish_operation(record.id).await?;
175                return Err(coven_storage::StorageFailure::NotFound
176                    .with_source(format!(
177                        "slots {} to {} this reload needs were deleted",
178                        first + 1,
179                        floor.header.first.get() - 1
180                    ))
181                    .into());
182            }
183            let mut starts = Vec::new();
184            for selection in chosen {
185                let start = match selection {
186                    Selection::Stored((_, announcement)) => {
187                        match self.select(announcement.clone(), ring, None).await {
188                            Ok(snapshot) => ReloadStart::Stored(snapshot),
189                            Err(error) => {
190                                // A body retention deleted ends it the same way.
191                                let deleted = matches!(&error, SyncError::Storage(error)
192                                    if error.failure() == coven_storage::StorageFailure::NotFound);
193                                let result = release(starts, Err(error)).await;
194                                if deleted {
195                                    self.database.finish_operation(record.id).await?;
196                                }
197                                return result;
198                            }
199                        }
200                    }
201                    Selection::Current(audience) => ReloadStart::Current(audience.clone()),
202                };
203                starts.push(start);
204            }
205            let (history, through) = match floor.as_ref().filter(|floor| floor.header.at > *target)
206            {
207                // A later floor can require newer authentication history without
208                // changing the selected bodies or their installation target.
209                Some(floor) => match self.floor_history(floor, ring, member).await {
210                    Ok((history, _)) => (history, floor.header.at),
211                    Err(error) => return release(starts, Err(error)).await,
212                },
213                None => (session.history.clone(), session.through),
214            };
215            let operation = match ReloadWork::Installed.update(&record) {
216                Ok(operation) => operation,
217                Err(error) => return release(starts, Err(error)).await,
218            };
219            let inputs = ReloadInputs {
220                target: *target,
221                history,
222                through,
223                operation: Some(operation),
224                rebuilds: Vec::new(),
225                store_history: None,
226            };
227            match self
228                .install_selected(session, starts, inputs, ring, member, floor.as_ref(), false)
229                .await?
230            {
231                Some(newer) => session.floor = Some(newer),
232                None => {
233                    self.database.finish_operation(record.id).await?;
234                    return Ok(());
235                }
236            }
237        }
238    }
239}
240
241mod announcement {
242    use super::*;
243    pub(super) fn serialize<S: serde::Serializer>(
244        value: &(Slot, SnapshotAnnouncement),
245        serializer: S,
246    ) -> Result<S::Ok, S::Error> {
247        (value.0.get(), value.1.encode(value.0).map_err(serde::ser::Error::custom)?)
248            .serialize(serializer)
249    }
250    pub(super) fn deserialize<'de, D: serde::Deserializer<'de>>(
251        deserializer: D,
252    ) -> Result<(Slot, SnapshotAnnouncement), D::Error> {
253        let (slot, bytes) = <(u64, Vec<u8>)>::deserialize(deserializer)?;
254        let slot = Slot::new(slot).ok_or_else(|| {
255            serde::de::Error::invalid_value(
256                serde::de::Unexpected::Unsigned(slot),
257                &"a positive slot number",
258            )
259        })?;
260        Ok((slot, SnapshotAnnouncement::decode(&bytes, slot).map_err(serde::de::Error::custom)?))
261    }
262}
263
264#[cfg(test)]
265#[path = "sequence_reload_operation_tests.rs"]
266mod tests;