Skip to main content

coven_database/
download_stream.rs

1//! Incremental write parts supplied by synchronization.
2
3use crate::sqlite::StoreSql;
4use crate::store_call::StoreCall;
5use crate::SnapshotError;
6use coven_format::chunks::CHUNK_SIZE;
7use coven_format::dismissal::WriteFrame;
8use coven_format::write_stream::{PartDecoder, WriteHeaderFrame};
9use std::io::Read;
10
11/// A checked write header and its audience streams. The database commits only
12/// after sync confirms authentication. Parts follow the header's order and count.
13pub struct DownloadedWriteStream<R> {
14    /// Authenticated identity, causality and plaintext stream boundaries.
15    pub header: WriteHeaderFrame,
16    /// Opened plaintext or an explicit unreadable audience, in header order.
17    pub parts: Vec<DownloadedPartStream<R>>,
18    /// The key that authenticated this original in its authored view.
19    pub signer: coven_crypto::SigningKey,
20    /// The signed header evidence and each opened part's keyed leaf hasher.
21    pub authorship: WriteAuthorship,
22}
23
24/// A write's signed header and part roots, and the hashers that check each
25/// opened part against its root (D9, D11). The database checks the roots;
26/// sync checks the header signature with the rest of the object.
27#[derive(Clone)]
28pub struct WriteAuthorship {
29    /// The cleartext prefix, sealed header, roots and header signature.
30    pub evidence: crate::HeaderEvidence,
31    /// Each part's keyed leaf hasher, in header order, for the opened parts.
32    pub hashers: Vec<Option<coven_crypto::AuthorshipHasher>>,
33}
34
35impl WriteAuthorship {
36    fn root(&self, part: usize) -> Result<crate::authorship::PartRoot, crate::DbError> {
37        let hasher =
38            self.hashers.get(part).cloned().flatten().ok_or(crate::DbError::Invariant {
39                what: "an opened part has its authorship hasher",
40            })?;
41        let root =
42            *self.evidence.roots.get(part).ok_or_else(|| {
43                crate::snapshot_error::invalid("write evidence lacks a part's root")
44            })?;
45        Ok(crate::authorship::PartRoot::new(hasher, root))
46    }
47}
48
49fn hash_frame(
50    root: &mut crate::authorship::PartRoot,
51    frame: &WriteFrame,
52) -> Result<(), crate::DbError> {
53    match frame.record() {
54        Some(record) => root.record(record),
55        None => Ok(()),
56    }
57}
58
59/// Whether sync could decrypt the corresponding part in the header.
60pub enum DownloadedPartStream<R> {
61    /// A complete plaintext part stream, starting at its first byte.
62    Opened(R),
63    /// The part is outside this installation's current audience.
64    Skipped,
65}
66
67pub(crate) struct PreparedWrite<'a> {
68    header: WriteHeaderFrame,
69    parts: Vec<Option<PreparedPart<'a>>>,
70    signer: coven_crypto::SigningKey,
71    evidence: crate::HeaderEvidence,
72}
73pub(crate) struct PreparedPart<'a> {
74    records: crate::input_preparation::PreparedRecords<'a>,
75    hashes: Vec<[u8; 32]>,
76}
77impl<R: Read> DownloadedWriteStream<R> {
78    pub(crate) fn prepare<'a>(
79        self,
80        inputs: &crate::input_preparation::PreparedInputs<'a>,
81    ) -> Result<PreparedWrite<'a>, crate::DbError> {
82        if self.header.parts.len() != self.parts.len()
83            || self.authorship.evidence.roots.len() != self.parts.len()
84        {
85            return Err(
86                SnapshotError::Inconsistent("write stream count differs from its header").into()
87            );
88        }
89        let mut parts = Vec::new();
90        for (index, (header, stream)) in self.header.parts.iter().zip(self.parts).enumerate() {
91            match stream {
92                DownloadedPartStream::Skipped => parts.push(None),
93                DownloadedPartStream::Opened(input) => {
94                    let mut records = inputs.records();
95                    let mut root = self.authorship.root(index)?;
96                    read_part(input, header.clone(), |frame| {
97                        hash_frame(&mut root, &frame)?;
98                        records.push(coven_format::merge_fields::encode_write_frame(&frame)?)
99                    })?;
100                    parts.push(Some(PreparedPart { records, hashes: root.finish()? }));
101                }
102            }
103        }
104        Ok(PreparedWrite {
105            header: self.header,
106            parts,
107            signer: self.signer,
108            evidence: self.authorship.evidence,
109        })
110    }
111}
112impl PreparedWrite<'_> {
113    /// The write's header frame.
114    pub(crate) fn header(&self) -> &WriteHeaderFrame {
115        &self.header
116    }
117    /// The key the write was signed with.
118    pub(crate) fn signer(&self) -> &coven_crypto::SigningKey {
119        &self.signer
120    }
121    /// The audiences of parts this installation could not open.
122    pub(crate) fn unopened_audiences(&self) -> impl Iterator<Item = &coven_merge::Audience> {
123        self.header
124            .parts
125            .iter()
126            .zip(&self.parts)
127            .filter(|(_, part)| part.is_none())
128            .map(|(header, _)| &header.audience)
129    }
130}
131
132/// Stage one prepared original into the store's connection, inside its
133/// containing slot's transaction. The caller materializes the complete batch
134/// only after all parts authenticate. Before the write merges, or is consumed
135/// refused, `reach` puts back the kept rows it reaches beside the queue
136/// (§6.2); a reload passes none, having put back every kept row first.
137/// `ahead` is the breaking version a rebuild's write above its database's
138/// version needs: the write doesn't wait, and each of its changes is kept as a
139/// frozen lost value (§18.3).
140pub(crate) fn stage_selected(
141    database: &StoreSql,
142    call: &StoreCall<'_>,
143    schema: &crate::write_schema::WriteSchema,
144    write: PreparedWrite<'_>,
145    slot: coven_merge::Slot,
146    refused: bool,
147    ahead: Option<u32>,
148    selected: impl Fn(&coven_merge::Audience) -> bool,
149    reach: Option<&mut crate::queued_writes::Reach>,
150) -> Result<(), crate::DbError> {
151    let opened: Vec<_> = write
152        .header
153        .parts
154        .iter()
155        .zip(&write.parts)
156        .filter(|(part, stream)| selected(&part.audience) && stream.is_some())
157        .map(|(part, _)| part.audience.clone())
158        .collect();
159    // A write the cut-off consumes is never judged, so what it claims to
160    // have read decides nothing (§14.1).
161    if !refused {
162        crate::write_commit::check_reads(database, &write.header.header)?;
163        if ahead.is_none() {
164            if let Some(wait) = crate::download::prerequisite(database, call, &write.header.header)?
165            {
166                return Err(crate::DbError::WriteWaiting(wait));
167            }
168        }
169    }
170    if !refused {
171        crate::merge_store::MergeStore::from_staged(database, call, &schema.schema).apply(
172            &coven_format::write::WriteRecord {
173                header: write.header.header.clone(),
174                parts: vec![],
175            },
176        )?;
177    }
178    crate::forget_entries::superseded(database, write.header.header.position)?;
179    crate::write_commit::retain_original(database, &write.header.header, Some(slot))?;
180    let original_header = write.header.clone();
181    let form = crate::write_sources::KeptForm::new(schema, original_header.header.schema_version);
182    let boundaries = crate::write_boundary::WriteBoundary::judging(database)?;
183    let mut dismissed = Vec::new();
184    read_authenticated(database, call, write, |header, audience, frame| {
185        if !selected(audience) {
186            return Ok(());
187        }
188        if let WriteFrame::Dismissal(dismissal) = &frame {
189            dismissed.push(dismissal.row.clone());
190        }
191        if refused {
192            if let Some(record) = frame.record() {
193                crate::write_sources::retain(database, call, &form, header, record)?;
194                crate::write_sources::admit(
195                    database,
196                    call,
197                    header,
198                    record.row(),
199                    &coven_format::snapshot_rows::ChangeVerdict::Refused,
200                )?;
201            }
202            return Ok(());
203        }
204        let ignored =
205            crate::write_boundary::WriteBoundary::ignore(&boundaries, header, audience, Some(slot));
206        crate::download_stage::frame(database, call, &form, header, ignored, frame)
207    })?;
208    if let Some(reach) = reach {
209        crate::queued_writes::put_back(
210            database,
211            call,
212            schema,
213            &original_header.header,
214            reach,
215            dismissed,
216        )?;
217    }
218    if refused {
219        crate::forget_records::none_current(
220            database,
221            original_header.header.position,
222            &opened,
223            slot,
224        )?;
225    } else {
226        crate::download_stage::stage(
227            database,
228            call,
229            schema,
230            &original_header.header,
231            &opened,
232            Some(slot),
233            ahead,
234            |audience| Ok(selected(audience)),
235        )?;
236    }
237    crate::download_stage::release(database, &original_header.header)
238}
239
240/// Retain a prepared write's authenticated source evidence in the store's
241/// connection without changing rows or admission.
242#[cfg(test)]
243pub(crate) fn retain_sources(
244    db: &StoreSql,
245    call: &StoreCall<'_>,
246    schema: &crate::write_schema::WriteSchema,
247    write: PreparedWrite<'_>,
248) -> Result<(), crate::DbError> {
249    crate::download_stage::begin(db)?;
250    let header = write.header.header.clone();
251    let form = crate::write_sources::KeptForm::new(schema, header.schema_version);
252    read_authenticated(db, call, write, |header, _, frame| {
253        if let Some(record) = frame.record() {
254            crate::write_sources::retain(db, call, &form, header, record)?;
255        }
256        Ok(())
257    })?;
258    crate::download_stage::release(db, &header)
259}
260
261/// Hand each opened part's prepared records to `consume`, then keep the
262/// write's plaintext header, and, for another member's write, each part's
263/// leaf hashes and the header evidence in the store's connection
264/// (`authorship::keeps_evidence`).
265fn read_authenticated(
266    database: &StoreSql,
267    call: &StoreCall<'_>,
268    write: PreparedWrite<'_>,
269    mut consume: impl FnMut(
270        &coven_format::write::WriteHeader,
271        &coven_merge::Audience,
272        WriteFrame,
273    ) -> Result<(), crate::DbError>,
274) -> Result<(), crate::DbError> {
275    let position = write.header.header.position;
276    let evidence = crate::authorship::keeps_evidence(database, call, position)?;
277    for (header, part) in write.header.parts.iter().zip(write.parts) {
278        let Some(part) = part else {
279            continue;
280        };
281        part.records.each(|bytes| {
282            consume(&write.header.header, &header.audience, WriteFrame::decode(&bytes)?)
283        })?;
284        if evidence {
285            crate::authorship::retain_leaves(database, position, &header.audience, &part.hashes)?;
286        }
287    }
288    crate::write_headers::retain(database, &write.header)?;
289    if evidence {
290        crate::authorship::retain_header(database, position, &write.evidence)?;
291    }
292    Ok(())
293}
294
295/// Decode and validate one part without collecting its row frames. Every
296/// consumer checks the same chunk lengths, record counts, ordering and EOF.
297pub(crate) fn read_part<R: Read, E: From<SnapshotError> + From<coven_format::Error>>(
298    mut input: R,
299    header: coven_format::write_stream::PartHeader,
300    consume: impl FnMut(WriteFrame) -> Result<(), E>,
301) -> Result<(), E> {
302    visit_part(
303        header,
304        |chunk| input.read_exact(chunk).map_err(|error| SnapshotError::Read(error).into()),
305        consume,
306    )?;
307    let mut trailing = [0];
308    loop {
309        match input.read(&mut trailing) {
310            Ok(0) => return Ok(()),
311            Ok(_) => return Err(coven_format::Error::TrailingBytes.into()),
312            Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
313            Err(error) => return Err(SnapshotError::Read(error).into()),
314        }
315    }
316}
317
318/// Visit a part from either an I/O stream or the upload queue's SQLite BLOB.
319/// The source fills each requested chunk exactly; the decoder checks framing,
320/// ordering, audience and record count before completing the part.
321pub(crate) fn visit_part<E: From<coven_format::Error>>(
322    header: coven_format::write_stream::PartHeader,
323    mut read_chunk: impl FnMut(&mut [u8]) -> Result<(), E>,
324    mut consume: impl FnMut(WriteFrame) -> Result<(), E>,
325) -> Result<(), E> {
326    let mut left = header.plaintext_length;
327    let mut decoder = PartDecoder::new(header)?;
328    let mut chunk = [0; CHUNK_SIZE];
329    while left > 0 {
330        let length = left.min(CHUNK_SIZE as u64) as usize;
331        read_chunk(&mut chunk[..length])?;
332        for frame in decoder.chunk(&chunk[..length])? {
333            consume(frame)?;
334        }
335        left -= length as u64;
336    }
337    decoder.finish()?;
338    Ok(())
339}