littlegraph-query-api 0.2.1

Neo4j-compatible HTTP Query API for the littlegraph database
Documentation
use std::collections::BTreeMap;
use std::time::Duration;

use littlegraph_core::{Params, TransactionOptions, Value};
use serde::{Deserialize, Deserializer};

use crate::error::HttpError;
use crate::QueryApiLimits;

#[derive(Clone, Debug, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub(crate) struct QueryRequest {
    pub(crate) statement: Option<String>,
    #[serde(default, deserialize_with = "deserialize_null_default")]
    parameters: BTreeMap<String, serde_json::Value>,
    #[allow(dead_code)]
    #[serde(default, deserialize_with = "deserialize_null_default")]
    pub(crate) include_counters: bool,
    pub(crate) access_mode: Option<AccessMode>,
    #[serde(default, deserialize_with = "deserialize_null_default")]
    pub(crate) max_execution_time: i32,
    #[serde(default, deserialize_with = "deserialize_null_default")]
    bookmarks: Vec<String>,
    pub(crate) impersonated_user: Option<String>,
    pub(crate) tx_type: Option<String>,
    pub(crate) tx_metadata: Option<BTreeMap<String, serde_json::Value>>,
    #[serde(skip)]
    pub(crate) typed_parameters: bool,
}

fn deserialize_null_default<'de, D, T>(deserializer: D) -> std::result::Result<T, D::Error>
where
    D: Deserializer<'de>,
    T: Deserialize<'de> + Default,
{
    Ok(Option::<T>::deserialize(deserializer)?.unwrap_or_default())
}

#[derive(Clone, Copy, Debug)]
pub(crate) enum AccessMode {
    Read,
    Write,
}

impl<'de> Deserialize<'de> for AccessMode {
    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let value = String::deserialize(deserializer)?;
        if value.eq_ignore_ascii_case("READ") {
            Ok(Self::Read)
        } else if value.eq_ignore_ascii_case("WRITE") {
            Ok(Self::Write)
        } else {
            Err(serde::de::Error::unknown_variant(
                &value,
                &["READ", "WRITE"],
            ))
        }
    }
}

impl QueryRequest {
    pub(crate) fn validate_extensions(&self) -> std::result::Result<(), HttpError> {
        if !self.bookmarks.is_empty() {
            return Err(HttpError::invalid(
                "bookmarks are not supported by this littlegraph server",
            ));
        }
        if self
            .impersonated_user
            .as_deref()
            .is_some_and(|user| !user.trim().is_empty())
        {
            return Err(HttpError::invalid(
                "impersonatedUser is not supported by this littlegraph server",
            ));
        }
        if self
            .tx_type
            .as_deref()
            .is_some_and(|tx_type| !tx_type.trim().is_empty())
        {
            return Err(HttpError::invalid(
                "txType is not supported by this littlegraph server",
            ));
        }
        if self
            .tx_metadata
            .as_ref()
            .is_some_and(|value| !value.is_empty())
        {
            return Err(HttpError::invalid(
                "txMetadata is not supported by this littlegraph server",
            ));
        }
        Ok(())
    }

    pub(crate) fn statement_required(&self) -> std::result::Result<&str, HttpError> {
        self.statement
            .as_deref()
            .filter(|statement| !statement.is_empty())
            .ok_or_else(|| HttpError::invalid("statement cannot be null or empty"))
    }

    pub(crate) fn params(&self) -> std::result::Result<Params, HttpError> {
        self.parameters
            .iter()
            .map(|(key, value)| {
                decode_parameter(value.clone(), self.typed_parameters)
                    .map(|value| (key.clone(), value))
            })
            .collect()
    }

    pub(crate) fn options(&self, limits: &QueryApiLimits) -> TransactionOptions {
        let requested = (self.max_execution_time > 0)
            .then(|| Duration::from_secs(self.max_execution_time as u64));
        TransactionOptions {
            timeout: Some(
                requested
                    .unwrap_or(limits.transaction_timeout)
                    .min(limits.transaction_timeout),
            ),
            max_workspace_bytes: Some(limits.max_transaction_workspace_bytes),
            max_records: Some(limits.max_transaction_records),
            max_journal_bytes: Some(limits.max_transaction_journal_bytes),
            max_query_memory_bytes: Some(limits.max_query_memory_bytes),
            read_only: matches!(self.access_mode, Some(AccessMode::Read)),
            ..TransactionOptions::default()
        }
    }
}

