Skip to main content

qubit_fs/write/
write_options.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Write operation options.
9
10use crate::error::FsError;
11use crate::error::FsErrorKind;
12use crate::error::FsOperation;
13use crate::metadata::AtomicityRequirement;
14use crate::metadata::Checksum;
15use crate::metadata::DurabilityRequirement;
16use crate::metadata::FileSystemCapabilities;
17use crate::metadata::FileSystemCapability;
18use crate::metadata::NonSensitiveMetadata;
19use crate::metadata::UserMetadata;
20use crate::write::WriteDisposition;
21use crate::write::WritePrecondition;
22
23/// Options controlling a write operation.
24///
25/// By default, `create_parent` is `false`, `disposition` is
26/// [`WriteDisposition::CreateOrReplace`], `atomicity` is
27/// [`AtomicityRequirement::Preferred`], `durability` is
28/// [`DurabilityRequirement::NotRequired`], and `precondition` is
29/// [`WritePrecondition::None`]. Content type and checksum are `None`, and user
30/// metadata is empty. These are request policies; provider support and
31/// successful completion are reported separately.
32///
33/// # Examples
34/// ```rust
35/// use qubit_fs::write::WriteOptions;
36/// use qubit_fs::metadata::AtomicityRequirement;
37/// use qubit_fs::metadata::FileSystemCapabilities;
38/// let options = WriteOptions::default().with_atomicity(AtomicityRequirement::Required);
39/// assert!(options.validate_against(FileSystemCapabilities::new()).is_err());
40/// ```
41///
42/// Refuse to replace an existing destination:
43/// ```rust
44/// use qubit_fs::write::WriteDisposition;
45/// use qubit_fs::write::WriteOptions;
46///
47/// let options = WriteOptions::default()
48///     .with_disposition(WriteDisposition::CreateNew);
49/// assert_eq!(options.disposition(), WriteDisposition::CreateNew);
50/// ```
51#[non_exhaustive]
52#[derive(Clone, Debug, PartialEq)]
53pub struct WriteOptions {
54    /// Whether missing parent directories should be created.
55    create_parent: bool,
56    /// How an existing destination is treated.
57    disposition: WriteDisposition,
58    /// Required atomicity of destination publication.
59    atomicity: AtomicityRequirement,
60    /// Required durability of completed publication.
61    durability: DurabilityRequirement,
62    /// Version precondition applied to the destination.
63    precondition: WritePrecondition,
64    /// Optional content type.
65    content_type: Option<String>,
66    /// User-defined metadata with validated non-sensitive structural keys.
67    user_metadata: NonSensitiveMetadata,
68    /// Optional expected content checksum.
69    checksum: Option<Checksum>,
70}
71
72impl Default for WriteOptions {
73    /// Uses conservative defaults: no parent creation and replacement behavior.
74    #[inline]
75    fn default() -> Self {
76        Self {
77            create_parent: false,
78            disposition: WriteDisposition::default(),
79            atomicity: AtomicityRequirement::default(),
80            durability: DurabilityRequirement::default(),
81            precondition: WritePrecondition::default(),
82            content_type: None,
83            user_metadata: NonSensitiveMetadata::new(),
84            checksum: None,
85        }
86    }
87}
88
89impl WriteOptions {
90    /// Returns whether missing parent directories are created.
91    #[inline]
92    #[must_use]
93    pub const fn create_parent(&self) -> bool {
94        self.create_parent
95    }
96
97    /// Returns the destination disposition.
98    #[inline]
99    #[must_use]
100    pub const fn disposition(&self) -> WriteDisposition {
101        self.disposition
102    }
103
104    /// Returns the atomicity requirement.
105    #[inline]
106    #[must_use]
107    pub const fn atomicity(&self) -> AtomicityRequirement {
108        self.atomicity
109    }
110
111    /// Returns the completed-publication durability requirement.
112    #[inline]
113    #[must_use]
114    pub const fn durability(&self) -> DurabilityRequirement {
115        self.durability
116    }
117
118    /// Returns the version precondition.
119    #[inline]
120    #[must_use]
121    pub const fn precondition(&self) -> &WritePrecondition {
122        &self.precondition
123    }
124
125    /// Returns the optional content type.
126    #[inline]
127    pub fn content_type(&self) -> Option<&str> {
128        self.content_type.as_deref()
129    }
130
131    /// Returns the user metadata attached to this write.
132    #[inline]
133    #[must_use]
134    pub const fn user_metadata(&self) -> &NonSensitiveMetadata {
135        &self.user_metadata
136    }
137
138    /// Returns the optional expected checksum.
139    #[inline]
140    pub const fn checksum(&self) -> Option<&Checksum> {
141        self.checksum.as_ref()
142    }
143
144    /// Returns a copy with parent creation replaced.
145    /// # Parameters
146    /// - `create`: Whether parent directories should be created.
147    #[inline]
148    #[must_use]
149    pub const fn with_create_parent(mut self, create: bool) -> Self {
150        self.create_parent = create;
151        self
152    }
153
154    /// Returns a copy with the destination disposition replaced.
155    /// # Parameters
156    /// - `disposition`: Destination creation or replacement behavior.
157    #[inline]
158    #[must_use]
159    pub const fn with_disposition(mut self, disposition: WriteDisposition) -> Self {
160        self.disposition = disposition;
161        self
162    }
163
164    /// Returns a copy with the atomicity requirement replaced.
165    /// # Parameters
166    /// - `atomicity`: Required atomic publication behavior.
167    #[inline]
168    #[must_use]
169    pub const fn with_atomicity(mut self, atomicity: AtomicityRequirement) -> Self {
170        self.atomicity = atomicity;
171        self
172    }
173
174    /// Returns a copy with the durability requirement replaced.
175    /// # Parameters
176    /// - `durability`: Required durability after publication.
177    #[inline]
178    #[must_use]
179    pub const fn with_durability(mut self, durability: DurabilityRequirement) -> Self {
180        self.durability = durability;
181        self
182    }
183
184    /// Returns a copy with the version precondition replaced.
185    /// # Parameters
186    /// - `precondition`: Version condition required before publication.
187    #[inline]
188    #[must_use]
189    pub fn with_precondition(mut self, precondition: WritePrecondition) -> Self {
190        self.precondition = precondition;
191        self
192    }
193
194    /// Returns a copy with the content type replaced.
195    /// # Parameters
196    /// - `content_type`: Optional content type associated with the new file.
197    #[inline]
198    #[must_use]
199    pub fn with_content_type(mut self, content_type: Option<String>) -> Self {
200        self.content_type = content_type;
201        self
202    }
203
204    /// Returns a copy with the expected checksum replaced.
205    /// # Parameters
206    /// - `checksum`: Optional expected checksum for the written content.
207    #[inline]
208    #[must_use]
209    pub fn with_checksum(mut self, checksum: Option<Checksum>) -> Self {
210        self.checksum = checksum;
211        self
212    }
213
214    /// Replaces user-defined metadata that has already passed key validation.
215    /// # Parameters
216    /// - `metadata`: Validated user metadata associated with the new file.
217    #[inline]
218    #[must_use]
219    pub fn with_user_metadata(mut self, metadata: UserMetadata) -> Self {
220        self.user_metadata = NonSensitiveMetadata::from(metadata);
221        self
222    }
223
224    /// Validates combinations that have no coherent provider interpretation.
225    ///
226    /// # Errors
227    /// Returns [`FsErrorKind::InvalidOptions`] before a writer is opened when
228    /// append is combined with atomic publication or a version precondition,
229    /// or when create-new is combined with an existing-version requirement.
230    #[inline]
231    pub fn validate(&self) -> Result<(), FsError> {
232        if self.disposition == WriteDisposition::Append
233            && (self.atomicity == AtomicityRequirement::Required || self.precondition != WritePrecondition::None)
234        {
235            return Err(FsError::new(
236                FsErrorKind::InvalidOptions,
237                FsOperation::OpenWriter,
238                "append cannot require atomic publication or a destination version",
239            ));
240        }
241        if self.disposition == WriteDisposition::CreateNew
242            && matches!(&self.precondition, WritePrecondition::IfMatch(_))
243        {
244            return Err(FsError::new(
245                FsErrorKind::InvalidOptions,
246                FsOperation::OpenWriter,
247                "create-new cannot require an existing destination version",
248            ));
249        }
250        Ok(())
251    }
252
253    /// Validates write options against stable configured capabilities.
254    ///
255    /// Providers should call this before opening a write session. In
256    /// particular, required atomic publication is rejected before any staging
257    /// write when [`FileSystemCapability::AtomicReplace`] is absent.
258    ///
259    /// # Errors
260    ///
261    /// Returns invalid-option errors from [`Self::validate`], or a typed
262    /// [`FsErrorKind::RequirementNotMet`] for unsupported append, conditional,
263    /// or required-atomic writes.
264    /// # Parameters
265    /// - `capabilities`: Capabilities against which the requested policy is
266    ///   checked.
267    pub fn validate_against(&self, capabilities: FileSystemCapabilities) -> Result<(), FsError> {
268        self.validate()?;
269        if self.disposition == WriteDisposition::Append && !capabilities.supports(FileSystemCapability::Append) {
270            return Err(missing_requirement(
271                FileSystemCapability::Append,
272                "append writes are required but not supported",
273            ));
274        }
275        if self.precondition != WritePrecondition::None
276            && !capabilities.supports(FileSystemCapability::ConditionalWrite)
277        {
278            return Err(missing_requirement(
279                FileSystemCapability::ConditionalWrite,
280                "conditional writes are required but not supported",
281            ));
282        }
283        if self.atomicity == AtomicityRequirement::Required
284            && !capabilities.supports(FileSystemCapability::AtomicReplace)
285        {
286            return Err(missing_requirement(
287                FileSystemCapability::AtomicReplace,
288                "atomic write publication is required but not supported",
289            ));
290        }
291        if self.durability == DurabilityRequirement::Required
292            && !capabilities.supports(FileSystemCapability::DurableWrite)
293        {
294            return Err(missing_requirement(
295                FileSystemCapability::DurableWrite,
296                "durable write publication is required but not supported",
297            ));
298        }
299        Ok(())
300    }
301}
302
303/// Builds an error that identifies the unsupported capability required by a
304/// write.
305/// # Parameters
306/// - `capability`: Capability that the provider must support.
307/// - `message`: Stable description included in the invalid-state error.
308fn missing_requirement(capability: FileSystemCapability, message: &str) -> FsError {
309    FsError::new(FsErrorKind::RequirementNotMet, FsOperation::OpenWriter, message).with_required_capability(capability)
310}