Skip to main content

AsyncFileSystemFixture

Trait AsyncFileSystemFixture 

Source
pub trait AsyncFileSystemFixture: Sync {
Show 27 methods // Required methods fn file_system(&self) -> &AsyncFileSystem; fn path(&self, relative: &str) -> FixtureResult<Path>; fn teardown(&self) -> FixtureFuture<'_, ()>; // Provided methods fn random_access_operation(&self) -> FixtureSupport<bool> { ... } fn replace_random_access_path<'a>( &'a self, path: &'a Path, bytes: &'a [u8], ) -> FixtureFuture<'a, FixtureSupport<()>> { ... } fn arm_random_access_pending_read( &self, path: &Path, ) -> FixtureResult<FixtureSupport<()>> { ... } fn disarm_random_access_pending_read( &self, path: &Path, ) -> FixtureResult<()> { ... } fn random_access_pending_read_reached( &self, path: &Path, ) -> FixtureResult<FixtureSupport<bool>> { ... } fn snapshot_namespace_paths( &self, ) -> FixtureFuture<'_, FixtureSupport<Vec<Path>>> { ... } fn prepare_copy<'a>( &'a self, scenario: CopyScenario, source_relative: &'a str, target_relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<CopyFixtureCase>> { ... } fn prepare_delete<'a>( &'a self, _scenario: DeleteScenario, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<Path>> { ... } fn prepare_read<'a>( &'a self, scenario: ReadScenario, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<Path>> { ... } fn prepare_write<'a>( &'a self, scenario: WriteScenario, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<WriteFixtureCase>> { ... } fn copy_fallback_only(&self) -> bool { ... } fn list_prefix(&self, root: &Path, relative: &str) -> FixtureResult<String> { ... } fn seed_file<'a>( &'a self, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixtureSupport<Path>> { ... } fn read_file<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<Vec<u8>>> { ... } fn exists_out_of_band<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<bool>> { ... } fn write_file_out_of_band<'a>( &'a self, path: &'a Path, bytes: &'a [u8], ) -> FixtureFuture<'a, FixtureSupport<()>> { ... } fn resource_version<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<ResourceVersion>> { ... } fn stale_resource_version<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<ResourceVersion>> { ... } fn checksum_failure_case<'a>( &'a self, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Path>> { ... } fn seed_empty_directory<'a>( &'a self, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Path>> { ... } fn seed_symlink<'a>( &'a self, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Path>> { ... } fn copy_fast_path_case<'a>( &'a self, method: CopyMethod, ) -> FixtureFuture<'a, FixtureSupport<CopyFixtureCase>> { ... } fn prepare_copy_cancellation<'a>( &'a self, stage: AsyncCopyCancellationStage, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Box<dyn CopyCancellationProbe>>> { ... } fn prepare_write_cancellation<'a>( &'a self, stage: AsyncWriteCancellationStage, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Box<dyn WriteCancellationProbe>>> { ... }
}
Expand description

Supplies an isolated asynchronous facade and optional provider observations.

§Examples

use qubit_fs_testkit::{AsyncFileSystemContractSuite, AsyncFileSystemFixture};

let fixture = RustdocAsyncFixture::new();
let suite = AsyncFileSystemContractSuite::new(&fixture);
assert!(suite.run().report().checks().is_empty());

Required Methods§

Source

fn file_system(&self) -> &AsyncFileSystem

Returns the concrete asynchronous filesystem facade under test.

§Returns

The isolated asynchronous facade owned by this fixture.

Source

fn path(&self, relative: &str) -> FixtureResult<Path>

Maps a testkit-relative name to an isolated logical path.

§Parameters
  • relative - Suite-generated name relative to the fixture namespace.
§Returns

The corresponding logical path within the isolated namespace.

§Errors

Returns FixtureError when the name cannot be represented by the provider’s path model.

Source

fn teardown(&self) -> FixtureFuture<'_, ()>

Independently releases every resource owned by this fixture.

This mandatory operation must be idempotent and must reclaim partially prepared resources and staging state, including resources unknown to the suite. Use a native or out-of-band channel independent of the facade under test. Return an error if cleanup could not be confirmed. A cancelled asynchronous attempt must remain safe to retry.

