qubit-fs 0.3.2

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.
// =============================================================================
//! Write operation options.

use crate::error::FsError;
use crate::error::FsErrorKind;
use crate::error::FsOperation;
use crate::metadata::AtomicityRequirement;
use crate::metadata::Checksum;
use crate::metadata::DurabilityRequirement;
use crate::metadata::FileSystemCapabilities;
use crate::metadata::FileSystemCapability;
use crate::metadata::NonSensitiveMetadata;
use crate::metadata::UserMetadata;
use crate::write::WriteDisposition;
use crate::write::WritePrecondition;

/// Options controlling a write operation.
///
/// By default, `create_parent` is `false`, `disposition` is
/// [`WriteDisposition::CreateOrReplace`], `atomicity` is
/// [`AtomicityRequirement::Preferred`], `durability` is
/// [`DurabilityRequirement::NotRequired`], and `precondition` is
/// [`WritePrecondition::None`]. Content type and checksum are `None`, and user
/// metadata is empty. These are request policies; provider support and
/// successful completion are reported separately.
///
/// # Examples
/// ```rust
/// use qubit_fs::write::WriteOptions;
/// use qubit_fs::metadata::AtomicityRequirement;
/// use qubit_fs::metadata::FileSystemCapabilities;
/// let options = WriteOptions::default().with_atomicity(AtomicityRequirement::Required);
/// assert!(options.validate_against(FileSystemCapabilities::new()).is_err());
/// ```
///
/// Refuse to replace an existing destination:
/// ```rust
/// use qubit_fs::write::WriteDisposition;
/// use qubit_fs::write::WriteOptions;
///
/// let options = WriteOptions::default()
///     .with_disposition(WriteDisposition::CreateNew);
/// assert_eq!(options.disposition(), WriteDisposition::CreateNew);
/// ```
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq)]
pub struct WriteOptions {
    /// Whether missing parent directories should be created.
    create_parent: bool,
    /// How an existing destination is treated.
    disposition: WriteDisposition,
    /// Required atomicity of destination publication.
    atomicity: AtomicityRequirement,
    /// Required durability of completed publication.
    durability: DurabilityRequirement,
    /// Version precondition applied to the destination.
    precondition: WritePrecondition,
    /// Optional content type.
    content_type: Option<String>,
    /// User-defined metadata with validated non-sensitive structural keys.
    user_metadata: NonSensitiveMetadata,
    /// Optional expected content checksum.
    checksum: Option<Checksum>,
}

impl Default for WriteOptions {
    /// Uses conservative defaults: no parent creation and replacement behavior.
    #[inline]
    fn default() -> Self {
        Self {
            create_parent: false,
            disposition: WriteDisposition::default(),
            atomicity: AtomicityRequirement::default(),
            durability: DurabilityRequirement::default(),
            precondition: WritePrecondition::default(),
            content_type: None,
            user_metadata: NonSensitiveMetadata::new(),
            checksum: None,
        }
    }
}

impl WriteOptions {
    /// Returns whether missing parent directories are created.
    #[inline]
    #[must_use]
    pub const fn create_parent(&self) -> bool {
        self.create_parent
    }

    /// Returns the destination disposition.
    #[inline]
    #[must_use]
    pub const fn disposition(&self) -> WriteDisposition {
        self.disposition
    }

    /// Returns the atomicity requirement.
    #[inline]
    #[must_use]
    pub const fn atomicity(&self) -> AtomicityRequirement {
        self.atomicity
    }

    /// Returns the completed-publication durability requirement.
    #[inline]
    #[must_use]
    pub const fn durability(&self) -> DurabilityRequirement {
        self.durability
    }

    /// Returns the version precondition.
    #[inline]
    #[must_use]
    pub const fn precondition(&self) -> &WritePrecondition {
        &self.precondition
    }

    /// Returns the optional content type.
    #[inline]
    pub fn content_type(&self) -> Option<&str> {
        self.content_type.as_deref()
    }

    /// Returns the user metadata attached to this write.
    #[inline]
    #[must_use]
    pub const fn user_metadata(&self) -> &NonSensitiveMetadata {
        &self.user_metadata
    }

    /// Returns the optional expected checksum.
    #[inline]
    pub const fn checksum(&self) -> Option<&Checksum> {
        self.checksum.as_ref()
    }

    /// Returns a copy with parent creation replaced.
    /// # Parameters
    /// - `create`: Whether parent directories should be created.
    #[inline]
    #[must_use]
    pub const fn with_create_parent(mut self, create: bool) -> Self {
        self.create_parent = create;
        self
    }

    /// Returns a copy with the destination disposition replaced.
    /// # Parameters
    /// - `disposition`: Destination creation or replacement behavior.
    #[inline]
    #[must_use]
    pub const fn with_disposition(mut self, disposition: WriteDisposition) -> Self {
        self.disposition = disposition;
        self
    }

