gobby_code/graph/
typed_query.rs

1use std::collections::{BTreeMap, HashMap};
2use std::fmt;
3
4use serde::{Deserialize, Serialize};
5
6#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
7pub struct TypedQuery {
8    pub cypher: String,
9    pub params: HashMap<String, String>,
10}
11
12#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
13pub enum TypedValue {
14    Null,
15    String(String),
16    Integer(i64),
17    Float(f64),
18    Bool(bool),
19    List(Vec<TypedValue>),
20    Map(BTreeMap<String, TypedValue>),
21}
22
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
24pub enum IdentifierKind {
25    ParameterName,
26    MapKey,
27}
28
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub enum ValueContext {
31    String,
32}
33
34#[derive(Debug, Clone, PartialEq, Eq)]
35pub enum TypedQueryError {
36    InvalidIdentifier {
37        kind: IdentifierKind,
38        identifier: String,
39    },
40    ControlCharacter {
41        context: ValueContext,
42        codepoint: u32,
43    },
44    NonFiniteFloat {
45        value: String,
46    },
47}
48
49impl TypedQuery {
50    pub fn new(cypher: impl Into<String>) -> Self {
51        Self {
52            cypher: cypher.into(),
53            params: HashMap::new(),
54        }
55    }
56
57    pub fn with_params<I, K>(cypher: impl Into<String>, params: I) -> Result<Self, TypedQueryError>
58    where
59        I: IntoIterator<Item = (K, TypedValue)>,
60        K: Into<String>,
61    {
62        let mut query = Self::new(cypher);
63        for (name, value) in params {
64            query.insert_param(name, value)?;
65        }
66        Ok(query)
67    }
68
69    pub fn insert_param(
70        &mut self,
71        name: impl Into<String>,
72        value: TypedValue,
73    ) -> Result<(), TypedQueryError> {
74        let name = name.into();
75        validate_identifier(&name, IdentifierKind::ParameterName)?;
76        let rendered = render_cypher_value(&value)?;
77        self.params.insert(name, rendered);
78        Ok(())
79    }
80}
81
82pub fn cypher_string_literal(s: &str) -> String {
83    format!("'{}'", escape_string_contents(s))
84}
85
86pub fn render_cypher_value(value: &TypedValue) -> Result<String, TypedQueryError> {
87    match value {
88        TypedValue::Null => Ok("null".to_string()),
89        TypedValue::String(value) => render_string_literal(value),
90        TypedValue::Integer(value) => Ok(value.to_string()),
91        TypedValue::Float(value) => render_float(*value),
92        TypedValue::Bool(value) => Ok(value.to_string()),
93        TypedValue::List(values) => values
94            .iter()
95            .map(render_cypher_value)
96            .collect::<Result<Vec<_>, _>>()
97            .map(|values| format!("[{}]", values.join(", "))),
98        TypedValue::Map(values) => values
99            .iter()
100            .map(|(key, value)| {
101                validate_identifier(key, IdentifierKind::MapKey)?;
102                Ok(format!("{key}: {}", render_cypher_value(value)?))
103            })
104            .collect::<Result<Vec<_>, _>>()
105            .map(|values| format!("{{{}}}", values.join(", "))),
106    }
107}
108
109pub fn string_params(values: &[(&str, &str)]) -> HashMap<String, String> {
110    values
111        .iter()
112        .map(|(key, value)| ((*key).to_string(), cypher_string_literal(value)))
113        .collect()
114}
115
116pub fn clamp_limit(limit: usize, max: usize) -> usize {
117    limit.clamp(1, max)
118}
119
120pub fn clamp_offset(offset: usize, max: usize) -> usize {
121    offset.min(max)
122}
123
124pub fn id_list_literal(ids: &[String]) -> String {
125    ids.iter()
126        .map(|id| cypher_string_literal(id))
127        .collect::<Vec<_>>()
128        .join(", ")
129}
130
131pub fn validate_identifier(identifier: &str, kind: IdentifierKind) -> Result<(), TypedQueryError> {
132    let mut chars = identifier.chars();
133    let Some(first) = chars.next() else {
134        return Err(TypedQueryError::InvalidIdentifier {
135            kind,
136            identifier: identifier.to_string(),
137        });
138    };
139
140    if !(first == '_' || first.is_ascii_alphabetic())
141        || !chars.all(|ch| ch == '_' || ch.is_ascii_alphanumeric())
142    {
143        return Err(TypedQueryError::InvalidIdentifier {
144            kind,
145            identifier: identifier.to_string(),
146        });
147    }
148
149    Ok(())
150}
151
152fn render_string_literal(value: &str) -> Result<String, TypedQueryError> {
153    reject_control_characters(value, ValueContext::String)?;
154    Ok(cypher_string_literal(value))
155}
156
157fn reject_control_characters(value: &str, context: ValueContext) -> Result<(), TypedQueryError> {
158    if let Some(ch) = value.chars().find(|ch| ch.is_control()) {
159        return Err(TypedQueryError::ControlCharacter {
160            context,
161            codepoint: ch as u32,
162        });
163    }
164    Ok(())
165}
166
167fn escape_string_contents(value: &str) -> String {
168    value
169        .replace('\\', "\\\\")
170        .replace('\'', "\\'")
171        .replace('"', "\\\"")
172}
173
174fn render_float(value: f64) -> Result<String, TypedQueryError> {
175    if !value.is_finite() {
176        return Err(TypedQueryError::NonFiniteFloat {
177            value: value.to_string(),
178        });
179    }
180
181    let mut rendered = value.to_string();
182    if !rendered.contains('.') && !rendered.contains('e') && !rendered.contains('E') {
183        rendered.push_str(".0");
184    }
185    Ok(rendered)
186}
187
188impl fmt::Display for IdentifierKind {
189    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
190        match self {
191            Self::ParameterName => f.write_str("parameter name"),
192            Self::MapKey => f.write_str("map key"),
193        }
194    }
195}
196
197impl fmt::Display for ValueContext {
198    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
199        match self {
200            Self::String => f.write_str("string"),
201        }
202    }
203}
204
205impl fmt::Display for TypedQueryError {
206    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
207        match self {
208            Self::InvalidIdentifier { kind, identifier } => write!(
209                f,
210                "invalid {kind} `{identifier}`; expected ^[A-Za-z_][A-Za-z0-9_]*$"
211            ),
212            Self::ControlCharacter { context, codepoint } => write!(
213                f,
214                "control character U+{codepoint:04X} is not allowed in {context} value"
215            ),
216            Self::NonFiniteFloat { value } => {
217                write!(f, "non-finite float `{value}` is not allowed")
218            }
219        }
220    }
221}
222
223impl std::error::Error for TypedQueryError {}
224
225#[cfg(test)]
226mod tests {
227    use super::*;
228    use std::collections::BTreeMap;
229
230    #[test]
231    fn typed_params_render_nested_safe_cypher_literals() {
232        let mut props = BTreeMap::new();
233        props.insert("enabled".to_string(), TypedValue::Bool(true));
234        props.insert(
235            "label".to_string(),
236            TypedValue::String("caf\u{00e9} \"quote\" and 'single' \\ slash".to_string()),
237        );
238        props.insert(
239            "nested".to_string(),
240            TypedValue::List(vec![
241                TypedValue::Integer(1),
242                TypedValue::Float(2.25),
243                TypedValue::Bool(false),
244            ]),
245        );
246
247        let query = TypedQuery::with_params(
248            "RETURN $name, $count, $ratio, $whole, $enabled, $items, $props",
249            [
250                (
251                    "name",
252                    TypedValue::String("O'Reilly \\ path \u{2603}".to_string()),
253                ),
254                ("count", TypedValue::Integer(42)),
255                ("ratio", TypedValue::Float(1.5)),
256                ("whole", TypedValue::Float(1.0)),
257                ("enabled", TypedValue::Bool(true)),
258                (
259                    "items",
260                    TypedValue::List(vec![
261                        TypedValue::String("a".to_string()),
262                        TypedValue::Integer(-7),
263                        TypedValue::Bool(false),
264                    ]),
265                ),
266                ("props", TypedValue::Map(props)),
267            ],
268        )
269        .expect("valid typed params should render");
270
271        assert_eq!(
272            query.cypher,
273            "RETURN $name, $count, $ratio, $whole, $enabled, $items, $props"
274        );
275        assert_eq!(
276            query.params.get("name").map(String::as_str),
277            Some("'O\\'Reilly \\\\ path \u{2603}'")
278        );
279        assert_eq!(query.params.get("count").map(String::as_str), Some("42"));
280        assert_eq!(query.params.get("ratio").map(String::as_str), Some("1.5"));
281        assert_eq!(query.params.get("whole").map(String::as_str), Some("1.0"));
282        assert_eq!(
283            query.params.get("enabled").map(String::as_str),
284            Some("true")
285        );
286        assert_eq!(
287            query.params.get("items").map(String::as_str),
288            Some("['a', -7, false]")
289        );
290        assert_eq!(
291            query.params.get("props").map(String::as_str),
292            Some(
293                "{enabled: true, label: 'caf\u{00e9} \\\"quote\\\" and \\'single\\' \\\\ slash', nested: [1, 2.25, false]}"
294            )
295        );
296    }
297
298    #[test]
299    fn string_literals_escape_both_quote_delimiters() {
300        let rendered = render_cypher_value(&TypedValue::String("a 'single' and \"double\"".into()))
301            .expect("valid string should render");
302
303        assert_eq!(rendered, "'a \\'single\\' and \\\"double\\\"'");
304    }
305
306    #[test]
307    fn invalid_identifiers_return_typed_errors() {
308        let param_error =
309            TypedQuery::with_params("RETURN $bad", [("bad-name", TypedValue::Bool(true))])
310                .expect_err("invalid parameter name should fail");
311        assert_eq!(
312            param_error,
313            TypedQueryError::InvalidIdentifier {
314                kind: IdentifierKind::ParameterName,
315                identifier: "bad-name".to_string(),
316            }
317        );
318
319        let mut props = BTreeMap::new();
320        props.insert("bad.key".to_string(), TypedValue::Integer(1));
321        let map_error =
322            render_cypher_value(&TypedValue::Map(props)).expect_err("invalid map key should fail");
323        assert_eq!(
324            map_error,
325            TypedQueryError::InvalidIdentifier {
326                kind: IdentifierKind::MapKey,
327                identifier: "bad.key".to_string(),
328            }
329        );
330    }
331
332    #[test]
333    fn unsafe_values_return_typed_errors() {
334        let control_error = TypedQuery::with_params(
335            "RETURN $name",
336            [("name", TypedValue::String("line\nbreak".to_string()))],
337        )
338        .expect_err("control characters should fail");
339        assert!(matches!(
340            control_error,
341            TypedQueryError::ControlCharacter {
342                context: ValueContext::String,
343                ..
344            }
345        ));
346
347        for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
348            let error = render_cypher_value(&TypedValue::Float(value))
349                .expect_err("non-finite float should fail");
350            assert!(matches!(error, TypedQueryError::NonFiniteFloat { .. }));
351        }
352    }
353}
gobby_code/graph/typed_query.rs

gobby_code/graph/
typed_query.rs