fn decode_parameter(
    value: serde_json::Value,
    typed: bool,
) -> std::result::Result<Value, HttpError> {
    if typed {
        if let serde_json::Value::Object(object) = &value {
            if let (Some(serde_json::Value::String(kind)), Some(inner)) =
                (object.get("$type"), object.get("_value"))
            {
                return decode_typed(kind, inner.clone());
            }
        }
        return Err(HttpError::invalid(
            "typed Query API parameters require $type and _value",
        ));
    }
    Value::from_json(value).map_err(|error| HttpError::invalid(error.to_string()))
}

fn decode_typed(kind: &str, value: serde_json::Value) -> std::result::Result<Value, HttpError> {
    match kind {
        "Null" if value.is_null() => Ok(Value::Null),
        "Boolean" => value
            .as_bool()
            .map(Value::Boolean)
            .ok_or_else(|| HttpError::invalid("typed Boolean value must be a boolean")),
        "Integer" => value
            .as_str()
            .ok_or_else(|| HttpError::invalid("typed Integer value must be a string"))?
            .parse::<i64>()
            .map(Value::Integer)
            .map_err(|_| {
                HttpError::invalid("typed Integer value is outside the signed 64-bit range")
            }),
        "Float" => value
            .as_str()
            .ok_or_else(|| HttpError::invalid("typed Float value must be a string"))?
            .parse::<f64>()
            .ok()
            .filter(|value| value.is_finite())
            .map(Value::Float)
            .ok_or_else(|| HttpError::invalid("typed Float value must be finite")),
        "String" => value
            .as_str()
            .map(|value| Value::String(value.to_owned()))
            .ok_or_else(|| HttpError::invalid("typed String value must be a string")),
        "List" => value
            .as_array()
            .ok_or_else(|| HttpError::invalid("typed List value must be an array"))?
            .iter()
            .cloned()
            .map(|value| decode_parameter(value, true))
            .collect::<std::result::Result<Vec<_>, _>>()
            .map(Value::List),
        "Map" => value
            .as_object()
            .ok_or_else(|| HttpError::invalid("typed Map value must be an object"))?
            .iter()
            .map(|(key, value)| {
                decode_parameter(value.clone(), true).map(|value| (key.clone(), value))
            })
            .collect::<std::result::Result<BTreeMap<_, _>, _>>()
            .map(Value::Map),
        _ => Err(HttpError::invalid(format!(
            "unsupported typed Query API value {kind}"
        ))),
    }
}

#[cfg(test)]
mod tests {
    use littlegraph_core::Value;
    use serde_json::json;

    use super::{decode_parameter, QueryRequest};

    #[test]
    fn content_type_controls_typed_parameter_decoding() {
        let wrapper = json!({"$type": "Integer", "_value": "42"});
        assert_eq!(
            decode_parameter(wrapper.clone(), true).unwrap(),
            Value::Integer(42)
        );
        let Value::Map(map) = decode_parameter(wrapper, false).unwrap() else {
            panic!("plain JSON wrapper-shaped object must remain a map");
        };
        assert_eq!(map["$type"], Value::String("Integer".into()));
        assert!(decode_parameter(json!(42), true).is_err());
    }

    #[test]
    fn nullable_optional_request_values_use_defaults() {
        let request: QueryRequest = serde_json::from_value(json!({
            "parameters": null,
            "includeCounters": null,
            "maxExecutionTime": null,
            "bookmarks": null
        }))
        .unwrap();
        assert!(request.parameters.is_empty());
        assert!(!request.include_counters);
        assert_eq!(request.max_execution_time, 0);
        assert!(request.bookmarks.is_empty());
    }

    #[test]
    fn max_execution_time_matches_neo4j_integer_bounds() {
        let request: QueryRequest = serde_json::from_value(json!({
            "maxExecutionTime": -1
        }))
        .unwrap();
        let limits = crate::QueryApiLimits::default();
        assert_eq!(
            request.options(&limits).timeout,
            Some(limits.transaction_timeout)
        );

        assert!(serde_json::from_value::<QueryRequest>(json!({
            "maxExecutionTime": i64::from(i32::MAX) + 1
        }))
        .is_err());
    }
}