Skip to main content

yaiko_core/
search.rs

1//! Safe query filtering and sorting primitives.
2
3use std::collections::{BTreeMap, BTreeSet};
4
5#[derive(Debug, Clone, PartialEq, Eq)]
6pub enum FilterOperator {
7    Eq,
8    Ne,
9    Gt,
10    Gte,
11    Lt,
12    Lte,
13    Contains,
14    Prefix,
15}
16
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub struct Filter {
19    pub field: String,
20    pub operator: FilterOperator,
21    pub value: String,
22}
23
24#[derive(Debug, Clone, PartialEq, Eq)]
25pub struct SortField {
26    pub field: String,
27    pub descending: bool,
28}
29
30#[derive(Debug, Clone, PartialEq, Eq)]
31pub struct QuerySpec {
32    pub filters: Vec<Filter>,
33    pub sort: Vec<SortField>,
34    pub limit: Option<usize>,
35    pub cursor: Option<String>,
36}
37
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub enum QueryError {
40    InvalidFilter,
41    UnsupportedOperator,
42    InvalidSortField,
43    InvalidLimit,
44    InvalidParameter,
45}
46
47#[derive(Debug, Clone, Default)]
48pub struct QueryBuilder {
49    allowed_fields: BTreeSet<String>,
50    filters: Vec<Filter>,
51    sort: Vec<SortField>,
52    limit: Option<usize>,
53    cursor: Option<String>,
54}
55
56impl QueryBuilder {
57    pub fn new(allowed_fields: impl IntoIterator<Item = impl Into<String>>) -> Self {
58        Self {
59            allowed_fields: allowed_fields.into_iter().map(Into::into).collect(),
60            ..Self::default()
61        }
62    }
63    pub fn parse(mut self, params: &BTreeMap<String, String>) -> Result<QuerySpec, QueryError> {
64        for (key, value) in params {
65            if key == "sort" {
66                self.parse_sort(value)?;
67            } else if key == "limit" {
68                self.limit = Some(value.parse().map_err(|_| QueryError::InvalidLimit)?);
69            } else if key == "cursor" {
70                self.cursor = Some(value.clone());
71            } else if let Some((field, operator)) = parse_filter_key(key) {
72                self.filters.push(Filter {
73                    field: self.checked_field(field)?,
74                    operator,
75                    value: value.clone(),
76                });
77            } else {
78                return Err(QueryError::InvalidParameter);
79            }
80        }
81        Ok(QuerySpec {
82            filters: self.filters,
83            sort: self.sort,
84            limit: self.limit,
85            cursor: self.cursor,
86        })
87    }
88
89    fn parse_sort(&mut self, value: &str) -> Result<(), QueryError> {
90        for raw in value.split(',').filter(|part| !part.trim().is_empty()) {
91            let raw = raw.trim();
92            let descending = raw.starts_with('-');
93            let field = raw.trim_start_matches('-');
94            self.sort.push(SortField {
95                field: self.checked_field(field)?,
96                descending,
97            });
98        }
99        Ok(())
100    }
101
102    fn checked_field(&self, field: &str) -> Result<String, QueryError> {
103        if self.allowed_fields.contains(field)
104            && field
105                .chars()
106                .all(|character| character.is_ascii_alphanumeric() || character == '_')
107        {
108            Ok(field.to_string())
109        } else {
110            Err(QueryError::InvalidSortField)
111        }
112    }
113}
114
115fn parse_filter_key(key: &str) -> Option<(&str, FilterOperator)> {
116    let (field, operator) = key.split_once('[')?;
117    let operator = operator.strip_suffix(']')?;
118    let operator = match operator {
119        "eq" => FilterOperator::Eq,
120        "ne" => FilterOperator::Ne,
121        "gt" => FilterOperator::Gt,
122        "gte" => FilterOperator::Gte,
123        "lt" => FilterOperator::Lt,
124        "lte" => FilterOperator::Lte,
125        "contains" => FilterOperator::Contains,
126        "prefix" => FilterOperator::Prefix,
127        _ => return None,
128    };
129    Some((field, operator))
130}
131
132#[cfg(test)]
133mod tests {
134    use super::*;
135
136    #[test]
137    fn parses_filters_sorts_limits_and_cursor() {
138        let params = BTreeMap::from([
139            (String::from("name[contains]"), String::from("Ada")),
140            (String::from("sort"), String::from("-created_at,name")),
141            (String::from("limit"), String::from("25")),
142            (String::from("cursor"), String::from("opaque")),
143        ]);
144        let query = QueryBuilder::new(["name", "created_at"])
145            .parse(&params)
146            .unwrap();
147        assert_eq!(query.filters[0].operator, FilterOperator::Contains);
148        assert!(query.sort[0].descending);
149        assert_eq!(query.limit, Some(25));
150        assert_eq!(query.cursor.as_deref(), Some("opaque"));
151    }
152
153    #[test]
154    fn rejects_unallowlisted_fields_and_malformed_parameters() {
155        let params = BTreeMap::from([(String::from("sort"), String::from("password"))]);
156        assert_eq!(
157            QueryBuilder::new(["name"]).parse(&params),
158            Err(QueryError::InvalidSortField)
159        );
160        let params = BTreeMap::from([(String::from("name[unknown]"), String::from("x"))]);
161        assert_eq!(
162            QueryBuilder::new(["name"]).parse(&params),
163            Err(QueryError::InvalidParameter)
164        );
165    }
166
167    #[test]
168    fn accepts_only_safe_field_identifiers() {
169        let params = BTreeMap::from([(String::from("name[eq]"), String::from("x"))]);
170        assert!(QueryBuilder::new(["name"]).parse(&params).is_ok());
171        let params = BTreeMap::from([(String::from("name[eq]"), String::from("x"))]);
172        assert!(QueryBuilder::new(["name;drop"]).parse(&params).is_err());
173    }
174}