Skip to main content

coven_database/
input_database.rs

1//! Durable remote observations, independently committed while application writes run.
2
3use super::StoreDatabase;
4use crate::app_policy::CovenPolicy;
5use crate::sqlite::StoreSql;
6use crate::store_call::{StoreCall, TestRecords};
7use crate::DbError;
8use coven_format::path::{ObjectPath, PathError};
9use coven_foundation::id_source::{DeviceId, KeyId, ObjectId};
10use coven_foundation::locks::{lock_unpoisoned, read_unpoisoned, write_unpoisoned};
11use sqlive::Database;
12use std::collections::{BTreeMap, BTreeSet};
13use std::sync::{Arc, Mutex, RwLock, Weak};
14
15#[path = "input_bytes.rs"]
16mod bytes;
17pub use bytes::RetainedBytes;
18#[path = "snapshot_staging.rs"]
19pub(crate) mod staging;
20#[cfg(any(test, feature = "test-utils"))]
21pub use staging::StagedDamage;
22pub use staging::{SnapshotStaging, StagedDigest};
23
24/// The input database, `None` once the store closes it. The store shares it
25/// with the retained bytes read from it, whose reads after the close fail.
26/// Closing takes the database out in one step, so a panic never leaves it
27/// half closed, and every caller takes the lock even when a panic poisoned
28/// it.
29type InputConnection = Arc<RwLock<Option<Database<CovenPolicy>>>>;
30
31fn read_local<R>(
32    database: &InputConnection,
33    run: impl FnOnce(&StoreSql, &StoreCall<'_>) -> Result<R, DbError>,
34) -> Result<R, DbError> {
35    let guard = read_unpoisoned(database);
36    let database = guard.as_ref().ok_or(DbError::StoreClosed)?;
37    let reader = database.reader();
38    reader.host(|reader| {
39        // Reading the input catalog records none of coven's work.
40        crate::store_call::outside_store(|call| {
41            crate::transaction_constants::read_with_constants(reader, call, || run(reader, call))
42        })
43    })
44}
45
46pub(crate) struct InputDatabase {
47    database: InputConnection,
48    /// What coven's tests read back of the calls on the input writer.
49    tests: TestRecords,
50    active: Arc<Mutex<BTreeMap<i64, Weak<InputRead>>>>,
51    /// The next snapshot staging's number; 0 is the installing snapshot's.
52    stagings: std::sync::atomic::AtomicI64,
53    /// A test's request to damage a staging before the next load or file
54    /// check reads it, as damage on this device's disk would.
55    #[cfg(any(test, feature = "test-utils"))]
56    damage_staged: Mutex<Option<staging::StagedDamage>>,
57    /// A test's request to damage the next stagings that finish, and how
58    /// many, before finishing checks them, as damage on this device's disk
59    /// would.
60    #[cfg(any(test, feature = "test-utils"))]
61    damage_finishing: Mutex<Option<(staging::StagedDamage, u32)>>,
62    /// A test's request to fail the next removal of the stagings a failed
63    /// load or file check ends, as a disk error would.
64    #[cfg(any(test, feature = "test-utils"))]
65    fail_removal: std::sync::atomic::AtomicBool,
66}
67
68struct InputRead {
69    id: i64,
70    active: Weak<Mutex<BTreeMap<i64, Weak<InputRead>>>>,
71    receiving: tokio::sync::Mutex<()>,
72}
73
74impl Drop for InputRead {
75    fn drop(&mut self) {
76        if let Some(active) = self.active.upgrade() {
77            let mut active = lock_unpoisoned(&active);
78            // A concurrent new reader may already have replaced this expired weak entry.
79            if active.get(&self.id).is_some_and(|saved| saved.strong_count() == 0) {
80                active.remove(&self.id);
81            }
82        }
83    }
84}
85
86/// One observed object version. A replacement invalidates the preceding handle.
87#[derive(Clone)]
88pub struct RetainedInput {
89    database: StoreDatabase,
90    id: i64,
91    reading: Arc<InputRead>,
92}
93
94/// Encrypted bytes received for one provider observation; completion is separate.
95pub struct RetainedRange {
96    /// Byte offset in the encrypted object.
97    pub offset: u64,
98    /// The exact provider bytes.
99    pub bytes: Vec<u8>,
100}
101
102/// Retained encrypted bytes have a maintained total and explicit eviction count.
103#[derive(Clone, Copy, Debug, PartialEq, Eq)]
104pub struct InputBudget {
105    /// Maximum retained encrypted bytes, excluding checked metadata and references.
106    pub maximum: u64,
107    /// Currently retained encrypted bytes.
108    pub retained: u64,
109    /// Bytes explicitly evicted since this catalog was created.
110    pub evicted: u64,
111}
112
113/// Copy the current claim attempt's exact bytes from the store connection into
114/// the input catalog, so applying a landed claim reads no provider bytes.
115fn copy_claim(inputs: &InputDatabase, source: &StoreSql, id: i64) -> Result<(), DbError> {
116    inputs.write(|db, _| {
117        db.execute("DELETE FROM _coven_input_ranges WHERE object=?1", [id])?;
118        crate::claim::read_attempt::<_, DbError>(source, |chunks| {
119            let mut offset = 0u64;
120            for chunk in chunks {
121                let bytes = chunk?;
122                let start = sql_offset(offset)?;
123                offset += bytes.len() as u64;
124                db.execute(
125                    "INSERT INTO _coven_input_ranges(object,start,end,bytes) VALUES(?1,?2,?3,?4)",
126                    (id, start, sql_offset(offset)?, bytes),
127                )?;
128            }
129            Ok(())
130        })?;
131        db.execute("UPDATE _coven_input_objects SET received=1 WHERE id=?1", [id])?;
132        evict(db, &inputs.active)
133    })
134}
135
136impl InputDatabase {
137    /// Prepare inputs for one slot's application, in one input transaction.
138    pub(crate) fn prepare<T>(
139        &self,
140        consume: impl FnOnce(&crate::input_preparation::PreparedInputs<'_>) -> Result<T, DbError>,
141    ) -> Result<T, DbError> {
142        self.with_writer(|writer, _| {
143            writer.transaction(|db| {
144                let inputs = crate::input_preparation::PreparedInputs::new(db)?;
145                let result = consume(&inputs)?;
146                inputs.finish()?;
147                Ok(result)
148            })
149        })
150    }
151    pub(crate) fn prepare_claim<T>(
152        &self,
153        attempt: crate::ClaimAttempt<impl std::io::Read>,
154        consume: impl FnOnce(
155            crate::claim_preparation::PreparedClaim<crate::claim_preparation::PreparedBytes<'_>>,
156        ) -> Result<T, DbError>,
157    ) -> Result<T, DbError> {
158        self.with_writer(|writer, _| {
159            writer.transaction(|db| crate::claim_preparation::prepare(db, attempt, consume))
160        })
161    }
162    /// Drop an object's received bytes and its receipt, so its next read
163    /// fetches it again.
164    fn discard(&self, id: i64) -> Result<(), DbError> {
165        self.write(|db, _| {
166            db.execute("DELETE FROM _coven_input_ranges WHERE object=?1", [id])?;
167            db.execute("UPDATE _coven_input_objects SET received=0 WHERE id=?1", [id])?;
168            Ok(())
169        })
170    }
171
172    fn release(&self, ids: Vec<i64>) -> Result<(), DbError> {
173        let pending = self.read(|db, _| {
174            let mut pending = Vec::new();
175            for id in ids {
176                if !db.query_row(
177                    "SELECT released FROM _coven_input_objects WHERE id=?1",
178                    [id],
179                    |r| r.get::<_, bool>(0),
180                )? {
181                    pending.push(id);
182                }
183            }
184            Ok(pending)
185        })?;
186        if pending.is_empty() {
187            return Ok(());
188        }
189        self.write(|db, _| {
190            for id in pending {
191                db.execute("UPDATE _coven_input_objects SET released=1 WHERE id=?1", [id])?;
192            }
193            Ok(())
194        })
195    }
196    #[cfg(any(test, feature = "test-utils"))]
197    pub(super) fn test_track_work(&self, counter: &crate::test_utils::WorkCounter) {
198        let database = read_unpoisoned(&self.database);
199        let database = database.as_ref().expect("the store keeps its input database open");
200        database.each_reader(|reader| counter.track(reader));
201        database.host(|writer| counter.track(writer));
202        self.tests.track_work(counter.clone());
203    }
204    /// The input database `database`. Its writer's temporary storage, on
205    /// disk, holds prepared inputs and staged snapshots.
206    pub(crate) fn new(database: Database<CovenPolicy>) -> Result<Self, DbError> {
207        database.host(|writer| staging::create_tables(writer))?;
208        Ok(Self {
209            database: Arc::new(RwLock::new(Some(database))),
210            tests: TestRecords::new(),
211            active: Arc::new(Mutex::new(BTreeMap::new())),
212            stagings: std::sync::atomic::AtomicI64::new(1),
213            #[cfg(any(test, feature = "test-utils"))]
214            damage_staged: Mutex::new(None),
215            #[cfg(any(test, feature = "test-utils"))]
216            damage_finishing: Mutex::new(None),
217            #[cfg(any(test, feature = "test-utils"))]
218            fail_removal: std::sync::atomic::AtomicBool::new(false),
219        })
220    }
221
222    fn reading(&self, id: i64) -> Arc<InputRead> {
223        let mut active = lock_unpoisoned(&self.active);
224        if let Some(reading) = active.get(&id).and_then(Weak::upgrade) {
225            return reading;
226        }
227        let reading = Arc::new(InputRead {
228            id,
229            active: Arc::downgrade(&self.active),
230            receiving: tokio::sync::Mutex::new(()),
231        });
232        active.insert(id, Arc::downgrade(&reading));
233        reading
234    }
235
236    pub(crate) fn close(self) -> Vec<DbError> {
237        let database = write_unpoisoned(&self.database).take();
238        let database = database.expect("the store closes its input database once");
239        database.close().into_iter().map(DbError::from).collect()
240    }
241
242    fn read<R>(
243        &self,
244        run: impl FnOnce(&StoreSql, &StoreCall<'_>) -> Result<R, DbError>,
245    ) -> Result<R, DbError> {
246        read_local(&self.database, run)
247    }
248
249    fn write<R>(
250        &self,
251        run: impl FnOnce(&StoreSql, &StoreCall<'_>) -> Result<R, DbError>,
252    ) -> Result<R, DbError> {
253        self.with_writer(|writer, call| {
254            #[cfg(any(test, feature = "test-utils"))]
255            self.tests.record_work(|work| work.writer_holds += 1);
256            writer.transaction(|db| run(db, call))
257        })
258    }
259
260    /// Run `run` on the input writer, with constants of its own.
261    fn with_writer<R>(&self, run: impl FnOnce(&mut StoreSql, &StoreCall<'_>) -> R) -> R {
262        let database = read_unpoisoned(&self.database);
263        let database = database.as_ref().expect("the store keeps its input database open");
264        database.host(|writer| run(writer, &crate::store_call::StoreCall::new(None, &self.tests)))
265    }
266}
267
268#[expect(
269    clippy::map_err_ignore,
270    reason = "a size past the target integer is TooLarge, which names the field and size"
271)]
272fn sql_offset(value: u64) -> Result<i64, DbError> {
273    i64::try_from(value).map_err(|_| DbError::TooLarge {
274        field: "retained input bytes",
275        actual: value,
276        maximum: i64::MAX as u64,
277    })
278}
279
280fn observation(db: &StoreSql, path: &str) -> Result<Option<(i64, Vec<u8>)>, DbError> {
281    Ok(db
282        .query("SELECT id,identity FROM _coven_input_objects WHERE path=?1", [path], |r| {
283            Ok((r.get(0)?, r.get(1)?))
284        })?
285        .into_iter()
286        .next())
287}
288
289// Nonoverlapping ranges need at most the immediately preceding range plus
290// ranges beginning inside the requested interval. Seek to that boundary.
291const RANGES: &str = "SELECT max(start,?2),substr(bytes,max(start,?2)-start+1,min(end,?3)-max(start,?2)) FROM _coven_input_ranges WHERE object=?1 AND start>=coalesce((SELECT start FROM _coven_input_ranges WHERE object=?1 AND start<=?2 ORDER BY start DESC LIMIT 1),?2) AND start<?3 AND end>?2 ORDER BY start";
292
293fn budget(db: &StoreSql) -> Result<InputBudget, DbError> {
294    Ok(db.query_row(
295        "SELECT maximum,retained,evicted FROM _coven_input_budget WHERE singleton=1",
296        [],
297        |r| {
298            Ok(InputBudget {
299                maximum: r.get::<_, i64>(0)? as u64,
300                retained: r.get::<_, i64>(1)? as u64,
301                evicted: r.get::<_, i64>(2)? as u64,
302            })
303        },
304    )?)
305}
306
307fn evict(db: &StoreSql, active: &Mutex<BTreeMap<i64, Weak<InputRead>>>) -> Result<(), DbError> {
308    // A released object can be borrowed by another consumer. Keep its bytes
309    // until that consumer drops its handle, including across network awaits.
310    let active = lock_unpoisoned(active);
311    let before = budget(db)?;
312    let mut retained = before.retained;
313    let mut after = 0;
314    while retained > before.maximum {
315        let next = db.query(
316            "SELECT r.id,r.object FROM _coven_input_ranges r JOIN _coven_input_objects o ON o.id=r.object WHERE o.released=1 AND r.id>?1 ORDER BY r.id LIMIT 1",
317            [after], |r| Ok((r.get::<_,i64>(0)?, r.get::<_,i64>(1)?)),
318        )?.into_iter().next();
319        let Some((id, object)) = next else {
320            return Err(DbError::InputBudgetExceeded {
321                required: retained,
322                maximum: before.maximum,
323            });
324        };
325        after = id;
326        if active.get(&object).is_some_and(|input| input.strong_count() > 0) {
327            continue;
328        }
329        // Evict a complete input together: retaining only its suffix would
330        // turn the next read into separate requests around an internal gap.
331        db.execute("DELETE FROM _coven_input_ranges WHERE object=?1", [object])?;
332        retained = budget(db)?.retained;
333    }
334    let evicted = before.retained - retained;
335    if evicted > 0 {
336        db.execute(
337            "UPDATE _coven_input_budget SET evicted=evicted+?1 WHERE singleton=1",
338            [sql_offset(evicted)?],
339        )?;
340        tracing::debug!(bytes = evicted, retained, "evicted retained remote input bytes");
341    }
342    Ok(())
343}
344
345impl InputDatabase {
346    /// Delete the records of the objects `select` picks, except those a live
347    /// handle holds: a reader in flight keeps its rows. The cascades take each
348    /// record's ranges, file evidence and unread parts.
349    fn forget(&self, select: &str, params: impl sqlive::rusqlite::Params) -> Result<(), DbError> {
350        self.write(|db, _| {
351            let active = lock_unpoisoned(&self.active);
352            for object in db.query(select, params, |r| r.get::<_, i64>(0))? {
353                if active.get(&object).is_some_and(|input| input.strong_count() > 0) {
354                    continue;
355                }
356                db.execute("DELETE FROM _coven_input_objects WHERE id=?1", [object])?;
357            }
358            Ok(())
359        })
360    }
361
362    fn forget_slots_below(&self, first: u64) -> Result<(), DbError> {
363        self.forget("SELECT id FROM _coven_input_objects WHERE slot<?1", [sql_offset(first)?])
364    }
365
366    pub(crate) fn forget_path(&self, path: &str) -> Result<(), DbError> {
367        self.forget("SELECT id FROM _coven_input_objects WHERE path=?1", [path])
368    }
369}
370
371impl StoreDatabase {
372    /// Forget the input records of the slots below a checked floor's `first`:
373    /// nothing reads them again (§16.4). A record a live read holds stays.
374    pub async fn forget_slot_inputs_below(
375        &self,
376        first: coven_format::value::Slot,
377    ) -> Result<(), DbError> {
378        self.call(move |inner| inner.inputs.forget_slots_below(first.get())).await
379    }
380
381    /// A seekable local input for applying the current claim without a provider
382    /// reread after successful creation. One cache identity is reused across
383    /// claims; the journal remains the authoritative copy until settlement.
384    #[cfg(any(test, feature = "test-utils"))]
385    pub async fn claim_input(&self) -> Result<RetainedBytes, DbError> {
386        let (database, reading, length) = self.call(|inner| {
387            inner.access.with_committed(|source, _| {
388                let upload = crate::claim::upload(source)?;
389                let id = inner.inputs.write(|db: &StoreSql, _| {
390                    db.execute("DELETE FROM _coven_input_objects WHERE path='local-claim'", [])?;
391                    Ok(db.query_row("INSERT INTO _coven_input_objects(path,identity,observation) VALUES('local-claim',x'',x'') RETURNING id", [], |row| row.get(0))?)
392                })?;
393                let reading = inner.inputs.reading(id);
394                copy_claim(&inner.inputs, source, id)?;
395                inner.inputs.release(vec![id])?;
396                Ok::<_, DbError>((inner.inputs.database.clone(), reading, upload.size))
397            })
398        }).await?;
399        Ok(RetainedBytes::new(database, reading, length))
400    }
401    /// The retained provider observation of an exact path, if any. A drained
402    /// writer's discovered objects are found here instead of by probing (§6.1).
403    pub async fn retained_observation(&self, path: String) -> Result<Option<Vec<u8>>, DbError> {
404        self.call(move |inner| {
405            inner.inputs.read(|db, _| {
406                Ok(db
407                    .query(
408                        "SELECT observation FROM _coven_input_objects WHERE path=?1",
409                        [&path],
410                        |r| r.get(0),
411                    )?
412                    .into_iter()
413                    .next())
414            })
415        })
416        .await
417    }
418
419    /// Retain a provider observation before reading it. Immutable identity changes
420    /// return `None` and preserve the preceding evidence. A replacement discards
421    /// only that path's preceding version. Equal observations acquire no writer.
422    pub async fn observe_input(
423        &self,
424        path: String,
425        identity: Vec<u8>,
426        observation_bytes: Vec<u8>,
427        replaceable: bool,
428    ) -> Result<Option<RetainedInput>, DbError> {
429        let slot = ObjectPath::parse(&path)
430            .map_err(|PathError| DbError::Invariant {
431                what: "an observed input names a storage path",
432            })?
433            .slot_number()
434            .map(|slot| sql_offset(slot.get()))
435            .transpose()?;
436        let id = self.call(move |inner| {
437            let previous = inner.inputs.read(|db, _| observation(db, &path))?;
438            match previous {
439                Some((id, saved)) if saved == identity => return Ok(Some(id)),
440                Some(_) if !replaceable => return Ok(None),
441                _ => (),
442            }
443            inner.inputs.write(|db: &StoreSql, _| {
444                match observation(db, &path)? {
445                    Some((id, saved)) if saved == identity => return Ok(Some(id)),
446                    Some(_) if !replaceable => return Ok(None),
447                    _ => (),
448                }
449                db.execute("DELETE FROM _coven_input_objects WHERE path=?1", [&path])?;
450                Ok(db.query_row("INSERT INTO _coven_input_objects(path,slot,identity,observation) VALUES(?1,?2,?3,?4) RETURNING id", (&path, slot, &identity, &observation_bytes), |r| r.get(0)).map(Some)?)
451            })
452        }).await?;
453        match id {
454            None => Ok(None),
455            Some(id) => {
456                let reading =
457                    self.call(move |inner| Ok::<_, DbError>(inner.inputs.reading(id))).await?;
458                Ok(Some(RetainedInput { database: self.clone(), id, reading }))
459            }
460        }
461    }
462
463    /// Configure retained encrypted input independently of application file caches.
464    /// Lowering the budget evicts oldest completed inputs atomically with accounting.
465    /// Checked facts and file protection are never evicted with their bytes.
466    #[cfg(any(test, feature = "test-utils"))]
467    pub async fn set_input_budget(&self, maximum: u64) -> Result<InputBudget, DbError> {
468        self.call(move |inner| {
469            let previous = inner.inputs.read(|db, _| budget(db))?;
470            if previous.maximum == maximum {
471                return Ok(previous);
472            }
473            inner.inputs.write(|db: &StoreSql, _| {
474                db.execute(
475                    "UPDATE _coven_input_budget SET maximum=?1 WHERE singleton=1",
476                    [sql_offset(maximum)?],
477                )?;
478                evict(db, &inner.inputs.active)?;
479                budget(db)
480            })
481        })
482        .await
483    }
484
485    /// Report byte retention and explicit eviction without scanning cached chunks.
486    #[cfg(any(test, feature = "test-utils"))]
487    pub async fn input_budget(&self) -> Result<InputBudget, DbError> {
488        self.call(|inner| inner.inputs.read(|db, _| budget(db))).await
489    }
490
491    /// The most retained bytes any input write has required since this was
492    /// first called, before its evictions, sampled on every change.
493    #[cfg(any(test, feature = "test-utils"))]
494    pub async fn input_peak(&self) -> Result<u64, DbError> {
495        self.call(|inner| {
496            inner.inputs.with_writer(|writer, _| {
497                writer.batch(
498                    "CREATE TEMP TABLE IF NOT EXISTS _coven_input_peak(peak INTEGER NOT NULL);
499                     INSERT INTO _coven_input_peak SELECT retained FROM main._coven_input_budget WHERE NOT EXISTS(SELECT 1 FROM _coven_input_peak);
500                     CREATE TEMP TRIGGER IF NOT EXISTS _coven_input_peak_change AFTER UPDATE OF retained ON main._coven_input_budget BEGIN
501                         UPDATE _coven_input_peak SET peak=max(peak,NEW.retained);
502                     END;",
503                )?;
504                Ok(writer.query_row("SELECT peak FROM temp._coven_input_peak", [], |row| {
505                    row.get::<_, i64>(0)
506                })?)
507            })
508        })
509        .await
510        .map(|peak| peak as u64)
511    }
512}
513
514impl RetainedInput {
515    /// Retain the confirmed current claim under its provider observation without
516    /// downloading bytes already owned by the journal. The caller has settled
517    /// publication and checked the floor before associating these bytes.
518    pub async fn keep_claim_bytes(&self) -> Result<(), DbError> {
519        if self.received().await? {
520            return Ok(());
521        }
522        let id = self.id;
523        self.database
524            .call(move |inner| {
525                inner.access.with_committed(|source, _| copy_claim(&inner.inputs, source, id))
526            })
527            .await
528    }
529    /// A seekable reader over received bytes, pinned against eviction. It never
530    /// fetches missing bytes or acquires the application writer. Consumers may
531    /// use it inside a slot transaction after completing transport and floor checks.
532    pub async fn local_bytes(&self, length: u64) -> Result<RetainedBytes, DbError> {
533        let database =
534            self.database.call(|inner| Ok::<_, DbError>(inner.inputs.database.clone())).await?;
535        Ok(RetainedBytes::new(database, self.reading.clone(), length))
536    }
537    /// The first completed provider observation for this identity, including
538    /// native metadata whose representation can differ in later listings.
539    pub async fn observation(&self) -> Result<Vec<u8>, DbError> {
540        self.read(|db, _, id| {
541            Ok(db.query_row(
542                "SELECT observation FROM _coven_input_objects WHERE id=?1",
543                [id],
544                |r| r.get(0),
545            )?)
546        })
547        .await
548    }
549    /// Share an in-flight range across consumers of the same durable observation.
550    /// The guard spans checking retained ranges, fetching gaps, and committing them.
551    pub async fn receiving(&self) -> tokio::sync::MutexGuard<'_, ()> {
552        self.reading.receiving.lock().await
553    }
554    async fn read<R: Send + 'static>(
555        &self,
556        run: impl FnOnce(&StoreSql, &StoreCall<'_>, i64) -> Result<R, DbError> + Send + 'static,
557    ) -> Result<R, DbError> {
558        let id = self.id;
559        self.database.call(move |inner| inner.inputs.read(|db, call| run(db, call, id))).await
560    }
561
562    async fn write<R: Send + 'static>(
563        &self,
564        run: impl FnOnce(&StoreSql, &StoreCall<'_>, i64) -> Result<R, DbError> + Send + 'static,
565    ) -> Result<R, DbError> {
566        let id = self.id;
567        self.database.call(move |inner| inner.inputs.write(|db, call| run(db, call, id))).await
568    }
569
570    /// Cached portions of a requested interval, clipped so memory is bounded by it.
571    pub async fn ranges(&self, start: u64, end: u64) -> Result<Vec<RetainedRange>, DbError> {
572        let start = sql_offset(start)?;
573        let end = sql_offset(end)?;
574        self.read(move |db, _, id| {
575            Ok(db.query(RANGES, (id, start, end), |r| {
576                Ok(RetainedRange { offset: r.get::<_, i64>(0)? as u64, bytes: r.get(1)? })
577            })?)
578        })
579        .await
580    }
581
582    /// Commit newly fetched, nonoverlapping bytes. Refilling an evicted range is
583    /// a new insertion, while retained bytes must be consumed without fetching.
584    pub async fn keep_range(&self, offset: u64, bytes: Vec<u8>) -> Result<(), DbError> {
585        self.keep_received_range(offset, bytes, false).await
586    }
587
588    /// Whether a whole response (or all of its bounded ranges) reached checked
589    /// transport EOF. This records receipt, never content authentication.
590    pub async fn received(&self) -> Result<bool, DbError> {
591        self.read(|db, _, id| {
592            Ok(db.query_row(
593                "SELECT received FROM _coven_input_objects WHERE id=?1",
594                [id],
595                |r| r.get(0),
596            )?)
597        })
598        .await
599    }
600
601    /// How many of the object's bytes are retained: its ranges never overlap,
602    /// so the object is held whole when this equals its size.
603    pub async fn retained_length(&self) -> Result<u64, DbError> {
604        self.read(|db, _, id| {
605            Ok(db.query_row(
606                "SELECT coalesce(sum(end-start),0) FROM _coven_input_ranges WHERE object=?1",
607                [id],
608                |r| r.get::<_, i64>(0),
609            )?)
610        })
611        .await
612        .map(|length| length as u64)
613    }
614
615    /// Commit received bytes and, at successful EOF, the transport completion
616    /// fact in one transaction. Neither fact can survive a failed byte commit.
617    pub async fn keep_received_range(
618        &self,
619        offset: u64,
620        bytes: Vec<u8>,
621        complete: bool,
622    ) -> Result<(), DbError> {
623        if bytes.is_empty() && (!complete || self.received().await?) {
624            return Ok(());
625        }
626        let end = offset
627            .checked_add(bytes.len() as u64)
628            .ok_or(DbError::Invariant { what: "an input range's end fits u64" })?;
629        let offset = sql_offset(offset)?;
630        let end = sql_offset(end)?;
631        let id = self.id;
632        self.database.call(move |inner| inner.inputs.write(|db: &StoreSql, _| {
633            if !bytes.is_empty() {
634                db.execute("INSERT INTO _coven_input_ranges(object,start,end,bytes) VALUES(?1,?2,?3,?4)", (id,offset,end,bytes))?;
635            }
636            if complete {
637                db.execute("UPDATE _coven_input_objects SET received=1 WHERE id=?1", [id])?;
638            }
639            evict(db, &inner.inputs.active)
640        })).await
641    }
642
643    /// The complete input has been applied (with reversible inputs committed),
644    /// or permanently refused. Release its encrypted ranges for explicit eviction;
645    /// checked metadata, file protection, and the refusal remain durable.
646    pub async fn release_ranges(self) -> Result<(), DbError> {
647        let id = self.id;
648        self.database.call(move |inner| inner.inputs.release(vec![id])).await
649    }
650
651    /// Drop the received bytes, which a second read of the object
652    /// contradicted, so the next read fetches the object again (§19.1).
653    pub async fn discard(self) -> Result<(), DbError> {
654        let id = self.id;
655        self.database.call(move |inner| inner.inputs.discard(id)).await
656    }
657
658    /// The checked file evidence of these bytes, if any (§17.10).
659    pub async fn files(&self) -> Result<Option<FileEvidence>, DbError> {
660        self.read(|db, _, id| {
661            let (complete, schema): (Option<bool>, Option<u32>) = db.query_row(
662                "SELECT files_complete,files_schema FROM _coven_input_objects WHERE id=?1",
663                [id],
664                |r| Ok((r.get(0)?, r.get(1)?)),
665            )?;
666            Ok(match (complete, schema) {
667                (None, _) => None,
668                (Some(false), Some(version)) => {
669                    Some(FileEvidence::Unproven(UnprovenFiles::Schema(version)))
670                }
671                (Some(false), None) => {
672                    let parts = db
673                        .query(
674                            "SELECT audience,key FROM _coven_input_unread WHERE object=?1",
675                            [id],
676                            |r| {
677                                Ok((
678                                    crate::write_encoding::audience(r, 0)?,
679                                    r.get::<_, KeyId>(1)?,
680                                ))
681                            },
682                        )?
683                        .into_iter()
684                        .collect::<BTreeSet<_>>();
685                    if parts.is_empty() {
686                        return Err(DbError::DamagedDatabase);
687                    }
688                    Some(FileEvidence::Unproven(UnprovenFiles::Parts(parts)))
689                }
690                (Some(true), _) => Some(FileEvidence::Complete(
691                    db.query(
692                        "SELECT device,stored_object FROM _coven_input_files WHERE object=?1 ORDER BY device,stored_object",
693                        [id],
694                        |r| Ok((r.get::<_, DeviceId>(0)?, r.get::<_, ObjectId>(1)?)),
695                    )?
696                    .into_iter()
697                    .collect(),
698                )),
699            })
700        })
701        .await
702    }
703
704    /// Record references only after complete authentication. Unproven evidence
705    /// proves no file absent and names what must change before these bytes
706    /// are checked again.
707    pub async fn keep_files(&self, files: FileEvidence) -> Result<(), DbError> {
708        if self.files().await?.as_ref() == Some(&files) {
709            return Ok(());
710        }
711        self.write(move |db: &StoreSql, _, id| {
712            db.execute("DELETE FROM _coven_input_files WHERE object=?1", [id])?;
713            db.execute("DELETE FROM _coven_input_unread WHERE object=?1", [id])?;
714            let (complete, schema) = match &files {
715                FileEvidence::Complete(_) => (true, None),
716                FileEvidence::Unproven(UnprovenFiles::Schema(version)) => (false, Some(*version)),
717                FileEvidence::Unproven(UnprovenFiles::Parts(_)) => (false, None),
718            };
719            db.execute(
720                "UPDATE _coven_input_objects SET files_complete=?2,files_schema=?3 WHERE id=?1",
721                (id, complete, schema),
722            )?;
723            match files {
724                FileEvidence::Complete(files) => {
725                    for (device, object) in files {
726                        db.execute(
727                            "INSERT INTO _coven_input_files(object,device,stored_object) VALUES(?1,?2,?3)",
728                            (id, device, object),
729                        )?;
730                    }
731                }
732                FileEvidence::Unproven(UnprovenFiles::Parts(parts)) => {
733                    if parts.is_empty() {
734                        return Err(DbError::Invariant {
735                            what: "unproven file evidence names a part",
736                        });
737                    }
738                    for (audience, key) in parts {
739                        db.execute(
740                            "INSERT INTO _coven_input_unread(object,audience,key) VALUES(?1,?2,?3)",
741                            (
742                                id,
743                                &audience,
744                                key,
745                            ),
746                        )?;
747                    }
748                }
749                FileEvidence::Unproven(UnprovenFiles::Schema(_)) => (),
750            }
751            Ok(())
752        })
753        .await
754    }
755}
756
757/// What checked retained bytes establish about the uploaded files they name
758/// (§17.10).
759#[derive(Clone, Debug, PartialEq, Eq)]
760pub enum FileEvidence {
761    /// Every fixed file path the bytes name, after complete authentication.
762    Complete(BTreeSet<(DeviceId, ObjectId)>),
763    /// The bytes cannot prove any file absent, and are not read again for that
764    /// purpose until this prerequisite changes.
765    Unproven(UnprovenFiles),
766}
767
768/// Why retained bytes cannot yet name every file they refer to (§17.10).
769#[derive(Clone, Debug, PartialEq, Eq)]
770pub enum UnprovenFiles {
771    /// Parts sealed for these audiences under these keys, which this device
772    /// could not open: it lacked the key or could not read the audience.
773    Parts(BTreeSet<(coven_merge::Audience, KeyId)>),
774    /// A schema version this version cannot interpret.
775    Schema(u32),
776}
777
778impl UnprovenFiles {
779    /// Whether reading the same bytes again could now succeed: one of the
780    /// parts now opens, or the schema version is now supported.
781    pub fn changed(
782        &self,
783        opens: impl Fn(&coven_merge::Audience, KeyId) -> bool,
784        versions: &std::ops::RangeInclusive<u32>,
785    ) -> bool {
786        match self {
787            Self::Parts(parts) => parts.iter().any(|(audience, key)| opens(audience, *key)),
788            Self::Schema(version) => versions.contains(version),
789        }
790    }
791}
792
793#[cfg(test)]
794#[path = "input_database_tests.rs"]
795mod tests;