pub struct FileSystem { /* private fields */ }Expand description
Application-facing synchronous filesystem facade.
§Examples
Applications obtain their configured facade from a provider or registry integration. The function below reads at most three bytes; the result may be shorter when the file contains fewer bytes.
use qubit_fs::{FileSystem, FsResult, Path};
use qubit_fs::read::ReadOptions;
fn read_report_prefix(filesystem: &FileSystem, path: &Path) -> FsResult<Vec<u8>> {
let prefix = filesystem.read_prefix(path, ReadOptions::default(), 3)?;
Ok(prefix.into_bytes())
}Implementations§
Source§impl FileSystem
impl FileSystem
Sourcepub fn from_spi<S>(spi: S) -> FsResult<Self>where
S: FileSystemSpi + 'static,
pub fn from_spi<S>(spi: S) -> FsResult<Self>where
S: FileSystemSpi + 'static,
Constructs a facade and caches the provider’s single validated property snapshot.
§Type Parameters
S: Concrete provider SPI implementation type.
§Parameters
spi: Provider implementation whose properties and operations back the facade.
§Returns
The facade when the provider property snapshot is valid.
§Errors
Returns the provider property validation error when its snapshot is inconsistent.
Sourcepub fn properties(&self) -> &FileSystemProperties
pub fn properties(&self) -> &FileSystemProperties
Returns the immutable property snapshot without provider I/O.
§Returns
The validated properties captured when this facade was constructed.
Sourcepub fn assess_copy(
&self,
source: &Path,
target: &Path,
options: &CopyOptions,
) -> FsResult<CopyAssessment>
pub fn assess_copy( &self, source: &Path, target: &Path, options: &CopyOptions, ) -> FsResult<CopyAssessment>
Assesses copy routes without performing provider I/O.
§Errors
Returns an invalid-options or requirement error when no provider or stream execution route can satisfy the request.
§Parameters
source: Logical source path.target: Logical destination path.options: Copy policy to assess.
§Returns
The selected route and the first statically rejected fallback, when one exists.
Sourcepub fn stat(&self, path: &Path) -> FsResult<FileMetadata>
pub fn stat(&self, path: &Path) -> FsResult<FileMetadata>
Reads metadata after all local validation succeeds.
§Errors
Returns the provider or validation error when path is invalid, the
provider cannot stat it, or the provider returns a mismatched path.
§Parameters
path: Logical resource path to inspect.
§Returns
Metadata for the requested path after provider identity validation.
Sourcepub fn exists(&self, path: &Path) -> FsResult<bool>
pub fn exists(&self, path: &Path) -> FsResult<bool>
Returns false only for an explicit not-found response.
§Errors
Returns the original filesystem error for validation, provider, or
provider-contract failures other than NotFound.
§Parameters
path: Logical resource path to check.
§Returns
true when metadata is returned, or false for an explicit not-found
response.
Sourcepub fn copy(
&self,
source: &Path,
target: &Path,
options: CopyOptions,
) -> Result<CopyOutcome, CopyFailure>
pub fn copy( &self, source: &Path, target: &Path, options: CopyOptions, ) -> Result<CopyOutcome, CopyFailure>
Copies source to target through an optional provider fast path and a
safe stream fallback.
§Errors
Returns CopyFailure with a recovery state. A provider failure is
never retried; only an explicit provider decline can select the
facade’s allowlisted fallback.
§Parameters
source: Logical resource to copy.target: Logical destination path.options: Copy behavior and fallback policy.
§Returns
The confirmed copy outcome.
Sourcepub fn rename(
&self,
source: &Path,
target: &Path,
options: RenameOptions,
) -> Result<RenameOutcome, RenameFailure>
pub fn rename( &self, source: &Path, target: &Path, options: RenameOptions, ) -> Result<RenameOutcome, RenameFailure>
Renames one resource through exactly one provider rename primitive.
§Errors
Returns RenameFailure with the provider-confirmed transition state.
This method never implements rename through copy and delete.
§Parameters
source: Existing logical resource path.target: Destination logical path.options: Rename policy passed to the provider.
§Returns
The provider-confirmed rename outcome.
Sourcepub fn list(
&self,
scope: &ListScope,
options: ListOptions,
) -> FsResult<DirectoryStream>
pub fn list( &self, scope: &ListScope, options: ListOptions, ) -> FsResult<DirectoryStream>
Opens a provider directory stream after local option validation.
§Errors
Returns an invalid-options, missing-capability, or provider error when the scope or options cannot be served.
§Parameters
scope: Directory scope to enumerate.options: Listing behavior and limits.
§Returns
A stream of validated directory entries.
Sourcepub fn open_reader(
&self,
path: &Path,
options: ReadOptions,
) -> FsResult<FileReader>
pub fn open_reader( &self, path: &Path, options: ReadOptions, ) -> FsResult<FileReader>
Opens a provider reader after local option validation.
§Errors
Returns an invalid-path, unsupported-capability, provider, or provider-contract error when the reader cannot be opened safely.
§Parameters
path: Logical file path to open.options: Read range and behavior.
§Returns
A reader bound to the validated provider handle.
Sourcepub fn open_random_access_reader(
&self,
path: &Path,
options: ReadOptions,
) -> FsResult<RandomAccessReader>
pub fn open_random_access_reader( &self, path: &Path, options: ReadOptions, ) -> FsResult<RandomAccessReader>
Opens a complete file for explicit-offset reads on one opened object. The observed length is an upper bound, not a content snapshot.
§Parameters
path: Logical file path to open.options: Read options. Only no offset or offset zero, no length, and no checksum validation are accepted; version conditions are kept.
§Returns
A handle whose reads use the object opened by the provider.
§Errors
Returns path/option errors, missing read or operation errors, the provider open error, or a provider-contract error for mismatched identity, missing metadata, non-file kind, or unknown length.
Sourcepub fn open_writer(
&self,
path: &Path,
options: WriteOptions,
) -> Result<FileWriter, OpenFailure<RejectedWriter>>
pub fn open_writer( &self, path: &Path, options: WriteOptions, ) -> Result<FileWriter, OpenFailure<RejectedWriter>>
Opens a provider writer after local option validation.
§Errors
Returns OpenFailure identifying preflight, provider-open, or
provider-contract failure; a retained rejected writer is available when
provider cleanup is required.
§Parameters
path: Logical file path to open for writing.options: Write and publication behavior.
§Returns
The writer, or an OpenFailure retaining cleanup state when needed.
Sourcepub fn create_temp_file(
&self,
options: TempOptions,
) -> Result<TempFile, OpenFailure<RejectedTempResource>>
pub fn create_temp_file( &self, options: TempOptions, ) -> Result<TempFile, OpenFailure<RejectedTempResource>>
Creates a temporary file and binds its provider session to this facade.
§Errors
Returns OpenFailure when preflight, provider creation, or temporary
identity validation fails; the recovery value may retain cleanup work.
§Parameters
options: Parent and naming policy for the temporary file.
§Returns
A temporary file handle bound to this facade.
Sourcepub fn create_temp_directory(
&self,
options: TempOptions,
) -> Result<TempDirectory, OpenFailure<RejectedTempResource>>
pub fn create_temp_directory( &self, options: TempOptions, ) -> Result<TempDirectory, OpenFailure<RejectedTempResource>>
Creates a temporary directory and binds its provider session to this facade.
§Errors
Returns OpenFailure when preflight, provider creation, or temporary
identity validation fails; the recovery value may retain cleanup work.
§Parameters
options: Parent and naming policy for the temporary directory.
§Returns
A temporary directory handle bound to this facade.
Sourcepub fn create_directory(
&self,
path: &Path,
options: CreateDirectoryOptions,
) -> FsResult<CreateDirectoryOutcome>
pub fn create_directory( &self, path: &Path, options: CreateDirectoryOptions, ) -> FsResult<CreateDirectoryOutcome>
Creates a directory after local path validation.
§Errors
Returns an invalid-path, missing-capability, provider, or provider- contract error when the directory cannot be created as requested.
§Parameters
path: Logical directory path to create.options: Creation and parent handling policy.
§Returns
The provider-confirmed directory creation outcome.
Sourcepub fn delete_file(
&self,
path: &Path,
options: DeleteOptions,
) -> FsResult<DeleteOutcome>
pub fn delete_file( &self, path: &Path, options: DeleteOptions, ) -> FsResult<DeleteOutcome>
Sourcepub fn delete_directory(
&self,
path: &Path,
options: DeleteOptions,
) -> FsResult<DeleteOutcome>
pub fn delete_directory( &self, path: &Path, options: DeleteOptions, ) -> FsResult<DeleteOutcome>
Deletes a directory after local option validation.
§Errors
Returns an invalid-options, missing-capability, provider, or provider-contract error when deletion cannot be confirmed.
§Parameters
path: Logical directory path to delete.options: Deletion policy.
§Returns
The provider-confirmed deletion outcome.
Sourcepub fn read_all(
&self,
path: &Path,
options: ReadOptions,
max_bytes: usize,
) -> FsResult<Vec<u8>>
pub fn read_all( &self, path: &Path, options: ReadOptions, max_bytes: usize, ) -> FsResult<Vec<u8>>
Reads one file into memory up to max_bytes after opening a reader.
The byte cap applies to bytes actually read, even when opened metadata overestimates the resource length.
§Errors
Returns the reader or read error when validation, opening, or bounded reading fails.
§Parameters
path: Logical file path to read.options: Read range and behavior.max_bytes: Maximum number of bytes allowed in memory.
§Returns
The complete contents when the file fits within the byte cap.
Sourcepub fn read_prefix(
&self,
path: &Path,
options: ReadOptions,
max_bytes: usize,
) -> FsResult<PrefixReadOutcome>
pub fn read_prefix( &self, path: &Path, options: ReadOptions, max_bytes: usize, ) -> FsResult<PrefixReadOutcome>
Reads at most max_bytes from a file without requiring a complete read.
§Errors
Returns the reader or read error when validation, opening, or bounded reading fails.
§Parameters
path: Logical file path to read.options: Read range and behavior.max_bytes: Maximum number of bytes to consume.
§Returns
The bytes read and the termination reason, which distinguishes end of file from reaching the byte limit.
Sourcepub fn write_all(
&self,
path: &Path,
bytes: &[u8],
options: WriteOptions,
) -> Result<WriteOutcome, WriteAllFailure>
pub fn write_all( &self, path: &Path, bytes: &[u8], options: WriteOptions, ) -> Result<WriteOutcome, WriteAllFailure>
Writes all bytes and retains the writer if transfer or commit fails.
§Errors
Returns WriteAllFailure with the confirmed byte count and retained
writer when validation, transfer, or publication fails.
§Parameters
path: Logical destination path.bytes: Complete payload to write.options: Write and publication behavior.
§Returns
The confirmed write outcome, or a failure retaining the writer and confirmed transfer state.
Sourcepub fn validate_write(
&self,
path: &Path,
options: &WriteOptions,
) -> FsResult<()>
pub fn validate_write( &self, path: &Path, options: &WriteOptions, ) -> FsResult<()>
Validates a write request without opening a provider session.
§Parameters
path: Logical destination path to validate.options: Write configuration checked against cached capabilities and limits.
§Returns
Ok(()) when the request is locally valid.
§Errors
Returns the path, option, capability, or limit validation error.