qubit-fs 0.1.0

Pluggable filesystem abstraction for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

/*******************************************************************************
 *
 *    Copyright (c) 2026 Haixing Hu.
 *
 *    SPDX-License-Identifier: Apache-2.0
 *
 *    Licensed under the Apache License, Version 2.0.
 *
 ******************************************************************************/
//! Temporary file handle trait.

use crate::{
    FileReader,
    FileSystemExt,
    FileWriter,
    FsPath,
    FsResult,
    PersistOptions,
    ReadOptions,
    TempResource,
    WriteOptions,
    WriteOutcome,
};

/// Temporary file handle with cleanup responsibility.
pub trait TempFile: TempResource {
    /// Opens the temporary file for reading.
    ///
    /// # Parameters
    /// - `options`: Read options.
    ///
    /// # Returns
    /// Reader handle opened by the owning filesystem.
    ///
    /// # Errors
    /// Returns [`crate::FsError`] when the owning filesystem cannot open the
    /// temporary file for reading.
    fn open_reader(&self, options: &ReadOptions) -> FsResult<Box<dyn FileReader>> {
        self.fs().as_ref().open_reader(self.path(), options)
    }

    /// Opens the temporary file for writing.
    ///
    /// # Parameters
    /// - `options`: Write options.
    ///
    /// # Returns
    /// Writer handle opened by the owning filesystem.
    ///
    /// # Errors
    /// Returns [`crate::FsError`] when the owning filesystem cannot open the
    /// temporary file for writing.
    fn open_writer(&self, options: &WriteOptions) -> FsResult<Box<dyn FileWriter>> {
        self.fs().as_ref().open_writer(self.path(), options)
    }

    /// Reads the whole temporary file into memory.
    ///
    /// # Returns
    /// Complete temporary file bytes.
    ///
    /// # Errors
    /// Returns [`crate::FsError`] when opening or reading fails.
    fn read_all(&self) -> FsResult<Vec<u8>> {
        self.fs().as_ref().read_all(self.path())
    }

    /// Writes all bytes to the temporary file and commits the writer.
    ///
    /// # Parameters
    /// - `bytes`: Bytes to write.
    ///
    /// # Returns
    /// Write outcome reported by the owning filesystem.
    ///
    /// # Errors
    /// Returns [`crate::FsError`] when opening, writing, aborting, or committing
    /// fails.
    fn write_all(&self, bytes: &[u8]) -> FsResult<WriteOutcome> {
        self.fs().as_ref().write_all(self.path(), bytes)
    }

    /// Persists the temporary file to a target path.
    ///
    /// # Parameters
    /// - `target`: Final target path.
    /// - `options`: Persistence options.
    ///
    /// # Returns
    /// Write outcome for the persisted resource.
    ///
    /// # Errors
    /// Returns [`crate::FsError`] when persistence fails.
    fn persist(self: Box<Self>, target: &FsPath, options: &PersistOptions) -> FsResult<WriteOutcome>;
}