Skip to main content

coven_database/
local_file.rs

1//! Resolve a file still on this device only to its one local byte source.
2
3use crate::sqlite::StoreSql;
4use crate::DbError;
5use coven_foundation::files::StoreDirAccess;
6use coven_foundation::task::{Bug, CarriesBug};
7use coven_foundation::{
8    files::{
9        FileError, FileReader, LeasePlace, ObservationError, StagedName, StoreDir, StoreLockError,
10        StoreReadLock, UserOriginal,
11    },
12    id_source::DeviceId,
13};
14use std::{path::PathBuf, sync::Arc};
15
16/// A local file operation's typed failure.
17#[derive(Debug, thiserror::Error)]
18pub enum LocalFileError {
19    /// The recorded original is absent.
20    #[error("original {id} is missing at {}", path.display())]
21    UserFileMissing {
22        /// The file's id.
23        id: String,
24        /// Its recorded original path.
25        path: PathBuf,
26    },
27    /// The recorded original's facts changed.
28    #[error("original {id} changed at {}", path.display())]
29    UserFileChanged {
30        /// The file's id.
31        id: String,
32        /// Its recorded original path.
33        path: PathBuf,
34    },
35    /// Bytes did not match the file's content or an owned copy disappeared.
36    #[error("file {id} failed its content check")]
37    Integrity {
38        /// The file's id.
39        id: String,
40    },
41    /// The requested range exceeds the file's size.
42    #[error("file {id} range {offset}..{end} exceeds {size}")]
43    RangeOutOfBounds {
44        /// The file's id.
45        id: String,
46        /// The requested first byte.
47        offset: u64,
48        /// The requested exclusive end, saturated if addition overflows.
49        end: u64,
50        /// The file's whole size.
51        size: u64,
52    },
53    /// Looking up the file failed.
54    #[error(transparent)]
55    Database(DbError),
56    /// The filesystem failed.
57    #[error(transparent)]
58    Disk(FileError),
59    /// The store cannot be retained while opening its file.
60    #[error(transparent)]
61    Lock(StoreLockError),
62    /// Opening or reading the file panicked: a bug, which the caller reports
63    /// (E15).
64    #[error(transparent)]
65    Bug(#[from] Bug),
66}
67
68impl From<DbError> for LocalFileError {
69    fn from(error: DbError) -> Self {
70        match error {
71            DbError::Bug(bug) => Self::Bug(bug),
72            error => Self::Database(error),
73        }
74    }
75}
76
77impl From<FileError> for LocalFileError {
78    fn from(error: FileError) -> Self {
79        match error {
80            FileError::Bug(bug) => Self::Bug(bug),
81            error => Self::Disk(error),
82        }
83    }
84}
85
86impl From<StoreLockError> for LocalFileError {
87    fn from(error: StoreLockError) -> Self {
88        match error {
89            StoreLockError::Bug(bug) => Self::Bug(bug),
90            error => Self::Lock(error),
91        }
92    }
93}
94
95impl LocalFileError {
96    /// Whether this failure judges the bytes a source holds: missing, or
97    /// changed from what its record says, rather than a failure to look.
98    pub(crate) fn judges_bytes(&self) -> bool {
99        matches!(
100            self,
101            Self::UserFileMissing { .. } | Self::UserFileChanged { .. } | Self::Integrity { .. }
102        )
103    }
104}
105
106impl CarriesBug for LocalFileError {
107    fn bug(&self) -> Option<&Bug> {
108        match self {
109            Self::Bug(bug) => Some(bug),
110            Self::Database(error) => error.bug(),
111            Self::Disk(error) => error.bug(),
112            Self::Lock(error) => error.bug(),
113            _ => None,
114        }
115    }
116}
117
118/// An open local file checked against its recorded facts. Retaining it keeps
119/// the opened bytes readable across its upload completing and file
120/// unlinking, and prevents store deletion until its reads and handles have
121/// finished. It holds its place of the app's budget until then (§17.3).
122pub struct LocalFileStream {
123    file: Arc<LocalFileReader>,
124    /// Where a panic in a read its caller stopped waiting for goes (E15).
125    bugs: coven_foundation::task::BugSinkRef,
126}
127
128struct LocalFileReader {
129    // An original's reader holds its own place.
130    reader: FileReader,
131    // Coven's copy holds the stream's place here, which goes back after the
132    // open file closes.
133    _place: Option<LeasePlace>,
134    // Drop the open file before allowing deletion, even on a cancelled read.
135    _lock: StoreReadLock,
136    id: String,
137    original: Option<PathBuf>,
138}
139
140impl LocalFileStream {
141    /// The complete plaintext byte count.
142    pub fn plaintext_size(&self) -> u64 {
143        self.file.plaintext_size()
144    }
145
146    /// Read a positioned range on a blocking worker, retaining this open
147    /// handle. A caller that stops waiting leaves the read to finish, and
148    /// its panic goes to the store's bug sink (E15).
149    pub async fn read_at(&self, offset: u64, len: u64) -> Result<Vec<u8>, LocalFileError> {
150        let file = self.file.clone();
151        coven_foundation::task::blocking_completing(
152            "read the local file",
153            self.bugs.clone(),
154            move || file.read_at(offset, len),
155        )
156        .await
157        .map_err(FileError::from)?
158    }
159
160    /// Read a complete plaintext chunk and compare its first-read hash before
161    /// returning any bytes to an encryptor. Metadata checks alone cannot detect
162    /// a same-size overwrite whose modification time was restored.
163    pub async fn read_verified_at(
164        &self,
165        offset: u64,
166        len: u64,
167        expected: coven_crypto::ContentHash,
168    ) -> Result<Vec<u8>, LocalFileError> {
169        let bytes = self.read_at(offset, len).await?;
170        let mut hash = coven_crypto::ContentHasher::new();
171        hash.update(&bytes);
172        if hash.finish() != expected {
173            return Err(changed(&self.file.id, self.file.original.as_ref()));
174        }
175        Ok(bytes)
176    }
177}
178
179impl LocalFileReader {
180    fn plaintext_size(&self) -> u64 {
181        self.reader.size()
182    }
183
184    #[expect(
185        clippy::map_err_ignore,
186        reason = "a size past the target integer is TooLarge, which names the field and size"
187    )]
188    fn read_at(&self, offset: u64, len: u64) -> Result<Vec<u8>, LocalFileError> {
189        let end = offset.saturating_add(len);
190        if offset.checked_add(len).is_none() || end > self.reader.size() {
191            return Err(LocalFileError::RangeOutOfBounds {
192                id: self.id.clone(),
193                offset,
194                end,
195                size: self.reader.size(),
196            });
197        }
198        let length = usize::try_from(len).map_err(|_| DbError::TooLarge {
199            field: "file range",
200            actual: len,
201            maximum: usize::MAX as u64,
202        })?;
203        self.reader
204            .read_at(offset, length)
205            .map_err(|error| observation(error, &self.id, self.original.is_some()))
206    }
207}
208
209/// What a read of a file here finds in one committed state: its bytes here
210/// while its record keeps it on this device only, or else that record, or
211/// no record (§17.7).
212#[derive(Debug)]
213pub enum Located<T> {
214    /// The record keeps the file on this device only: its bytes here.
215    Here(T),
216    /// The record as the read found it, which doesn't keep the file on this
217    /// device only: the file is stored, its bytes in the cache or storage,
218    /// or it is on another device only. A file whose upload this device
219    /// finished since a reference to it was taken is stored.
220    Elsewhere(crate::FileRef),
221    /// This device has no record of the file.
222    Gone,
223}
224
225impl<T> Located<T> {
226    /// The bytes here, or what the read found instead.
227    pub(crate) fn here<U>(self) -> Result<T, Located<U>> {
228        match self {
229            Self::Here(here) => Ok(here),
230            Self::Elsewhere(record) => Err(Located::Elsewhere(record)),
231            Self::Gone => Err(Located::Gone),
232        }
233    }
234}
235
236/// Where the bytes of `file` are while its record, as this read finds it,
237/// keeps it on this device only: the user's original, or coven's copy.
238/// This device keeps them while a record puts the file here (§17.11,
239/// ResetBytes `reset_finds_bytes`), so such a record with none is a bug.
240/// Reads only the database.
241pub(crate) fn device_only_source(
242    db: &StoreSql,
243    device: DeviceId,
244    file: coven_foundation::id_source::FileId,
245) -> Result<Located<LocalSource>, DbError> {
246    let record = match super::read(db, file) {
247        Ok(record) => record,
248        Err(DbError::FileAbsent { .. }) => return Ok(Located::Gone),
249        Err(error) => return Err(error),
250    };
251    if record.place() != (crate::FilePlace::DeviceOnly { device }) {
252        return Ok(Located::Elsewhere(record));
253    }
254    file_source(db, file)?
255        .map(Located::Here)
256        .ok_or(DbError::Invariant { what: "a file on this device only has its bytes here" })
257}
258
259/// Where a file's bytes are on this device: the user's original, as
260/// recorded, or coven's own copy.
261pub(crate) enum LocalSource {
262    Original { path: PathBuf, modified_at: std::time::SystemTime },
263    Copy(StagedName),
264}
265
266/// Where this device keeps the bytes of `file`, whose record keeps it on
267/// this device only: its original or coven's copy. Reads only the database.
268fn file_source(
269    db: &StoreSql,
270    file: coven_foundation::id_source::FileId,
271) -> Result<Option<LocalSource>, DbError> {
272    if let Some(original) = crate::user_file::read(db, file)? {
273        return Ok(Some(LocalSource::Original {
274            path: original.path,
275            modified_at: original.modified_at,
276        }));
277    }
278    db.query("SELECT path FROM _coven_device_files WHERE file=?1", [file], |row| {
279        row.get::<_, String>(0)
280    })?
281    .into_iter()
282    .next()
283    .map(|name| StagedName::parse(&name).map(LocalSource::Copy).ok_or(DbError::DamagedDatabase))
284    .transpose()
285}
286
287/// The source an upload's entry fixed at staging; `None` once it is no
288/// longer queued. Reads only the database.
289pub(crate) fn queued_source(db: &StoreSql, upload: i64) -> Result<Option<LocalSource>, DbError> {
290    let sources = db.query(
291        "SELECT original,modified_at,copy FROM _coven_file_uploads WHERE id=?1",
292        [upload],
293        |row| {
294            Ok((
295                row.get::<_, Option<Vec<u8>>>(0)?,
296                row.get::<_, Option<Vec<u8>>>(1)?,
297                row.get::<_, Option<String>>(2)?,
298            ))
299        },
300    )?;
301    let Some(source) = sources.into_iter().next() else {
302        return Ok(None);
303    };
304    match source {
305        (Some(path), Some(modified_at), None) => Ok(Some(LocalSource::Original {
306            path: crate::user_file::decode_path(path)?,
307            modified_at: crate::user_file::decode_time(&modified_at)?,
308        })),
309        (None, None, Some(name)) => {
310            Ok(Some(LocalSource::Copy(StagedName::parse(&name).ok_or(DbError::DamagedDatabase)?)))
311        }
312        _ => Err(DbError::DamagedDatabase),
313    }
314}
315
316/// Open a file's local source in `place`: it must still have the size, and
317/// an original the modification time, recorded at staging. Reads then return
318/// what's on disk; an upload checks each chunk it sends (§17.9). The stream
319/// holds the place until its last read ends. Touches only the disk, never
320/// the database. `id` names the file in its errors.
321pub(crate) fn open_source(
322    directory: &StoreDir,
323    id: &str,
324    size: u64,
325    source: LocalSource,
326    place: LeasePlace,
327) -> Result<LocalFileStream, LocalFileError> {
328    let id = id.to_owned();
329    let lock = directory.lock_read_only()?;
330    let (reader, original, place) = match source {
331        LocalSource::Original { path, modified_at } => (
332            UserOriginal::at(path.clone())
333                .open_reader(place, size, modified_at)
334                .map_err(|error| observation(error, &id, true))?,
335            Some(path),
336            None,
337        ),
338        LocalSource::Copy(name) => {
339            (open_copy_reader(directory, &id, size, &name)?, None, Some(place))
340        }
341    };
342    Ok(stream(directory, LocalFileReader { reader, _place: place, _lock: lock, id, original }))
343}
344
345/// Open coven's own copy of a file, which must have its size. No place is
346/// held: the copy is coven's file, kept for a pin (§17.8).
347pub(crate) fn open_copy(
348    directory: &StoreDir,
349    id: &str,
350    size: u64,
351    name: &StagedName,
352) -> Result<LocalFileStream, LocalFileError> {
353    let lock = directory.lock_read_only()?;
354    let reader = open_copy_reader(directory, id, size, name)?;
355    Ok(stream(
356        directory,
357        LocalFileReader { reader, _place: None, _lock: lock, id: id.to_owned(), original: None },
358    ))
359}
360
361fn open_copy_reader(
362    directory: &StoreDir,
363    id: &str,
364    size: u64,
365    name: &StagedName,
366) -> Result<FileReader, LocalFileError> {
367    let reader =
368        directory.staged_file(name).open_reader().map_err(|error| observation(error, id, false))?;
369    // The stream's size is its open handle's, which must be the file's.
370    if reader.size() != size {
371        return Err(LocalFileError::Integrity { id: id.to_owned() });
372    }
373    Ok(reader)
374}
375
376fn stream(directory: &StoreDir, reader: LocalFileReader) -> LocalFileStream {
377    LocalFileStream { file: Arc::new(reader), bugs: directory.bugs().clone() }
378}
379
380fn observation(error: ObservationError, id: &str, original: bool) -> LocalFileError {
381    match (error, original) {
382        (ObservationError::Missing(path), true) => {
383            LocalFileError::UserFileMissing { id: id.into(), path }
384        }
385        (ObservationError::Changed(path), true) => {
386            LocalFileError::UserFileChanged { id: id.into(), path }
387        }
388        (ObservationError::Missing(_) | ObservationError::Changed(_), false) => {
389            LocalFileError::Integrity { id: id.into() }
390        }
391        (ObservationError::File(error), _) => error.into(),
392    }
393}
394
395fn changed(id: &str, original: Option<&PathBuf>) -> LocalFileError {
396    match original {
397        Some(path) => LocalFileError::UserFileChanged { id: id.into(), path: path.clone() },
398        None => LocalFileError::Integrity { id: id.into() },
399    }
400}