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}