§Returns

A future completing after fixture-owned resources and staging state have been independently reclaimed.

§Errors

The future returns FixtureError when cleanup cannot be confirmed.

Provided Methods§

Source

fn random_access_operation(&self) -> FixtureSupport<bool>

Independently reports whether the provider implements random-access sessions. This must reflect provider SPI configuration rather than range-read support.

§Returns

Supported(true) or Supported(false) with the independent SPI declaration, or Unsupported when the fixture cannot observe it.

Source

fn replace_random_access_path<'a>( &'a self, path: &'a Path, bytes: &'a [u8], ) -> FixtureFuture<'a, FixtureSupport<()>>

Replaces a path while preserving any object already opened by a reader. The fixture must use an independent setup path rather than the facade under test.

§Parameters
  • path - Seeded path to replace.
  • bytes - Replacement object content.
§Returns

A future resolving to Supported(()) when replacement is available, or Unsupported when it cannot be performed independently.

§Errors

The future returns FixtureError when fixture replacement fails.

Source

fn arm_random_access_pending_read( &self, path: &Path, ) -> FixtureResult<FixtureSupport<()>>

Arms a deterministic pending read for the next random-access read. The hook changes fixture state only; it must not start an async runtime.

§Parameters
  • path - Seed path whose next random-access read will be gated.
§Returns

Supported(()) when the gate was armed, or Unsupported when this fixture cannot inject a pending read.

§Errors

Returns FixtureError when arming fails.

Source

fn disarm_random_access_pending_read(&self, path: &Path) -> FixtureResult<()>

Idempotently releases a previously armed pending-read probe. This hook is synchronous so guards can release the gate during future cancellation without a runtime.

§Parameters
  • path - Seed path associated with the gate.
§Returns

Ok(()) once the gate has been released.

§Errors

Returns FixtureError when release fails.

Source

fn random_access_pending_read_reached( &self, path: &Path, ) -> FixtureResult<FixtureSupport<bool>>

Independently reports whether a random-access read reached the injected pending gate. This must inspect fixture instrumentation only and must not perform I/O. The cancellation check passes only for Supported(true) after observing the read future return Pending; Supported(false) and Unsupported leave the check unverified. The runner drops the future before querying this hook, then disarms the gate. The fixture must allow the reader to be used again after disarming.

§Parameters
  • path - Seed path associated with the pending-read probe.
§Returns

Supported(true) when the read reached the gate, Supported(false) when it did not, or Unsupported when this fixture cannot observe gate entry.

§Errors

Returns FixtureError when reading the independent instrumentation fails.

Source

fn snapshot_namespace_paths( &self, ) -> FixtureFuture<'_, FixtureSupport<Vec<Path>>>

Snapshots every logical path in the isolated configured namespace.

Use the underlying SDK or fixture model, never the facade list method. Include resources created by earlier checks, not only the current seed. Returns unsupported when independent completeness cannot be established.

§Returns

A future resolving to every path in the isolated namespace, or Unsupported when the fixture cannot establish a complete snapshot.

§Errors

The future returns FixtureError when the independent snapshot operation fails.

Source

fn prepare_copy<'a>( &'a self, scenario: CopyScenario, source_relative: &'a str, target_relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<CopyFixtureCase>>

Independently prepares a copy source and a scenario-specific target.

File scenarios contain the supplied bytes and use file options, with Required atomicity or durability for the respective strong scenario. Native cases provide an independently seeded source containing 1..=64 KiB; missing independent source evidence is reported as unverified. ServerSide cases use provider-selected bytes that are independently seeded and readable, contain 1..=64 KiB, and require server-side copy. The suite independently checks source contents and target absence before execution, then source and target contents after execution; unavailable preparation or observation evidence is reported as unverified. Ready cases have distinct paths, and Conflict targets contain b"existing". Teardown must clean partial setup even when preparation fails.

§Parameters
  • scenario - Copy behavior and guarantees to prepare.
  • source_relative - Testkit-relative source name.
  • target_relative - Testkit-relative destination name.
  • bytes - Source content for file-copy scenarios and the child file for tree-copy scenarios.
