Struct FileSystem 

pub struct FileSystem { /* private fields */ }

Application-facing synchronous filesystem facade.

Examples

The example runs against an isolated in-memory fixture. Applications obtain their configured facade from a provider or registry integration.

use qubit_fs::Path;
use qubit_fs::read::ReadOptions;

let path = Path::parse("/report")?;
let bytes = filesystem.read_prefix(&path, ReadOptions::default(), 3)?;
assert_eq!(b"rep", bytes.bytes());

Implementations

impl FileSystem

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.

pub fn from_shared_spi(spi: Arc<dyn FileSystemSpi>) -> FsResult<Self>

Constructs a facade from a shared provider implementation.

pub fn properties(&self) -> &FileSystemProperties

Returns the immutable property snapshot without provider I/O.

pub fn validate_write( &self, path: &Path, options: &WriteOptions, ) -> FsResult<()>

Validates a write request without opening a provider session.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

pub fn delete_file( &self, path: &Path, options: DeleteOptions, ) -> FsResult<DeleteOutcome>

Deletes a file after local option validation.

Errors

Returns an invalid-options, missing-capability, provider, or provider-contract error when deletion cannot be confirmed.

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.

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.

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.

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.

Trait Implementations

impl Clone for FileSystem

fn clone(&self) -> FileSystem

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.