extendable_assets/filesystem/
mod.rs

1mod fallback;
2pub use fallback::*;
3
4#[cfg(feature = "fs-embed")]
5mod embed;
6#[cfg(feature = "fs-embed")]
7pub use embed::*;
8
9#[cfg(feature = "fs-native")]
10mod native;
11#[cfg(feature = "fs-native")]
12pub use native::*;
13
14use async_trait::async_trait;
15
16/// Errors that can occur during filesystem operations.
17#[derive(Debug, thiserror::Error)]
18#[non_exhaustive]
19pub enum FilesystemError {
20    /// Standard I/O error occurred.
21    #[error("I/O: {0}")]
22    Io(#[from] std::io::Error),
23    /// Writing operations are not supported by this filesystem implementation.
24    #[error("Writing is unsupported on this filesystem")]
25    WriteUnsupported,
26    /// The requested asset file was not found.
27    #[error("Asset not found: {0}")]
28    NotFound(String),
29    /// Any other filesystem-related error.
30    #[error(transparent)]
31    Other(anyhow::Error),
32}
33
34/// Abstraction for reading files from different storage backends.
35///
36/// This trait allows the asset system to work with different filesystem
37/// implementations, such as native filesystem, network storage, or embedded assets.
38/// All filesystem operations are async to support non-blocking I/O.
39#[async_trait]
40pub trait Filesystem: Send + Sync {
41    /// Asynchronously reads the contents of an asset file as raw bytes.
42    ///
43    /// This method performs non-blocking I/O to read the entire file into memory.
44    /// For large files, consider implementing streaming or chunked reading.
45    ///
46    /// # Arguments
47    ///
48    /// * `asset_path` - The path to the asset file
49    ///
50    /// # Returns
51    ///
52    /// A future that resolves to the file contents as bytes, or an error if the file could not be read.
53    async fn read_bytes(&self, asset_path: &str) -> Result<Vec<u8>, FilesystemError>;
54
55    /// Asynchronously writes raw bytes to an asset file.
56    ///
57    /// This method provides a default implementation that returns `WriteUnsupported`.
58    /// Filesystem implementations that support writing should override this method.
59    ///
60    /// # Arguments
61    ///
62    /// * `asset_path` - The path where the asset file should be written
63    /// * `data` - The raw bytes to write to the file
64    ///
65    /// # Returns
66    ///
67    /// A future that resolves to success or an error if the write operation fails.
68    /// The default implementation always returns `WriteUnsupported`.
69    #[allow(unused_variables)]
70    async fn write_bytes(&self, asset_path: &str, data: &[u8]) -> Result<(), FilesystemError> {
71        Err(FilesystemError::WriteUnsupported)
72    }
73}
extendable_assets/filesystem/mod.rs

extendable_assets/filesystem/
mod.rs
