appstruct-core 0.2.0

Pure naming, query, and resource algorithms shared by AppStruct tools and generated backends
Documentation
// Shared resource protocol types and parsing helpers.

use base64::Engine as _;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::error::Error;
use std::fmt;

pub const MAX_BULK_ITEMS: usize = 100;
pub const MAX_CSV_IMPORT_ROWS: usize = 10_000;
pub const MAX_CSV_EXPORT_ROWS: u64 = 10_000;
pub const CSV_EXPORT_PAGE_SIZE: u64 = 500;

#[derive(Debug, Default, Deserialize)]
pub struct ListQuery {
    pub page: Option<u64>,
    pub page_size: Option<u64>,
    pub cursor: Option<String>,
    pub limit: Option<u64>,
    pub direction: Option<String>,
    pub sort: Option<String>,
    pub q: Option<String>,
    #[serde(rename = "where")]
    pub expression: Option<String>,
    pub fields: Option<String>,
    #[serde(flatten)]
    pub filters: BTreeMap<String, String>,
}

#[derive(Debug, Serialize)]
#[serde(untagged)]
pub enum ListMeta {
    Page {
        page: u64,
        page_size: u64,
        total: u64,
    },
    Cursor {
        limit: u64,
        next_cursor: Option<String>,
        previous_cursor: Option<String>,
        has_more: bool,
    },
}

#[derive(Debug, Serialize)]
pub struct ListResponse<T> {
    pub data: Vec<T>,
    pub meta: ListMeta,
}

#[derive(Clone, Debug, Deserialize)]
pub struct BulkUpdateInput<T> {
    pub ids: Vec<String>,
    pub patch: T,
    pub expected_revisions: BTreeMap<String, i64>,
}