    /// Returns a copy with the atomicity requirement replaced.
    /// # Parameters
    /// - `atomicity`: Required atomic publication behavior.
    #[inline]
    #[must_use]
    pub const fn with_atomicity(mut self, atomicity: AtomicityRequirement) -> Self {
        self.atomicity = atomicity;
        self
    }

    /// Returns a copy with the durability requirement replaced.
    /// # Parameters
    /// - `durability`: Required durability after publication.
    #[inline]
    #[must_use]
    pub const fn with_durability(mut self, durability: DurabilityRequirement) -> Self {
        self.durability = durability;
        self
    }

    /// Returns a copy with the version precondition replaced.
    /// # Parameters
    /// - `precondition`: Version condition required before publication.
    #[inline]
    #[must_use]
    pub fn with_precondition(mut self, precondition: WritePrecondition) -> Self {
        self.precondition = precondition;
        self
    }

    /// Returns a copy with the content type replaced.
    /// # Parameters
    /// - `content_type`: Optional content type associated with the new file.
    #[inline]
    #[must_use]
    pub fn with_content_type(mut self, content_type: Option<String>) -> Self {
        self.content_type = content_type;
        self
    }

    /// Returns a copy with the expected checksum replaced.
    /// # Parameters
    /// - `checksum`: Optional expected checksum for the written content.
    #[inline]
    #[must_use]
    pub fn with_checksum(mut self, checksum: Option<Checksum>) -> Self {
        self.checksum = checksum;
        self
    }

    /// Replaces user-defined metadata that has already passed key validation.
    /// # Parameters
    /// - `metadata`: Validated user metadata associated with the new file.
    #[inline]
    #[must_use]
    pub fn with_user_metadata(mut self, metadata: UserMetadata) -> Self {
        self.user_metadata = NonSensitiveMetadata::from(metadata);
        self
    }

    /// Validates combinations that have no coherent provider interpretation.
    ///
    /// # Errors
    /// Returns [`FsErrorKind::InvalidOptions`] before a writer is opened when
    /// append is combined with atomic publication or a version precondition,
    /// or when create-new is combined with an existing-version requirement.
    #[inline]
    pub fn validate(&self) -> Result<(), FsError> {
        if self.disposition == WriteDisposition::Append
            && (self.atomicity == AtomicityRequirement::Required || self.precondition != WritePrecondition::None)
        {
            return Err(FsError::new(
                FsErrorKind::InvalidOptions,
                FsOperation::OpenWriter,
                "append cannot require atomic publication or a destination version",
            ));
        }
        if self.disposition == WriteDisposition::CreateNew
            && matches!(&self.precondition, WritePrecondition::IfMatch(_))
        {
            return Err(FsError::new(
                FsErrorKind::InvalidOptions,
                FsOperation::OpenWriter,
                "create-new cannot require an existing destination version",
            ));
        }
        Ok(())
    }

    /// Validates write options against stable configured capabilities.
    ///
    /// Providers should call this before opening a write session. In
    /// particular, required atomic publication is rejected before any staging
    /// write when [`FileSystemCapability::AtomicReplace`] is absent.
    ///
    /// # Errors
    ///
    /// Returns invalid-option errors from [`Self::validate`], or a typed
    /// [`FsErrorKind::RequirementNotMet`] for unsupported append, conditional,
    /// or required-atomic writes.
    /// # Parameters
    /// - `capabilities`: Capabilities against which the requested policy is
    ///   checked.
    pub fn validate_against(&self, capabilities: FileSystemCapabilities) -> Result<(), FsError> {
        self.validate()?;
        if self.disposition == WriteDisposition::Append && !capabilities.supports(FileSystemCapability::Append) {
            return Err(missing_requirement(
                FileSystemCapability::Append,
                "append writes are required but not supported",
            ));
        }
        if self.precondition != WritePrecondition::None
            && !capabilities.supports(FileSystemCapability::ConditionalWrite)
        {
            return Err(missing_requirement(
                FileSystemCapability::ConditionalWrite,
                "conditional writes are required but not supported",
            ));
        }
        if self.atomicity == AtomicityRequirement::Required
            && !capabilities.supports(FileSystemCapability::AtomicReplace)
        {
            return Err(missing_requirement(
                FileSystemCapability::AtomicReplace,
                "atomic write publication is required but not supported",
            ));
        }
        if self.durability == DurabilityRequirement::Required
            && !capabilities.supports(FileSystemCapability::DurableWrite)
        {
            return Err(missing_requirement(
                FileSystemCapability::DurableWrite,
                "durable write publication is required but not supported",
            ));
        }
        Ok(())
    }
}

/// Builds an error that identifies the unsupported capability required by a
/// write.
/// # Parameters
/// - `capability`: Capability that the provider must support.
/// - `message`: Stable description included in the invalid-state error.
fn missing_requirement(capability: FileSystemCapability, message: &str) -> FsError {
    FsError::new(FsErrorKind::RequirementNotMet, FsOperation::OpenWriter, message).with_required_capability(capability)
}