Skip to main content

appstruct_core/
resource.rs

1// Shared resource protocol types and parsing helpers.
2
3use base64::Engine as _;
4use serde::{Deserialize, Serialize};
5use std::collections::BTreeMap;
6use std::error::Error;
7use std::fmt;
8
9pub const MAX_BULK_ITEMS: usize = 100;
10pub const MAX_CSV_IMPORT_ROWS: usize = 10_000;
11pub const MAX_CSV_EXPORT_ROWS: u64 = 10_000;
12pub const CSV_EXPORT_PAGE_SIZE: u64 = 500;
13
14#[derive(Debug, Default, Deserialize)]
15pub struct ListQuery {
16    pub page: Option<u64>,
17    pub page_size: Option<u64>,
18    pub cursor: Option<String>,
19    pub limit: Option<u64>,
20    pub direction: Option<String>,
21    pub sort: Option<String>,
22    pub q: Option<String>,
23    #[serde(rename = "where")]
24    pub expression: Option<String>,
25    pub fields: Option<String>,
26    #[serde(flatten)]
27    pub filters: BTreeMap<String, String>,
28}
29
30#[derive(Debug, Serialize)]
31#[serde(untagged)]
32pub enum ListMeta {
33    Page {
34        page: u64,
35        page_size: u64,
36        total: u64,
37    },
38    Cursor {
39        limit: u64,
40        next_cursor: Option<String>,
41        previous_cursor: Option<String>,
42        has_more: bool,
43    },
44}
45
46#[derive(Debug, Serialize)]
47pub struct ListResponse<T> {
48    pub data: Vec<T>,
49    pub meta: ListMeta,
50}
51
52#[derive(Clone, Debug, Deserialize)]
53pub struct BulkUpdateInput<T> {
54    pub ids: Vec<String>,
55    pub patch: T,
56    pub expected_revisions: BTreeMap<String, i64>,
57}
58
59#[derive(Debug, Deserialize)]
60pub struct BulkDeleteInput {
61    pub ids: Vec<String>,
62    pub expected_revisions: BTreeMap<String, i64>,
63}
64
65#[derive(Debug, Serialize, Deserialize)]
66pub struct BulkFailure {
67    pub id: String,
68    pub code: String,
69    pub message: String,
70}
71
72#[derive(Debug, Default, Serialize, Deserialize)]
73pub struct BulkResult {
74    pub succeeded: Vec<String>,
75    pub failed: Vec<BulkFailure>,
76}
77
78#[must_use]
79pub fn bulk_failure(id: &str, code: &str, message: impl Into<String>) -> BulkFailure {
80    BulkFailure {
81        id: id.to_owned(),
82        code: code.to_owned(),
83        message: message.into(),
84    }
85}
86
87#[must_use]
88pub const fn bulk_request_size_is_valid(ids: usize, expected_revisions: usize) -> bool {
89    ids > 0 && ids <= MAX_BULK_ITEMS && expected_revisions <= MAX_BULK_ITEMS
90}
91
92#[must_use]
93pub fn encode_cursor(value: &str) -> String {
94    base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(format!("v1:{value}"))
95}
96
97#[must_use]
98pub fn decode_cursor(cursor: &str) -> Option<String> {
99    base64::engine::general_purpose::URL_SAFE_NO_PAD
100        .decode(cursor)
101        .ok()
102        .and_then(|bytes| String::from_utf8(bytes).ok())
103        .and_then(|value| value.strip_prefix("v1:").map(str::to_owned))
104        .filter(|value| !value.is_empty())
105}
106
107#[must_use]
108pub fn parse_revision_etag(value: &str) -> Option<i64> {
109    value
110        .strip_prefix("\"rev-")
111        .and_then(|value| value.strip_suffix('"'))
112        .and_then(|value| value.parse().ok())
113        .filter(|value| *value >= 1)
114}
115
116#[must_use]
117pub fn revision_etag(revision: i64) -> String {
118    format!("\"rev-{revision}\"")
119}
120
121#[must_use]
122pub fn csv_escape(value: &str) -> String {
123    if value.contains([',', '"', '\n', '\r']) {
124        format!("\"{}\"", value.replace('"', "\"\""))
125    } else {
126        value.to_owned()
127    }
128}
129
130#[must_use]
131pub fn csv_cell(value: &serde_json::Value) -> String {
132    match value {
133        serde_json::Value::Null => String::new(),
134        serde_json::Value::String(value) => value.clone(),
135        serde_json::Value::Bool(value) => value.to_string(),
136        serde_json::Value::Number(value) => value.to_string(),
137        serde_json::Value::Array(_) | serde_json::Value::Object(_) => value.to_string(),
138    }
139}
140
141#[derive(Clone, Copy, Debug, PartialEq, Eq)]
142pub struct CsvError;
143
144impl fmt::Display for CsvError {
145    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
146        formatter.write_str("CSV contains an unterminated quote")
147    }
148}
149
150impl Error for CsvError {}
151
152/// Parses CSV input into rows and decoded field values.
153///
154/// # Errors
155///
156/// Returns [`CsvError`] for an invalid or unterminated quoted field.
157pub fn parse_csv_rows(body: &str) -> Result<Vec<Vec<String>>, CsvError> {
158    let mut rows = Vec::new();
159    let mut row = Vec::new();
160    let mut value = String::new();
161    let mut quoted = false;
162    let mut closed = false;
163    let mut characters = body.trim_start_matches('\u{feff}').chars().peekable();
164    while let Some(character) = characters.next() {
165        if quoted {
166            if character == '"' {
167                if characters.peek() == Some(&'"') {
168                    value.push('"');
169                    characters.next();
170                } else {
171                    quoted = false;
172                    closed = true;
173                }
174            } else {
175                value.push(character);
176            }
177        } else {
178            match character {
179                ',' => {
180                    row.push(std::mem::take(&mut value));
181                    closed = false;
182                }
183                '\n' | '\r' => {
184                    if character == '\r' && characters.peek() == Some(&'\n') {
185                        characters.next();
186                    }
187                    row.push(std::mem::take(&mut value));
188                    if row.len() > 1 || !row[0].is_empty() {
189                        rows.push(std::mem::take(&mut row));
190                    } else {
191                        row.clear();
192                    }
193                    closed = false;
194                }
195                '"' if value.is_empty() && !closed => quoted = true,
196                '"' => return Err(CsvError),
197                _ if closed => return Err(CsvError),
198                _ => value.push(character),
199            }
200        }
201    }
202    if quoted {
203        return Err(CsvError);
204    }
205    if !value.is_empty() || !row.is_empty() || closed {
206        row.push(value);
207        if row.len() > 1 || !row[0].is_empty() {
208            rows.push(row);
209        }
210    }
211    Ok(rows)
212}
213
214#[must_use]
215pub fn csv_json_value(value: &str, kind: &str) -> serde_json::Value {
216    if value.is_empty() {
217        return serde_json::Value::Null;
218    }
219    match kind {
220        "boolean" => value.parse::<bool>().map_or_else(
221            |_| serde_json::Value::String(value.to_owned()),
222            serde_json::Value::Bool,
223        ),
224        "integer" => value.parse::<i32>().map_or_else(
225            |_| serde_json::Value::String(value.to_owned()),
226            |value| serde_json::json!(value),
227        ),
228        "bigint" => value.parse::<i64>().map_or_else(
229            |_| serde_json::Value::String(value.to_owned()),
230            |value| serde_json::json!(value),
231        ),
232        _ => serde_json::Value::String(value.to_owned()),
233    }
234}
235
236#[cfg(test)]
237mod tests {
238    use super::*;
239
240    #[test]
241    fn cursor_round_trips_and_rejects_other_versions() {
242        let cursor = encode_cursor("018f");
243        assert_eq!(decode_cursor(&cursor).as_deref(), Some("018f"));
244        let wrong_version = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode("v2:018f");
245        assert_eq!(decode_cursor(&wrong_version), None);
246    }
247
248    #[test]
249    fn revision_etags_are_strict() {
250        assert_eq!(parse_revision_etag(&revision_etag(7)), Some(7));
251        assert_eq!(parse_revision_etag("rev-7"), None);
252        assert_eq!(parse_revision_etag("\"rev-0\""), None);
253    }
254
255    #[test]
256    fn csv_parser_handles_escaped_quotes_and_newlines() {
257        let rows = parse_csv_rows("name,note\nAda,\"one, \"\"two\"\"\"\n").unwrap();
258        assert_eq!(rows[1], ["Ada", "one, \"two\""]);
259        assert!(parse_csv_rows("name\n\"unterminated").is_err());
260    }
261
262    #[test]
263    fn csv_parser_handles_bom_empty_lines_crlf_and_rejects_invalid_quotes() {
264        let rows =
265            parse_csv_rows("\u{feff}\r\nname,note\r\nAda,\"line\r\nnext\"\r\n\r\n,,\r\n").unwrap();
266        assert_eq!(
267            rows,
268            vec![
269                vec!["name", "note"],
270                vec!["Ada", "line\r\nnext"],
271                vec!["", "", ""]
272            ]
273        );
274        assert!(parse_csv_rows("name\n\"closed\"extra").is_err());
275        assert!(parse_csv_rows("name\ninvalid\"quote").is_err());
276    }
277
278    #[test]
279    fn bulk_request_size_is_bounded() {
280        assert!(bulk_request_size_is_valid(1, 1));
281        assert!(bulk_request_size_is_valid(MAX_BULK_ITEMS, MAX_BULK_ITEMS));
282        assert!(!bulk_request_size_is_valid(0, 0));
283        assert!(!bulk_request_size_is_valid(MAX_BULK_ITEMS + 1, 1));
284        assert!(!bulk_request_size_is_valid(1, MAX_BULK_ITEMS + 1));
285    }
286
287    #[test]
288    fn csv_helpers_cover_escaping_json_coercion_and_errors() {
289        assert_eq!(csv_escape("plain"), "plain");
290        assert_eq!(csv_escape("a,b"), "\"a,b\"");
291        assert_eq!(csv_escape("say \"hi\""), "\"say \"\"hi\"\"\"");
292        assert_eq!(csv_cell(&serde_json::Value::Null), "");
293        assert_eq!(
294            csv_cell(&serde_json::json!("say \"hi\"\nnext")),
295            "say \"hi\"\nnext"
296        );
297        assert_eq!(csv_cell(&serde_json::json!(true)), "true");
298        assert_eq!(csv_cell(&serde_json::json!(12.5)), "12.5");
299        assert_eq!(csv_cell(&serde_json::json!(["one", 2])), "[\"one\",2]");
300        assert_eq!(csv_json_value("", "string"), serde_json::Value::Null);
301        assert_eq!(csv_json_value("true", "boolean"), serde_json::json!(true));
302        assert_eq!(csv_json_value("nope", "boolean"), serde_json::json!("nope"));
303        assert_eq!(csv_json_value("12", "integer"), serde_json::json!(12));
304        assert_eq!(csv_json_value("12", "bigint"), serde_json::json!(12));
305        assert_eq!(csv_json_value("x", "text"), serde_json::json!("x"));
306        assert_eq!(CsvError.to_string(), "CSV contains an unterminated quote");
307        let rows = parse_csv_rows("one,two\r\n").unwrap();
308        assert_eq!(rows[0], ["one", "two"]);
309        assert_eq!(decode_cursor(""), None);
310        assert_eq!(bulk_failure("1", "AS1", "nope").code, "AS1");
311    }
312}