1use crate::cell::CellValue;
2use crate::error::{Error, Result};
3use crate::output::budget::OutputBudget;
4use crate::resource::ResourceOperation;
5use crate::rich_text::RichTextRun;
6use crate::utils::constants::{MAX_COLUMNS, MAX_ROWS};
7
8pub const MAX_CSV_OUTPUT_BYTES: u64 = 64 * 1024 * 1024;
12
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
15pub enum CsvFormulaPolicy {
16 #[default]
18 SpreadsheetSafe,
19 RawExchange,
21}
22
23pub fn serialize_csv(rows: &[(u32, Vec<(u32, CellValue)>)]) -> Result<Vec<u8>> {
31 serialize_csv_with_policy(rows, CsvFormulaPolicy::SpreadsheetSafe)
32}
33
34pub fn serialize_csv_with_policy(
40 rows: &[(u32, Vec<(u32, CellValue)>)],
41 formula_policy: CsvFormulaPolicy,
42) -> Result<Vec<u8>> {
43 serialize_csv_with_limit(rows, formula_policy, MAX_CSV_OUTPUT_BYTES)
44}
45
46fn serialize_csv_with_limit(
47 rows: &[(u32, Vec<(u32, CellValue)>)],
48 formula_policy: CsvFormulaPolicy,
49 limit: u64,
50) -> Result<Vec<u8>> {
51 let mut budget = OutputBudget::new(ResourceOperation::Export, limit);
52 serialize_csv_with_reserve(rows, formula_policy, |output, bytes| {
53 budget.reserve(output, bytes)
54 })
55}
56
57fn serialize_csv_with_reserve(
58 rows: &[(u32, Vec<(u32, CellValue)>)],
59 formula_policy: CsvFormulaPolicy,
60 mut reserve: impl FnMut(&mut Vec<u8>, u64) -> Result<()>,
61) -> Result<Vec<u8>> {
62 let Some(max_column) = validate_csv_coordinates(rows)? else {
63 return Ok(Vec::new());
64 };
65
66 let output_bytes = measure_csv_output(rows, max_column, formula_policy);
67 let mut output = Vec::new();
68 reserve(&mut output, output_bytes)?;
69
70 for (row_index, (_, cells)) in rows.iter().enumerate() {
71 if row_index > 0 {
72 output.push(b'\n');
73 }
74 let mut cell_index = 0usize;
75 for column in 1..=max_column {
76 if column > 1 {
77 output.push(b',');
78 }
79
80 while cells
81 .get(cell_index)
82 .is_some_and(|(cell_column, _)| *cell_column < column)
83 {
84 cell_index += 1;
85 }
86 if let Some((cell_column, value)) = cells.get(cell_index) {
87 if *cell_column == column {
88 append_field(&mut output, value, formula_policy);
89 cell_index += 1;
90 }
91 }
92 }
93 }
94
95 debug_assert_eq!(u64::try_from(output.len()).ok(), Some(output_bytes));
96 Ok(output)
97}
98
99fn measure_csv_output(
100 rows: &[(u32, Vec<(u32, CellValue)>)],
101 max_column: u32,
102 formula_policy: CsvFormulaPolicy,
103) -> u64 {
104 let separators = u64::try_from(rows.len().saturating_sub(1)).unwrap_or(u64::MAX);
105 let structural_per_row = u64::from(max_column.saturating_sub(1));
106 let mut output_bytes = structural_per_row
107 .saturating_mul(u64::try_from(rows.len()).unwrap_or(u64::MAX))
108 .saturating_add(separators);
109 for (_, cells) in rows {
110 for (_, value) in cells {
111 let field = CsvField::from_cell(value);
112 let mut stats = FieldStats::default();
113 field.for_each_segment(|segment| stats.observe(segment));
114 output_bytes = output_bytes.saturating_add(
115 stats.output_bytes(
116 formula_policy == CsvFormulaPolicy::SpreadsheetSafe
117 && field.is_textual()
118 && stats
119 .first_significant
120 .is_some_and(is_formula_trigger_character),
121 ),
122 );
123 }
124 }
125 output_bytes
126}
127
128fn validate_csv_coordinates(rows: &[(u32, Vec<(u32, CellValue)>)]) -> Result<Option<u32>> {
129 let mut previous_row = 0u32;
130 let mut max_column = None;
131
132 for (row, cells) in rows {
133 if *row == 0 || *row > MAX_ROWS {
134 return Err(Error::InvalidRowNumber(*row));
135 }
136 if *row <= previous_row {
137 return Err(Error::Internal(
138 "CSV row coordinates must be strictly increasing and unique".to_string(),
139 ));
140 }
141 previous_row = *row;
142
143 let mut previous_column = 0u32;
144 for (column, _) in cells {
145 if *column == 0 || *column > MAX_COLUMNS {
146 return Err(Error::InvalidColumnNumber(*column));
147 }
148 if *column <= previous_column {
149 return Err(Error::Internal(
150 "CSV column coordinates must be strictly increasing and unique".to_string(),
151 ));
152 }
153 previous_column = *column;
154 max_column = Some(max_column.unwrap_or(0).max(*column));
155 }
156 }
157
158 Ok(max_column)
159}
160
161enum CsvField<'a> {
162 Borrowed { text: &'a str, textual: bool },
163 Owned { text: String, textual: bool },
164 Rich(&'a [RichTextRun]),
165 Formula(&'a str),
166}
167
168impl<'a> CsvField<'a> {
169 fn from_cell(value: &'a CellValue) -> Self {
170 match value {
171 CellValue::Formula { expr, .. } => Self::Formula(expr),
172 CellValue::Empty => Self::Borrowed {
173 text: "",
174 textual: false,
175 },
176 CellValue::Bool(value) => Self::Borrowed {
177 text: if *value { "TRUE" } else { "FALSE" },
178 textual: false,
179 },
180 CellValue::Number(_) | CellValue::Date(_) => Self::Owned {
181 text: value.to_string(),
182 textual: false,
183 },
184 CellValue::String(text) => Self::Borrowed {
185 text,
186 textual: true,
187 },
188 CellValue::Error(text) => Self::Borrowed {
189 text,
190 textual: !is_excel_error_token(text),
191 },
192 CellValue::RichString(runs) => Self::Rich(runs),
193 }
194 }
195
196 fn for_each_segment(&self, mut visit: impl FnMut(&str)) {
197 match self {
198 Self::Borrowed { text, .. } => visit(text),
199 Self::Owned { text, .. } => visit(text),
200 Self::Rich(runs) => {
201 for run in *runs {
202 visit(&run.text);
203 }
204 }
205 Self::Formula(expression) => {
206 visit("=");
207 visit(expression);
208 }
209 }
210 }
211
212 fn is_textual(&self) -> bool {
213 match self {
214 Self::Borrowed { textual, .. } | Self::Owned { textual, .. } => *textual,
215 Self::Rich(_) | Self::Formula(_) => true,
216 }
217 }
218}
219
220#[derive(Default)]
221struct FieldStats {
222 content_bytes: u64,
223 quote_count: u64,
224 needs_quotes: bool,
225 first_significant: Option<char>,
226}
227
228impl FieldStats {
229 fn observe(&mut self, segment: &str) {
230 self.content_bytes = self
231 .content_bytes
232 .saturating_add(u64::try_from(segment.len()).unwrap_or(u64::MAX));
233 self.quote_count = self.quote_count.saturating_add(
234 u64::try_from(segment.bytes().filter(|byte| *byte == b'"').count()).unwrap_or(u64::MAX),
235 );
236 self.needs_quotes |= segment
237 .bytes()
238 .any(|byte| matches!(byte, b',' | b'"' | b'\r' | b'\n'));
239 if self.first_significant.is_none() {
240 self.first_significant = segment
241 .chars()
242 .find(|character| !is_formula_leading_character(*character));
243 }
244 }
245
246 fn output_bytes(&self, neutralized: bool) -> u64 {
247 let neutralizer = u64::from(neutralized);
248 let structural = if self.needs_quotes { 2 } else { 0 };
249 self.content_bytes
250 .checked_add(self.quote_count)
251 .and_then(|value| value.checked_add(neutralizer))
252 .and_then(|value| value.checked_add(structural))
253 .unwrap_or(u64::MAX)
254 }
255}
256
257fn append_field(output: &mut Vec<u8>, value: &CellValue, formula_policy: CsvFormulaPolicy) {
258 let field = CsvField::from_cell(value);
259 let mut stats = FieldStats::default();
260 field.for_each_segment(|segment| stats.observe(segment));
261 let neutralized = formula_policy == CsvFormulaPolicy::SpreadsheetSafe
262 && field.is_textual()
263 && stats
264 .first_significant
265 .is_some_and(is_formula_trigger_character);
266 if stats.needs_quotes {
267 output.push(b'"');
268 }
269 if neutralized {
270 output.push(b'\'');
271 }
272 field.for_each_segment(|segment| append_segment(output, segment, stats.needs_quotes));
273 if stats.needs_quotes {
274 output.push(b'"');
275 }
276}
277
278fn append_segment(output: &mut Vec<u8>, segment: &str, quoted: bool) {
279 if !quoted {
280 output.extend_from_slice(segment.as_bytes());
281 return;
282 }
283
284 let mut start = 0usize;
285 for (index, byte) in segment.bytes().enumerate() {
286 if byte == b'"' {
287 output.extend_from_slice(&segment.as_bytes()[start..index]);
288 output.extend_from_slice(b"\"\"");
289 start = index + 1;
290 }
291 }
292 output.extend_from_slice(&segment.as_bytes()[start..]);
293}
294
295fn is_formula_leading_character(character: char) -> bool {
296 character.is_whitespace() || character.is_control() || character == '\u{feff}'
297}
298
299fn is_formula_trigger_character(character: char) -> bool {
300 matches!(character, '=' | '+' | '-' | '@')
301}
302
303pub(crate) fn is_excel_error_token(value: &str) -> bool {
304 matches!(
305 value,
306 "#NULL!"
307 | "#DIV/0!"
308 | "#VALUE!"
309 | "#REF!"
310 | "#NAME?"
311 | "#NUM!"
312 | "#N/A"
313 | "#GETTING_DATA"
314 | "#SPILL!"
315 | "#CALC!"
316 | "#FIELD!"
317 | "#BLOCKED!"
318 | "#UNKNOWN!"
319 | "#CONNECT!"
320 | "#BUSY!"
321 | "#PYTHON!"
322 )
323}
324
325#[cfg(test)]
326mod tests {
327 use super::*;
328 use crate::resource::ResourceDimension;
329
330 fn one_cell(value: &str) -> Vec<(u32, Vec<(u32, CellValue)>)> {
331 vec![(1, vec![(1, CellValue::String(value.to_string()))])]
332 }
333
334 fn metadata(error: Error) -> crate::ResourceLimitError {
335 let Error::ResourceLimitExceeded(metadata) = error else {
336 panic!("expected resource limit error");
337 };
338 metadata
339 }
340
341 #[test]
342 fn exact_output_limit_succeeds_and_plus_one_is_rejected() {
343 let rows = one_cell("a");
344 assert_eq!(
345 serialize_csv_with_limit(&rows, CsvFormulaPolicy::SpreadsheetSafe, 1).unwrap(),
346 b"a"
347 );
348
349 let error =
350 serialize_csv_with_limit(&rows, CsvFormulaPolicy::SpreadsheetSafe, 0).unwrap_err();
351 let metadata = metadata(error);
352 assert_eq!(metadata.limit(), 0);
353 assert_eq!(metadata.observed(), 1);
354 assert_eq!(metadata.operation(), ResourceOperation::Export);
355 assert_eq!(metadata.category(), crate::ResourceCategory::Output);
356 assert_eq!(metadata.dimension(), ResourceDimension::OutputBytes);
357 assert_eq!(metadata.stage(), Some(crate::ResourceStage::Serialize));
358 }
359
360 #[test]
361 fn formula_cells_export_expressions_regardless_of_cached_results() {
362 let rows = vec![
363 (
364 1,
365 vec![(
366 1,
367 CellValue::Formula {
368 expr: "1+1".to_string(),
369 result: Some(Box::new(CellValue::Number(2.0))),
370 },
371 )],
372 ),
373 (
374 2,
375 vec![(
376 1,
377 CellValue::Formula {
378 expr: "2+2".to_string(),
379 result: None,
380 },
381 )],
382 ),
383 ];
384
385 assert_eq!(
386 serialize_csv(&rows).unwrap(),
387 b"'=1+1\n'=2+2",
388 "default CSV bytes must match the Node and CLI contract"
389 );
390 assert_eq!(
391 serialize_csv_with_policy(&rows, CsvFormulaPolicy::RawExchange).unwrap(),
392 b"=1+1\n=2+2"
393 );
394 }
395
396 #[test]
397 fn rejection_returns_no_partial_output_value() {
398 let rows = one_cell("=dangerous");
399 assert!(serialize_csv_with_limit(&rows, CsvFormulaPolicy::SpreadsheetSafe, 1).is_err());
400 }
401
402 #[test]
403 fn serialization_reserves_the_exact_output_once_before_emission() {
404 let rows = vec![(
405 1,
406 (1..=4_096)
407 .map(|column| (column, CellValue::String("value".to_string())))
408 .collect(),
409 )];
410 let mut reserve_calls = Vec::new();
411
412 let output = serialize_csv_with_reserve(
413 &rows,
414 CsvFormulaPolicy::SpreadsheetSafe,
415 |output, bytes| {
416 reserve_calls.push(bytes);
417 output
418 .try_reserve_exact(usize::try_from(bytes).unwrap())
419 .map_err(|_| Error::Internal("test allocation failed".to_string()))
420 },
421 )
422 .unwrap();
423
424 assert_eq!(reserve_calls, [u64::try_from(output.len()).unwrap()]);
425 }
426}