qubit-fs 0.3.3

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Shared validation for provider directory entries.

use crate::directory::ListScope;
use crate::error::FsError;
use crate::error::FsErrorKind;
use crate::error::FsOperation;
use crate::error::FsResult;
use crate::metadata::DirEntry;
use crate::metadata::FileSystemLimits;
use crate::path::Path;
use crate::path::PathConstraints;
use crate::path::PathSemantics;

/// Validates provider-controlled identity fields before applying list policy.
///
/// # Parameters
///
/// - `entry`: Provider-returned directory entry being validated or selected.
/// - `scope`: Requested directory or namespace listing scope.
/// - `semantics`: Path interpretation rules declared by the provider.
/// - `limits`: Provider resource limits applied to the operation.
/// - `constraints`: Provider path constraints applied to returned entries.
///
/// # Errors
///
/// Returns a provider-contract violation when the entry uses different path
/// semantics, exceeds filesystem path limits, has an inconsistent name or
/// metadata kind, or lies outside the requested root.
pub(crate) fn validate_entry(
    entry: &DirEntry,
    scope: &ListScope,
    semantics: PathSemantics,
    limits: FileSystemLimits,
    constraints: &PathConstraints,
) -> FsResult<()> {
    if entry.path.semantics() != semantics {
        return Err(contract_error(
            &entry.path,
            "provider returned a directory entry with foreign path semantics",
        ));
    }
    if constraints.validate(&entry.path).is_err() {
        return Err(contract_error(
            &entry.path,
            "provider returned a directory entry with a disallowed path form",
        ));
    }
    if limits
        .validate_path(&entry.path, semantics, FsOperation::ValidateProviderOutcome)
        .is_err()
    {
        return Err(contract_error(
            &entry.path,
            "provider returned a directory entry outside filesystem path limits",
        ));
    }
    let expected_name = entry.path.file_name().unwrap_or_default();
    if entry.name != expected_name {
        return Err(contract_error(
            &entry.path,
            "provider returned a directory entry with an inconsistent name",
        ));
    }
    if entry
        .metadata
        .as_ref()
        .is_some_and(|metadata| metadata.kind() != &entry.kind)
    {
        return Err(contract_error(
            &entry.path,
            "provider returned directory metadata with a different kind",
        ));
    }
    if crate::directory::internal::relative_path(scope, &entry.path, semantics).is_none() {
        return Err(contract_error(
            &entry.path,
            "provider returned directory entry outside requested root",
        ));
    }
    Ok(())
}

/// Builds a stable provider-contract error for list option filtering.
///
/// # Parameters
///
/// - `scope`: Requested directory or namespace listing scope.
/// - `message`: Diagnostic message for the constructed filesystem error.
pub(crate) fn option_error(scope: &ListScope, message: &'static str) -> FsError {
    let error = FsError::new(
        FsErrorKind::ProviderContractViolation,
        FsOperation::ValidateProviderOutcome,
        message,
    );
    match scope.path() {
        Some(path) => error.with_path(path.clone()),
        None => error,
    }
}

/// Returns the entry path relative to `root` when it remains in the root.
///
/// # Parameters
///
/// - `root`: Requested list root used to calculate an entry-relative path.
/// - `entry`: Provider-returned directory entry being validated or selected.
fn relative_path<'a>(root: &Path, entry: &'a Path) -> Option<&'a str> {
    if root == entry {
        Some("")
    } else if root.as_str() == "/" {
        entry.as_str().strip_prefix('/')
    } else {
        let remainder = entry.as_str().strip_prefix(root.as_str())?;
        if root.as_str().ends_with('/') {
            Some(remainder)
        } else {
            remainder.strip_prefix('/')
        }
    }
}

/// Returns the descendant depth of `entry` below `root`.
///
/// Returns `Some(0)` when both paths identify the root, `Some(n)` for a
/// descendant `n` components below it, and `None` when `entry` is outside the
/// root.
///
/// # Parameters
///
/// - `root`: Requested list root used to calculate an entry-relative path.
/// - `entry`: Provider-returned directory entry being validated or selected.
pub(crate) fn entry_depth(root: &Path, entry: &Path) -> Option<usize> {
    let relative = relative_path(root, entry)?;
    if relative.is_empty() {
        Some(0)
    } else {
        Some(relative.split('/').count())
    }
}

/// Builds a provider-contract error for one invalid entry identity.
///
/// # Parameters
///
/// - `path`: Logical path of the resource involved in this operation.
/// - `message`: Diagnostic message for the constructed filesystem error.
fn contract_error(path: &Path, message: &'static str) -> FsError {
    FsError::new(
        FsErrorKind::ProviderContractViolation,
        FsOperation::ValidateProviderOutcome,
        message,
    )
    .with_path(path.clone())
}