Skip to main content

coven_sync/
file_read.rs

1//! Authenticated, bounded ranged reads with cached ciphertext and read-ahead.
2
3use super::{FilesMode, StorageState};
4use crate::{
5    files::file_failure::stored,
6    files::file_status::Uploading,
7    files::{Files, FilesInner},
8    FileReadError,
9};
10use coven_crypto::{ContentHash, ContentHasher, FileKey};
11use coven_database::{
12    CacheReservation, DbError, FileLocation, FilePlace, FileRef, LocalFileStream, Located,
13    TransferEnd, TransferMeter,
14};
15use coven_database::{FileLocationKey, Writer};
16use coven_format::{
17    chunks::CHUNK_SIZE,
18    file::{FileHeader, FILE_HEADER_LEN},
19};
20use coven_foundation::files::StoreDirAccess;
21use coven_foundation::files::{FileLease, FileName, LeasePlace, StoreReadLock};
22use coven_storage::{ByteProgress, ByteRange, ObjectPath};
23use std::sync::atomic::{AtomicU64, Ordering};
24use std::sync::Arc;
25
26use super::file_error::TransferError;
27
28#[path = "file_read_partial.rs"]
29mod partial;
30#[path = "file_read_parts.rs"]
31mod parts;
32#[path = "file_read_whole.rs"]
33mod whole;
34
35const REQUEST_BYTES: u64 = 1024 * 1024;
36/// An open file. A file never changes its bytes, so nothing later changes
37/// what it reads. Its shared store lock prevents deletion until the stream
38/// and its I/O finish, including reads still running after the store closes
39/// or the caller cancels.
40pub struct FileStream<M: FilesMode = Writer> {
41    id: String,
42    source: OpenFile<M>,
43    state: tokio::sync::Mutex<FileStreamState>,
44}
45enum OpenFile<M: FilesMode> {
46    Local {
47        stream: LocalFileStream,
48        owner: Arc<FilesInner<M>>,
49        file: FileRef,
50        /// Its upload, while one is queued: reads settle or record its
51        /// source's failure there, or on its move. A file with no upload
52        /// records nothing; its reads' errors go to the caller.
53        uploading: Option<Arc<Uploading>>,
54    },
55    Uploaded(Arc<UploadedFile<M>>),
56}
57struct FileStreamState {
58    end: Option<u64>,
59    hash: Option<ContentHasher>,
60    ahead: Option<coven_foundation::task::OwnedTask>,
61}
62impl Drop for FileStreamState {
63    fn drop(&mut self) {
64        if let Some(task) = &self.ahead {
65            task.abort();
66        }
67    }
68}
69pub(crate) struct UploadedFile<M: FilesMode = Writer> {
70    owner: Arc<FilesInner<M>>,
71    file: FileRef,
72    /// Where its bytes are stored.
73    location: FileLocation,
74    /// The SHA-256 of its bytes, which a whole read checks.
75    hash: ContentHash,
76    /// The layout the file's size fixes; the stored header must equal it
77    /// before any of its chunks is trusted.
78    header: FileHeader,
79    /// Whether this open has checked the stored header, from the cache or
80    /// from storage. Set under the file's fetch lock.
81    header_checked: std::sync::atomic::AtomicBool,
82    key: FileKey,
83    path: ObjectPath,
84    /// The parts of its object it holds, on a provider whose ranged read
85    /// moves whole parts; `None` on one whose range moves only its bytes.
86    /// Settled at its first fetch, from the provider's part size (§17.7).
87    parts: std::sync::OnceLock<Option<parts::HeldParts>>,
88    /// The stream's place of the app's budget, which a pin's download
89    /// (coven's own work on its cache) holds none of. It goes back after the
90    /// stream's reads end.
91    _place: Option<LeasePlace>,
92    _lock: StoreReadLock,
93}
94/// Where a read that fetches from storage tells how much of its range is
95/// here: the count of the range's bytes in hand, cached or received, each
96/// time it grows while the read fetches. A read this device serves alone,
97/// from its own copy or the cache, tells it nothing (§17.7).
98#[derive(Clone)]
99pub struct ReadProgress {
100    report: Arc<dyn Fn(u64) + Send + Sync>,
101}
102impl std::fmt::Debug for ReadProgress {
103    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
104        f.debug_struct("ReadProgress").finish_non_exhaustive()
105    }
106}
107impl ReadProgress {
108    /// Tell `report` each new count of the range's bytes in hand.
109    pub fn new(report: impl Fn(u64) + Send + Sync + 'static) -> Self {
110        Self { report: Arc::new(report) }
111    }
112    fn tell(&self, here: u64) {
113        (self.report)(here);
114    }
115}
116/// A read's range and how much of it the steps before this one put in hand,
117/// for the fetch that follows to count on from.
118struct RangeHere<'a> {
119    progress: &'a ReadProgress,
120    offset: u64,
121    len: u64,
122    here: u64,
123}
124enum ChunkDestination<'a> {
125    /// The cache, for a read; `None` for one whose progress nothing shows.
126    Cache(Option<RangeHere<'a>>),
127    /// A pin's whole file, whose download `progress` hears as its bytes
128    /// arrive; `fetched` counts the bytes this step's range received.
129    WholeFile { progress: &'a Arc<whole::WholeProgress>, fetched: &'a Arc<AtomicU64> },
130}
131impl<M: FilesMode> Files<M> {
132    /// Open the file as its record now stands: its bytes here while it is on
133    /// this device only, uploading or not, or else its cached or stored
134    /// bytes. A file only on another device can't be read here (§17.7), and
135    /// only such a file fails with `DeviceOnly`: a file that leaves this
136    /// device only as it opens goes on as the record the open found says,
137    /// which never keeps it here. The stream holds one place of `lease`
138    /// until it drops.
139    pub async fn open_file_stream(
140        &self,
141        file: &FileRef,
142        lease: &FileLease,
143    ) -> Result<FileStream<M>, FileReadError> {
144        self.inner.check_open()?;
145        let mut file = self.inner.current(file).await?;
146        if let FilePlace::DeviceOnly { .. } = file.place() {
147            let uploading = self.inner.local(&file).await?.map(Arc::new);
148            let local = self
149                .inner
150                .database
151                .open_local(&file, lease.place().await)
152                .await
153                .map_err(FileReadError::from);
154            match local {
155                Ok(Located::Here(stream)) => {
156                    return Ok(FileStream::new(
157                        &file,
158                        OpenFile::Local {
159                            stream,
160                            owner: self.inner.clone(),
161                            file: file.clone(),
162                            uploading,
163                        },
164                    ))
165                }
166                // Its upload completed meanwhile, even as it opened, and its
167                // bytes are stored; or its record says another device has
168                // it.
169                Ok(Located::Elsewhere(record)) => file = record,
170                Ok(Located::Gone) => return Err(DbError::FileAbsent { file: file.id() }.into()),
171                Err(error) => {
172                    return match &uploading {
173                        Some(uploading) => {
174                            self.inner.complete_local_read(file.id(), uploading, Err(error)).await
175                        }
176                        None => Err(error),
177                    }
178                }
179            }
180        }
181        if let FilePlace::DeviceOnly { device } = file.place() {
182            return Err(FileReadError::DeviceOnly { file: file.id(), device });
183        }
184        let place = Some(lease.place().await);
185        let opened = match UploadedFile::open(self.inner.clone(), file.clone(), true, place).await {
186            Ok(opened) => opened,
187            Err(error) => return self.inner.complete_read(&file, Err(error.into()), false).await,
188        };
189        Ok(FileStream::new(&file, OpenFile::Uploaded(Arc::new(opened))))
190    }
191    /// Read the whole file, in one place of `lease`. A stored file is checked
192    /// against its content hash; a file this device uploads reads as it is on
193    /// disk (§17.7).
194    pub async fn read_file(
195        &self,
196        file: &FileRef,
197        lease: &FileLease,
198    ) -> Result<Vec<u8>, FileReadError> {
199        self.open_file_stream(file, lease).await?.read_at(0, file.size()).await
200    }
201}
202impl<M: FilesMode> FileStream<M> {
203    fn new(file: &FileRef, source: OpenFile<M>) -> Self {
204        Self {
205            id: file.id().to_string(),
206            source,
207            state: tokio::sync::Mutex::new(FileStreamState {
208                end: Some(0),
209                hash: Some(ContentHasher::new()),
210                ahead: None,
211            }),
212        }
213    }
214
215    /// Complete plaintext size.
216    pub fn plaintext_size(&self) -> u64 {
217        match &self.source {
218            OpenFile::Local { stream, .. } => stream.plaintext_size(),
219            OpenFile::Uploaded(file) => file.header.size(),
220        }
221    }
222    /// Read exactly the requested range. Network requests cover only missing
223    /// chunks, batching adjacent chunks within 1 MiB. Use `read_range` to keep
224    /// returned plaintext bounded independently of the requested range length.
225    pub async fn read_at(&self, offset: u64, len: u64) -> Result<Vec<u8>, FileReadError> {
226        self.read(offset, len, None).await
227    }
228    /// [`Self::read_at`], telling `progress` how many of the range's bytes are
229    /// here each time that grows while the read fetches from storage. A read
230    /// served from this device's copy or the cache tells it nothing.
231    pub async fn read_at_reporting(
232        &self,
233        offset: u64,
234        len: u64,
235        progress: &ReadProgress,
236    ) -> Result<Vec<u8>, FileReadError> {
237        self.read(offset, len, Some(progress)).await
238    }
239    async fn read(
240        &self,
241        offset: u64,
242        len: u64,
243        progress: Option<&ReadProgress>,
244    ) -> Result<Vec<u8>, FileReadError> {
245        match &self.source {
246            OpenFile::Local { stream, owner, file, uploading } => {
247                let read = stream.read_at(offset, len).await.map_err(FileReadError::from);
248                match uploading {
249                    Some(uploading) => owner.complete_local_read(file.id(), uploading, read).await,
250                    None => read,
251                }
252            }
253            OpenFile::Uploaded(file) => {
254                file.check_range(offset, len)?;
255                let mut state = self.state.lock().await;
256                let sequential = state.end == Some(offset);
257                if !sequential {
258                    if let Some(task) = state.ahead.take() {
259                        task.abort();
260                    }
261                }
262                if offset == 0 {
263                    state.hash = Some(ContentHasher::new());
264                } else if !sequential {
265                    state.hash = None;
266                }
267                let read = file.range(offset, len, progress).await;
268                let bytes = match read {
269                    Ok(bytes) => bytes,
270                    Err(error) => {
271                        return file.owner.complete_read(&file.file, Err(error.into()), false).await
272                    }
273                };
274                let mut whole = false;
275                if let Some(hash) = &mut state.hash {
276                    hash.update(&bytes);
277                }
278                if offset + len == file.header.size() {
279                    if let Some(hash) = state.hash.take() {
280                        if hash.finish() != file.hash {
281                            return file
282                                .owner
283                                .complete_read(
284                                    &file.file,
285                                    Err(TransferError::Refused(crate::Refusal::ContentHash)),
286                                    false,
287                                )
288                                .await;
289                        }
290                        whole = true;
291                    }
292                }
293                state.end = Some(offset + len);
294                if sequential && offset > 0 && offset + len < file.header.size() {
295                    if let Some(task) = state.ahead.take() {
296                        task.abort();
297                    }
298                    let ahead = file.clone();
299                    let start = offset + len;
300                    // Nobody waits for it: a panic in it goes to the store's
301                    // bug sink, and the next read fetches what it would have.
302                    state.ahead = Some(coven_foundation::task::spawn_owned(
303                        "a read-ahead",
304                        file.owner.database.bugs().clone(),
305                        async move {
306                            let length = (ahead.header.size() - start).min(REQUEST_BYTES);
307                            let result =
308                                ahead.range(start, length, None).await.map_err(TransferError::from);
309                            ahead.owner.finish_read_ahead(&ahead.file, result).await;
310                        },
311                        |_| async {},
312                    ));
313                }
314                file.owner.complete_read(&file.file, Ok(bytes), whole).await
315            }
316        }
317    }
318    /// Stream a byte range in bounded plaintext buffers, authenticating each
319    /// fetched chunk before yielding its bytes. For a stored file, the final
320    /// buffer checks the whole-file hash when reading sequentially from zero
321    /// through the end.
322    pub fn read_range(
323        &self,
324        offset: u64,
325        len: u64,
326    ) -> Result<FileRangeStream<'_, M>, FileReadError> {
327        if offset.checked_add(len).is_none_or(|end| end > self.plaintext_size()) {
328            return Err(FileReadError::RangeOutOfBounds {
329                id: self.id.clone(),
330                offset,
331                end: offset.saturating_add(len),
332                size: self.plaintext_size(),
333            });
334        }
335        Ok(FileRangeStream { file: self, offset, remaining: len, empty: len == 0 })
336    }
337}
338/// A borrowed stream of bounded authenticated plaintext buffers.
339pub struct FileRangeStream<'a, M: FilesMode = Writer> {
340    file: &'a FileStream<M>,
341    offset: u64,
342    remaining: u64,
343    empty: bool,
344}
345impl<M: FilesMode> FileRangeStream<'_, M> {
346    /// Yield the next buffer, or `None` after the exact requested range.
347    pub async fn next(&mut self) -> Result<Option<Vec<u8>>, FileReadError> {
348        if self.empty {
349            self.empty = false;
350            self.file.read_at(self.offset, self.remaining).await?;
351            self.remaining = 0;
352            return Ok(None);
353        }
354        if self.remaining == 0 {
355            return Ok(None);
356        }
357        let length = self.remaining.min(REQUEST_BYTES - CHUNK_SIZE as u64);
358        let bytes = self.file.read_at(self.offset, length).await?;
359        self.offset += length;
360        self.remaining -= length;
361        Ok(Some(bytes))
362    }
363}
364impl FilesInner {
365    /// A pin's whole copy of the stored file, downloaded as `keep_whole`
366    /// assembles it (§17.8), or `None` when a metered network the app keeps
367    /// files off stopped it before a request to storage: nothing failed.
368    pub(crate) async fn download_whole(
369        self: &Arc<Self>,
370        file: FileRef,
371    ) -> Result<Option<CacheReservation>, TransferError> {
372        // An empty file's header is its whole object, which opening reads.
373        if file.size() == 0 && self.downloads_held() {
374            return Ok(None);
375        }
376        UploadedFile::open(self.clone(), file, false, None).await?.keep_whole().await
377    }
378}
379impl<M: FilesMode> UploadedFile<M> {
380    /// Open an uploaded file without a request when its header is cached.
381    /// Otherwise the first fetch checks the header: one starting at chunk
382    /// zero carries it in the same request, and any other first fetch reads
383    /// it alone (§17.7). An empty file's header is the whole object, so it
384    /// is checked here, waiting for a connection that is coming when
385    /// `wait_for_connection`, which a pin's download, holding the pins' lock,
386    /// leaves off. The open file holds `place` until it drops.
387    pub(crate) async fn open(
388        owner: Arc<FilesInner<M>>,
389        file: FileRef,
390        wait_for_connection: bool,
391        place: Option<LeasePlace>,
392    ) -> Result<Self, FileReadError> {
393        let (location, hash) = stored(&file)?;
394        let location = location.clone();
395        let directory = owner.directory.clone();
396        let lock = coven_foundation::task::blocking_completing(
397            "lock the store for reading",
398            owner.database.bugs().clone(),
399            move || directory.lock_read_only(),
400        )
401        .await
402        .map_err(coven_foundation::files::FileError::from)??;
403        let coven_format::file_reference::FileReference { device, object, key } =
404            location.reference()?;
405        let path = ObjectPath::file(owner.directory.id(), device, object);
406        let opened = Self {
407            header: FileHeader::new(file.size()),
408            header_checked: std::sync::atomic::AtomicBool::new(false),
409            owner,
410            file,
411            location,
412            hash,
413            key,
414            path,
415            parts: std::sync::OnceLock::new(),
416            _place: place,
417            _lock: lock,
418        };
419        if opened.header.chunk_count() == 0 {
420            opened.open_header(wait_for_connection).await?;
421        }
422        Ok(opened)
423    }
424    /// Check an empty file's header, fetching it when the cache lacks it. A
425    /// fetch while a connection is coming waits for it holding none of the
426    /// cache's locks.
427    async fn open_header(&self, wait_for_connection: bool) -> Result<(), FileReadError> {
428        loop {
429            {
430                let _file = self.owner.lock_file(&self.file, &self.location).await;
431                let _guard = self.owner.cache.read().await;
432                let cached = self.cached_header().await?;
433                if cached == CachedHeader::Checked {
434                    return Ok(());
435                }
436                if !(wait_for_connection
437                    && matches!(self.owner.storage_state(), StorageState::Connecting))
438                {
439                    return self.fetch_header(cached).await;
440                }
441            }
442            self.owner.settled().await?;
443        }
444    }
445    /// Check the header cached for this file, if one is.
446    async fn cached_header(&self) -> Result<CachedHeader, FileReadError> {
447        if self.header_checked.load(std::sync::atomic::Ordering::Acquire) {
448            return Ok(CachedHeader::Checked);
449        }
450        let Some(bytes) = self.owner.database.cached(&self.file, -1).await? else {
451            return Ok(CachedHeader::Missing);
452        };
453        // The cache keeps only a header that checked, so one that fails now
454        // changed on this device.
455        Ok(match self.accept_header(&bytes) {
456            Ok(()) => CachedHeader::Checked,
457            Err(_) => CachedHeader::Damaged,
458        })
459    }
460    /// Read the header alone and check it, then cache it, or write it back
461    /// over the cached copy that failed its check.
462    async fn fetch_header(&self, cached: CachedHeader) -> Result<(), FileReadError> {
463        let bytes = self.fetch(0, FILE_HEADER_LEN as u64, &ByteProgress::unread()).await?;
464        if let Err(refused) = self.accept_header(&bytes) {
465            return Err(self.confirm(0, &bytes, refused).await);
466        }
467        match cached {
468            CachedHeader::Damaged => {
469                Ok(self.owner.database.repair_cached(&self.file, -1, bytes).await?)
470            }
471            CachedHeader::Checked | CachedHeader::Missing => self.publish_header(bytes).await,
472        }
473    }
474    /// A refusal judges the stored file, not one fetch of it, and nothing
475    /// checks a fetch's transfer: bytes from `start` that a check refused are
476    /// fetched again, and the refusal stands only when the second fetch
477    /// returns the same bytes. Different bytes mean a fault on the way
478    /// changed a fetch, which fails as a read with `Corrupted` (§19.1).
479    async fn confirm(&self, start: u64, first: &[u8], refused: FileReadError) -> FileReadError {
480        if !matches!(refused, FileReadError::Integrity { .. }) {
481            return refused;
482        }
483        let end = start + first.len() as u64;
484        // The second fetch asks storage, never the parts this open file
485        // holds, which would hand back the same bytes (§17.7).
486        if let Some(Some(parts)) = self.parts.get() {
487            parts.forget(start, end);
488        }
489        match self.fetch(start, end, &ByteProgress::unread()).await {
490            Ok(again) if again == first => refused,
491            Ok(_) => coven_storage::StorageFailure::Corrupted
492                .with_source("a second fetch of the file returned other bytes")
493                .into(),
494            Err(error) => error,
495        }
496    }
497    /// Check fetched header bytes, then cache them before any chunk.
498    async fn publish_header(&self, bytes: Vec<u8>) -> Result<(), FileReadError> {
499        self.accept_header(&bytes)?;
500        cache(&self.owner, &self.file, -1, 1, bytes).await?;
501        self.owner.trim(self.file.namespace()).await;
502        Ok(())
503    }
504    /// The stored header must be the one the row's size fixes; a newer format
505    /// needs an update, anything else is damage at the fixed path.
506    fn accept_header(&self, bytes: &[u8]) -> Result<(), FileReadError> {
507        let header = FileHeader::decode(bytes).map_err(|error| match error {
508            coven_format::Error::UnsupportedVersion(version)
509                if version > coven_format::FORMAT_VERSION =>
510            {
511                FileReadError::UpdateRequired(crate::RequiredUpdate::CovenFormat { version })
512            }
513            _ => self.integrity(),
514        })?;
515        if header != self.header {
516            return Err(self.integrity());
517        }
518        self.header_checked.store(true, std::sync::atomic::Ordering::Release);
519        Ok(())
520    }
521    fn integrity(&self) -> FileReadError {
522        FileReadError::Integrity { id: self.file.id().to_string(), cause: None }
523    }
524    fn check_range(&self, offset: u64, len: u64) -> Result<(), FileReadError> {
525        if offset.checked_add(len).is_none_or(|end| end > self.header.size()) {
526            Err(FileReadError::RangeOutOfBounds {
527                id: self.file.id().to_string(),
528                offset,
529                end: offset.saturating_add(len),
530                size: self.header.size(),
531            })
532        } else {
533            Ok(())
534        }
535    }
536    #[expect(
537        clippy::map_err_ignore,
538        reason = "a size past the target integer is TooLarge, which names the field and size"
539    )]
540    pub(crate) async fn range(
541        &self,
542        offset: u64,
543        len: u64,
544        progress: Option<&ReadProgress>,
545    ) -> Result<Vec<u8>, FileReadError> {
546        self.owner.check_open()?;
547        self.check_range(offset, len)?;
548        let length = usize::try_from(len).map_err(|_| DbError::TooLarge {
549            field: "file range",
550            actual: len,
551            maximum: usize::MAX as u64,
552        })?;
553        let mut result = Vec::new();
554        result.try_reserve_exact(length).map_err(|_| DbError::TooLarge {
555            field: "file range",
556            actual: len,
557            maximum: usize::MAX as u64,
558        })?;
559        if len == 0 {
560            return Ok(result);
561        }
562        let size = CHUNK_SIZE as u64;
563        let mut index = offset / size;
564        let last = (offset + len - 1) / size;
565        while index <= last {
566            let here = result.len() as u64;
567            let destination = ChunkDestination::Cache(progress.map(|progress| RangeHere {
568                progress,
569                offset,
570                len,
571                here,
572            }));
573            let ChunkStep::Read(end, chunks) = self.chunks(index, last, destination).await? else {
574                unreachable!("only a pin's download waits for the network")
575            };
576            for (number, chunk) in chunks.into_iter().enumerate() {
577                let plain = chunk.plaintext;
578                let position = (index + number as u64) * size;
579                let start = offset.saturating_sub(position) as usize;
580                let end = (offset + len - position).min(plain.len() as u64) as usize;
581                result.extend_from_slice(&plain[start..end]);
582            }
583            index = end + 1;
584        }
585        Ok(result)
586    }
587    // Reads of one file coalesce; independent files can fetch concurrently,
588    // and so can a pin's ranges of one file, which put nothing in the cache.
589    // The shared cache guard excludes eviction and store close during a fetch.
590    async fn chunks(
591        &self,
592        first: u64,
593        last: u64,
594        destination: ChunkDestination<'_>,
595    ) -> Result<ChunkStep, FileReadError> {
596        loop {
597            match self.chunks_once(first, last, &destination).await? {
598                ChunkStep::Connecting => {
599                    // The read needs storage and a connection is coming:
600                    // wait for it holding none of the cache's locks, then
601                    // read again, as the cache may serve it by then.
602                    self.owner.settled().await?;
603                }
604                step => return Ok(step),
605            }
606        }
607    }
608    #[expect(
609        clippy::map_err_ignore,
610        reason = "a chunk the file size's layout lacks is the disagreement Integrity names"
611    )]
612    async fn chunks_once(
613        &self,
614        first: u64,
615        last: u64,
616        destination: &ChunkDestination<'_>,
617    ) -> Result<ChunkStep, FileReadError> {
618        self.owner.check_open()?;
619        let file_lock = self.owner.lock_file(&self.file, &self.location).await;
620        let _guard = self.owner.cache.read().await;
621        // A cached copy that fails its check changed on this device, which
622        // says nothing about the stored file (§17.8): its bytes are fetched.
623        let cached = self
624            .owner
625            .database
626            .cached(&self.file, first as i64)
627            .await?
628            .map(|bytes| self.open_chunk(first, bytes));
629        let header = self.cached_header().await?;
630        // A pin's download asks storage for nothing while a metered network
631        // holds it; what is here already it still takes (§17.8).
632        if matches!(destination, ChunkDestination::WholeFile { .. })
633            && (!matches!(cached, Some(Ok(_))) || header != CachedHeader::Checked)
634            && self.owner.downloads_held()
635        {
636            return Ok(ChunkStep::Held);
637        }
638        // Only a fetch needs storage: a read the cache serves goes on, and
639        // one that must fetch waits while a connection is coming. A pin's
640        // download holds the pins' lock and fails instead: its failure waits
641        // for a new connection.
642        if matches!(destination, ChunkDestination::Cache(_))
643            && !(matches!(cached, Some(Ok(_))) && header == CachedHeader::Checked)
644            && matches!(self.owner.storage_state(), StorageState::Connecting)
645        {
646            return Ok(ChunkStep::Connecting);
647        }
648        // An unchecked header comes with an uncached chunk zero; any other
649        // first read checks it alone (§17.7).
650        let mut with_header = false;
651        if header == CachedHeader::Missing && first == 0 && cached.is_none() {
652            with_header = true;
653        } else if header != CachedHeader::Checked {
654            self.fetch_header(header).await?;
655        }
656        match cached {
657            Some(Ok(chunk)) => return Ok(ChunkStep::Read(first, vec![chunk])),
658            Some(Err(_)) => {
659                return Ok(ChunkStep::Read(first, vec![self.write_back(first, destination).await?]))
660            }
661            None => {}
662        }
663        let first_chunk = self.header.chunk(first).map_err(|_| self.integrity())?;
664        let start = first_chunk.offset;
665        let mut end_index = first;
666        // The fetch stops at the first cached chunk after the ones it needs.
667        // That chunk's bytes, read here, finish this step, so it is read once
668        // and counts as read before the trim that follows caching the fetched
669        // range.
670        let mut stop = None;
671        let mut end = first_chunk.end();
672        while end_index < last {
673            let next = self.header.chunk(end_index + 1).map_err(|_| self.integrity())?;
674            let next_end = next.end();
675            let request_start = if with_header { 0 } else { start };
676            if next_end - request_start > REQUEST_BYTES {
677                break;
678            }
679            if let Some(bytes) =
680                self.owner.database.cached(&self.file, (end_index + 1) as i64).await?
681            {
682                stop = Some(bytes);
683                break;
684            }
685            end_index += 1;
686            end = next_end;
687        }
688        let received = self.received(destination, first, end_index, start)?;
689        let request_start = if with_header { 0 } else { start };
690        // A pin's fetch puts nothing in the cache, so its file's other reads
691        // need not wait for it: the lock covered reading the cache and
692        // checking the header. A header that comes with chunk zero is
693        // published under it, and the reads after wait to find it checked.
694        if matches!(destination, ChunkDestination::WholeFile { .. }) && !with_header {
695            drop(file_lock);
696        }
697        let fetched = self.fetch(request_start, end, &received).await?;
698        // The header precedes chunk zero: one request carries both, and the
699        // header is cached once it checks, whatever the chunks turn out.
700        let chunks_start = if with_header {
701            let header = fetched.get(..FILE_HEADER_LEN).ok_or_else(|| self.integrity())?;
702            if let Err(refused) = self.accept_header(header) {
703                return Err(self.confirm(request_start, &fetched, refused).await);
704            }
705            self.publish_header(header.to_vec()).await?;
706            FILE_HEADER_LEN
707        } else {
708            0
709        };
710        let (bytes, mut plain) = match self.open_fetched(&fetched[chunks_start..], first, end_index)
711        {
712            Ok(opened) => opened,
713            Err(refused) => return Err(self.confirm(request_start, &fetched, refused).await),
714        };
715        // Every chunk of the range authenticated: it is published as one
716        // file and one row. A failed chunk publishes none of it. A pin writes
717        // these bytes to its reserved whole file instead; adding them to the
718        // cache too could evict a cached tail before pinning reaches it.
719        if matches!(destination, ChunkDestination::Cache(_)) {
720            cache(&self.owner, &self.file, first as i64, (end_index - first + 1) as i64, bytes)
721                .await?;
722            self.owner.trim(self.file.namespace()).await;
723        }
724        // A cached chunk that fails its check is left for the next step,
725        // which fetches it as its first.
726        if let Some(Ok(chunk)) = stop.map(|bytes| self.open_chunk(end_index + 1, bytes)) {
727            end_index += 1;
728            plain.push(chunk);
729        }
730        Ok(ChunkStep::Read(end_index, plain))
731    }
732    /// Chunk `index`'s cached copy failed its check: damage on this device,
733    /// which says nothing about the stored file (§17.8). Its stored bytes are
734    /// fetched, judged as any fetch's are, and written back over the copy.
735    #[expect(
736        clippy::map_err_ignore,
737        reason = "a chunk the file size's layout lacks is the disagreement Integrity names"
738    )]
739    async fn write_back(
740        &self,
741        index: u64,
742        destination: &ChunkDestination<'_>,
743    ) -> Result<OpenedChunk, FileReadError> {
744        let chunk = self.header.chunk(index).map_err(|_| self.integrity())?;
745        let received = self.received(destination, index, index, chunk.offset)?;
746        let fetched = self.fetch(chunk.offset, chunk.end(), &received).await?;
747        let opened = match self.open_chunk(index, fetched.clone()) {
748            Ok(opened) => opened,
749            Err(refused) => return Err(self.confirm(chunk.offset, &fetched, refused).await),
750        };
751        self.owner.database.repair_cached(&self.file, index as i64, fetched).await?;
752        Ok(opened)
753    }
754    /// What hears a fetch of chunks `first..=last`, which starts `start`
755    /// bytes into the object. A pin's meter hears the furthest through the
756    /// object the bytes received reach. A read that shows its progress hears,
757    /// from the fetch's start, its range's bytes in hand: those the steps
758    /// before had, and the received part of each fetched chunk that falls in
759    /// the range.
760    #[expect(
761        clippy::map_err_ignore,
762        reason = "a chunk the file size's layout lacks is the disagreement Integrity names"
763    )]
764    fn received(
765        &self,
766        destination: &ChunkDestination<'_>,
767        first: u64,
768        last: u64,
769        start: u64,
770    ) -> Result<ByteProgress, FileReadError> {
771        match destination {
772            ChunkDestination::WholeFile { progress, fetched } => {
773                let (progress, fetched) = ((*progress).clone(), (*fetched).clone());
774                let furthest = AtomicU64::new(start);
775                Ok(ByteProgress::new(move |reached| {
776                    let before = furthest.fetch_max(reached, Ordering::Relaxed);
777                    if reached > before {
778                        fetched.fetch_add(reached - before, Ordering::Relaxed);
779                        progress.arrived(reached - before);
780                    }
781                }))
782            }
783            ChunkDestination::Cache(None) => Ok(ByteProgress::unread()),
784            ChunkDestination::Cache(Some(range)) => {
785                // Each fetched chunk's place in the object, its plaintext
786                // length, and the part of the range it holds.
787                let mut chunks = Vec::new();
788                for index in first..=last {
789                    let chunk = self.header.chunk(index).map_err(|_| self.integrity())?;
790                    let plain_start = chunk.plaintext_start();
791                    let from = range.offset.max(plain_start) - plain_start;
792                    let to = (range.offset + range.len)
793                        .min(plain_start + chunk.plaintext_length as u64)
794                        - plain_start;
795                    chunks.push((chunk.offset, chunk.plaintext_length as u64, from, to));
796                }
797                let progress = range.progress.clone();
798                let here = range.here;
799                progress.tell(here);
800                Ok(ByteProgress::new(move |reached| {
801                    let fetched: u64 = chunks
802                        .iter()
803                        .map(|&(offset, length, from, to)| {
804                            let received = reached.saturating_sub(offset).min(length);
805                            received.clamp(from, to) - from
806                        })
807                        .sum();
808                    progress.tell(here + fetched);
809                }))
810            }
811        }
812    }
813    /// Open fetched chunks `first..=last`, every one of which must
814    /// authenticate: their sealed bytes, and each one opened.
815    #[expect(
816        clippy::map_err_ignore,
817        reason = "a chunk the file size's layout lacks is the disagreement Integrity names"
818    )]
819    fn open_fetched(
820        &self,
821        fetched: &[u8],
822        first: u64,
823        last: u64,
824    ) -> Result<(Vec<u8>, Vec<OpenedChunk>), FileReadError> {
825        let bytes = fetched.to_vec();
826        let mut plain = Vec::new();
827        let mut cursor = 0;
828        for index in first..=last {
829            let length = self.header.chunk(index).map_err(|_| self.integrity())?.stored_length();
830            let sealed = bytes.get(cursor..cursor + length).ok_or_else(|| self.integrity())?;
831            let opened = self
832                .header
833                .open_chunk(&self.key, self.path.as_str(), index, sealed)
834                .map_err(|error| FileReadError::chunk(self.file.id().to_string(), error))?;
835            plain.push(OpenedChunk { plaintext: opened, ciphertext: sealed.to_vec() });
836            cursor += length;
837        }
838        Ok((bytes, plain))
839    }
840    /// Authenticate chunk `index`'s sealed bytes.
841    fn open_chunk(&self, index: u64, bytes: Vec<u8>) -> Result<OpenedChunk, FileReadError> {
842        let plaintext = self
843            .header
844            .open_chunk(&self.key, self.path.as_str(), index, &bytes)
845            .map_err(|error| FileReadError::chunk(self.file.id().to_string(), error))?;
846        Ok(OpenedChunk { plaintext, ciphertext: bytes })
847    }
848}
849
850struct OpenedChunk {
851    plaintext: Vec<u8>,
852    ciphertext: Vec<u8>,
853}
854
855/// What the cache holds of a file's header.
856#[derive(Clone, Copy, PartialEq, Eq)]
857enum CachedHeader {
858    /// A header this open checked, from the cache or from storage.
859    Checked,
860    /// No header.
861    Missing,
862    /// A copy that fails its check, which changed on this device (§17.8).
863    Damaged,
864}
865
866/// What one step of reading chunks found.
867enum ChunkStep {
868    /// The chunks from the first asked for through this one.
869    Read(u64, Vec<OpenedChunk>),
870    /// A pin's download needs storage, and a metered network holds it.
871    Held,
872    /// A read needs storage and a connection is coming: it waits for the
873    /// connection outside the cache's lock, which the connection's change
874    /// takes, and goes again.
875    Connecting,
876}
877
878async fn cache<M: FilesMode>(
879    owner: &FilesInner<M>,
880    file: &FileRef,
881    first: i64,
882    chunks: i64,
883    bytes: Vec<u8>,
884) -> Result<(), FileReadError> {
885    let name = FileName::new(owner.ids.new_id().to_string()).expect("UUID cache name");
886    owner.database.cache_range(file, first, chunks, name, bytes).await?;
887    Ok(())
888}
889impl<M: FilesMode> UploadedFile<M> {
890    /// Fetch `start..end` of the file's object, telling `received` how far
891    /// through the object the bytes received reach. On a provider whose
892    /// ranged read moves whole parts, the bytes come from the parts this open
893    /// file holds, each fetched once (§17.7).
894    #[expect(
895        clippy::map_err_ignore,
896        reason = "a size whose encrypted layout overflows is the disagreement Integrity names"
897    )]
898    async fn fetch(
899        &self,
900        start: u64,
901        end: u64,
902        received: &ByteProgress,
903    ) -> Result<Vec<u8>, FileReadError> {
904        let storage = super::file_storage::connected(self.owner.storage_state())?;
905        let size = self.header.encrypted_size().map_err(|_| self.integrity())?;
906        let parts = self
907            .parts
908            .get_or_init(|| storage.read_part_size().map(|part| parts::HeldParts::new(part, size)));
909        let (owner, file, path) = (&self.owner, &self.file, &self.path);
910        match parts {
911            None => fetch(owner, file, path, storage.as_ref(), start, end, received).await,
912            Some(parts) => {
913                parts
914                    .read(start, end, received, |from, to, heard| {
915                        let storage = storage.clone();
916                        async move {
917                            fetch(owner, file, path, storage.as_ref(), from, to, &heard).await
918                        }
919                    })
920                    .await
921            }
922        }
923    }
924}
925
926/// Fetch `start..end` of the file's object from `storage`, telling
927/// `received` how far through the object the bytes received reach: storage
928/// tells it as the stream is read, and CloudKit also as each part's fetch
929/// goes, ahead of the read.
930async fn fetch<M: FilesMode>(
931    owner: &FilesInner<M>,
932    file: &FileRef,
933    path: &ObjectPath,
934    storage: &dyn coven_storage::Storage,
935    start: u64,
936    end: u64,
937    received: &ByteProgress,
938) -> Result<Vec<u8>, FileReadError> {
939    // A stored file's record names it only once it is stored (§17.2):
940    // confirmed absence means storage lost it, never a provider failure or
941    // an upload to wait for.
942    let mut stream = match storage
943        .stream_object_reporting(path, Some(ByteRange::new(start, end)?), received)
944        .await
945    {
946        Ok(stream) => stream,
947        Err(error) if error.failure() == coven_storage::StorageFailure::NotFound => {
948            let (location, _) = stored(file)?;
949            return Err(owner.absence_error(file, location));
950        }
951        // Every requested range lies within the file's encrypted size; an
952        // object too short to hold it is damage at the fixed path.
953        Err(error) if error.failure() == coven_storage::StorageFailure::InvalidRange => {
954            return Err(FileReadError::Integrity { id: file.id().to_string(), cause: None })
955        }
956        Err(error) => return Err(error.into()),
957    };
958    // The reply describes the complete object (§20.5). Any size but the file's is
959    // damage, as file status says, even when the requested range is there.
960    crate::files::file_status::complete(file, stream.metadata())?;
961    let mut bytes = Vec::with_capacity((end - start) as usize);
962    let mut buffer = vec![0; 64 * 1024];
963    loop {
964        let length = stream.read(&mut buffer).await?;
965        if length == 0 {
966            break;
967        }
968        bytes.extend_from_slice(&buffer[..length]);
969    }
970    if bytes.len() as u64 != end - start {
971        return Err(FileReadError::Integrity { id: file.id().to_string(), cause: None });
972    }
973    Ok(bytes)
974}