Skip to main content

sheetkit_core/
save.rs

1//! Finite resource limits and durability options for workbook and
2//! streamed-sheet serialization.
3
4use crate::error::{Error, Result};
5use crate::resource::{
6    ResourceCategory, ResourceDimension, ResourceLimitError, ResourceOperation, ResourceStage,
7};
8
9const MIB: u64 = 1024 * 1024;
10const GIB: u64 = 1024 * MIB;
11
12/// Default maximum compressed bytes emitted by one workbook save.
13pub const DEFAULT_SAVE_OUTPUT_BYTES: u64 = 512 * MIB;
14/// Default maximum bytes emitted by one serialized XML part.
15pub const DEFAULT_SAVE_XML_PART_BYTES: u64 = 128 * MIB;
16/// Default maximum occupied rows serialized by one workbook save.
17pub const DEFAULT_SAVE_ROWS: u64 = 10_000_000;
18/// Default maximum occupied cells serialized by one workbook save.
19pub const DEFAULT_SAVE_CELLS: u64 = 10_000_000;
20
21/// Default maximum bytes in one streamed row XML fragment.
22pub const DEFAULT_STREAM_ROW_XML_BYTES: u64 = 16 * MIB;
23/// Default maximum bytes in one streamed worksheet's row fragments.
24pub const DEFAULT_STREAM_OUTPUT_BYTES: u64 = 512 * MIB;
25/// Default maximum occupied rows accepted by one stream writer.
26pub const DEFAULT_STREAM_ROWS: u64 = 1_048_576;
27/// Default maximum cell slots accepted by one stream writer.
28pub const DEFAULT_STREAM_CELLS: u64 = 10_000_000;
29/// Default maximum distinct stream configuration entries.
30pub const DEFAULT_STREAM_CONFIG_COUNT: u64 = 100_000;
31/// Default maximum retained bytes used by stream configuration.
32pub const DEFAULT_STREAM_CONFIG_BYTES: u64 = 16 * MIB;
33
34const HARD_SAVE_OUTPUT_BYTES: u64 = 2 * GIB;
35const HARD_SAVE_XML_PART_BYTES: u64 = 512 * MIB;
36const HARD_SAVE_ROWS: u64 = 100_000_000;
37const HARD_SAVE_CELLS: u64 = 100_000_000;
38const HARD_STREAM_ROW_XML_BYTES: u64 = 128 * MIB;
39const HARD_STREAM_OUTPUT_BYTES: u64 = 2 * GIB;
40const HARD_STREAM_ROWS: u64 = 1_048_576;
41const HARD_STREAM_CELLS: u64 = 100_000_000;
42const HARD_STREAM_CONFIG_COUNT: u64 = 1_000_000;
43const HARD_STREAM_CONFIG_BYTES: u64 = 128 * MIB;
44
45/// Finite limits for one workbook save operation.
46#[derive(Debug, Clone, Copy, PartialEq, Eq)]
47pub struct SaveLimits {
48    /// Maximum compressed archive or encrypted-container output bytes.
49    pub output_bytes: u64,
50    /// Maximum serialized bytes in one XML package part.
51    pub xml_part_bytes: u64,
52    /// Maximum occupied rows serialized across the workbook.
53    pub row_count: u64,
54    /// Maximum occupied cells serialized across the workbook.
55    pub cell_count: u64,
56}
57
58impl Default for SaveLimits {
59    fn default() -> Self {
60        Self {
61            output_bytes: DEFAULT_SAVE_OUTPUT_BYTES,
62            xml_part_bytes: DEFAULT_SAVE_XML_PART_BYTES,
63            row_count: DEFAULT_SAVE_ROWS,
64            cell_count: DEFAULT_SAVE_CELLS,
65        }
66    }
67}
68
69impl SaveLimits {
70    /// Largest supported finite values. These ceilings cannot be disabled.
71    pub const fn hard_ceiling() -> Self {
72        Self {
73            output_bytes: HARD_SAVE_OUTPUT_BYTES,
74            xml_part_bytes: HARD_SAVE_XML_PART_BYTES,
75            row_count: HARD_SAVE_ROWS,
76            cell_count: HARD_SAVE_CELLS,
77        }
78    }
79
80    /// Validates the limits against the non-overridable hard ceilings.
81    pub fn validate(self) -> Result<Self> {
82        validate_limits(
83            ResourceOperation::WorkbookSave,
84            &[
85                (
86                    ResourceDimension::OutputBytes,
87                    self.output_bytes,
88                    HARD_SAVE_OUTPUT_BYTES,
89                ),
90                (
91                    ResourceDimension::XmlBytes,
92                    self.xml_part_bytes,
93                    HARD_SAVE_XML_PART_BYTES,
94                ),
95                (ResourceDimension::RowCount, self.row_count, HARD_SAVE_ROWS),
96                (
97                    ResourceDimension::CellCount,
98                    self.cell_count,
99                    HARD_SAVE_CELLS,
100                ),
101            ],
102        )?;
103        Ok(self)
104    }
105}
106
107/// Durability policy for one path save.
108///
109/// Every path save writes a temporary file (prefix `.sheetkit-`) in the
110/// destination directory and renames it over the destination. A failed save
111/// or an application crash before the rename leaves the previous file intact;
112/// a hard kill can leave an orphan temporary file behind.
113///
114/// - `durable: false` (default): no flush is requested. After a power loss or
115///   operating-system crash shortly after a successful save, the destination
116///   may hold the previous version, the new one, or, depending on the file
117///   system and mount options, an empty or incomplete file.
118/// - `durable: true`: the temporary file is flushed to storage before the
119///   rename (`fsync`; `F_FULLFSYNC` on macOS, which costs several
120///   milliseconds; `FlushFileBuffers` on Windows), and on Unix the parent
121///   directory is synced after the rename. A failed directory sync returns
122///   [`Error::Io`] stating that the new file is already in place. Windows has
123///   no directory sync, so that step is skipped there.
124///
125/// Network file systems and drives that ignore flush requests can weaken
126/// either guarantee. Construct it with a struct literal or
127/// `SaveOptions::default()`.
128#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
129pub struct SaveOptions {
130    /// Flush the file and its directory entry to storage before returning.
131    pub durable: bool,
132}
133
134/// Finite limits for one streamed-sheet construction operation.
135#[derive(Debug, Clone, Copy, PartialEq, Eq)]
136pub struct StreamLimits {
137    /// Maximum occupied rows accepted by the writer.
138    pub row_count: u64,
139    /// Maximum cell slots accepted by the writer.
140    pub cell_count: u64,
141    /// Maximum serialized bytes in one row XML fragment.
142    pub row_xml_bytes: u64,
143    /// Maximum serialized bytes across all row XML fragments.
144    pub output_bytes: u64,
145    /// Maximum distinct column, merge, and pane configuration entries.
146    pub config_count: u64,
147    /// Maximum retained bytes used by stream configuration.
148    pub config_bytes: u64,
149}
150
151impl Default for StreamLimits {
152    fn default() -> Self {
153        Self {
154            row_count: DEFAULT_STREAM_ROWS,
155            cell_count: DEFAULT_STREAM_CELLS,
156            row_xml_bytes: DEFAULT_STREAM_ROW_XML_BYTES,
157            output_bytes: DEFAULT_STREAM_OUTPUT_BYTES,
158            config_count: DEFAULT_STREAM_CONFIG_COUNT,
159            config_bytes: DEFAULT_STREAM_CONFIG_BYTES,
160        }
161    }
162}
163
164impl StreamLimits {
165    /// Largest supported finite values. These ceilings cannot be disabled.
166    pub const fn hard_ceiling() -> Self {
167        Self {
168            row_count: HARD_STREAM_ROWS,
169            cell_count: HARD_STREAM_CELLS,
170            row_xml_bytes: HARD_STREAM_ROW_XML_BYTES,
171            output_bytes: HARD_STREAM_OUTPUT_BYTES,
172            config_count: HARD_STREAM_CONFIG_COUNT,
173            config_bytes: HARD_STREAM_CONFIG_BYTES,
174        }
175    }
176
177    /// Validates the limits against the non-overridable hard ceilings.
178    pub fn validate(self) -> Result<Self> {
179        validate_limits(
180            ResourceOperation::StreamWrite,
181            &[
182                (
183                    ResourceDimension::RowCount,
184                    self.row_count,
185                    HARD_STREAM_ROWS,
186                ),
187                (
188                    ResourceDimension::CellCount,
189                    self.cell_count,
190                    HARD_STREAM_CELLS,
191                ),
192                (
193                    ResourceDimension::XmlBytes,
194                    self.row_xml_bytes,
195                    HARD_STREAM_ROW_XML_BYTES,
196                ),
197                (
198                    ResourceDimension::OutputBytes,
199                    self.output_bytes,
200                    HARD_STREAM_OUTPUT_BYTES,
201                ),
202                (
203                    ResourceDimension::CollectionCount,
204                    self.config_count,
205                    HARD_STREAM_CONFIG_COUNT,
206                ),
207                (
208                    ResourceDimension::RetainedBytes,
209                    self.config_bytes,
210                    HARD_STREAM_CONFIG_BYTES,
211                ),
212            ],
213        )?;
214        Ok(self)
215    }
216}
217
218pub(crate) fn resource_limit(
219    operation: ResourceOperation,
220    category: ResourceCategory,
221    dimension: ResourceDimension,
222    limit: u64,
223    observed: u64,
224    stage: ResourceStage,
225) -> Error {
226    ResourceLimitError::exceeded(
227        operation,
228        category,
229        dimension,
230        limit,
231        observed.max(limit.saturating_add(1)),
232        Some(stage),
233    )
234    .map(Error::from)
235    .unwrap_or_else(|| Error::Internal("invalid save resource limit state".to_string()))
236}
237
238fn validate_limits(
239    operation: ResourceOperation,
240    limits: &[(ResourceDimension, u64, u64)],
241) -> Result<()> {
242    for &(dimension, value, maximum) in limits {
243        if value == 0 || value > maximum {
244            return Err(resource_limit(
245                operation,
246                ResourceCategory::Output,
247                dimension,
248                maximum,
249                value.max(maximum.saturating_add(1)),
250                ResourceStage::Validate,
251            ));
252        }
253    }
254    Ok(())
255}
256
257#[cfg(test)]
258mod tests {
259    use super::*;
260
261    #[test]
262    fn defaults_are_finite_and_hard_ceilings_are_enforced() {
263        SaveLimits::default().validate().unwrap();
264        StreamLimits::default().validate().unwrap();
265
266        let error = SaveLimits {
267            output_bytes: HARD_SAVE_OUTPUT_BYTES + 1,
268            ..SaveLimits::default()
269        }
270        .validate()
271        .unwrap_err();
272        assert_eq!(
273            error.resource_metadata().unwrap().dimension(),
274            ResourceDimension::OutputBytes
275        );
276
277        let error = StreamLimits {
278            row_xml_bytes: HARD_STREAM_ROW_XML_BYTES + 1,
279            ..StreamLimits::default()
280        }
281        .validate()
282        .unwrap_err();
283        assert_eq!(
284            error.resource_metadata().unwrap().operation(),
285            ResourceOperation::StreamWrite
286        );
287    }
288}