Skip to main content

AsyncFileSystem

Struct AsyncFileSystem 

Source
pub struct AsyncFileSystem { /* private fields */ }
Expand description

Application-facing asynchronous filesystem facade.

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

§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::{AsyncFileSystem, FsResult, Path};
use qubit_fs::read::ReadOptions;

async fn read_report_prefix(filesystem: &AsyncFileSystem, path: &Path) -> FsResult<Vec<u8>> {
    let prefix = filesystem.read_prefix(path, ReadOptions::default(), 3).await?;
    Ok(prefix.into_bytes())
}

Implementations§

Source§

impl AsyncFileSystem

Source

pub fn from_spi<S>(spi: S) -> FsResult<Self>
where S: AsyncFileSystemSpi + 'static,

Constructs a facade and caches one validated provider snapshot.

§Type Parameters
  • S: Concrete provider SPI implementation type.
§Parameters
  • spi: Provider implementation whose properties and operations back this facade.
Source

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

Constructs a facade from a shared provider implementation.

§Parameters
  • spi: Provider implementation whose properties and operations back this facade.
Source

pub fn properties(&self) -> &FileSystemProperties

Returns the immutable property snapshot without provider I/O.

Source

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

Validates a write request without opening a provider session.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Write behavior and guarantees to validate before provider work begins.
Source

pub fn assess_copy( &self, source: &Path, target: &Path, options: &CopyOptions, ) -> FsResult<CopyAssessment>

Assesses copy routes without performing provider I/O.

§Parameters
  • source: Logical path of the source resource.
  • target: Destination logical path affected by the operation.
  • options: Copy route, conflict, consistency, and metadata guarantees requested by the caller.
§Errors

Returns an invalid-options or requirement error when no provider or stream execution route can satisfy the request.

Source

pub async fn stat(&self, path: &Path) -> FsResult<FileMetadata>

Asynchronously reads metadata after local validation completes.

§Parameters
  • path: Logical path of the resource involved in this operation.
§Errors

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

Source

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

Asynchronously reports whether the path exists.

§Parameters
  • path: Logical path of the resource involved in this operation.
§Errors

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

Source

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

Asynchronously opens a validated directory stream.

§Parameters
  • scope: Requested directory or namespace listing scope.
  • options: Selection, recursion, page-size, and deadline settings for the listing.
§Errors

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

Source

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

Asynchronously opens a validated reader and verifies its identity.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Read behavior and limits for opening or consuming the resource.
§Errors

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

Source

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

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 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.

Long aggregate reads may periodically return std::task::Poll::Pending even when the provider remains ready. This gives the executor an opportunity to schedule other tasks and observe cancellation. It does not bound the time spent in a single provider poll or guarantee a scheduling order; cancellation cannot interrupt a provider poll already in progress. The byte cap bounds the result size, not elapsed time.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Read behavior and limits for opening or consuming the resource.
  • max_bytes: Maximum number of bytes this operation may return or consume.
§Errors

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

Source

pub async fn read_prefix( &self, path: &Path, options: ReadOptions, max_bytes: usize, ) -> FsResult<PrefixReadOutcome>

Asynchronously reads at most max_bytes from a file.

Long aggregate reads may periodically return std::task::Poll::Pending even when the provider remains ready. This gives the executor an opportunity to schedule other tasks and observe cancellation. It does not bound the time spent in a single provider poll or guarantee a scheduling order; cancellation cannot interrupt a provider poll already in progress. The byte cap bounds the result size, not elapsed time.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Read behavior and limits for opening or consuming the resource.
  • max_bytes: Maximum number of bytes this operation may return or consume.
§Errors

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

Source

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

Asynchronously opens a validated writer and verifies its identity.

An OpenFailure identifies where the attempt stopped: OpenFailureStage::Preflight means local validation rejected it before provider I/O; OpenFailureStage::ProviderOpen means the provider returned an error before an opened envelope; and OpenFailureStage::OutcomeValidation means an opened envelope failed identity validation. The last stage can retain a RejectedAsyncWriter that owns an isolated session with abort-only cleanup authority. Handle that recovery explicitly with abort_async; dropping the failure or receiving no recovery does not prove that no side effect occurred. Keep the typed failure intact when recovery matters instead of using ? to discard it.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Write behavior and guarantees to validate before provider work begins.
§Errors

Returns the contextual error, opening stage, and any isolated recovery session when validation, provider opening, or outcome validation fails.

Source

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.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • bytes: Payload to write as one complete resource.
  • options: Write behavior and guarantees to validate before provider work begins.
§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.

Source

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

Asynchronously creates a directory after local validation.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Options that define the operation and its requested guarantees.
§Errors

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

Source

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

Asynchronously deletes a file after local validation.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Deletion behavior, including whether a missing target is acceptable.
§Errors

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

Source

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

Asynchronously deletes a directory after local validation.

§Parameters
  • path: Logical path of the resource involved in this operation.
  • options: Deletion behavior, including whether a missing target is acceptable.
§Errors

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

Source

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

Renames one resource through the single asynchronous provider primitive.

§Parameters
  • source: Logical path of the source resource.
  • target: Destination logical path affected by the operation.
  • options: Overwrite, atomicity, and durability requirements for the rename.
§Errors

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

Source

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

Asynchronously creates a temporary file and validates its provider identity.

§Parameters
  • options: Parent, naming, and parent-creation settings for the temporary resource.
§Errors

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

Source

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

Asynchronously creates a temporary directory and validates its identity.

§Parameters
  • options: Parent, naming, and parent-creation settings for the temporary resource.
§Errors

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

Source

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. Keep the returned operation outside the cancellation scope and cancel only its execute future. The operation then remains available to inspect publication state and take any retained writer recovery.

§Parameters
  • source: Logical path of the source resource.
  • target: Destination logical path affected by the operation.
  • options: Copy route, conflict, consistency, and metadata guarantees requested by the caller.
§Errors

Returns AsyncCopyFailure when local preflight rejects the request.

Trait Implementations§

Source§

impl Clone for AsyncFileSystem

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.