Struct AsyncFileSystem 

pub struct AsyncFileSystem { /* private fields */ }

Application-facing asynchronous filesystem facade.

It validates provider boundaries, exposes asynchronous operations, and owns the cancellation-safe copy operation entry point.

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 bytes = filesystem.read_prefix(&Path::parse("/report")?, ReadOptions::default(), 3).await?;
assert_eq!(b"byt", bytes.bytes());

Implementations

impl AsyncFileSystem

pub fn from_spi<S>(spi: S) -> FsResult<Self>

where S: AsyncFileSystemSpi + 'static,

Constructs a facade and caches one validated provider snapshot.

pub fn from_shared_spi(spi: Arc<dyn AsyncFileSystemSpi>) -> 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 async fn stat(&self, path: &Path) -> FsResult<FileMetadata>

Asynchronously reads metadata after local validation completes.

Local validation happens before this future reaches the provider. A provider response is checked again after awaiting to bind the returned metadata to the requested logical path.

Errors

Returns a validation, provider, or provider-contract error when the path cannot be read or the response identifies another path.

pub async fn exists(&self, path: &Path) -> FsResult<bool>

Asynchronously reports whether the path exists.

Errors

Returns the original filesystem error for failures other than an explicit NotFound response.

pub async fn list( &self, scope: &ListScope, options: ListOptions, ) -> FsResult<AsyncDirectoryStream>

Asynchronously opens a validated directory stream.

Errors

Returns an invalid-options, missing-capability, or provider error when the scope or options cannot be served.

pub async fn open_reader( &self, path: &Path, options: ReadOptions, ) -> FsResult<AsyncFileReader>

Asynchronously opens a validated reader and verifies its identity.

Errors

Returns a validation, capability, provider, or provider-contract error when the reader cannot be opened safely.

pub async fn read_all( &self, path: &Path, options: ReadOptions, max_bytes: usize, ) -> FsResult<Vec<u8>>

Asynchronously reads an entire file while enforcing a strict byte cap.

The 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 async fn read_prefix( &self, path: &Path, options: ReadOptions, max_bytes: usize, ) -> FsResult<PrefixReadOutcome>

Asynchronously reads at most max_bytes from a file.

Errors

Returns the reader or read error when validation, opening, or bounded reading fails.

pub async fn open_writer( &self, path: &Path, options: WriteOptions, ) -> Result<AsyncFileWriter, OpenFailure<RejectedAsyncWriter>>

Asynchronously opens a validated writer and verifies its identity.

pub fn begin_write_all( &self, path: Path, bytes: Vec<u8>, options: WriteOptions, ) -> Result<AsyncWriteAllOperation, AsyncWriteAllOperationFailure>

Begins an owning asynchronous whole-file write operation.

Moves path, bytes, and options into the request and retains a clone of this filesystem. Construction performs no provider I/O. Keep the operation outside the cancellation scope and cancel only its execute future so publication facts and recovery responsibility remain available.

Returns

A ready operation that no longer borrows the caller’s filesystem or payload. The payload is released after execution ends or is cancelled.

Errors

Returns a NotPublished failure with zero confirmed bytes if the path, capabilities, options, or payload size fail local validation. Rejected construction consumes and releases the payload.

pub async fn create_directory( &self, path: &Path, options: CreateDirectoryOptions, ) -> FsResult<CreateDirectoryOutcome>

Asynchronously creates a directory after local validation.

Errors

Returns a validation, capability, provider, or provider-contract error when the directory cannot be created as requested.

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

Asynchronously deletes a file after local validation.

Errors

Returns a validation, capability, provider, or provider-contract error when deletion cannot be confirmed.

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

Asynchronously deletes a directory after local validation.

Errors

Returns a validation, capability, provider, or provider-contract error when deletion cannot be confirmed.

pub async fn rename( &self, source: &Path, target: &Path, options: RenameOptions, ) -> Result<RenameOutcome, RenameFailure>

Renames one resource through the single asynchronous provider primitive.

Errors

Returns RenameFailure with the confirmed transition state when validation, provider execution, or outcome validation fails.

pub async fn create_temp_file( &self, options: TempOptions, ) -> Result<AsyncTempFile, OpenFailure<RejectedAsyncTempResource>>

Asynchronously creates a temporary file and validates its provider identity.

Errors

Returns OpenFailure when preflight, provider creation, or temporary identity validation fails.

pub async fn create_temp_directory( &self, options: TempOptions, ) -> Result<AsyncTempDirectory, OpenFailure<RejectedAsyncTempResource>>

Asynchronously creates a temporary directory and validates its identity.

Errors

Returns OpenFailure when preflight, provider creation, or temporary identity validation fails.

pub fn begin_copy( &self, source: Path, target: Path, options: CopyOptions, ) -> Result<AsyncCopyOperation, AsyncCopyFailure>

Begins a copy after synchronous path, option, and capability preflight.

This method performs no provider I/O. Provider work begins only when AsyncCopyOperation::execute is polled.

Errors

Returns AsyncCopyFailure when local preflight rejects the request.

Trait Implementations

impl Clone for AsyncFileSystem

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.