Skip to main content

coven_sync/
sequence_sync.rs

1//! Read, apply and claim the shared sequence in one serialized installation.
2
3use crate::{
4    chunk_reader::PartPlaintext,
5    floor_object::FloorObject,
6    history::{History, KeyCopy},
7    object_input::ObjectInput,
8    slot_object::{self, ReceivedSlot, SlotBody},
9    snapshot_object, PendingReason, PendingRecord, PendingSubject, Prerequisite, SequenceState,
10    SequenceStatus, SyncError,
11};
12use coven_crypto::{
13    custody::{KeySession, PersonEntries},
14    MemberIdentity, StoreKeyring,
15};
16use coven_database::operation_kind;
17use coven_database::{
18    IncomingSlot, LoadStep, NewOperation, ProviderAccessChange, SlotContent, StoreDatabase,
19};
20use coven_format::{
21    floor::OriginalSlot,
22    sealed_slot::SlotKind,
23    sequence::{Purpose, SlotFrame},
24};
25use coven_foundation::{
26    files::StoreDir,
27    id_source::{DeviceId, StoreId},
28};
29use coven_merge::{Audience, Slot};
30use coven_storage::{ObjectPath, Storage, StorageFailure};
31use std::sync::Arc;
32use tokio::sync::Mutex;
33
34pub(crate) struct Session {
35    history: History,
36    through: u64,
37    floor: Option<FloorObject>,
38    /// The floor revision `read_forward` last authenticated. Reading it back
39    /// unchanged needs no second check: the history through its `at`, which
40    /// the check reads, never changes once applied.
41    checked_floor: Option<coven_storage::StoredObject>,
42    blocked: Option<PendingRecord>,
43    /// The next slot a member without store keys inspects for its copies.
44    scanned: Slot,
45    /// How far the scan for the circle key a stuck slot waits on got, while
46    /// this owner is open (§5.4, §12.1).
47    stuck_scan: Option<sequence_bootstrap::StuckScan>,
48    /// Committed originals wait for store keys before their history is
49    /// reconstructed: custody held none when this owner opened.
50    locked: bool,
51}
52
53/// Owns sequence progress. App commits use the database independently; every
54/// publisher shares this owner's serialization and actual blocked state.
55#[derive(Clone)]
56pub struct SequenceSync {
57    database: StoreDatabase,
58    storage: Arc<dyn Storage>,
59    keys: Arc<KeySession<StoreKeyring>>,
60    member: Arc<KeySession<MemberIdentity>>,
61    /// The person's restore code and S3 key: the code's store name follows
62    /// applied renames (§13.1), and both are deleted when they leave (§14.1).
63    person: Arc<PersonEntries>,
64    /// The store's directory, whose recorded location is read for the code
65    /// that replaces an unreadable saved entry (§13.1).
66    directory: StoreDir,
67    device: DeviceId,
68    state: Arc<SequenceState>,
69    clock: coven_foundation::clock::ClockRef,
70    ids: coven_foundation::id_source::IdSourceRef,
71    waits: Arc<crate::RetryWaits>,
72    files: crate::Files,
73    /// The steps `unlock` reports as it loads the store (§13.4).
74    progress: coven_foundation::progress::ProgressChannel<LoadStep>,
75    session: Arc<Mutex<Session>>,
76}
77
78impl SequenceSync {
79    /// Reconstruct historical bindings once from committed originals. It
80    /// performs no provider request and grants no sending authority.
81    pub async fn open(
82        database: StoreDatabase,
83        storage: Arc<dyn Storage>,
84        directory: StoreDir,
85        device: DeviceId,
86        keys: Arc<KeySession<StoreKeyring>>,
87        member: Arc<KeySession<MemberIdentity>>,
88        person: Arc<PersonEntries>,
89        state: Arc<SequenceState>,
90        clock: coven_foundation::clock::ClockRef,
91        ids: coven_foundation::id_source::IdSourceRef,
92        waits: Arc<crate::RetryWaits>,
93        files: crate::Files,
94    ) -> Result<Self, SyncError> {
95        let originals = database.original_slots().await?;
96        let through = database.applied_slot().await?;
97        let identity = member.read()?.ok_or(coven_storage::StorageFailure::MemberKeysMissing)?;
98        // A slot binding the member to a pair recorded here is one this
99        // installation can sign with; any other stops it (§12.3).
100        database
101            .hold_member_keys(
102                std::iter::once(identity.keys().public_keys())
103                    .chain(identity.candidate().map(|keys| keys.public_keys()))
104                    .collect(),
105            )
106            .await?;
107        // Without store keys in custody, history waits for this member's
108        // copies in storage (§12.1).
109        let (history, locked) = match keys.read()? {
110            Some(mut ring) => {
111                let history = History::restore(&originals, directory.id(), &mut ring, &identity)?;
112                keys.persist(&ring)?;
113                (history, false)
114            }
115            None => (History::default(), !originals.is_empty()),
116        };
117        let blocked = database.pending::<PendingRecord>().await?.into_iter().find(|record| {
118            next_slot(through).is_ok_and(|next| record.subject == PendingSubject::Slot(next))
119                && !matches!(record.reason, PendingReason::WritesRefused { .. })
120        });
121        if let Some(record) = &blocked {
122            state.set(SequenceStatus::Blocked(Box::new(record.clone())));
123        }
124        // A device the applied state removes, or whose member it removes, has
125        // stopped for good: it reads no slot after the removal and loads no
126        // floor past it (§14.1).
127        if let Some(coven_database::DeviceStop::Removed(removal)) = database.device_stop().await? {
128            state.set(SequenceStatus::Stopped(crate::SyncFailure::Removed(removal)));
129        }
130        Ok(Self {
131            database,
132            storage,
133            keys,
134            member,
135            person,
136            directory,
137            device,
138            state,
139            clock,
140            ids,
141            waits,
142            files,
143            progress: coven_foundation::progress::ProgressChannel::new(),
144            session: Arc::new(Mutex::new(Session {
145                history,
146                through,
147                floor: None,
148                checked_floor: None,
149                blocked,
150                scanned: Slot::FIRST,
151                stuck_scan: None,
152                locked,
153            })),
154        })
155    }
156
157    /// Decide this device's slot 1 in its database, as creating the store
158    /// does, and rebuild the session from the applied slots as opening does.
159    /// Slot 1 makes the creator's private circle, named "Private", whose
160    /// first key joins `ring` in this device's custody; it returns that
161    /// circle as slot 1 records it.
162    #[cfg(test)]
163    pub(crate) async fn decide_creation(
164        &self,
165        name: &str,
166        device_name: &str,
167        circles: Vec<crate::NewCircle>,
168        ring: &StoreKeyring,
169    ) -> Result<coven_format::admin::NewCircle, SyncError> {
170        let member = self.member.read()?.ok_or(StorageFailure::MemberKeysMissing)?;
171        let circle = crate::NewCircle {
172            circle: coven_foundation::id_source::CircleId(self.ids.new_id()),
173            name: "Private".into(),
174            key: coven_foundation::id_source::KeyId(self.ids.new_id()),
175        };
176        let mut ring = ring.clone();
177        ring.insert_circle_key(coven_crypto::CircleKey::generate(circle.circle, circle.key)?)?;
178        self.keys.persist(&ring)?;
179        let recorded = coven_format::admin::NewCircle {
180            circle: circle.circle,
181            name: circle.name.clone(),
182            breaking_version: self.database.breaking_version().await?,
183            key: circle.key,
184            key_hash: ring.circle_key(circle.circle, circle.key)?.hash(),
185        };
186        crate::decide_creation(
187            &self.database,
188            crate::Creation {
189                store: self.store(),
190                name: name.into(),
191                device: self.device,
192                device_name: device_name.into(),
193                member: &member,
194                person: "Ana".into(),
195                circle,
196                circles,
197                ring: &ring,
198            },
199        )
200        .await?;
201        let originals = self.database.original_slots().await?;
202        let identity = self.member.read()?.ok_or(StorageFailure::MemberKeysMissing)?;
203        let mut ring = self.keys.read()?.ok_or(StorageFailure::MemberKeysMissing)?;
204        let history = History::restore(&originals, self.store(), &mut ring, &identity)?;
205        let mut session = self.session.lock().await;
206        session.through = self.database.applied_slot().await?;
207        session.history = history;
208        Ok(recorded)
209    }
210
211    /// Use candidate credentials while retaining this installation's exact
212    /// progress and serialization. Failed setup can keep the old provider
213    /// without replaying history the candidate already applied.
214    pub fn reconnect(&self, storage: Arc<dyn Storage>) -> Self {
215        Self { storage, ..self.clone() }
216    }
217
218    /// The steps `unlock` reports as it loads the store from storage, each
219    /// with how much of it is done (§13.4). Passes report none.
220    pub fn subscribe_progress(&self) -> coven_foundation::progress::ProgressWatch<LoadStep> {
221        self.progress.watch()
222    }
223
224    pub(crate) fn store(&self) -> StoreId {
225        self.directory.id()
226    }
227
228    /// The app's write steps over this owner's own fields, for tests that
229    /// run a step beside the pass.
230    #[cfg(test)]
231    pub(crate) fn operation_steps(&self) -> crate::OperationSteps {
232        // Custody holding no storage credentials: these tests give an
233        // invite's key in the call.
234        let keychain = coven_crypto::custody::Keychain::in_memory("operation steps").unwrap();
235        let credentials = crate::DeviceCredentials::new(
236            Arc::new(coven_crypto::custody::StoreKeychain::new(keychain.clone(), self.store())),
237            Arc::new(coven_crypto::custody::PersonEntries::new(keychain, self.store())),
238            self.directory.clone(),
239            None,
240        );
241        crate::OperationSteps::new(
242            self.device,
243            self.member.clone(),
244            self.ids.clone(),
245            self.clock.clone(),
246            self.directory.clone(),
247            Arc::new(credentials),
248            self.waits.clone(),
249            self.state.clone(),
250        )
251    }
252    pub(crate) fn path(&self, slot: Slot) -> ObjectPath {
253        ObjectPath::slot(self.store(), slot.into())
254    }
255
256    /// Reach the current read end, publish this pass's captured eligible queue,
257    /// then perform the effects of its applied administrative state.
258    pub async fn pass(&self) -> Result<SequenceStatus, SyncError> {
259        let mut session = self.session.lock().await;
260        // What earlier passes' slots left for this device's files goes out
261        // in this pass, in a write of this device's own (§17.2).
262        self.database.settle_files().await?;
263        let waiting = self.database.waiting_snapshot_headers().await?;
264        let first = waiting.first().map(|write| write.header.position);
265        // What the queue lets out, if anything: a raise's capture and a
266        // bound upload's hold keep later writes waiting (§6.3).
267        let sendable = self
268            .database
269            .sendable_through()
270            .await?
271            .zip(first)
272            .filter(|(through, first)| *through >= first.number);
273        let member = self.member.read()?.ok_or(StorageFailure::MemberKeysMissing)?;
274        let mut ring = self.ring(&mut session, &member).await?;
275        self.read_forward(&mut session, &mut ring, &member).await?;
276        self.check_admitted(&session, &member).await?;
277        self.settle_open(&mut session, &mut ring, &member).await?;
278        self.resume_rebuilds(&mut session, &ring, &member).await?;
279        if let Some((through, first)) = sendable {
280            // The queue's first write names a wait for its sealing key; a
281            // later send that succeeds settles that condition.
282            let subject = PendingSubject::Write(coven_merge::WriteId {
283                device: first.device,
284                number: first.number,
285            });
286            match self.send_writes(&mut session, &mut ring, &member, through).await {
287                Ok(()) => self.database.clear_pending(subject).await?,
288                Err(SyncError::KeyUnavailable { audience, key }) => {
289                    let holders =
290                        Some(session.history.key_holders(&audience, key, member.member()));
291                    self.database
292                        .record_pending(PendingRecord::new(
293                            subject,
294                            PendingReason::KeyUnavailable { audience, key, holders },
295                        ))
296                        .await?;
297                }
298                Err(error) => return Err(error),
299            }
300        }
301        self.resume_administration(&mut session, &mut ring, &member).await?;
302        // Provider work, rotation and retention send for this installation;
303        // one still loading before its registration sends none of them.
304        if self.registered(&session) {
305            self.resume_access(&mut session, &mut ring, &member).await?;
306            self.resume_invites(&mut session, &mut ring, &member).await?;
307            self.resume_pairings(&session).await?;
308            self.end_gone_requests(&session, &member).await?;
309            self.resume_member_keys(&mut session, &mut ring).await?;
310            let member =
311                self.member.read()?.ok_or(coven_storage::StorageFailure::MemberKeysMissing)?;
312            self.rotate_exposed(&mut session, &mut ring, &member).await?;
313            self.send_owed_copies(&mut session, &mut ring, &member).await?;
314            self.publish_raises(&mut session, &mut ring, &member).await?;
315            // A snapshot announced here is named by this pass's floor write.
316            self.request_snapshots(&mut session, &mut ring, &member).await?;
317            self.retain_sequence(&mut session, &mut ring, &member).await?;
318            self.retain_snapshots(&mut session, &mut ring, &member).await?;
319            self.retain_files(&session, &ring, &member).await?;
320        }
321        let status = SequenceStatus::Synced { through: session.through };
322        self.state.set(status.clone());
323        Ok(status)
324    }
325
326    /// Whether the applied history registers this installation as active.
327    pub(crate) fn registered(&self, session: &Session) -> bool {
328        session.history.state.devices.get(&self.device).is_some_and(|device| device.active())
329    }
330
331    /// A slot's bytes: the ones already received for it if this device holds
332    /// them whole, since a slot is created once and never changes, or else
333    /// the provider's. None when the provider has no such slot.
334    pub(crate) async fn fetch(&self, path: &ObjectPath) -> Result<Option<ObjectInput>, SyncError> {
335        match self.held_slot(path).await? {
336            Some(input) => Ok(Some(input)),
337            None => self.read_slot(path).await,
338        }
339    }
340
341    /// The slot's bytes if this device already holds all of them.
342    pub(crate) async fn held_slot(
343        &self,
344        path: &ObjectPath,
345    ) -> Result<Option<ObjectInput>, SyncError> {
346        match ObjectInput::retained(&self.database, path).await? {
347            Some(input) if input.held().await? => Ok(Some(input)),
348            _ => Ok(None),
349        }
350    }
351
352    /// The slot's bytes from the provider, None when it has no such slot.
353    pub(crate) async fn read_slot(
354        &self,
355        path: &ObjectPath,
356    ) -> Result<Option<ObjectInput>, SyncError> {
357        let response = match self.storage.stream_object(path, None).await {
358            Ok(response) => response,
359            Err(error) if error.failure() == StorageFailure::NotFound => return Ok(None),
360            Err(error) => return Err(error.into()),
361        };
362        ObjectInput::receive_response(&self.database, self.storage.as_ref(), path, response)
363            .await
364            .map(Some)
365    }
366
367    /// A refusal judges the stored slot, not one read of it, and nothing
368    /// checks a slot's transfer: the slot whose kept copy a check refused is
369    /// read again, and the refusal stands only when the second read returns
370    /// the same bytes (§19.1). Different bytes mean a fault on the way
371    /// changed a read: a refusal recorded over the copy ends, the copy is
372    /// dropped so the next pass reads the slot again, and this pass fails
373    /// with `Corrupted`.
374    async fn confirm_refusal(&self, session: &mut Session, slot: Slot) -> Result<(), SyncError> {
375        let path = self.path(slot);
376        let Some(kept) = self.held_slot(&path).await? else {
377            return Ok(());
378        };
379        if kept.same_as_stored(self.storage.as_ref()).await? {
380            return Ok(());
381        }
382        self.database.clear_pending(PendingSubject::Slot(slot)).await?;
383        session.blocked = None;
384        kept.discard().await?;
385        Err(crate::object_input::corrupted(&path))
386    }
387
388    /// Stop for good on history showing another copy of this installation
389    /// using its device id (§19.3), and end what this copy's app journaled
390    /// and the invites it made: none would ever run, and no slot applies
391    /// this stop to end them (§14.1). A copy stopped by a slot signed with
392    /// its id records the stop in the same transaction, which a reset reads.
393    /// That write's failure fails the pass with its cause and leaves the
394    /// copy not stopped: the next pass finds the evidence again and writes
395    /// the record again.
396    pub(crate) async fn stop_copy(&self, evidence: crate::DeviceIdEvidence) -> SyncError {
397        let ended = match evidence {
398            crate::DeviceIdEvidence::Replaced => {
399                self.database.end_for_good(coven_database::DeviceStop::Replaced).await
400            }
401            crate::DeviceIdEvidence::UnattemptedSlot { slot } => {
402                self.database.end_for_copy(slot).await
403            }
404        };
405        match (ended, evidence) {
406            (Err(error), crate::DeviceIdEvidence::UnattemptedSlot { .. }) => error.into(),
407            (ended, _) => {
408                if let Err(error) = ended {
409                    tracing::error!("a stopped copy's operations stay journaled: {error}");
410                }
411                self.state.stop_copy(evidence)
412            }
413        }
414    }
415
416    /// Whether the applied history ever bound this member id to the pair
417    /// this installation holds. A store's history binds it before it has
418    /// applied anything else, slot 1 its creator's and a restore's loading
419    /// a pair history bound, except a store a join published once it found
420    /// its admission, whose first load applies that admission (§13.2).
421    pub(crate) fn pair_bound(&self, session: &Session, member: &MemberIdentity) -> bool {
422        let keys = member.keys().public_keys();
423        session
424            .history
425            .bindings
426            .iter()
427            .any(|binding| binding.member == member.member() && binding.keys == keys)
428    }
429
430    /// Stop for good once a store's history, read to the end of the
431    /// sequence, binds its pair nowhere: the admission a join published it
432    /// on was refused, and its device never became a member (§13.2, §14.1).
433    /// Only a pass, and the first load of a store a join published, check
434    /// this: every store a pass runs on has a pair its history binds first,
435    /// but a joined store's, while a creation that loses slot 1 never gets a
436    /// pass. No slot applies this stop, so it ends what the app journaled
437    /// and the invites the device made, as a stopped copy does; every pass
438    /// finds it again. A failed write fails the handle with its cause, which
439    /// every call reports.
440    pub(crate) async fn check_admitted(
441        &self,
442        session: &Session,
443        member: &MemberIdentity,
444    ) -> Result<(), SyncError> {
445        if session.through == 0 || self.pair_bound(session, member) {
446            return Ok(());
447        }
448        let removal = coven_database::Removal::NeverAdmitted;
449        self.state.set(SequenceStatus::Stopped(crate::SyncFailure::Removed(removal)));
450        if let Err(error) =
451            self.database.end_for_good(coven_database::DeviceStop::Removed(removal)).await
452        {
453            tracing::error!("a store never admitted keeps its operations journaled: {error}");
454        }
455        Err(SyncError::Removed(removal))
456    }
457
458    pub(crate) async fn check_copy(
459        &self,
460        received: &ReceivedSlot,
461        path: &ObjectPath,
462    ) -> Result<(), SyncError> {
463        let received = received.envelope();
464        if received.header.device == self.device
465            && !self
466                .database
467                .attempted_slot(received.header.claim, path.clone(), received.digest)
468                .await?
469        {
470            return Err(self
471                .stop_copy(crate::DeviceIdEvidence::UnattemptedSlot { slot: received.slot() })
472                .await);
473        }
474        Ok(())
475    }
476
477    pub(crate) fn check_binding(
478        &self,
479        session: &Session,
480        member: &MemberIdentity,
481    ) -> Result<(), SyncError> {
482        if let Some(device) = session.history.state.devices.get(&self.device) {
483            match device.state {
484                coven_database::DeviceState::Removed => {
485                    let (_, removal) = session.history.removal(self.device).ok_or_else(|| {
486                        SyncError::Bug(coven_foundation::task::Bug::new(
487                            "check the device's binding",
488                            "a removed device is removed by a counted entry",
489                        ))
490                    })?;
491                    self.state.set(SequenceStatus::Stopped(crate::SyncFailure::Removed(removal)));
492                    return Err(SyncError::Removed(removal));
493                }
494                coven_database::DeviceState::Replaced => {
495                    return Err(self.state.stop_copy(crate::DeviceIdEvidence::Replaced))
496                }
497                coven_database::DeviceState::Active => (),
498            }
499            // This member's own replacement binds its kept candidate before
500            // custody installs it (§11.5).
501            let current = session.history.state.members[&device.member].keys;
502            if current != member.keys().public_keys()
503                && member.candidate().map(|keys| keys.public_keys()) != Some(current)
504            {
505                return Err(SyncError::MemberKeysReplaced { member: device.member });
506            }
507        }
508        self.state.registered(
509            session.history.state.devices.get(&self.device).is_some_and(|device| device.active()),
510        );
511        Ok(())
512    }
513
514    /// Bring the person's entries to `next` before committing the
515    /// slots or snapshot that reach it from `applied`, so a failure returns to
516    /// the caller with nothing committed; the retried pass or call reads the
517    /// same slots and repeats it.
518    ///
519    /// The person leaves the store when their member's removal applies, by
520    /// any admin including themselves. Their saved restore code and S3 key
521    /// then serve no device of theirs, so this device deletes them: from
522    /// iCloud Keychain for all their Apple devices, or from this phone's Block
523    /// Store (§14.1). From then on the keychain refuses to write them again.
524    /// Removing only a device leaves them: the person keeps their other
525    /// devices. Otherwise a rename, this device's or another's, rewrites the
526    /// saved code's store name, unless the entry's is newer (§13.1).
527    pub(crate) fn follow_person_entries(
528        &self,
529        applied: &History,
530        next: &History,
531        member: &MemberIdentity,
532    ) -> Result<(), SyncError> {
533        let left = |history: &History| crate::effects::left(&history.state, &member.member());
534        if left(next) {
535            if !left(applied) {
536                self.person.delete_entries()?;
537            }
538            return Ok(());
539        }
540        let named = |history: &History| history.state.store.as_ref().map(crate::SavedName::of);
541        match named(next) {
542            Some(name) if named(applied) != Some(name.clone()) => {
543                crate::follow_name(&self.person, &name, || {
544                    let location = coven_storage::recorded_config(&self.directory)?;
545                    crate::replacement_code(&next.state, Some(member), location.as_ref())
546                })
547            }
548            _ => Ok(()),
549        }
550    }
551
552    pub(crate) async fn apply(
553        &self,
554        session: &mut Session,
555        mut incoming: IncomingSlot<coven_database::DownloadedWriteStream<PartPlaintext>>,
556        history: History,
557        ring: &StoreKeyring,
558        member: &MemberIdentity,
559    ) -> Result<(), SyncError> {
560        let at = incoming.slot;
561        // A reload's fixed target already installed this slot.
562        if at.get() <= session.through {
563            return Ok(());
564        }
565        let mut reloads = Vec::new();
566        if let SlotContent::Admin { effect: Some(effect), .. } = &mut incoming.content {
567            effect.provider_access = history.provider_access(member.member())?;
568            // A circle below this device's version waits for its rebuild
569            // instead of reloading (§18.3).
570            let breaking = self.database.breaking_version().await?;
571            reloads = effect
572                .reload
573                .iter()
574                .filter(|audience| !history.state.rebuilt_by(audience, breaking))
575                .cloned()
576                .collect();
577        }
578        // A reload persists the audience gates before any replacement body is
579        // read, and keeps the keys after it loads.
580        if reloads.is_empty() {
581            self.keys.persist(ring)?;
582        }
583        let result = self
584            .database
585            .apply_slot::<PendingRecord, _, _>(incoming, history.writers(self.device), || Ok(()))
586            .await
587            .map_err(|error| crate::write_object::database_failure(&self.path(at), error))?;
588        match (result, reloads.is_empty()) {
589            // The database applied the slot whole: no audience in it needs
590            // replacement data, and a circle below this device's version
591            // waits for its rebuild instead (§18.3).
592            (coven_database::ApplyOutcome::Applied, _)
593            | (coven_database::ApplyOutcome::AlreadyApplied, true) => {
594                if !reloads.is_empty() {
595                    self.keys.persist(ring)?;
596                }
597                session.through = at.get();
598                session.history = history;
599                self.check_binding(session, member)?;
600                Ok(())
601            }
602            (coven_database::ApplyOutcome::AlreadyApplied, false)
603            | (
604                coven_database::ApplyOutcome::Waiting(coven_database::WriteWait::Reload(_)),
605                false,
606            ) => self.reload_activation(session, at, &reloads, history, ring, member).await,
607            (coven_database::ApplyOutcome::Waiting(wait), _) => Err(self.waiting_slot(at, wait)),
608        }
609    }
610
611    /// Why the slot at `at` didn't apply: the database's wait, as the slot's
612    /// error. A genuine write names only sources that landed before it, so a
613    /// source that hasn't is named by a write that isn't genuine and no later
614    /// slot supplies it: the slot is damaged (§9.5).
615    pub(crate) fn waiting_slot(&self, at: Slot, wait: coven_database::WriteWait) -> SyncError {
616        match wait {
617            coven_database::WriteWait::Sources(_) => {
618                crate::write_object::damaged(&self.path(at), crate::Refusal::Parse { cause: None })
619            }
620            coven_database::WriteWait::Reload(audience) => {
621                SyncError::Pending(Box::new(PendingRecord::new(
622                    PendingSubject::Slot(at),
623                    PendingReason::Waits(Prerequisite::Reload(audience)),
624                )))
625            }
626            coven_database::WriteWait::SchemaVersion(version) => {
627                SyncError::Pending(Box::new(PendingRecord::new(
628                    PendingSubject::Slot(at),
629                    PendingReason::UpdateRequired(crate::RequiredUpdate::AppSchema { version }),
630                )))
631            }
632        }
633    }
634
635    /// Every variant is matched by name, so a new one is classified here.
636    #[deny(clippy::wildcard_enum_match_arm)]
637    async fn block(&self, session: &mut Session, slot: Slot, error: SyncError) -> SyncError {
638        if let SyncError::DeviceIdInUse(evidence) = error {
639            return self.stop_copy(evidence).await;
640        }
641        if let SyncError::Removed(removal) = error {
642            self.state.set(SequenceStatus::Stopped(crate::SyncFailure::Removed(removal)));
643            return error;
644        }
645        let path = self.path(slot);
646        let refused = matches!(&error, SyncError::Damaged(object) if object.path == path.as_str());
647        if refused {
648            if let Err(failed) = self.confirm_refusal(session, slot).await {
649                return failed;
650            }
651        }
652        let mut reason = slot_block_reason(&error, self.storage.config().provider());
653        if let (PendingReason::KeyUnavailable { audience, key, holders }, Ok(Some(member))) =
654            (&mut reason, self.member.read())
655        {
656            *holders = Some(session.history.key_holders(audience, *key, member.member()));
657        }
658        let subject = PendingSubject::Slot(slot);
659        self.waits.log_failure(&subject, &reason, error.cause());
660        let cause = blocked_cause(session, &subject, &error);
661        let record = PendingRecord { subject, reason, cause };
662        session.blocked = Some(record.clone());
663        self.state.set(SequenceStatus::Blocked(Box::new(record.clone())));
664        match self.database.record_pending(record).await {
665            Ok(()) => error,
666            Err(cleanup) => SyncError::cleanup(error, cleanup.into()),
667        }
668    }
669}
670
671/// The cause a blocked slot's record keeps: the text of the error that
672/// blocked it. A pass that stops at the same wait again has no error of its
673/// own, so the record keeps the one this run met for it, if any.
674/// Why a slot blocks on `error`: the reason it gives any request, except a
675/// rejection. A slot's block isn't this device's own request, so a
676/// rejection there isn't the app's to answer, and `Never` would leave the
677/// sequence with no recourse; it stays a local operation failure (§19.1).
678fn slot_block_reason(error: &SyncError, provider: coven_storage::CloudProvider) -> PendingReason {
679    match error {
680        SyncError::Rejected(_) => PendingReason::Failed(crate::LocalFailure::Operation),
681        error => error.pending_reason(provider),
682    }
683}
684
685fn blocked_cause(session: &Session, slot: &PendingSubject, error: &SyncError) -> Option<String> {
686    if let SyncError::Pending(wait) = error {
687        if wait.subject == *slot {
688            return session
689                .blocked
690                .as_ref()
691                .filter(|blocked| **blocked == **wait)
692                .and_then(|blocked| blocked.cause.clone());
693        }
694    }
695    Some(error.cause().to_string())
696}
697
698impl History {
699    pub(crate) fn restore(
700        originals: &[OriginalSlot],
701        store: StoreId,
702        ring: &mut StoreKeyring,
703        member: &MemberIdentity,
704    ) -> Result<Self, SyncError> {
705        Self::restore_while(originals, store, ring, member, |_, _| true)
706    }
707
708    /// `restore`, consuming the originals in order until `go_on` refuses the
709    /// history one has just made and the slot it consumed as.
710    pub(crate) fn restore_while(
711        originals: &[OriginalSlot],
712        store: StoreId,
713        ring: &mut StoreKeyring,
714        member: &MemberIdentity,
715        mut go_on: impl FnMut(
716            &Self,
717            &IncomingSlot<coven_database::DownloadedWriteStream<PartPlaintext>>,
718        ) -> bool,
719    ) -> Result<Self, SyncError> {
720        for original in originals {
721            snapshot_object::open_routing(original, store, ring, member)?;
722        }
723        let mut history = Self::default();
724        for original in originals {
725            let path = original.path(store);
726            let received =
727                slot_object::open_bounded(original.object.clone(), &path, ring, &history)?;
728            let incoming = history.consume(received, member.member());
729            if !go_on(&history, &incoming) {
730                break;
731            }
732        }
733        history.acquire(ring, member)?;
734        Ok(history)
735    }
736
737    /// The audience an admin change makes this member read anew: the store on
738    /// the member's admission, the boundary's audience on a raise or reset, a
739    /// circle the member is added to. One change names at most one.
740    fn reload_of(
741        &self,
742        effect: &coven_database::AdminEffect,
743        member: &coven_foundation::id_source::MemberId,
744    ) -> Option<Audience> {
745        use coven_format::admin::StoreChange::{AddCircleMember, AdmitMember, RaiseSchema, Reset};
746        match &effect.change {
747            AdmitMember { .. }
748                if self.state.store.is_some()
749                    && !crate::effects::belongs(&self.state, &Audience::Store, member)
750                    && crate::effects::belongs(&effect.state, &Audience::Store, member) =>
751            {
752                Some(Audience::Store)
753            }
754            RaiseSchema { .. } | Reset { .. } => effect
755                .boundary
756                .as_ref()
757                .map(|boundary| boundary.snapshot().audience.clone())
758                .filter(|audience| crate::effects::belongs(&effect.state, audience, member)),
759            AddCircleMember { circle, .. }
760                if self.state.circles.contains_key(circle)
761                    && effect.state.readable_circles(member).contains(circle)
762                    && !self.state.readable_circles(member).contains(circle) =>
763            {
764                Some(Audience::Circle(*circle))
765            }
766            _ => None,
767        }
768    }
769
770    /// Take `effect`, admitted at `slot`, into history, and leave in it the
771    /// state a device of `member` installs: history takes the effect's own
772    /// state, and a device of the member a store's removal removes installs
773    /// it keeping their circles (§14.1).
774    pub(crate) fn take_admin(
775        &mut self,
776        slot: Slot,
777        header: &coven_format::sequence::SlotHeader,
778        effect: &mut coven_database::AdminEffect,
779        member: &coven_foundation::id_source::MemberId,
780    ) {
781        effect.reload = self.reload_of(effect, member);
782        let kept = crate::circle_effects::KeptCircles::through(member, &effect.change, &self.state);
783        self.accept_admin(slot, header, effect);
784        if let Some(kept) = kept {
785            kept.install(&mut effect.state);
786        }
787    }
788
789    pub(crate) fn consume(
790        &mut self,
791        received: ReceivedSlot,
792        member: coven_foundation::id_source::MemberId,
793    ) -> IncomingSlot<coven_database::DownloadedWriteStream<PartPlaintext>> {
794        let (received, body) = received.into_parts();
795        let slot = received.slot();
796        let content = match body {
797            SlotBody::Writes { size, writes } => SlotContent::Writes { size, writes },
798            SlotBody::Bounded { frame: SlotFrame::Admin(change), original } => {
799                // An admission's copies stand in history whether or not its
800                // entry counts: a refused one still disclosed them (§12.2).
801                let validated = match &received.prefix.kind {
802                    SlotKind::Admission { copies, own } => self.validate_admission(
803                        &received.header,
804                        slot,
805                        &change,
806                        copies,
807                        own.as_ref(),
808                    ),
809                    _ => self.validate(&received.header, slot, &change),
810                };
811                self.copies.extend(KeyCopy::all(&received.path, &received.prefix));
812                let effect = match validated {
813                    Ok(mut effect) => {
814                        if let Some(effect) = &mut effect {
815                            self.take_admin(slot, &received.header, effect, &member);
816                        }
817                        effect
818                    }
819                    Err(reason) => {
820                        tracing::debug!(?slot, ?reason, "consumed refused administrative slot");
821                        None
822                    }
823                };
824                SlotContent::Admin { original, effect }
825            }
826            SlotBody::Bounded { frame: SlotFrame::KeyCopy, original } => {
827                self.copies.extend(KeyCopy::all(&received.path, &received.prefix));
828                SlotContent::KeyCopy(original)
829            }
830            SlotBody::Bounded { frame: SlotFrame::Announcement(announcement), original } => {
831                let accepted = if self.announcement_allowed(slot, &received.header, &announcement) {
832                    self.announcements.insert(slot, announcement.clone());
833                    Some(announcement)
834                } else {
835                    tracing::debug!(?slot, "consumed stale or unauthorized snapshot announcement");
836                    None
837                };
838                SlotContent::Announcement { original, accepted }
839            }
840        };
841        IncomingSlot { slot, header: received.header, digest: received.digest, content }
842    }
843
844    fn announcement_allowed(
845        &self,
846        slot: Slot,
847        header: &coven_format::sequence::SlotHeader,
848        announcement: &coven_format::sequence::SnapshotAnnouncement,
849    ) -> bool {
850        if !crate::effects::belongs(&self.state, &announcement.snapshot.audience, &header.author)
851            || !self.state.device_acts_for(&header.device, &header.author)
852            || announcement.snapshot.device != header.device
853            || announcement.covers >= slot.get()
854        {
855            return false;
856        }
857        let previous = self
858            .announcements
859            .values()
860            .filter(|prior| prior.snapshot.audience == announcement.snapshot.audience)
861            .map(|prior| prior.covers)
862            .max();
863        let boundary = self
864            .boundaries
865            .iter()
866            .filter(|prior| prior.boundary.snapshot().audience == announcement.snapshot.audience)
867            .map(|prior| prior.boundary.entry().get())
868            .max();
869        // Covering the latest raise, the audience's version at the coverage
870        // is its version now (§16.3).
871        let reached = match announcement.purpose {
872            Purpose::Raise(version) => version,
873            Purpose::Ordinary | Purpose::Reset => {
874                self.state.reached(&announcement.snapshot.audience)
875            }
876        };
877        previous.is_none_or(|covers| announcement.covers >= covers)
878            && boundary.is_none_or(|at| announcement.covers >= at)
879            && announcement.breaking_version <= reached
880    }
881}
882
883/// The journal row and intention for one provider account; the caller sets
884/// whether history already shows it granted.
885pub(crate) fn account_change(
886    account: &str,
887    intended: bool,
888    needs_invitation: bool,
889) -> Result<ProviderAccessChange, SyncError> {
890    Ok(ProviderAccessChange {
891        operation: NewOperation {
892            kind: operation_kind::PROVIDER_ACCESS.into(),
893            data: serde_json::to_vec(account)?,
894            started_by: operation_kind::COVEN.into(),
895            pauses_writes: false,
896        },
897        account: account.to_owned(),
898        intended,
899        initially_granted: false,
900        needs_invitation,
901    })
902}
903
904#[path = "operation_state.rs"]
905mod operation_state;
906pub(crate) use operation_state::OperationState;
907#[path = "sequence_access.rs"]
908mod sequence_access;
909#[path = "sequence_access_keys.rs"]
910mod sequence_access_keys;
911#[path = "sequence_bootstrap.rs"]
912pub(crate) mod sequence_bootstrap;
913#[path = "sequence_claim.rs"]
914mod sequence_claim;
915#[path = "sequence_copies.rs"]
916pub(crate) mod sequence_copies;
917#[path = "sequence_credentials.rs"]
918mod sequence_credentials;
919#[path = "sequence_cut_off.rs"]
920mod sequence_cut_off;
921#[path = "sequence_files.rs"]
922mod sequence_files;
923#[path = "sequence_gone_requests.rs"]
924mod sequence_gone_requests;
925#[path = "sequence_gone_storage.rs"]
926mod sequence_gone_storage;
927#[path = "sequence_invites.rs"]
928pub(crate) mod sequence_invites;
929#[path = "sequence_join.rs"]
930pub(crate) mod sequence_join;
931#[path = "sequence_keys.rs"]
932mod sequence_keys;
933#[path = "sequence_member_keys.rs"]
934mod sequence_member_keys;
935#[path = "sequence_pairings.rs"]
936pub(crate) mod sequence_pairings;
937pub(crate) use sequence_member_keys::registered;
938#[path = "sequence_operations.rs"]
939pub(crate) mod sequence_operations;
940#[path = "sequence_own_membership.rs"]
941mod sequence_own_membership;
942pub use sequence_own_membership::{registration_journaled, removal_journaled};
943#[path = "sequence_raises.rs"]
944mod sequence_raises;
945#[path = "sequence_read.rs"]
946mod sequence_read;
947pub(crate) use sequence_read::next_slot;
948#[path = "sequence_reload.rs"]
949pub(crate) mod sequence_reload;
950#[path = "sequence_retention.rs"]
951pub(crate) mod sequence_retention;
952#[path = "sequence_retry.rs"]
953mod sequence_retry;
954pub(crate) use sequence_retry::{make_retry_due, OperationFailure};
955#[path = "sequence_snapshots.rs"]
956mod sequence_snapshots;
957#[path = "slot_reading.rs"]
958mod slot_reading;
959use slot_reading::SlotReading;
960#[path = "slot_reads.rs"]
961mod slot_reads;
962pub(crate) use slot_reads::SlotReads;
963#[path = "snapshot_capture.rs"]
964pub(crate) mod snapshot_capture;
965#[path = "snapshot_file_scan.rs"]
966mod snapshot_file_scan;
967#[path = "snapshot_staged.rs"]
968mod snapshot_staged;
969#[path = "snapshot_upload.rs"]
970mod snapshot_upload;
971#[path = "sync_loop.rs"]
972pub(crate) mod sync_loop;
973
974#[cfg(test)]
975#[path = "sequence_sync_tests.rs"]
976pub(crate) mod tests;