Skip to main content

coven_sync/
sequence_operations.rs

1//! One journal owns validation, prerequisite artifacts, claims and undo.
2
3use crate::operation_outcome::EntryOutcome;
4#[cfg(test)]
5use crate::operation_outcome::SettledByPass;
6use crate::sequence_sync::OperationState;
7use crate::{
8    sequence_sync::snapshot_capture::{Capture, SnapshotArtifact, SnapshotRequest},
9    sequence_sync::{next_slot, SequenceSync, Session},
10    OperationRejection, SyncError,
11};
12use coven_crypto::{MemberIdentity, StoreKeyring};
13use coven_database::operation_kind;
14use coven_database::{
15    ClaimSettlement, ClaimWork, Journal, NewOperation, OperationId, OperationRecord,
16};
17use coven_format::{
18    admin::StoreChange,
19    sealed_key::KeyCopyPrefix,
20    sequence::{Purpose, SlotHeader},
21};
22use coven_merge::{Audience, Slot};
23use serde::{Deserialize, Serialize};
24
25use super::sequence_copies::{change, required_copies, route, ApprovedAdmission};
26
27#[derive(Clone, Serialize, Deserialize)]
28pub(crate) enum Request {
29    Change(#[serde(with = "change")] StoreChange),
30    /// An approved join request's admission, with the member's own copy.
31    Admission(ApprovedAdmission),
32    Snapshot(SnapshotRequest),
33    Key(super::sequence_keys::KeyPreparation),
34    /// One key copy this device's member owes a current member (§12.1).
35    Copy(#[serde(with = "route")] KeyCopyPrefix),
36}
37
38impl Request {
39    /// Whether this journaled request is the work `asked` asks for, so a
40    /// call asking for it again runs this one (§11.4). An installation
41    /// registers once, so every registration is the same work, whatever
42    /// name it carries.
43    pub(crate) fn carries(&self, asked: &Request) -> bool {
44        match (self, asked) {
45            (
46                Self::Change(StoreChange::AddDevice { .. }),
47                Self::Change(StoreChange::AddDevice { .. }),
48            ) => true,
49            (Self::Change(journaled), Self::Change(asked)) => journaled == asked,
50            (Self::Snapshot(journaled), Self::Snapshot(asked)) => {
51                journaled.audience == asked.audience && journaled.purpose == asked.purpose
52            }
53            _ => false,
54        }
55    }
56}
57
58#[derive(Serialize, Deserialize)]
59pub(crate) enum OperationStep {
60    Preparing,
61    Copy(#[serde(with = "route")] KeyCopyPrefix),
62    Claiming,
63    Capturing(Capture),
64    Uploading(SnapshotArtifact),
65    Announcing(SnapshotArtifact),
66    Activating {
67        artifact: SnapshotArtifact,
68        #[serde(with = "coven_database::slot_json")]
69        announcement: Slot,
70    },
71    Applied(#[serde(with = "coven_database::slot_json")] Slot),
72    SnapshotApplied {
73        artifact: SnapshotArtifact,
74        #[serde(with = "coven_database::slot_json")]
75        slot: Slot,
76    },
77    Satisfied,
78}
79#[derive(Serialize, Deserialize)]
80pub(crate) enum OperationProgress {
81    Running(OperationStep),
82    Undo { step: OperationStep, reason: OperationRejection },
83}
84#[derive(Serialize, Deserialize)]
85pub(crate) struct SequenceOperation {
86    pub(crate) request: Request,
87    pub(crate) progress: OperationProgress,
88}
89impl OperationState for SequenceOperation {}
90
91impl SequenceOperation {
92    /// The journal row that starts this operation, before its first step.
93    pub(crate) fn journaled(&self, started_by: &str) -> Result<NewOperation, SyncError> {
94        Ok(NewOperation {
95            kind: operation_kind::SEQUENCE.into(),
96            data: serde_json::to_vec(self)?,
97            started_by: started_by.into(),
98            pauses_writes: false,
99        })
100    }
101
102    /// Journal the operation as one the app's write asked for.
103    pub(crate) fn start(
104        self,
105        journal: &Journal<'_>,
106        started_by: &str,
107    ) -> Result<OperationId, SyncError> {
108        let kind = self.kind().listed();
109        Ok(journal.start_app_operation(&self.journaled(started_by)?, &kind)?)
110    }
111
112    /// An administrative change, before its first step.
113    pub(crate) fn change(change: StoreChange) -> Self {
114        Self {
115            request: Request::Change(change),
116            progress: OperationProgress::Running(OperationStep::Preparing),
117        }
118    }
119
120    /// An admission, before its first step.
121    pub(crate) fn admission(admission: ApprovedAdmission) -> Self {
122        Self {
123            request: Request::Admission(admission),
124            progress: OperationProgress::Running(OperationStep::Preparing),
125        }
126    }
127
128    pub(crate) fn kind(&self) -> crate::OperationKind {
129        match &self.request {
130            Request::Key(target) => target.kind(),
131            Request::Copy(_) => crate::OperationKind::SendKeyCopy,
132            Request::Change(change) => crate::OperationKind::of(change),
133            Request::Admission(admission) => crate::OperationKind::of(&admission.change),
134            Request::Snapshot(request) => match request.purpose {
135                Purpose::Ordinary => crate::OperationKind::WriteSnapshot,
136                Purpose::Raise(_) => crate::OperationKind::SchemaChange,
137                Purpose::Reset => crate::OperationKind::Reset,
138            },
139        }
140    }
141}
142
143impl SequenceSync {
144    /// Administrative requests retain their target across contention and reopening.
145    pub async fn administer(
146        self: &std::sync::Arc<Self>,
147        change: StoreChange,
148    ) -> Result<(), SyncError> {
149        self.administer_at(change).await.map(drop)
150    }
151
152    /// Administer `change`, answering the slot its entry landed at, or
153    /// `None` when the applied state already had it. A store's creation
154    /// lands at slot 1, though its key copy lands after it.
155    pub async fn administer_at(
156        self: &std::sync::Arc<Self>,
157        change: StoreChange,
158    ) -> Result<Option<Slot>, SyncError> {
159        // An admission carries its member's own copy, which only an approved
160        // join request holds (§13.2).
161        if matches!(change, StoreChange::AdmitMember { .. } | StoreChange::RecoverMember { .. }) {
162            return Err(SyncError::Rejected(OperationRejection::NotAllowed));
163        }
164        self.submit(Request::Change(change)).await
165    }
166
167    /// Catch up, settle this device's open claim and run its journaled
168    /// operations to their ends, as every new operation does first (§11.4).
169    /// A storage setup a crash cut past its point of no return finishes a
170    /// creation this way.
171    pub async fn settle_operations(self: &std::sync::Arc<Self>) -> Result<(), SyncError> {
172        let owner = self.clone();
173        let settling = async move {
174            let mut session = owner.session.lock().await;
175            let member =
176                owner.member.read()?.ok_or(coven_storage::StorageFailure::MemberKeysMissing)?;
177            let mut ring = owner.ring(&mut session, &member).await?;
178            owner.read_forward(&mut session, &mut ring, &member).await?;
179            owner.settle_open(&mut session, &mut ring, &member).await?;
180            owner.resume_administration(&mut session, &mut ring, &member).await
181        };
182        coven_foundation::task::spawn_completing(
183            "settle operations",
184            self.database.bugs().clone(),
185            settling,
186        )
187        .await?
188    }
189
190    /// Send the slot 1 a store's creation decided, as the attempt it kept,
191    /// and settle it (§10.3). Answers `StoreExists` once another device's
192    /// bytes hold slot 1, and nothing when the creation is already
193    /// published.
194    pub async fn publish_creation(self: &std::sync::Arc<Self>) -> Result<(), SyncError> {
195        let owner = self.clone();
196        let publishing = async move {
197            let mut session = owner.session.lock().await;
198            let member =
199                owner.member.read()?.ok_or(coven_storage::StorageFailure::MemberKeysMissing)?;
200            let mut ring = owner.ring(&mut session, &member).await?;
201            owner.read_forward(&mut session, &mut ring, &member).await?;
202            owner.settle_open(&mut session, &mut ring, &member).await?;
203            let Some(id) = owner
204                .journaled(|request| {
205                    matches!(request, Request::Change(StoreChange::CreateStore { .. }))
206                })
207                .await?
208            else {
209                return Ok(());
210            };
211            owner.retry_operation(id).await?;
212            owner
213                .run_administration(&mut session, &mut ring, &member, id)
214                .await
215                .and_then(EntryOutcome::into_slot)
216                .map(drop)
217        };
218        coven_foundation::task::spawn_completing(
219            "publish a store's creation",
220            self.database.bugs().clone(),
221            publishing,
222        )
223        .await?
224    }
225
226    /// Register this installation for its member once the applied history
227    /// binds the member's current pair (§13). `replaces` names this member's
228    /// earlier installation that a reset supersedes.
229    pub async fn register_device(
230        self: &std::sync::Arc<Self>,
231        name: String,
232        replaces: Option<coven_foundation::id_source::DeviceId>,
233    ) -> Result<(), SyncError> {
234        self.submit(Request::Change(StoreChange::AddDevice { name, replaces })).await.map(drop)
235    }
236
237    /// Capture the counted audience prefix, upload it, then claim its announcement.
238    pub async fn snapshot(
239        self: &std::sync::Arc<Self>,
240        audience: Audience,
241    ) -> Result<Slot, SyncError> {
242        self.submit(Request::Snapshot(SnapshotRequest { audience, purpose: Purpose::Ordinary }))
243            .await
244            .map(|slot| slot.expect("snapshot completion has a counted announcement"))
245    }
246
247    /// Publish a prepared reset and activate it through the same operation journal.
248    pub async fn reset(self: &std::sync::Arc<Self>, audience: Audience) -> Result<(), SyncError> {
249        self.submit(Request::Snapshot(SnapshotRequest { audience, purpose: Purpose::Reset }))
250            .await
251            .map(drop)
252    }
253
254    /// Publish the captured breaking migration and activate its audience version.
255    #[cfg(any(test, feature = "test-utils"))]
256    pub async fn raise_schema(
257        self: &std::sync::Arc<Self>,
258        audience: Audience,
259        version: u32,
260    ) -> Result<(), SyncError> {
261        self.submit(Request::Snapshot(SnapshotRequest {
262            audience,
263            purpose: Purpose::Raise(version),
264        }))
265        .await
266        .map(drop)
267    }
268
269    pub(super) async fn submit(
270        self: &std::sync::Arc<Self>,
271        request: Request,
272    ) -> Result<Option<Slot>, SyncError> {
273        let owner = self.clone();
274        // The owned task survives cancellation of the app's waiter, including
275        // requests that the provider cannot cancel once sent.
276        let submitting = async move {
277            let mut session = owner.session.lock().await;
278            let member =
279                owner.member.read()?.ok_or(coven_storage::StorageFailure::MemberKeysMissing)?;
280            let mut ring = owner.ring(&mut session, &member).await?;
281            owner.read_forward(&mut session, &mut ring, &member).await?;
282            owner.settle_open(&mut session, &mut ring, &member).await?;
283            owner.resume_administration(&mut session, &mut ring, &member).await?;
284            if let Request::Change(StoreChange::AddDevice { .. }) = &request {
285                super::sequence_bootstrap::restorable(owner.admission(&session, &member), &member)?;
286                // A registration journaled before a restart has just ended:
287                // landed, this device is registered and needs no other.
288                if session.history.state.device_acts_for(&owner.device, &member.member()) {
289                    return Ok(None);
290                }
291            }
292            let creation = matches!(request, Request::Change(StoreChange::CreateStore { .. }));
293            // Work the journal already holds runs now, even while it waits
294            // for the app to ask again: a second operation for it would meet
295            // the first's open claim, and a claimed entry is final (§11.4).
296            let ran = match owner.journaled(|journaled| journaled.carries(&request)).await? {
297                Some(id) => {
298                    owner.retry_operation(id).await?;
299                    owner.run_administration(&mut session, &mut ring, &member, id).await
300                }
301                None => {
302                    owner
303                        .start_request(&mut session, &mut ring, &member, request, "operation")
304                        .await
305                }
306            };
307            match ran.and_then(EntryOutcome::into_slot) {
308                // Another creation claimed slot 1 first (§10).
309                Err(SyncError::Rejected(_)) if creation => {
310                    Err(coven_storage::StorageFailure::StoreExists.into())
311                }
312                result => result,
313            }
314        };
315        coven_foundation::task::spawn_completing(
316            "submit an operation",
317            self.database.bugs().clone(),
318            submitting,
319        )
320        .await?
321    }
322
323    /// Journal `request` as a new sequence operation, before its first step.
324    pub(crate) async fn start_request_row(
325        &self,
326        request: Request,
327        started_by: &str,
328    ) -> Result<OperationId, SyncError> {
329        let work = SequenceOperation {
330            request,
331            progress: OperationProgress::Running(OperationStep::Preparing),
332        };
333        Ok(self.database.start_operation(work.journaled(started_by)?).await?)
334    }
335
336    pub(crate) async fn start_request(
337        &self,
338        session: &mut Session,
339        ring: &mut StoreKeyring,
340        member: &MemberIdentity,
341        request: Request,
342        started_by: &str,
343    ) -> Result<EntryOutcome, SyncError> {
344        if !self.validate_request(session, member, &request)?? {
345            return Ok(EntryOutcome::Satisfied);
346        }
347        let id = self.start_request_row(request, started_by).await?;
348        self.run_administration(session, ring, member, id).await
349    }
350
351    fn operation_header(
352        &self,
353        session: &Session,
354        member: &MemberIdentity,
355        claim: u64,
356    ) -> SlotHeader {
357        SlotHeader { device: self.device, claim, author: member.member(), after: session.through }
358    }
359
360    /// Whether `request` still has work to claim, or the applied history's
361    /// rejection of it. Validating a change needs the slot it would take,
362    /// and none follows the last one.
363    pub(crate) fn validate_request(
364        &self,
365        session: &Session,
366        member: &MemberIdentity,
367        request: &Request,
368    ) -> Result<Result<bool, OperationRejection>, SyncError> {
369        Ok(match request {
370            Request::Key(_) => unreachable!("key preparation supplies its public commitment first"),
371            Request::Change(change) => session
372                .history
373                .validate(
374                    &self.operation_header(session, member, 1),
375                    next_slot(session.through)?,
376                    change,
377                )
378                .map(|effect| effect.is_some()),
379            Request::Admission(admission) => session
380                .history
381                .validate(
382                    &self.operation_header(session, member, 1),
383                    next_slot(session.through)?,
384                    &admission.change,
385                )
386                .map(|effect| effect.is_some()),
387            Request::Copy(route) => Ok(session.history.copy_wanted(route, member.member())),
388            Request::Snapshot(request) => self.validate_snapshot(session, member, request),
389        })
390    }
391
392    /// Whether a snapshot `request` still has work to claim, or the applied
393    /// history's rejection of it.
394    fn validate_snapshot(
395        &self,
396        session: &Session,
397        member: &MemberIdentity,
398        request: &SnapshotRequest,
399    ) -> Result<bool, OperationRejection> {
400        // Nobody raises a deleted circle: a raise started before the
401        // deletion applied finds nothing to claim, and adopts that
402        // state as it would an established version (§15.9, §18.3).
403        if matches!(request.purpose, Purpose::Raise(_))
404            && session.history.state.deleted(&request.audience)
405        {
406            return Ok(false);
407        }
408        let state = &session.history.state;
409        let author = member.member();
410        if state.active_member(&author).is_none() || !state.device_acts_for(&self.device, &author) {
411            return Err(OperationRejection::NotAllowed);
412        }
413        // A snapshot of a gone circle meets a gone target, as every
414        // change aimed at it does (§10.4).
415        if let Audience::Circle(circle) = &request.audience {
416            if state.gone_circle(circle) {
417                return Err(OperationRejection::TargetGone(crate::EntryTarget::Circle(*circle)));
418            }
419        }
420        if !crate::effects::belongs(state, &request.audience, &author)
421            || (request.purpose == Purpose::Reset
422                && request.audience == Audience::Store
423                && !state.active_admin(&author))
424        {
425            return Err(OperationRejection::NotAllowed);
426        }
427        // A raise that finds its version established adopts that
428        // state and claims nothing (§18.3).
429        if let Purpose::Raise(version) = request.purpose {
430            return Ok(session.history.state.reached(&request.audience) < version);
431        }
432        Ok(true)
433    }
434
435    /// The journaled operation whose request `carries` picks, if one runs.
436    pub(crate) async fn journaled(
437        &self,
438        carries: impl Fn(&Request) -> bool,
439    ) -> Result<Option<OperationId>, SyncError> {
440        for record in self.database.operations().await? {
441            if record.kind == operation_kind::SEQUENCE
442                && carries(&serde_json::from_slice::<SequenceOperation>(&record.data)?.request)
443            {
444                return Ok(Some(record.id));
445            }
446        }
447        Ok(None)
448    }
449
450    /// Coven's own work started in a pass: once journaled, its failure is the
451    /// operation's to report and retry under its backoff, and the pass goes
452    /// on (E5). A failure before journaling, or one stopping this
453    /// installation, ends the pass.
454    pub(crate) async fn own_work(
455        &self,
456        result: Result<(), SyncError>,
457        carries: impl Fn(&Request) -> bool,
458    ) -> Result<(), SyncError> {
459        match result {
460            Ok(()) => Ok(()),
461            Err(error) => {
462                self.state.check()?;
463                if self.journaled(carries).await?.is_some() {
464                    Ok(())
465                } else {
466                    Err(error)
467                }
468            }
469        }
470    }
471
472    pub(crate) async fn resume_administration(
473        &self,
474        session: &mut Session,
475        ring: &mut StoreKeyring,
476        member: &MemberIdentity,
477    ) -> Result<(), SyncError> {
478        let records = self.database.operations().await?;
479        self.waits.retain_operations(&records.iter().map(|r| r.id).collect());
480        for record in records {
481            if record.kind == operation_kind::SEQUENCE
482                && !parent_owned(&record)
483                && self.operation_ready(&record, ring).await?
484            {
485                // Its outcome is the journal's to keep: one the app's write
486                // journaled is listed until the app acknowledges it (§11.4).
487                let outcome = self.run_administration(session, ring, member, record.id).await?;
488                tracing::debug!(id = ?record.id, ?outcome, "resumed operation ended");
489            }
490        }
491        Ok(())
492    }
493
494    pub(crate) async fn run_administration(
495        &self,
496        session: &mut Session,
497        ring: &mut StoreKeyring,
498        member: &MemberIdentity,
499        id: OperationId,
500    ) -> Result<EntryOutcome, SyncError> {
501        let record = self.database.operation(id).await?.ok_or(SyncError::NotPending(id))?;
502        if parent_owned(&record) {
503            // The parent records the failure and owns its retry scope (§11.4).
504            return self.advance_administration(session, ring, member, id).await;
505        }
506        let scope = self.waits.begin_attempt(id);
507        let result = coven_database::in_commit_scope(
508            scope,
509            self.advance_administration(session, ring, member, id),
510        )
511        .await;
512        if let Err(error) = &result {
513            if let Some(record) = self.database.operation(id).await? {
514                let work: SequenceOperation = serde_json::from_slice(&record.data)?;
515                self.record_operation_error(
516                    id,
517                    work.kind(),
518                    crate::sequence_sync::OperationFailure::Returned(error),
519                    ring,
520                )
521                .await?;
522            }
523        } else {
524            self.waits.operation_advanced(id);
525        }
526        result
527    }
528
529    async fn advance_administration(
530        &self,
531        session: &mut Session,
532        ring: &mut StoreKeyring,
533        member: &MemberIdentity,
534        id: OperationId,
535    ) -> Result<EntryOutcome, SyncError> {
536        loop {
537            let record = self
538                .database
539                .operation(id)
540                .await?
541                .ok_or(coven_database::DbError::OperationChanged(id))?;
542            let work: SequenceOperation = serde_json::from_slice(&record.data)?;
543            let kind = work.kind();
544            let SequenceOperation { request, progress } = work;
545            let mut step = match progress {
546                OperationProgress::Undo { step, reason } => {
547                    self.abandon_settled_claim(id).await?;
548                    if let Err(cleanup) = self.undo_step(&step).await {
549                        return Err(SyncError::cleanup(reason.into(), cleanup));
550                    }
551                    return self.finish(&record, kind, EntryOutcome::Rejected(reason)).await;
552                }
553                OperationProgress::Running(step) => step,
554            };
555            match &step {
556                OperationStep::Applied(slot) => {
557                    return self.finish(&record, kind, EntryOutcome::Landed(*slot)).await
558                }
559                OperationStep::Satisfied => {
560                    return self.finish(&record, kind, EntryOutcome::Satisfied).await
561                }
562                OperationStep::SnapshotApplied { artifact, slot } => {
563                    self.remove_artifact(&artifact.capture.name).await?;
564                    return self.finish(&record, kind, EntryOutcome::Landed(*slot)).await;
565                }
566                _ => (),
567            }
568            if let Request::Key(target) = request {
569                self.prepare_audience_key(session, ring, member, &record, target).await?;
570                continue;
571            }
572            if let Some(claim) = self.database.current_claim().await? {
573                if claim.work != ClaimWork::Operation(id) {
574                    return Err(coven_database::DbError::ClaimPending.into());
575                }
576                match self.settle_claim(session, ring, member, &claim).await? {
577                    ClaimSettlement::Landed => {
578                        let slot = claim
579                            .attempts
580                            .last()
581                            .expect("claim attempt")
582                            .slot_number()
583                            .expect("slot");
584                        step = match step {
585                            OperationStep::Copy(_) => OperationStep::Preparing,
586                            OperationStep::Claiming => OperationStep::Applied(slot),
587                            OperationStep::Announcing(artifact)
588                                if artifact.capture.purpose == Purpose::Ordinary =>
589                            {
590                                OperationStep::SnapshotApplied { artifact, slot }
591                            }
592                            OperationStep::Announcing(artifact) => {
593                                OperationStep::Activating { artifact, announcement: slot }
594                            }
595                            OperationStep::Activating { artifact, .. } => {
596                                OperationStep::SnapshotApplied { artifact, slot }
597                            }
598                            _ => unreachable!("a publication step owns each claim"),
599                        };
600                        self.database
601                            .finish_claim(Some(
602                                SequenceOperation {
603                                    request,
604                                    progress: OperationProgress::Running(step),
605                                }
606                                .update(&record)?,
607                            ))
608                            .await?;
609                        continue;
610                    }
611                    // Slot 1 was decided and applied when the store was
612                    // created: another device's bytes holding it leave
613                    // this store unable to ever sync, and every attempt
614                    // to send it says so (§10.3).
615                    ClaimSettlement::NotLanded
616                        if matches!(request, Request::Change(StoreChange::CreateStore { .. })) =>
617                    {
618                        return Err(coven_storage::StorageFailure::StoreExists.into());
619                    }
620                    ClaimSettlement::NotLanded => {
621                        if claim
622                            .attempts
623                            .last()
624                            .expect("attempt")
625                            .slot_number()
626                            .expect("slot")
627                            .get()
628                            > session.through
629                        {
630                            match self.read_forward(session, ring, member).await {
631                                Ok(())
632                                | Err(
633                                    SyncError::Removed(_) | SyncError::MemberKeysReplaced { .. },
634                                ) => {}
635                                Err(error) => return Err(error),
636                            }
637                            if matches!(step, OperationStep::Copy(_) | OperationStep::Claiming) {
638                                step = OperationStep::Preparing;
639                            }
640                        }
641                    }
642                    ClaimSettlement::DeviceIdInUse => {
643                        return Err(self
644                            .stop_copy(crate::DeviceIdEvidence::UnattemptedSlot {
645                                slot: claim
646                                    .attempts
647                                    .last()
648                                    .expect("attempt")
649                                    .slot_number()
650                                    .expect("slot"),
651                            })
652                            .await)
653                    }
654                    _ => unreachable!("settled create"),
655                }
656            }
657            let validation = if self.awaits_access_key(member, &request).await {
658                // A key this connection doesn't hold: the call that journaled
659                // the entry never took it (§14.3).
660                Ok(false)
661            } else {
662                self.validate_request(session, member, &request)?
663            };
664            match validation {
665                Ok(false) => {
666                    self.abandon_settled_claim(id).await?;
667                    self.undo_step(&step).await?;
668                    self.database
669                        .advance_operation(
670                            SequenceOperation {
671                                request,
672                                progress: OperationProgress::Running(OperationStep::Satisfied),
673                            }
674                            .update(&record)?,
675                        )
676                        .await?;
677                    continue;
678                }
679                Err(reason) => {
680                    self.database
681                        .advance_operation(
682                            SequenceOperation {
683                                request,
684                                progress: OperationProgress::Undo { step, reason },
685                            }
686                            .update(&record)?,
687                        )
688                        .await?;
689                    continue;
690                }
691                Ok(true) => (),
692            }
693            if matches!(step, OperationStep::Preparing) {
694                step = match &request {
695                    Request::Key(_) => unreachable!("key preparation has advanced"),
696                    Request::Copy(route) => OperationStep::Copy(route.clone()),
697                    // An admission carries its copies in its own slot.
698                    Request::Admission(_) => OperationStep::Claiming,
699                    Request::Change(change) => {
700                        match required_copies(&session.history, ring, change, member.member())
701                            .into_iter()
702                            .find(|route| !session.history.has_copy(route))
703                        {
704                            Some(route) => OperationStep::Copy(route),
705                            None => OperationStep::Claiming,
706                        }
707                    }
708                    Request::Snapshot(request) => {
709                        let number = self.database.reserve_snapshot_number().await?.get();
710                        OperationStep::Capturing(Capture {
711                            id: coven_format::admin::SnapshotId {
712                                audience: request.audience.clone(),
713                                device: self.device,
714                                number,
715                            },
716                            purpose: request.purpose,
717                            key: session.history.sending_key(
718                                ring,
719                                member.member(),
720                                &request.audience,
721                            )?,
722                            name: format!("snapshot-{number}.sealed"),
723                        })
724                    }
725                };
726                self.database
727                    .advance_operation(
728                        SequenceOperation { request, progress: OperationProgress::Running(step) }
729                            .update(&record)?,
730                    )
731                    .await?;
732                continue;
733            }
734            match step {
735                OperationStep::Capturing(capture) => {
736                    // No snapshot is taken at a version the history doesn't
737                    // hold while this device's raise waits (§16.2).
738                    let progress = match self.capture_snapshot(&capture, ring, member).await {
739                        Err(SyncError::Database(coven_database::DbError::RaiseWaiting)) => {
740                            OperationProgress::Undo {
741                                step: OperationStep::Capturing(capture),
742                                reason: OperationRejection::NotAllowed,
743                            }
744                        }
745                        // A raise whose capture moved to a later version has
746                        // nothing left to raise; that capture raises it (§18.5).
747                        Ok(None) => OperationProgress::Running(OperationStep::Satisfied),
748                        Ok(Some(artifact)) => {
749                            OperationProgress::Running(OperationStep::Uploading(artifact))
750                        }
751                        Err(error) => return Err(error),
752                    };
753                    let captured = match &progress {
754                        OperationProgress::Running(OperationStep::Uploading(artifact)) => {
755                            Some((artifact.capture.name.clone(), artifact.size))
756                        }
757                        _ => None,
758                    };
759                    let update = SequenceOperation { request, progress }.update(&record)?;
760                    match captured {
761                        Some((name, size)) => {
762                            self.database
763                                .advance_operation_counting_capture(update, name, size)
764                                .await?
765                        }
766                        None => self.database.advance_operation(update).await?,
767                    }
768                }
769                OperationStep::Uploading(artifact) => {
770                    self.upload_snapshot(record, request, artifact).await?;
771                }
772                OperationStep::Announcing(ref artifact)
773                | OperationStep::Activating { ref artifact, .. }
774                    if !session.history.preparation_current(&artifact.announcement()) =>
775                {
776                    // No activation has landed. Its counted announcement
777                    // remains history while its unusable body is reclaimed.
778                    self.undo_step(&step).await?;
779                    self.database
780                        .advance_operation(
781                            SequenceOperation {
782                                request,
783                                progress: OperationProgress::Running(OperationStep::Preparing),
784                            }
785                            .update(&record)?,
786                        )
787                        .await?;
788                }
789                _ => self.claim_step(session, ring, member, &record, &request, &step).await?,
790            }
791        }
792    }
793
794    /// End the operation's journal row with its outcome, which the app's
795    /// record of it keeps in the same transaction, in the outcome type of
796    /// its kind (§11.4). An operation an invite started stays journaled at
797    /// its last step: the invite names it, and ends it in the transaction
798    /// that moves the invite on or ends the invite, so a restart never finds
799    /// one without the other (§13.2).
800    async fn finish(
801        &self,
802        record: &OperationRecord,
803        kind: crate::OperationKind,
804        outcome: EntryOutcome,
805    ) -> Result<EntryOutcome, SyncError> {
806        if !parent_owned(record) {
807            let listed = kind.listed_outcome(outcome.clone())?;
808            self.database.finish_operation_with_outcome(record.id, listed).await?;
809        }
810        Ok(outcome)
811    }
812}
813
814/// The journal row of `change` as the app's write journals it, and the kind
815/// `coven_operations` lists it under, for a test that journals it outside a
816/// store (api.md E4).
817#[cfg(any(test, feature = "test-utils"))]
818pub fn change_operation(change: StoreChange) -> Result<(NewOperation, String), SyncError> {
819    let operation = SequenceOperation::change(change);
820    Ok((operation.journaled("record_change")?, operation.kind().listed()))
821}
822
823#[cfg(test)]
824impl SequenceSync {
825    /// Run one of the app's journal steps in a write of its own, then a
826    /// pass, and return the operation's outcome as `coven_operations` lists
827    /// it, read as `O`, the outcome type of its kind; `None` when the step
828    /// journaled nothing.
829    pub(crate) async fn journal_and_pass<O: coven_database::types::FromSql + Send + 'static>(
830        &self,
831        step: impl FnOnce(&coven_database::SqlContext<'_, '_>) -> Result<Option<OperationId>, SyncError>
832            + Send
833            + 'static,
834    ) -> Result<Option<O>, SyncError> {
835        let journaled = self.database.write_as(move |sql| step(&sql)).await?;
836        let Some(id) = journaled else {
837            return Ok(None);
838        };
839        self.pass().await?;
840        let outcome = self
841            .database
842            .read(move |sql| {
843                Ok::<_, coven_database::DbError>(sql.query_row(
844                    "SELECT outcome FROM coven_operations WHERE operation=?1",
845                    [id.0],
846                    |row| row.get::<_, O>(0),
847                )?)
848            })
849            .await?;
850        Ok(Some(outcome))
851    }
852
853    /// Make a circle as the app's write step does, and run the pass that
854    /// lands it, returning its rejection as the error.
855    pub(crate) async fn create_circle(
856        &self,
857        name: String,
858    ) -> Result<coven_foundation::id_source::CircleId, SyncError> {
859        let steps = self.operation_steps();
860        let (sender, receiver) = tokio::sync::oneshot::channel();
861        let outcome: crate::FreshChangeOutcome = self
862            .journal_and_pass(move |sql| {
863                let (circle, operation) = steps.create_circle(sql, name)?;
864                sender.send(circle).expect("the caller waits");
865                Ok(Some(operation))
866            })
867            .await?
868            .expect("making a circle always journals");
869        outcome.settled()?;
870        Ok(receiver.await.expect("the step sent the circle"))
871    }
872}
873
874fn parent_owned(record: &OperationRecord) -> bool {
875    record.started_by == operation_kind::INVITE
876}
877
878#[path = "sequence_operations_claim.rs"]
879mod claim;
880
881#[cfg(test)]
882#[path = "sequence_operations_tests.rs"]
883mod tests;