Skip to main content

FileSystem

Struct FileSystem 

Source
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

Source

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.

Source

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

Constructs a facade from a shared provider implementation.

§Parameters
  • spi: Shared provider implementation retained by the facade.
§Returns

The facade when the provider property snapshot is valid.

§Errors

Returns the provider property validation error when its snapshot is inconsistent.

Source

pub fn properties(&self) -> &FileSystemProperties

Returns the immutable property snapshot without provider I/O.

§Returns

The validated properties captured when this facade was constructed.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

§Parameters
  • path: Logical file path to delete.
  • options: Deletion policy.
§Returns

The provider-confirmed deletion outcome.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Clone for FileSystem

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.