§Returns

A future resolving to Ready(case) when setup succeeds, or Unavailable when required fixture setup is unsupported.

§Errors

The future returns FixtureError when path mapping or an out-of-band preparation operation fails.

Source

fn prepare_delete<'a>( &'a self, _scenario: DeleteScenario, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<Path>>

Independently prepares an existing file for a selected deletion scenario. Version hooks must provide evidence for DeleteScenario::IfMatch.

§Parameters
  • scenario - Deletion behavior to prepare.
  • relative - Testkit-relative name of the file to seed.
  • bytes - Exact initial file content.
§Returns

A future resolving to the prepared path, or Unavailable when the fixture cannot seed the file.

§Errors

The future returns FixtureError when seeding fails.

Source

fn prepare_read<'a>( &'a self, scenario: ReadScenario, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<Path>>

Independently prepares one read scenario and its initial content.

A Ready path must contain the supplied bytes, except for the explicit corruption scenario. Version observations remain independent fixture hooks. Preparation errors must not become inapplicability declarations.

§Parameters
  • scenario - Read behavior to prepare.
  • relative - Testkit-relative name of the resource.
  • bytes - Exact initial content, except for checksum corruption.
§Returns

A future resolving to the prepared path, or Unavailable when the fixture cannot independently prepare the selected scenario.

§Errors

The future returns FixtureError when setup or checksum-case preparation fails.

Source

fn prepare_write<'a>( &'a self, scenario: WriteScenario, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixturePreparation<WriteFixtureCase>>

Independently prepares the selected write request and initial state.

The default prepares CreateNew and durable creation requests, and seeds targets for atomic replacement, creation conflicts and append independently. Missing setup remains explicit and is never counted as successful testing.

§Parameters
  • scenario - Write behavior and guarantees to prepare.
  • relative - Testkit-relative target name.
  • bytes - Payload submitted by the write operation.
§Returns

A future resolving to the prepared write request, or Unavailable when required setup is unsupported.

§Errors

The future returns FixtureError when path mapping or out-of-band seeding fails.

Source

fn copy_fallback_only(&self) -> bool

Reports whether copy is intentionally limited to the stream fallback.

§Returns

true when copy contract checks must use the stream fallback.

Source

fn list_prefix(&self, root: &Path, relative: &str) -> FixtureResult<String>

Maps a relative list prefix for the supplied root.

§Parameters
  • root - Logical directory passed to the list operation.
  • relative - Testkit-relative descendant selected by the contract.
§Returns

The provider-specific prefix expected by its list implementation.

§Errors

Returns FixtureError when the prefix cannot be represented for the supplied root.

Source

fn seed_file<'a>( &'a self, relative: &'a str, bytes: &'a [u8], ) -> FixtureFuture<'a, FixtureSupport<Path>>

Asynchronously seeds a complete file outside the operation under test.

§Parameters
  • relative - Testkit-relative path for the seeded file.
  • bytes - Exact content to publish.
§Returns

A future resolving to Supported(path) when seeding succeeds, or Unsupported when the fixture cannot prepare files out of band.

§Errors

The future returns FixtureError when provider-specific setup fails.

Source

fn read_file<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<Vec<u8>>>

Asynchronously observes a complete file outside the operation under test.

§Parameters
  • path - Logical path to observe.
§Returns

A future resolving to Supported(bytes) with complete content, or Unsupported when the fixture cannot observe files out of band.

§Errors

The future returns FixtureError when provider-specific observation fails.

Source

fn exists_out_of_band<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<bool>>

Asynchronously observes whether a resource exists out of band.

§Parameters
  • path - Resource to observe independently of the facade under test.
§Returns

A future resolving to Supported(true/false) when observable, or Unsupported when independent observation is unavailable.

§Errors

The future returns FixtureError when observation fails.

Source

fn write_file_out_of_band<'a>( &'a self, path: &'a Path, bytes: &'a [u8], ) -> FixtureFuture<'a, FixtureSupport<()>>

Asynchronously writes a complete resource through fixture setup.

