coven/read_handle.rs
1//! The read-only application surface caches files under a shared deletion guard.
2
3use crate::*;
4use coven_database::{ReadOnly, StoreDatabase};
5
6/// A handle that reads synced rows and maintains its local file cache (§4, E1).
7/// Its shared store lock prevents deletion until all its connections close.
8/// Its SQL may not read `coven_sync_status`: it can't tell whether the writer
9/// that last wrote the row still runs (E5).
10///
11/// ```compile_fail
12/// async fn no_writes(handle: &coven::CovenReadHandle) {
13/// handle.write(|_| Ok::<_, coven::CovenError>(())).await;
14/// }
15/// ```
16/// ```compile_fail
17/// fn no_live_query(handle: &coven::CovenReadHandle) {
18/// handle.subscribe(|_| Ok::<_, coven::CovenError>(()));
19/// }
20/// ```
21#[derive(Clone)]
22pub struct CovenReadHandle {
23 database: StoreDatabase<ReadOnly>,
24 files: coven_sync::Files<ReadOnly>,
25}
26
27impl CovenReadHandle {
28 pub(crate) fn new(
29 database: StoreDatabase<ReadOnly>,
30 files: coven_sync::Files<ReadOnly>,
31 ) -> Self {
32 Self { database, files }
33 }
34 /// The store's current name from this device's committed state (E9).
35 pub async fn store_name(&self) -> CovenResult<String> {
36 self.database.store_name().await.map_err(CovenError::from)
37 }
38
39 /// A read of one consistent snapshot, run when awaited.
40 pub fn read<F, R, E>(&self, read: F) -> Read<'_, F, ReadOnly>
41 where
42 F: FnOnce(SqlReadContext<'_>) -> Result<R, E> + Send + 'static,
43 R: Send + 'static,
44 E: From<DbError> + task::CarriesBug + Send + 'static,
45 {
46 self.database.read(read)
47 }
48 /// The SQLite settings this handle's connections have in effect (§4).
49 pub async fn sqlite_settings(&self) -> Result<SqliteSettingsInEffect, DbError> {
50 self.database.sqlite_settings().await
51 }
52 /// The file a row references, by the id the row holds.
53 pub async fn file_ref(&self, file: FileId) -> Result<FileRef, DbError> {
54 self.database.file_ref(file).await
55 }
56 /// The path, size and modification time recorded for a file's original.
57 pub async fn user_file(&self, file: FileId) -> Result<Option<UserFile>, DbError> {
58 self.database.user_file(file).await
59 }
60 /// Reads a whole file, in one place of `lease`. A stored file is checked
61 /// against its content hash.
62 pub async fn read_file(
63 &self,
64 file: &FileRef,
65 lease: &FileLease,
66 ) -> Result<Vec<u8>, FileReadError> {
67 let stream = self.open_file_stream(file, lease).await?;
68 stream.read_at(0, stream.plaintext_size()).await
69 }
70 /// Opens a file for reading ranges (§17.7), as its record stands when it
71 /// opens; keep the stream for as long as the file is read. The stream
72 /// holds one place of `lease` until it drops. Its shared store lock
73 /// prevents deletion until it and its I/O finish.
74 pub async fn open_file_stream(
75 &self,
76 file: &FileRef,
77 lease: &FileLease,
78 ) -> Result<FileStream<ReadOnly>, FileReadError> {
79 self.files.open_file_stream(file, lease).await
80 }
81 /// Closes read and cache connections on all clones and releases their
82 /// storage client and shared store lock, while the app still holds the
83 /// handle. From its first poll every clone refuses new calls with
84 /// `StoreClosed`; the closing itself runs as its own task, so dropping
85 /// this future doesn't stop it (E1, E15). File streams retain their own
86 /// locks.
87 pub async fn close(&self) -> Result<(), DbError> {
88 self.database.begin_close();
89 let handle = self.clone();
90 let bugs = self.database.bugs().clone();
91 let closing = async move {
92 handle.files.close().await;
93 handle.database.close().await
94 };
95 crate::task::spawn_completing("close the read-only store", bugs, closing).await?
96 }
97}