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§
Sourcefn file_system(&self) -> &AsyncFileSystem
fn file_system(&self) -> &AsyncFileSystem
Returns the concrete asynchronous filesystem facade under test.
§Returns
The isolated asynchronous facade owned by this fixture.
Sourcefn path(&self, relative: &str) -> FixtureResult<Path>
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.
Sourcefn teardown(&self) -> FixtureFuture<'_, ()>
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§
Sourcefn random_access_operation(&self) -> FixtureSupport<bool>
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.
Sourcefn replace_random_access_path<'a>(
&'a self,
path: &'a Path,
bytes: &'a [u8],
) -> FixtureFuture<'a, FixtureSupport<()>>
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.
Sourcefn arm_random_access_pending_read(
&self,
path: &Path,
) -> FixtureResult<FixtureSupport<()>>
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.
Sourcefn disarm_random_access_pending_read(&self, path: &Path) -> FixtureResult<()>
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.
Sourcefn random_access_pending_read_reached(
&self,
path: &Path,
) -> FixtureResult<FixtureSupport<bool>>
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.
Sourcefn snapshot_namespace_paths(
&self,
) -> FixtureFuture<'_, FixtureSupport<Vec<Path>>>
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.
Sourcefn prepare_copy<'a>(
&'a self,
scenario: CopyScenario,
source_relative: &'a str,
target_relative: &'a str,
bytes: &'a [u8],
) -> FixtureFuture<'a, FixturePreparation<CopyFixtureCase>>
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.
Sourcefn prepare_delete<'a>(
&'a self,
_scenario: DeleteScenario,
relative: &'a str,
bytes: &'a [u8],
) -> FixtureFuture<'a, FixturePreparation<Path>>
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.
Sourcefn prepare_read<'a>(
&'a self,
scenario: ReadScenario,
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>>
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.
Sourcefn prepare_write<'a>(
&'a self,
scenario: WriteScenario,
relative: &'a str,
bytes: &'a [u8],
) -> FixtureFuture<'a, FixturePreparation<WriteFixtureCase>>
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.
Sourcefn copy_fallback_only(&self) -> bool
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.
Sourcefn list_prefix(&self, root: &Path, relative: &str) -> FixtureResult<String>
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.
Sourcefn seed_file<'a>(
&'a self,
relative: &'a str,
bytes: &'a [u8],
) -> FixtureFuture<'a, FixtureSupport<Path>>
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.
Sourcefn read_file<'a>(
&'a self,
path: &'a Path,
) -> FixtureFuture<'a, FixtureSupport<Vec<u8>>>
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.
Sourcefn exists_out_of_band<'a>(
&'a self,
path: &'a Path,
) -> FixtureFuture<'a, FixtureSupport<bool>>
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.
Sourcefn write_file_out_of_band<'a>(
&'a self,
path: &'a Path,
bytes: &'a [u8],
) -> FixtureFuture<'a, FixtureSupport<()>>
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.
Sourcefn resource_version<'a>(
&'a self,
path: &'a Path,
) -> FixtureFuture<'a, FixtureSupport<ResourceVersion>>
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.
Sourcefn stale_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>>
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.
Sourcefn checksum_failure_case<'a>(
&'a self,
relative: &'a str,
) -> FixtureFuture<'a, FixtureSupport<Path>>
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.
Sourcefn seed_empty_directory<'a>(
&'a self,
relative: &'a str,
) -> FixtureFuture<'a, FixtureSupport<Path>>
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.
Sourcefn seed_symlink<'a>(
&'a self,
relative: &'a str,
) -> FixtureFuture<'a, FixtureSupport<Path>>
fn seed_symlink<'a>( &'a self, relative: &'a str, ) -> FixtureFuture<'a, FixtureSupport<Path>>
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.
Sourcefn copy_fast_path_case<'a>(
&'a self,
method: CopyMethod,
) -> FixtureFuture<'a, FixtureSupport<CopyFixtureCase>>
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.
Sourcefn prepare_copy_cancellation<'a>(
&'a self,
stage: AsyncCopyCancellationStage,
relative: &'a str,
) -> FixtureFuture<'a, FixtureSupport<Box<dyn CopyCancellationProbe>>>
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.
Sourcefn prepare_write_cancellation<'a>(
&'a self,
stage: AsyncWriteCancellationStage,
relative: &'a str,
) -> FixtureFuture<'a, FixtureSupport<Box<dyn WriteCancellationProbe>>>
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".