Skip to main content

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}