qubit-fs-testkit 0.9.2

Reusable provider contract checks for qubit-fs implementations
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Independently observed server-side copy requirements.

use qubit_fs::copy::CopyConflictPolicy;
use qubit_fs::copy::CopyFailureState;
use qubit_fs::copy::CopyMethod;
use qubit_fs::copy::CopyMode;
use qubit_fs::copy::CopyOptions;
use qubit_fs::copy::ServerSidePreference;
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::FixturePreparation;
use crate::FixtureSupport;
use crate::internal::verify_condition;

impl AsyncFileSystemContractSuite<'_> {
    /// Verifies that a copy requiring server-side execution uses that method,
    /// or that an unavailable capability is rejected with the expected
    /// context. If fixture preparation or independent observation is
    /// unavailable, records the check as unverified instead of treating it as
    /// a pass or failure.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when the requirement is verified, is not applicable,
    /// or cannot be independently verified and is recorded as unverified.
    ///
    /// # Errors
    ///
    /// Returns a [`ContractFailure`] if fixture evidence contradicts the
    /// requirement, an independent observation fails, or the required
    /// capability is incorrectly accepted or rejected.
    pub(super) async fn check_server_side_copy(&mut self) -> Result<(), ContractFailure> {
        let id = ContractCheckId::CopyServerSide;
        let capability = FileSystemCapability::ServerSideCopy;
        self.context.begin_check(id);
        if !self.capable(FileSystemCapability::Copy) {
            self.context.record_check(
                id,
                Some(capability),
                ContractCheckOutcome::NotApplicable {
                    reason: "Copy capability is unavailable".to_owned(),
                },
            );
            return Ok(());
        }
        let source_relative = self.context.relative_name("server-side-source");
        let target_relative = self.context.relative_name("server-side-target");
        if !self.capable(capability) {
            let source = self
                .fixture
                .path(&source_relative)
                .map_err(|error| ContractFailure::with_source("server-side source path failed", error).at(id))?;
            let target = self
                .fixture
                .path(&target_relative)
                .map_err(|error| ContractFailure::with_source("server-side target path failed", error).at(id))?;
            self.context.record_created(target.clone());
            let options = CopyOptions::file().with_server_side(ServerSidePreference::Require);
            let failure = match crate::internal::execute_copy::execute_copy(
                self.fixture.file_system(),
                source.clone(),
                target.clone(),
                options,
            )
            .await
            {
                Err(failure) => failure,
                Ok(_) => {
                    return Err(ContractFailure::message_only("unavailable server-side requirement succeeded").at(id));
                }
            };
            let error = failure.error();
            if error.kind() != FsErrorKind::RequirementNotMet
                || error.operation() != FsOperation::Copy
                || error.required_capability() != Some(capability)
                || error.path() != Some(&source)
                || error.target() != Some(&target)
                || error.provider() != Some(self.context.properties().info().provider_id())
                || failure.failure().state() != CopyFailureState::Unchanged
            {
                return Err(
                    ContractFailure::with_owned_source("server-side rejection context differs", failure).at(id),
                );
            }
            self.context
                .record_check(id, Some(capability), ContractCheckOutcome::RejectedAsExpected);
            return Ok(());
        }
        let scenario =
            crate::internal::check_catalog::required_copy_scenario(id, "server-side scenario absent from catalog")?;
        let prepared = self
            .fixture
            .prepare_copy(scenario, &source_relative, &target_relative, b"server-side")
            .await
            .map_err(|error| ContractFailure::with_source("server-side preparation failed", error).at(id))?;
        let case = match prepared {
            FixturePreparation::Ready(case) => case,
            FixturePreparation::Unavailable { reason } | FixturePreparation::NotApplicable { reason } => {
                self.context
                    .record_check(id, Some(capability), ContractCheckOutcome::Unverified { reason });
                return Ok(());
            }
        };
        let (source, target, options) = case.into_parts();
        self.context.record_created(source.clone());
        self.context.record_created(target.clone());
        verify_condition(
            source != target
                && options.mode() == CopyMode::File
                && options.server_side() == ServerSidePreference::Require
                && options.conflict() == CopyConflictPolicy::Fail,
            id,
            "server-side preparation changed required request semantics",
        )?;
        let snapshot = match self.fixture.read_file(&source).await.map_err(|error| {
            ContractFailure::with_source("server-side initial source observation failed", error).at(id)
        })? {
            FixtureSupport::Supported(bytes) => bytes,
            FixtureSupport::Unsupported => {
                self.context.record_check(
                    id,
                    Some(capability),
                    ContractCheckOutcome::Unverified {
                        reason: "independent server-side source observation unavailable".to_owned(),
                    },
                );
                return Ok(());
            }
        };
        verify_condition(
            !snapshot.is_empty() && snapshot.len() <= crate::internal::limit_probe_plan::MAX_PROBE_BYTES as usize,
            id,
            "server-side fixture source must contain 1..=64 KiB",
        )?;
        let before = self.fixture.exists_out_of_band(&target).await.map_err(|error| {
            ContractFailure::with_source("server-side destination absence observation failed", error).at(id)
        })?;
        let FixtureSupport::Supported(exists) = before else {
            self.context.record_check(
                id,
                Some(capability),
                ContractCheckOutcome::Unverified {
                    reason: "independent server-side destination absence observation unavailable".to_owned(),
                },
            );
            return Ok(());
        };
        verify_condition(!exists, id, "server-side destination already exists")?;
        let outcome = crate::internal::execute_copy::execute_copy(
            self.fixture.file_system(),
            source.clone(),
            target.clone(),
            options,
        )
        .await
        .map_err(|error| ContractFailure::with_owned_source("server-side execution failed", error).at(id))?;
        verify_condition(
            outcome.method() == CopyMethod::ServerSide && !outcome.used_fallback(),
            id,
            "copy did not provide the required server-side method",
        )?;
        verify_condition(
            outcome.stats().bytes == snapshot.len() as u64 && outcome.stats().files + outcome.stats().objects == 1,
            id,
            "server-side copy statistics differ",
        )?;
        for path in [&source, &target] {
            let observed = self.fixture.read_file(path).await.map_err(|error| {
                ContractFailure::with_source("server-side final contents observation failed", error).at(id)
            })?;
            match observed {
                FixtureSupport::Supported(actual) => verify_condition(
                    actual == snapshot,
                    id,
                    "server-side copy changed source or published incorrect target bytes",
                )?,
                FixtureSupport::Unsupported => {
                    self.context.record_check(
                        id,
                        Some(capability),
                        ContractCheckOutcome::Unverified {
                            reason: "independent server-side final contents observation unavailable".to_owned(),
                        },
                    );
                    return Ok(());
                }
            }
        }
        self.context
            .record_check(id, Some(capability), ContractCheckOutcome::Passed);
        Ok(())
    }
}