1use 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(¶ms)
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(¶ms),
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(¶ms),
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(¶ms).is_ok());
171 let params = BTreeMap::from([(String::from("name[eq]"), String::from("x"))]);
172 assert!(QueryBuilder::new(["name;drop"]).parse(¶ms).is_err());
173 }
174}