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
impl AsyncFileSystem
Sourcepub fn from_spi<S>(spi: S) -> FsResult<Self>where
S: AsyncFileSystemSpi + 'static,
pub fn from_spi<S>(spi: S) -> FsResult<Self>where
S: AsyncFileSystemSpi + 'static,
Constructs a facade from a shared provider implementation.
§Parameters
spi: Provider implementation whose properties and operations back this facade.
Sourcepub fn properties(&self) -> &FileSystemProperties
pub fn properties(&self) -> &FileSystemProperties
Returns the immutable property snapshot without provider I/O.
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 path of the resource involved in this operation.options: Write behavior and guarantees to validate before provider work begins.
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.
§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.
Sourcepub async fn stat(&self, path: &Path) -> FsResult<FileMetadata>
pub async fn stat(&self, path: &Path) -> FsResult<FileMetadata>
Sourcepub async fn list(
&self,
scope: &ListScope,
options: ListOptions,
) -> FsResult<AsyncDirectoryStream>
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.
Sourcepub async fn open_reader(
&self,
path: &Path,
options: ReadOptions,
) -> FsResult<AsyncFileReader>
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.
Sourcepub async fn open_random_access_reader(
&self,
path: &Path,
options: ReadOptions,
) -> FsResult<AsyncRandomAccessReader>
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.
Sourcepub async fn read_all(
&self,
path: &Path,
options: ReadOptions,
max_bytes: usize,
) -> FsResult<Vec<u8>>
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.
Sourcepub async fn read_prefix(
&self,
path: &Path,
options: ReadOptions,
max_bytes: usize,
) -> FsResult<PrefixReadOutcome>
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.
Sourcepub async fn open_writer(
&self,
path: &Path,
options: WriteOptions,
) -> Result<AsyncFileWriter, OpenFailure<RejectedAsyncWriter>>
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.
Sourcepub fn begin_write_all(
&self,
path: Path,
bytes: Vec<u8>,
options: WriteOptions,
) -> Result<AsyncWriteAllOperation, AsyncWriteAllOperationFailure>
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.
Sourcepub async fn create_directory(
&self,
path: &Path,
options: CreateDirectoryOptions,
) -> FsResult<CreateDirectoryOutcome>
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.
Sourcepub async fn delete_file(
&self,
path: &Path,
options: DeleteOptions,
) -> FsResult<DeleteOutcome>
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.
Sourcepub async fn delete_directory(
&self,
path: &Path,
options: DeleteOptions,
) -> FsResult<DeleteOutcome>
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.
Sourcepub async fn rename(
&self,
source: &Path,
target: &Path,
options: RenameOptions,
) -> Result<RenameOutcome, RenameFailure>
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.
Sourcepub async fn create_temp_file(
&self,
options: TempOptions,
) -> Result<AsyncTempFile, OpenFailure<RejectedAsyncTempResource>>
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.
Sourcepub async fn create_temp_directory(
&self,
options: TempOptions,
) -> Result<AsyncTempDirectory, OpenFailure<RejectedAsyncTempResource>>
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.
Sourcepub fn begin_copy(
&self,
source: Path,
target: Path,
options: CopyOptions,
) -> Result<AsyncCopyOperation, AsyncCopyFailure>
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.