#[derive(Debug, Deserialize)]
pub struct BulkDeleteInput {
    pub ids: Vec<String>,
    pub expected_revisions: BTreeMap<String, i64>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct BulkFailure {
    pub id: String,
    pub code: String,
    pub message: String,
}

#[derive(Debug, Default, Serialize, Deserialize)]
pub struct BulkResult {
    pub succeeded: Vec<String>,
    pub failed: Vec<BulkFailure>,
}

#[must_use]
pub fn bulk_failure(id: &str, code: &str, message: impl Into<String>) -> BulkFailure {
    BulkFailure {
        id: id.to_owned(),
        code: code.to_owned(),
        message: message.into(),
    }
}

#[must_use]
pub const fn bulk_request_size_is_valid(ids: usize, expected_revisions: usize) -> bool {
    ids > 0 && ids <= MAX_BULK_ITEMS && expected_revisions <= MAX_BULK_ITEMS
}

#[must_use]
pub fn encode_cursor(value: &str) -> String {
    base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(format!("v1:{value}"))
}

#[must_use]
pub fn decode_cursor(cursor: &str) -> Option<String> {
    base64::engine::general_purpose::URL_SAFE_NO_PAD
        .decode(cursor)
        .ok()
        .and_then(|bytes| String::from_utf8(bytes).ok())
        .and_then(|value| value.strip_prefix("v1:").map(str::to_owned))
        .filter(|value| !value.is_empty())
}

#[must_use]
pub fn parse_revision_etag(value: &str) -> Option<i64> {
    value
        .strip_prefix("\"rev-")
        .and_then(|value| value.strip_suffix('"'))
        .and_then(|value| value.parse().ok())
        .filter(|value| *value >= 1)
}

#[must_use]
pub fn revision_etag(revision: i64) -> String {
    format!("\"rev-{revision}\"")
}

#[must_use]
pub fn csv_escape(value: &str) -> String {
    if value.contains([',', '"', '\n', '\r']) {
        format!("\"{}\"", value.replace('"', "\"\""))
    } else {
        value.to_owned()
    }
}

#[must_use]
pub fn csv_cell(value: &serde_json::Value) -> String {
    match value {
        serde_json::Value::Null => String::new(),
        serde_json::Value::String(value) => value.clone(),
        serde_json::Value::Bool(value) => value.to_string(),
        serde_json::Value::Number(value) => value.to_string(),
        serde_json::Value::Array(_) | serde_json::Value::Object(_) => value.to_string(),
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct CsvError;

impl fmt::Display for CsvError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("CSV contains an unterminated quote")
    }
}

impl Error for CsvError {}

/// Parses CSV input into rows and decoded field values.
///
/// # Errors
///
/// Returns [`CsvError`] for an invalid or unterminated quoted field.
pub fn parse_csv_rows(body: &str) -> Result<Vec<Vec<String>>, CsvError> {
    let mut rows = Vec::new();
    let mut row = Vec::new();
    let mut value = String::new();
    let mut quoted = false;
    let mut closed = false;
    let mut characters = body.trim_start_matches('\u{feff}').chars().peekable();
    while let Some(character) = characters.next() {
        if quoted {
            if character == '"' {
                if characters.peek() == Some(&'"') {
                    value.push('"');
                    characters.next();
                } else {
                    quoted = false;
                    closed = true;
                }
            } else {
                value.push(character);
            }
        } else {
            match character {
                ',' => {
                    row.push(std::mem::take(&mut value));
                    closed = false;
                }
                '\n' | '\r' => {
                    if character == '\r' && characters.peek() == Some(&'\n') {
                        characters.next();
                    }
                    row.push(std::mem::take(&mut value));
                    if row.len() > 1 || !row[0].is_empty() {
                        rows.push(std::mem::take(&mut row));
                    } else {
                        row.clear();
                    }
                    closed = false;
                }
                '"' if value.is_empty() && !closed => quoted = true,
                '"' => return Err(CsvError),
                _ if closed => return Err(CsvError),
                _ => value.push(character),
            }
        }
    }
    if quoted {
        return Err(CsvError);
    }
    if !value.is_empty() || !row.is_empty() || closed {
        row.push(value);
        if row.len() > 1 || !row[0].is_empty() {
            rows.push(row);
        }
    }
    Ok(rows)
}

#[must_use]
pub fn csv_json_value(value: &str, kind: &str) -> serde_json::Value {
    if value.is_empty() {
        return serde_json::Value::Null;
    }
    match kind {
        "boolean" => value.parse::<bool>().map_or_else(
            |_| serde_json::Value::String(value.to_owned()),
            serde_json::Value::Bool,
        ),
        "integer" => value.parse::<i32>().map_or_else(
            |_| serde_json::Value::String(value.to_owned()),
            |value| serde_json::json!(value),
        ),
        "bigint" => value.parse::<i64>().map_or_else(
            |_| serde_json::Value::String(value.to_owned()),
            |value| serde_json::json!(value),
        ),
        _ => serde_json::Value::String(value.to_owned()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn cursor_round_trips_and_rejects_other_versions() {
        let cursor = encode_cursor("018f");
        assert_eq!(decode_cursor(&cursor).as_deref(), Some("018f"));
        let wrong_version = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode("v2:018f");
        assert_eq!(decode_cursor(&wrong_version), None);
    }

    #[test]
    fn revision_etags_are_strict() {
        assert_eq!(parse_revision_etag(&revision_etag(7)), Some(7));
        assert_eq!(parse_revision_etag("rev-7"), None);
        assert_eq!(parse_revision_etag("\"rev-0\""), None);
    }

    #[test]
    fn csv_parser_handles_escaped_quotes_and_newlines() {
        let rows = parse_csv_rows("name,note\nAda,\"one, \"\"two\"\"\"\n").unwrap();
        assert_eq!(rows[1], ["Ada", "one, \"two\""]);
        assert!(parse_csv_rows("name\n\"unterminated").is_err());
    }

    #[test]
    fn csv_parser_handles_bom_empty_lines_crlf_and_rejects_invalid_quotes() {
        let rows =
            parse_csv_rows("\u{feff}\r\nname,note\r\nAda,\"line\r\nnext\"\r\n\r\n,,\r\n").unwrap();
        assert_eq!(
            rows,
            vec![
                vec!["name", "note"],
                vec!["Ada", "line\r\nnext"],
                vec!["", "", ""]
            ]
        );
        assert!(parse_csv_rows("name\n\"closed\"extra").is_err());
        assert!(parse_csv_rows("name\ninvalid\"quote").is_err());
    }

    #[test]
    fn bulk_request_size_is_bounded() {
        assert!(bulk_request_size_is_valid(1, 1));
        assert!(bulk_request_size_is_valid(MAX_BULK_ITEMS, MAX_BULK_ITEMS));
        assert!(!bulk_request_size_is_valid(0, 0));
        assert!(!bulk_request_size_is_valid(MAX_BULK_ITEMS + 1, 1));
        assert!(!bulk_request_size_is_valid(1, MAX_BULK_ITEMS + 1));
    }

    #[test]
    fn csv_helpers_cover_escaping_json_coercion_and_errors() {
        assert_eq!(csv_escape("plain"), "plain");
        assert_eq!(csv_escape("a,b"), "\"a,b\"");
        assert_eq!(csv_escape("say \"hi\""), "\"say \"\"hi\"\"\"");
        assert_eq!(csv_cell(&serde_json::Value::Null), "");
        assert_eq!(
            csv_cell(&serde_json::json!("say \"hi\"\nnext")),
            "say \"hi\"\nnext"
        );
        assert_eq!(csv_cell(&serde_json::json!(true)), "true");
        assert_eq!(csv_cell(&serde_json::json!(12.5)), "12.5");
        assert_eq!(csv_cell(&serde_json::json!(["one", 2])), "[\"one\",2]");
        assert_eq!(csv_json_value("", "string"), serde_json::Value::Null);
        assert_eq!(csv_json_value("true", "boolean"), serde_json::json!(true));
        assert_eq!(csv_json_value("nope", "boolean"), serde_json::json!("nope"));
        assert_eq!(csv_json_value("12", "integer"), serde_json::json!(12));
        assert_eq!(csv_json_value("12", "bigint"), serde_json::json!(12));
        assert_eq!(csv_json_value("x", "text"), serde_json::json!("x"));
        assert_eq!(CsvError.to_string(), "CSV contains an unterminated quote");
        let rows = parse_csv_rows("one,two\r\n").unwrap();
        assert_eq!(rows[0], ["one", "two"]);
        assert_eq!(decode_cursor(""), None);
        assert_eq!(bulk_failure("1", "AS1", "nope").code, "AS1");
    }
}