qubit-fs-testkit 0.9.2

Reusable provider contract checks for qubit-fs implementations
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Independent basic copy and operation execution evidence.

use qubit_fs as qfs;
use qubit_fs::copy::CopyFailureState;
use qubit_fs::copy::CopyMethod;
use qubit_fs::copy::CopyOptions;
use qubit_fs::error::FsErrorKind;
use qubit_fs::error::FsOperation;
use qubit_fs::metadata::FileSystemCapability;

use crate::AsyncFileSystemContractSuite;
use crate::ContractCheckId;
use crate::ContractCheckOutcome;
use crate::ContractFailure;
use crate::FixtureSupport;
use crate::internal::verify_condition;

impl AsyncFileSystemContractSuite<'_> {
    /// Executes one basic copy requirement using independently prepared
    /// contents. Native copy requires the Copy capability; Read and Write are
    /// needed only when the facade uses streaming fallback.
    ///
    /// The check may create source and target paths, execute asynchronous
    /// filesystem I/O, and read files to observe the copied contents. It
    /// records the resulting check outcome in the suite context.
    ///
    /// # Parameters
    ///
    /// * `id` - Catalog identifier selecting the basic or repeated-execution
    ///   copy requirement.
    ///
    /// # Errors
    ///
    /// Returns a [`ContractFailure`] if preparation, copy execution, expected
    /// capability rejection, operation state, statistics, or observed contents
    /// do not satisfy the selected contract.
    pub(super) async fn check_basic_copy(&mut self, id: ContractCheckId) -> Result<(), ContractFailure> {
        self.context.begin_check(id);
        let source_relative = self.context.relative_name("copy-source");
        let target_relative = self.context.relative_name("copy-target");
        let target = self
            .fixture
            .path(&target_relative)
            .map_err(|error| ContractFailure::with_source("copy target preparation failed", error).at(id))?;
        self.context.record_created(target.clone());
        if self.check_copy_capability(id, &source_relative, &target).await? {
            return Ok(());
        }
        let bytes = crate::internal::limit_probe_plan::bounded_payload(
            b"copy bytes",
            self.context.properties().limits().max_write_bytes(),
        );
        let Some(case) = self
            .prepare_basic_copy(id, &source_relative, &target_relative, bytes)
            .await?
        else {
            return Ok(());
        };
        let (source, target, options) = case.into_parts();
        self.context.record_created(target.clone());
        verify_condition(
            options == CopyOptions::file(),
            id,
            "basic copy preparation changed required options",
        )?;
        self.context.record_created(source.clone());
        verify_condition(source != target, id, "copy source and target alias")?;
        if !self
            .verify_copy_contents(
                id,
                &source,
                bytes,
                "copy source observation failed",
                "copy source evidence is unavailable or differs",
            )
            .await?
        {
            return Ok(());
        }
        self.execute_basic_copy(id, source, target, bytes).await
    }

    /// Handles the capability branch before any copy input is prepared.
    ///
    /// # Parameters
    ///
    /// * `id` - Catalog identifier for the copy check.
    /// * `source_relative` - Fixture-relative name for the source path.
    /// * `target` - Prepared target path used to probe capability rejection.
    ///
    /// # Returns
    ///
    /// Returns `true` when missing capabilities make the check complete or
    /// inapplicable, and `false` when copy preparation may proceed.
    ///
    /// # Errors
    ///
    /// Returns a [`ContractFailure`] if the expected capability rejection
    /// cannot be observed or has inconsistent error context.
    async fn check_copy_capability(
        &mut self,
        id: ContractCheckId,
        source_relative: &str,
        target: &qfs::path::Path,
    ) -> Result<bool, ContractFailure> {
        if !self.capable(FileSystemCapability::Copy) {
            let required = [
                FileSystemCapability::Read,
                FileSystemCapability::Write,
                FileSystemCapability::Copy,
            ]
            .into_iter()
            .find(|capability| !self.capable(*capability))
            .expect("Copy capability is missing");
            if id != ContractCheckId::CopyBasic {
                self.context.record_check(
                    id,
                    Some(FileSystemCapability::Copy),
                    ContractCheckOutcome::NotApplicable {
                        reason: "copy prerequisites are unavailable".to_owned(),
                    },
                );
                return Ok(true);
            }
            let source = self
                .fixture
                .path(source_relative)
                .map_err(|error| ContractFailure::with_source("copy source path preparation failed", error).at(id))?;
            let (failure, retained_operation) =
                match self
                    .fixture
                    .file_system()
                    .begin_copy(source.clone(), target.clone(), CopyOptions::file())
                {
                    Err(error) => (error, None),
                    Ok(mut operation) => match operation.execute().await {
                        Err(error) => (error, Some(operation)),
                        Ok(_) => {
                            return Err(ContractFailure::message_only("unsupported copy succeeded").at(id));
                        }
                    },
                };
            let path = if required == FileSystemCapability::Write {
                target
            } else {
                &source
            };
            let error = failure.error();
            let capability_rejection_matches = match error.kind() {
                FsErrorKind::UnsupportedCapability => error.required_capability() == Some(required),
                FsErrorKind::RequirementNotMet => error.required_capability().is_none(),
                _ => false,
            };
            let path_matches = match error.kind() {
                FsErrorKind::UnsupportedCapability => error.path() == Some(path),
                FsErrorKind::RequirementNotMet => error.path() == Some(&source),
                _ => false,
            };
            if !capability_rejection_matches
                || error.operation() != FsOperation::Copy
                || !path_matches
                || error.target() != Some(target)
                || error.provider() != Some(self.context.properties().info().provider_id())
                || failure.state() != CopyFailureState::Unchanged
            {
                return Err(ContractFailure::with_owned_source(
                    "copy rejection context differs",
                    crate::ContractAsyncCopyFailure::new(failure, retained_operation),
                )
                .at(id));
            }
            self.context.record_check(
                id,
                Some(FileSystemCapability::Copy),
                ContractCheckOutcome::RejectedAsExpected,
            );
            return Ok(true);
        }
        Ok(false)
    }

    /// Prepares the independent source and target state for one copy check.
    ///
    /// # Parameters
    ///
    /// * `id` - Catalog identifier selecting the copy scenario to prepare.
    /// * `source_relative` - Fixture-relative name for the source file.
    /// * `target_relative` - Fixture-relative name for the target file.
    /// * `bytes` - Expected source contents supplied to the fixture.
    ///
    /// # Returns
    ///
    /// Returns the prepared case when the fixture can provide it, or `None`
    /// after recording an unavailable or inapplicable preparation.
    ///
    /// # Errors
    ///
    /// Returns a [`ContractFailure`] if the scenario is absent from the catalog
    /// or fixture preparation fails.
    async fn prepare_basic_copy(
        &mut self,
        id: ContractCheckId,
        source_relative: &str,
        target_relative: &str,
        bytes: &[u8],
    ) -> Result<Option<crate::CopyFixtureCase>, ContractFailure> {
        let scenario =
            crate::internal::check_catalog::required_copy_scenario(id, "copy preparation missing from catalog")?;
        let prepared = self
            .fixture
            .prepare_copy(scenario, source_relative, target_relative, bytes)
            .await
            .map_err(|error| ContractFailure::with_source("copy source preparation failed", error).at(id))?;
        let case = match prepared {
            crate::FixturePreparation::Ready(case) => case,
            crate::FixturePreparation::Unavailable { reason } | crate::FixturePreparation::NotApplicable { reason } => {
                self.context.record_check(
                    id,
                    Some(FileSystemCapability::Copy),
                    ContractCheckOutcome::Unverified { reason },
                );
                return Ok(None);
            }
        };
        Ok(Some(case))
    }

    /// Executes an admitted copy and verifies its outcome and retained state.
    ///
    /// # Parameters
    ///
    /// * `id` - Catalog identifier for the copy contract being checked.
    /// * `source` - Prepared source path to copy.
    /// * `target` - Prepared destination path.
    /// * `bytes` - Expected contents and byte count for the copy.
    ///
    /// # Errors
    ///
    /// Returns a [`ContractFailure`] if admission or execution fails, the
    /// operation state or statistics differ, or observed contents are
    /// incorrect.
    async fn execute_basic_copy(
        &mut self,
        id: ContractCheckId,
        source: qfs::path::Path,
        target: qfs::path::Path,
        bytes: &[u8],
    ) -> Result<(), ContractFailure> {
        let mut operation = self
            .fixture
            .file_system()
            .begin_copy(source.clone(), target.clone(), CopyOptions::file())
            .map_err(|error| {
                ContractFailure::with_owned_source(
                    "copy admission failed",
                    crate::ContractAsyncCopyFailure::new(error, None),
                )
                .at(id)
            })?;
        drop(operation.execute());
        verify_condition(
            operation.state() == qfs::copy::AsyncCopyOperationState::Ready && !operation.has_recovery(),
            id,
            "unpolled copy changed operation state",
        )?;
        let outcome = match operation.execute().await {
            Ok(outcome) => outcome,
            Err(error) => {
                return Err(ContractFailure::with_owned_source(
                    "copy execution failed",
                    crate::ContractAsyncCopyFailure::new(error, Some(operation)),
                )
                .at(id));
            }
        };
        verify_condition(
            outcome.stats().bytes == bytes.len() as u64 && outcome.stats().files + outcome.stats().objects == 1,
            id,
            "copy statistics differ",
        )?;
        verify_condition(
            outcome.used_fallback() == (outcome.method() == CopyMethod::Streamed),
            id,
            "copy method and fallback evidence disagree",
        )?;
        verify_condition(
            !self.fixture.copy_fallback_only() || outcome.method() == CopyMethod::Streamed,
            id,
            "fallback-only copy reported a native method",
        )?;
        verify_condition(
            operation.state() == qfs::copy::AsyncCopyOperationState::Completed,
            id,
            "successful copy did not complete the operation",
        )?;
        if id == ContractCheckId::CopyRepeatedExecute {
            for path in [&source, &target] {
                if !self
                    .verify_copy_contents(
                        id,
                        path,
                        bytes,
                        "initial copy observation failed",
                        "initial copy contents differ or evidence is unavailable",
                    )
                    .await?
                {
                    return Ok(());
                }
            }
            let repeated = match operation.execute().await {
                Err(error) => error,
                Ok(_) => return Err(ContractFailure::message_only("copy executed twice").at(id)),
            };
            if repeated.error().kind() != FsErrorKind::InvalidState
                || repeated.state() != CopyFailureState::Published
                || repeated.partial_stats() != outcome.stats()
            {
                return Err(ContractFailure::with_owned_source(
                    "repeated copy lost completed facts",
                    crate::ContractAsyncCopyFailure::new(repeated, Some(operation)),
                )
                .at(id));
            }
            verify_condition(
                operation.state() == qfs::copy::AsyncCopyOperationState::Completed,
                id,
                "repeat changed completed copy state",
            )?;
        }
        for path in [&source, &target] {
            if !self
                .verify_copy_contents(
                    id,
                    path,
                    bytes,
                    "copy contents observation failed",
                    "copy source or target contents differ or evidence is unavailable",
                )
                .await?
            {
                return Ok(());
            }
        }
        self.context
            .record_check(id, Some(FileSystemCapability::Copy), ContractCheckOutcome::Passed);
        Ok(())
    }

    /// Reads one path and verifies that the fixture exposes the expected bytes.
    ///
    /// The asynchronous read is an observation side effect on the fixture and
    /// converts provider errors into failures associated with the active check.
    ///
    /// # Parameters
    ///
    /// * `id` - Catalog identifier for the active copy check.
    /// * `path` - Fixture path whose contents are observed.
    /// * `expected` - Bytes that the fixture is expected to return.
    /// * `read_error` - Failure message used when the fixture read fails.
    /// * `mismatch` - Failure message used when observed bytes do not match.
    ///
    /// # Errors
    ///
    /// Returns a [`ContractFailure`] if the read fails or the observed contents
    /// are unsupported or differ from `expected`.
    async fn verify_copy_contents(
        &mut self,
        id: ContractCheckId,
        path: &qfs::path::Path,
        expected: &[u8],
        read_error: &'static str,
        mismatch: &'static str,
    ) -> Result<bool, ContractFailure> {
        let observed = self
            .fixture
            .read_file(path)
            .await
            .map_err(|error| ContractFailure::with_source(read_error, error).at(id))?;
        if matches!(observed, FixtureSupport::Unsupported) {
            self.context.record_check(
                id,
                Some(FileSystemCapability::Copy),
                ContractCheckOutcome::Unverified {
                    reason: format!("fixture.read_file cannot confirm contents: {read_error}"),
                },
            );
            return Ok(false);
        }
        verify_condition(
            matches!(observed, FixtureSupport::Supported(actual) if actual == expected),
            id,
            mismatch,
        )?;
        Ok(true)
    }
}