Skip to main content

coven_database/
sequence_apply.rs

1//! Atomic application of the next shared slot and its provisional queue overlay.
2
3use crate::download_stream::PreparedWrite;
4use crate::sqlite::StoreSql;
5use crate::store_call::StoreCall;
6use crate::{write_schema::WriteSchema, DbError, StoreState};
7use coven_format::{admin::StoreChange, floor::OriginalSlot, sequence::SlotHeader};
8use coven_merge::Slot;
9use std::collections::BTreeSet;
10
11/// An authenticated slot whose floor check completed before installation.
12pub struct IncomingSlot<R> {
13    /// Its exact sequence identity.
14    pub slot: Slot,
15    /// The authenticated device, claim, author and preceding prefix.
16    pub header: SlotHeader,
17    /// SHA-256 of every complete sealed slot byte, including its signature.
18    pub digest: [u8; 32],
19    /// Opened content and the policy decisions made against the preceding prefix.
20    pub content: SlotContent<R>,
21}
22
23/// One slot kind; readable write parts are applied together.
24pub enum SlotContent<R> {
25    /// Original writes in increasing author write-number order.
26    Writes {
27        /// The complete sealed slot's length, signature included.
28        size: u64,
29        /// The slot's inner writes.
30        writes: Vec<R>,
31    },
32    /// An original admin object and its checked effect, absent for a refusal.
33    Admin {
34        /// Exact signed evidence retained by store snapshots.
35        original: OriginalSlot,
36        /// The effect authorized by the preceding prefix.
37        effect: Option<AdminEffect>,
38    },
39    /// An authenticated key-copy object, including refused copies.
40    KeyCopy(OriginalSlot),
41    /// An authenticated snapshot announcement. Its original is kept only when
42    /// it is accepted: no rule reads a refused one (§16.1).
43    Announcement {
44        /// Exact signed evidence retained by store snapshots.
45        original: OriginalSlot,
46        /// The announcement as this device accepted it against the preceding
47        /// prefix; absent for a refused one, and for one a reload stages again
48        /// at or below its store snapshot's coverage, whose originals the
49        /// snapshot or this device already holds.
50        accepted: Option<coven_format::sequence::SnapshotAnnouncement>,
51    },
52}
53
54/// Membership and required reload work installed with an authorized admin slot.
55pub struct AdminEffect {
56    /// The checked original change.
57    pub change: StoreChange,
58    /// Membership, keys and audience state after the change, as this device
59    /// installs it: history's, except that a device of the member a store's
60    /// removal removes keeps every circle as it was (§14.1).
61    pub state: StoreState,
62    /// The activated snapshot for a raise or reset.
63    pub boundary: Option<crate::Boundary>,
64    /// The audience requiring replacement data: one change makes at most one.
65    /// `apply_slot` records its wait without consuming the slot, or, for a
66    /// circle below the device's breaking version, applies the slot and gates
67    /// the circle for its rebuild; `load_snapshots` installs the data.
68    pub reload: Option<coven_merge::Audience>,
69    /// Provider work recorded atomically with this state.
70    pub provider_access: Vec<crate::ProviderAccessChange>,
71}
72
73pub(crate) fn retain(db: &StoreSql, kind: &str, original: &OriginalSlot) -> Result<(), DbError> {
74    db.execute("INSERT INTO _coven_slot_records(slot,kind,record) VALUES(?1,?2,?3) ON CONFLICT(slot) DO NOTHING",
75        sqlive::rusqlite::params![original.slot.get().to_be_bytes().as_slice(),kind,original.object])?;
76    Ok(())
77}
78
79/// Forget the original slots of announcements no rule reads any more
80/// (§16.8). Each is a kept announcement's: one missing means the history the
81/// caller holds and these records disagree.
82pub(crate) fn forget_announcements(db: &StoreSql, slots: &BTreeSet<Slot>) -> Result<(), DbError> {
83    for slot in slots {
84        let deleted = db.execute(
85            "DELETE FROM _coven_slot_records WHERE slot=?1 AND kind='announcement'",
86            [slot.get().to_be_bytes()],
87        )?;
88        if deleted != 1 {
89            return Err(DbError::DamagedDatabase);
90        }
91    }
92    Ok(())
93}
94
95pub(crate) fn apply<P: crate::PendingValue>(
96    db: &mut StoreSql,
97    call: &StoreCall<'_>,
98    before: &StoreSql,
99    before_call: &StoreCall<'_>,
100    schema: &WriteSchema,
101    incoming: IncomingSlot<PreparedWrite<'_>>,
102    writers: &crate::Writers,
103    files: &crate::file_write::WriteFiles<'_>,
104    raises: Option<&crate::migration::MigrationOperation>,
105    joining: Option<&crate::joining_write::JoiningHook>,
106    now: std::time::SystemTime,
107    authenticate: impl FnOnce() -> Result<(), DbError>,
108) -> Result<crate::ApplyOutcome, DbError> {
109    // The slot that registers this device runs the app's joining write in the
110    // same transaction (§13.2).
111    let registering = match &incoming.content {
112        SlotContent::Admin { effect: Some(effect), .. } => {
113            crate::joining_write::owed(db, call, joining, &effect.state, schema, now, files)?
114        }
115        _ => None,
116    };
117    crate::download::source_wait(crate::local_write::stream_registering(
118        db,
119        call,
120        files,
121        registering,
122        |db| {
123            let outcome = apply_in::<P>(
124                db,
125                call,
126                before,
127                before_call,
128                schema,
129                incoming,
130                writers,
131                files,
132                raises,
133                now,
134                authenticate,
135            )?;
136            let applied = matches!(outcome, crate::ApplyOutcome::Applied);
137            Ok((outcome, applied))
138        },
139    ))
140}
141
142fn apply_in<P: crate::PendingValue>(
143    db: &StoreSql,
144    call: &StoreCall<'_>,
145    before: &StoreSql,
146    before_call: &StoreCall<'_>,
147    schema: &WriteSchema,
148    incoming: IncomingSlot<PreparedWrite<'_>>,
149    writers: &crate::Writers,
150    files: &crate::file_write::WriteFiles<'_>,
151    raises: Option<&crate::migration::MigrationOperation>,
152    now: std::time::SystemTime,
153    authenticate: impl FnOnce() -> Result<(), DbError>,
154) -> Result<crate::ApplyOutcome, DbError> {
155    {
156        let files = &crate::file_write::FileWrite::new(db, call, files);
157        // Applying a slot runs no migration and no DDL.
158        let _constants = crate::transaction_constants::keep_constants(db, call);
159        let applied = crate::sequence::applied(db)?;
160        if incoming.slot.get() <= applied {
161            return Ok(crate::ApplyOutcome::AlreadyApplied);
162        }
163        if applied.checked_add(1) != Some(incoming.slot.get()) || incoming.header.after > applied {
164            return Err(DbError::SequenceGap { applied, received: incoming.slot });
165        }
166        call.set_reset_change(Some(crate::reset_bytes::Change::Slot(incoming.slot.get())));
167        // Circles that became readable below this device's breaking version
168        // don't reload: the slot applies, and each waits for its rebuild.
169        let mut rebuilding = Vec::new();
170        if let SlotContent::Admin { effect: Some(effect), .. } = &incoming.content {
171            if let Some(audience) = &effect.reload {
172                if effect.state.rebuilt_by(audience, crate::raise_capture::breaking_version(db)?) {
173                    // The circle doesn't hold the slot back: it applies with
174                    // the circle gated (§18.3).
175                    rebuilding.push(audience.clone());
176                } else {
177                    authenticate()?;
178                    crate::reload_gate::require_reload::<P>(db, audience)?;
179                    return Ok(crate::ApplyOutcome::Waiting(crate::WriteWait::Reload(
180                        audience.clone(),
181                    )));
182                }
183            }
184        }
185        crate::download_stage::begin(db)?;
186        // An admin slot with an effect changes membership, cut-offs or
187        // boundaries, and with them how every queued write applies: every
188        // kept row is put back and the whole queue folds again. Any other
189        // slot puts back only the kept rows its writes reach (§6.2).
190        let whole = matches!(&incoming.content, SlotContent::Admin { effect: Some(_), .. });
191        let mut touched =
192            if whole { crate::published::restore(db, call, schema)? } else { BTreeSet::new() };
193        let mut reach = crate::queued_writes::Reach::new();
194        crate::pending::clear_slot(db, incoming.slot)?;
195        match incoming.content {
196            SlotContent::Writes { size, writes } => stage_writes::<P>(
197                db,
198                call,
199                schema,
200                incoming.slot,
201                &incoming.header,
202                size,
203                writes,
204                Staging::Next(&mut reach),
205            )?,
206            SlotContent::Admin { original, effect } => {
207                retain(db, "admin", &original)?;
208                if let Some(effect) = effect {
209                    let old = crate::store_state_tables::deleted_circles(db)?;
210                    let created =
211                        !crate::store_state_tables::created(db)? && effect.state.store.is_some();
212                    crate::sequence::cutoff(db, incoming.slot, &effect.change)?;
213                    crate::store_state_tables::replace(db, &effect.state)?;
214                    crate::rebuild_wait::release(db, call, &effect.state)?;
215                    if created {
216                        crate::raise_capture::capture_created(db, call, schema)?;
217                    }
218                    if let Some(circle) = effect.change.made_circle() {
219                        crate::raise_capture::capture_made(
220                            db,
221                            call,
222                            *circle,
223                            &effect.state,
224                            raises,
225                        )?;
226                    }
227                    crate::provider_access::adopt::<P>(db, &effect.provider_access)?;
228                    touched.extend(newly_deleted_rows(db, &old, &effect.state)?);
229                    if let Some(boundary) = effect.boundary {
230                        crate::write_boundary::record(db, &boundary)?;
231                    }
232                }
233            }
234            SlotContent::KeyCopy(original) => retain(db, "key", &original)?,
235            SlotContent::Announcement { original, accepted } => {
236                if let Some(announcement) = accepted {
237                    retain(db, "announcement", &original)?;
238                    snapshot_announced(db, &announcement)?;
239                }
240            }
241        }
242        authenticate()?;
243        crate::sequence::note_claim(db, &incoming.header, incoming.slot, incoming.digest)?;
244        crate::sequence::set_applied(db, incoming.slot.get())?;
245        if !rebuilding.is_empty() {
246            crate::rebuild_wait::begin::<P>(db, call, schema, now, &rebuilding)?;
247        }
248        crate::forget_records::forget(db, call, writers)?;
249        let refold = if whole {
250            crate::queued_writes::Refold::Whole
251        } else {
252            touched.extend(reach.restored().iter().cloned());
253            crate::queued_writes::Refold::Reached(&reach)
254        };
255        crate::queued_writes::overlay(db, call, schema, &mut touched, refold)?;
256        let deleted = crate::store_state_tables::deleted_circles(db)?;
257        crate::download_stage::materialize(
258            db,
259            call,
260            before,
261            before_call,
262            schema,
263            &deleted,
264            touched,
265            files,
266        )?;
267        files.before_commit()?;
268        crate::operation::end_on_stop(db)?;
269        Ok(crate::ApplyOutcome::Applied)
270    }
271}
272
273/// The rows of each circle `state` deletes that the deletions before it,
274/// `old`, don't: the removal rules take them out (§15.9).
275pub(crate) fn newly_deleted_rows(
276    db: &StoreSql,
277    old: &std::collections::BTreeMap<coven_foundation::id_source::CircleId, Slot>,
278    state: &StoreState,
279) -> Result<Vec<coven_merge::RowId>, DbError> {
280    let mut rows = Vec::new();
281    for circle in state.circle_deletions.keys().filter(|circle| !old.contains_key(circle)) {
282        rows.extend(db.query(
283            "SELECT DISTINCT table_name,key,audience FROM _coven_rows WHERE audience=?1",
284            [coven_merge::Audience::Circle(*circle)],
285            crate::row_queries::read_identity,
286        )?);
287    }
288    Ok(rows)
289}
290
291/// `announcement` was accepted, so no later reset of its audience names
292/// less coverage (§16.3). An ordinary snapshot's coverage only moves
293/// forward and is always usable, so a new device replays for its audience
294/// only the slots after it, and those at or below it never count toward that
295/// audience's next snapshot again (§16.2): their records of the audience's
296/// parts go, and each slot's size once no audience's part records it.
297fn snapshot_announced(
298    db: &StoreSql,
299    announcement: &coven_format::sequence::SnapshotAnnouncement,
300) -> Result<(), DbError> {
301    // No later reset of the audience names less coverage (§16.3).
302    crate::reset_bytes::bound(db, &announcement.snapshot.audience, announcement.covers)?;
303    if announcement.purpose != coven_format::sequence::Purpose::Ordinary {
304        return Ok(());
305    }
306    let covers = announcement.covers.to_be_bytes();
307    db.execute(
308        "DELETE FROM _coven_write_slot_audiences WHERE audience=?1 AND slot<=?2",
309        sqlive::rusqlite::params![announcement.snapshot.audience, covers],
310    )?;
311    db.execute(
312        "DELETE FROM _coven_write_slots WHERE slot<=?1
313         AND NOT EXISTS(SELECT 1 FROM _coven_write_slot_audiences a WHERE a.slot=_coven_write_slots.slot)",
314        [covers],
315    )?;
316    Ok(())
317}
318
319/// How a slot's writes are staged: as the next slot, or replayed by a reload.
320pub(crate) enum Staging<'a> {
321    /// The next slot, beside the queue: each write puts back the kept rows
322    /// it reaches before it merges (§6.2).
323    Next(&'a mut crate::queued_writes::Reach),
324    /// A reload's, into only the parts newer than their snapshots. The
325    /// reload put back every kept row first.
326    Reload(&'a crate::snapshot_coverage::SnapshotCoverage),
327}
328
329/// Ordinary application and reloads use the same ordering, cut-off and original
330/// validation.
331pub(crate) fn stage_writes<P: crate::PendingValue>(
332    db: &StoreSql,
333    call: &StoreCall<'_>,
334    schema: &WriteSchema,
335    slot: Slot,
336    header: &SlotHeader,
337    size: u64,
338    writes: Vec<PreparedWrite<'_>>,
339    mut staging: Staging<'_>,
340) -> Result<(), DbError> {
341    // A slot's object never changes, so a reload that stages it again
342    // finds the same size.
343    let stored = crate::sqlite::integer("writes slot size", size)?;
344    db.execute(
345        "INSERT INTO _coven_write_slots(slot,size) VALUES(?1,?2) ON CONFLICT(slot) DO NOTHING",
346        sqlive::rusqlite::params![slot.get().to_be_bytes(), stored],
347    )?;
348    // The parts of a circle awaiting its rebuild pass unread.
349    let gated: BTreeSet<_> = match &staging {
350        Staging::Next(_) => crate::reload_gate::rebuilding(db)?.into_keys().collect(),
351        Staging::Reload(_) => BTreeSet::new(),
352    };
353    let mut previous = None;
354    for write in writes {
355        header.check_write(&write.header().header)?;
356        if previous.is_some_and(|number| number >= write.header().header.position.number) {
357            return Err(crate::snapshot_error::invalid(
358                "slot writes are not in original number order",
359            ));
360        }
361        previous = Some(write.header().header.position.number);
362        for part in &write.header().parts {
363            db.execute(
364                "INSERT INTO _coven_write_slot_audiences(audience,slot) VALUES(?1,?2) ON CONFLICT DO NOTHING",
365                sqlive::rusqlite::params![part.audience, slot.get().to_be_bytes()],
366            )?;
367        }
368        let cutoff =
369            crate::sequence::refusal(db, slot, header.device, header.author, write.signer())?;
370        // A write above the rebuild's version is ahead of every audience the
371        // rebuild holds. The rebuild can't hold its changes at its version, so
372        // it keeps them as frozen lost values naming the breaking version the
373        // write needs (§18.3).
374        let schema_version = write.header().header.schema_version;
375        let ahead = match &staging {
376            Staging::Reload(coverage)
377                if coverage.is_rebuild()
378                    && schema_version > crate::transaction_constants::schema_version(db, call)? =>
379            {
380                Some(coverage.needed(schema_version).ok_or(DbError::Invariant {
381                    what: "a rebuild knows the breaking migration a write above it needs",
382                })?)
383            }
384            _ => None,
385        };
386        if let Some((cutoff, cause)) = cutoff {
387            db.execute("INSERT INTO _coven_write_refusals(slot,cutoff) VALUES(?1,?2) ON CONFLICT(slot) DO NOTHING",
388                sqlive::rusqlite::params![slot.get().to_be_bytes(), cutoff.get().to_be_bytes()])?;
389            crate::pending::save(db, &P::writes_refused(slot, cutoff, cause))?;
390        }
391        if let Staging::Reload(coverage) = &staging {
392            for audience in write.unopened_audiences() {
393                if coverage.needs(audience, slot) {
394                    return Err(crate::snapshot_error::invalid(
395                        "reload lacks a readable audience part",
396                    ));
397                }
398            }
399        }
400        match &mut staging {
401            Staging::Next(reach) => crate::download_stream::stage_selected(
402                db,
403                call,
404                schema,
405                write,
406                slot,
407                cutoff.is_some(),
408                None,
409                |audience| !gated.contains(audience),
410                Some(reach),
411            )?,
412            Staging::Reload(coverage) => crate::download_stream::stage_selected(
413                db,
414                call,
415                schema,
416                write,
417                slot,
418                cutoff.is_some(),
419                ahead,
420                |audience| coverage.needs(audience, slot),
421                None,
422            )?,
423        }
424    }
425    Ok(())
426}
427
428impl<R: std::io::Read> IncomingSlot<crate::DownloadedWriteStream<R>> {
429    pub(crate) fn prepare<'a>(
430        self,
431        inputs: &crate::input_preparation::PreparedInputs<'a>,
432    ) -> Result<IncomingSlot<PreparedWrite<'a>>, DbError> {
433        let content = match self.content {
434            SlotContent::Writes { size, writes } => SlotContent::Writes {
435                size,
436                writes: writes
437                    .into_iter()
438                    .map(|write| write.prepare(inputs))
439                    .collect::<Result<_, _>>()?,
440            },
441            SlotContent::Admin { original, effect } => SlotContent::Admin { original, effect },
442            SlotContent::KeyCopy(original) => SlotContent::KeyCopy(original),
443            SlotContent::Announcement { original, accepted } => {
444                SlotContent::Announcement { original, accepted }
445            }
446        };
447        Ok(IncomingSlot { slot: self.slot, header: self.header, digest: self.digest, content })
448    }
449}
450
451#[cfg(test)]
452#[path = "sequence_apply_tests.rs"]
453pub(crate) mod tests;