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.
// =============================================================================
//! Pure request and byte expectations shared by both read drivers.

use qubit_fs::error::FsErrorKind;
use qubit_fs::metadata::FileSystemLimit;
use qubit_fs::metadata::ResourceVersion;
use qubit_fs::read::ChecksumPolicy;
use qubit_fs::read::ReadOptions;

use crate::ReadScenario;

/// Stable content prepared independently for positive reads.
pub(crate) const CONTENT: &[u8] = b"read contract bytes";

/// Builds requests without accepting weaker expectations from a fixture.
///
/// # Parameters
///
/// - `scenario`: the contract behavior to request.
/// - `limit`: the provider's maximum read size, used to bound range requests.
/// - `version`: the independently observed resource version for conditional
///   requests.
pub(crate) fn options(scenario: ReadScenario, limit: FileSystemLimit, version: ResourceVersion) -> ReadOptions {
    match scenario {
        ReadScenario::Basic | ReadScenario::RangeLimit => ReadOptions::default(),
        ReadScenario::Range => {
            let (offset, length) = window(limit);
            ReadOptions::default()
                .with_offset(Some(offset))
                .with_length(Some(length))
        }
        ReadScenario::IfMatchCurrent | ReadScenario::IfMatchStale => {
            ReadOptions::default().with_if_match(Some(version))
        }
        ReadScenario::IfNoneMatchCurrent | ReadScenario::IfNoneMatchStale => {
            ReadOptions::default().with_if_none_match(Some(version))
        }
        ReadScenario::Checksum | ReadScenario::ChecksumCorruption => {
            ReadOptions::default().with_checksum(ChecksumPolicy::Required)
        }
    }
}

/// Returns the exact independently seeded bytes required from a positive read.
///
/// # Parameters
///
/// - `scenario`: the contract behavior whose content is expected.
/// - `limit`: the provider's maximum read size.
///
/// # Returns
///
/// The entire seed for ordinary reads, or the requested range of the seed.
#[must_use]
#[inline]
pub(crate) fn bytes(scenario: ReadScenario, limit: FileSystemLimit) -> &'static [u8] {
    if scenario == ReadScenario::Range {
        let (offset, length) = window(limit);
        &CONTENT[offset as usize..(offset + length) as usize]
    } else {
        CONTENT
    }
}

/// Distinguishes deliberate rejection scenarios from successful reads.
///
/// # Parameters
///
/// - `scenario`: the contract behavior being checked.
///
/// # Returns
///
/// `Some` with the expected error kind for rejection scenarios, or `None` for
/// scenarios expected to succeed.
#[inline]
pub(crate) const fn rejection(scenario: ReadScenario) -> Option<FsErrorKind> {
    match scenario {
        ReadScenario::IfMatchStale | ReadScenario::IfNoneMatchCurrent => Some(FsErrorKind::PreconditionFailed),
        ReadScenario::ChecksumCorruption => Some(FsErrorKind::DataCorruption),
        _ => None,
    }
}

/// Reports whether this request needs independently observed version evidence.
///
/// # Parameters
///
/// - `scenario`: the contract behavior being checked.
///
/// # Returns
///
/// `true` when the request uses a current or stale resource version.
#[must_use]
#[inline]
pub(crate) const fn uses_version(scenario: ReadScenario) -> bool {
    matches!(
        scenario,
        ReadScenario::IfMatchCurrent
            | ReadScenario::IfMatchStale
            | ReadScenario::IfNoneMatchCurrent
            | ReadScenario::IfNoneMatchStale
    )
}

/// Reports whether the request excludes or requires a deliberately stale
/// version.
///
/// # Parameters
///
/// - `scenario`: the contract behavior being checked.
///
/// # Returns
///
/// `true` when the request uses a stale resource version.
#[must_use]
#[inline]
pub(crate) const fn uses_stale(scenario: ReadScenario) -> bool {
    matches!(scenario, ReadScenario::IfMatchStale | ReadScenario::IfNoneMatchStale)
}

/// Bounds the range by provider limits and the known seed length, using an
/// interior offset for every non-empty range so small limits still verify
/// correct positioning.
///
/// # Parameters
///
/// - `limit`: the provider's maximum read size.
///
/// # Returns
///
/// The offset and length of the range that fits both limits.
#[must_use]
#[inline]
pub(crate) fn window(limit: FileSystemLimit) -> (u64, u64) {
    let length = limit.maximum().map_or(8, |maximum| maximum.min(8));
    (if length == 0 { 0 } else { 5 }, length)
}

/// Plans a legal range request together with sufficient and insufficient
/// caller byte budgets for that exact window.
///
/// # Parameters
///
/// - `limit`: The provider's maximum read-range length.
///
/// # Returns
///
/// The selected offset, length, accepted budget, and optional rejected budget.
#[must_use]
pub(crate) fn window_budget_plan(limit: FileSystemLimit) -> (u64, u64, usize, Option<usize>) {
    let (offset, length) = window(limit);
    let accepted = usize::try_from(length).expect("bounded read window fits usize");
    (offset, length, accepted, accepted.checked_sub(1))
}