§Parameters
  • path - Resource to seed independently of the facade under test.
  • bytes - Complete content to write.
§Returns

A future resolving to Supported(()) when setup succeeds, or Unsupported when out-of-band writing is unavailable.

§Errors

The future returns FixtureError when setup fails.

Source

fn resource_version<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<ResourceVersion>>

Asynchronously observes the current provider resource version.

§Parameters
  • path - Resource whose provider version is observed.
§Returns

A future resolving to the current version, or Unsupported when the fixture cannot independently obtain it.

§Errors

The future returns FixtureError when version observation fails.

Source

fn stale_resource_version<'a>( &'a self, path: &'a Path, ) -> FixtureFuture<'a, FixtureSupport<ResourceVersion>>

Asynchronously returns a valid version that cannot match the resource.

§Parameters
  • path - Resource whose current version the supplied token must not match.
§Returns

A future resolving to a valid stale version, or Unsupported when the fixture cannot produce one.

§Errors

The future returns FixtureError when producing or validating the version fails.

Source

fn checksum_failure_case<'a>( &'a self, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Path>>

Asynchronously supplies a resource whose checksum is invalid.

§Parameters
  • relative - Testkit-relative name for the corrupted resource.
§Returns

A future resolving to the prepared path, or Unsupported when the fixture cannot create a checksum-corrupt resource.

§Errors

The future returns FixtureError when preparation fails.

Source

fn seed_empty_directory<'a>( &'a self, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Path>>

Asynchronously seeds an empty directory or prefix.

§Parameters
  • relative - Testkit-relative name of the directory or prefix.
§Returns

A future resolving to its path, or Unsupported when independent seeding is unavailable.

§Errors

The future returns FixtureError when seeding fails.

Asynchronously seeds a symbolic link.

§Parameters
  • relative - Testkit-relative name for the symbolic link.
§Returns

A future resolving to the link path, or Unsupported when the fixture cannot seed symbolic links.

§Errors

The future returns FixtureError when seeding fails.

Source

fn copy_fast_path_case<'a>( &'a self, method: CopyMethod, ) -> FixtureFuture<'a, FixtureSupport<CopyFixtureCase>>

Supplies an asynchronously prepared native copy fast-path case.

§Parameters
  • method - Provider-native copy method the case must exercise.
§Returns

A future resolving to a case for that method, or Unsupported when the fixture cannot provide the native path. For Native, the case must be a single file with a distinct, independently confirmed absent target and an independently seeded source containing 1..=64 KiB. Return Unsupported when those premises cannot be guaranteed; a streamed result does not satisfy this request. Returned source and target paths are registered for cleanup immediately.

§Errors

The future returns FixtureError when case preparation fails.

Source

fn prepare_copy_cancellation<'a>( &'a self, stage: AsyncCopyCancellationStage, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Box<dyn CopyCancellationProbe>>>

Asynchronously prepares a stage-aware single-file cancellation probe.

A supported probe must also support independent read_file and exists_out_of_band observations for its source and destination. The source must contain a complete file and the destination must have a known initial state; otherwise return Unsupported.

§Parameters
  • stage - Provider-owned copy stage that must be held pending.
  • relative - Testkit-relative name used to isolate probe resources.
§Returns

A future resolving to a probe for the requested stage, or Unsupported when stage control or independent observations are unavailable.

§Errors

The future returns FixtureError when probe setup fails; setup errors must not be reported as Unsupported.

Source

fn prepare_write_cancellation<'a>( &'a self, stage: AsyncWriteCancellationStage, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Box<dyn WriteCancellationProbe>>>

Prepares a stage-aware whole-file write cancellation probe. A supported probe independently observes the target and reports bytes accepted by the provider writer. Return Unsupported when reliable stage acknowledgement or evidence is unavailable.

§Parameters
  • stage - Provider-owned write stage that must be held pending.
  • relative - Testkit-relative target name used to isolate the probe.
§Returns

A future resolving to a probe for the requested stage, or Unsupported when reliable stage control or independent evidence is unavailable.

§Errors

The future returns FixtureError when probe setup fails; setup errors must not be reported as Unsupported.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§