Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

20.6 KB
Raw Blame
//! Executable-document IR.
//!
//! apollo-parser's CST is lossless but awkward to walk repeatedly; we convert
//! each document once into a compact IR (and memoize by document hash at the
//! engine level). The IR is also where parse-time invariants are enforced so
//! the normalize/denormalize walks can be infallible about shape.

use crate::value::canonical_json;
use apollo_parser::cst;
use apollo_parser::cst::CstNode;
use serde_json::Value as Json;
use std::collections::HashMap;
use thiserror::Error;

mod prepare;
pub(crate) use prepare::prepare_selections;

#[derive(Debug, Error)]
pub enum DocumentError {
    #[error("GraphQL parse error: {0}")]
    Parse(String),
    #[error("document has no operations")]
    NoOperation,
    #[error("operation `{0}` not found")]
    UnknownOperation(String),
    #[error("unsupported operation type: {0}")]
    UnsupportedOperationType(String),
    #[error("fragment `{0}` is not defined")]
    UnknownFragment(String),
    #[error("unsupported directive `@{0}` requires network execution")]
    UnsupportedDirective(String),
    #[error("invalid condition for `@{0}`")]
    InvalidCondition(String),
    #[error("malformed document: {0}")]
    Malformed(&'static str),
}

/// Argument value: constant JSON or a variable reference resolved at
/// read/write time.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ArgValue {
    Const(Json),
    Variable(String),
    List(Vec<ArgValue>),
    Object(Vec<(String, ArgValue)>),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FieldNode {
    /// Response key (alias if present, else name).
    pub response_key: String,
    /// Schema field name.
    pub name: String,
    /// The field is persisted but omitted from hydration results.
    pub cache_only: bool,
    /// Conditional directives evaluated once against operation variables.
    pub conditions: Vec<(String, ArgValue)>,
    pub arguments: Vec<(String, ArgValue)>,
    pub selection_set: Vec<Selection>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Selection {
    Field(FieldNode),
    /// Inline fragment or named-fragment spread, already flattened to a type
    /// condition (None = no condition) plus selections.
    Fragment {
        type_condition: Option<String>,
        conditions: Vec<(String, ArgValue)>,
        selection_set: Vec<Selection>,
    },
}

/// Kind of an executable operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OperationKind {
    Query,
    Mutation,
    Subscription,
}

#[derive(Debug, Clone)]
pub struct Operation {
    pub name: Option<String>,
    pub kind: OperationKind,
    pub variable_defaults: serde_json::Map<String, Json>,
    pub selection_set: Vec<Selection>,
}

/// Named fragment definition retained for fragment-rooted record reads.
#[derive(Debug, Clone)]
pub struct Fragment {
    pub name: String,
    pub type_condition: String,
    pub selection_set: Vec<Selection>,
}

#[derive(Debug, Clone)]
pub struct Document {
    pub operations: Vec<Operation>,
    pub fragments: Vec<Fragment>,
}

impl Document {
    /// Parses executable document text into the IR. Fragment spreads are
    /// inlined (cycles rejected by the parser's recursion limit; fragments
    /// must be defined in the same document, which urql guarantees).
    pub fn parse(text: &str) -> Result<Document, DocumentError> {
        let tree = apollo_parser::Parser::new(text).parse();
        if tree.errors().len() > 0 {
            let msg = tree
                .errors()
                .map(|e| e.message().to_string())
                .collect::<Vec<_>>()
                .join("; ");
            return Err(DocumentError::Parse(msg));
        }
        let doc = tree.document();

        let mut fragments: HashMap<String, cst::FragmentDefinition> = HashMap::new();
        let mut operations_cst = Vec::new();
        for def in doc.definitions() {
            match def {
                cst::Definition::OperationDefinition(op) => operations_cst.push(op),
                cst::Definition::FragmentDefinition(frag) => {
                    let name = frag
                        .fragment_name()
                        .and_then(|n| n.name())
                        .ok_or(DocumentError::Malformed("fragment without name"))?
                        .text()
                        .to_string();
                    fragments.insert(name, frag);
                }
                _ => {
                    return Err(DocumentError::Malformed(
                        "type-system definition in executable document",
                    ));
                }
            }
        }
        if operations_cst.is_empty() && fragments.is_empty() {
            return Err(DocumentError::NoOperation);
        }

        let mut operations = Vec::new();
        for op in operations_cst {
            // Shorthand (no operation type keyword) is a query.
            let kind = match op.operation_type() {
                None => OperationKind::Query,
                Some(ty) if ty.query_token().is_some() => OperationKind::Query,
                Some(ty) if ty.mutation_token().is_some() => OperationKind::Mutation,
                Some(ty) if ty.subscription_token().is_some() => OperationKind::Subscription,
                Some(ty) => {
                    let label = ty.syntax().text().to_string();
                    return Err(DocumentError::UnsupportedOperationType(label));
                }
            };
            let selection_set = convert_selection_set(
                op.selection_set()
                    .ok_or(DocumentError::Malformed("operation without selection set"))?,
                &fragments,
                0,
            )?;
            let mut variable_defaults = serde_json::Map::new();
            if let Some(definitions) = op.variable_definitions() {
                for definition in definitions.variable_definitions() {
                    if let Some(value) = definition
                        .default_value()
                        .and_then(|default| default.value())
                    {
                        let name = definition
                            .variable()
                            .ok_or(DocumentError::Malformed("variable without name"))?
                            .text()
                            .to_string();
                        let value = resolve_arg(&convert_value(value)?, &serde_json::Map::new())
                            .map_err(|_| {
                                DocumentError::Malformed("nonconstant variable default")
                            })?;
                        variable_defaults.insert(name, value);
                    }
                }
            }
            prepare::conditions(op.directives())?;
            operations.push(Operation {
                name: op.name().map(|n| n.text().to_string()),
                kind,
                variable_defaults,
                selection_set,
            });
        }

        let mut fragment_names: Vec<_> = fragments.keys().cloned().collect();
        fragment_names.sort();
        let mut converted_fragments = Vec::with_capacity(fragment_names.len());
        for name in fragment_names {
            let definition = &fragments[&name];
            let type_condition = definition
                .type_condition()
                .and_then(|condition| condition.named_type())
                .and_then(|named| named.name())
                .ok_or(DocumentError::Malformed("fragment without type condition"))?
                .text()
                .to_string();
            let selection_set = convert_selection_set(
                definition
                    .selection_set()
                    .ok_or(DocumentError::Malformed("fragment without selections"))?,
                &fragments,
                0,
            )?;
            converted_fragments.push(Fragment {
                name,
                type_condition,
                selection_set,
            });
        }

        Ok(Document {
            operations,
            fragments: converted_fragments,
        })
    }

    /// Selects an operation by name (or the only one when unnamed).
    pub fn operation(&self, name: Option<&str>) -> Result<&Operation, DocumentError> {
        match name {
            None if self.operations.is_empty() => Err(DocumentError::NoOperation),
            None => {
                if self.operations.len() == 1 {
                    Ok(&self.operations[0])
                } else {
                    Err(DocumentError::Malformed(
                        "operation name required for multi-operation documents",
                    ))
                }
            }
            Some(n) => self
                .operations
                .iter()
                .find(|o| o.name.as_deref() == Some(n))
                .ok_or_else(|| DocumentError::UnknownOperation(n.to_string())),
        }
    }

    /// Selects a named fragment from this document.
    pub fn fragment(&self, name: &str) -> Result<&Fragment, DocumentError> {
        self.fragments
            .iter()
            .find(|fragment| fragment.name == name)
            .ok_or_else(|| DocumentError::UnknownFragment(name.to_string()))
    }
}

const MAX_FRAGMENT_DEPTH: usize = 32;

fn convert_selection_set(
    set: cst::SelectionSet,
    fragments: &HashMap<String, cst::FragmentDefinition>,
    depth: usize,
) -> Result<Vec<Selection>, DocumentError> {
    if depth > MAX_FRAGMENT_DEPTH {
        return Err(DocumentError::Malformed(
            "fragment nesting too deep (cycle?)",
        ));
    }
    let mut out = Vec::new();
    for sel in set.selections() {
        match sel {
            cst::Selection::Field(f) => {
                let name = f
                    .name()
                    .ok_or(DocumentError::Malformed("field without name"))?
                    .text()
                    .to_string();
                let response_key = f
                    .alias()
                    .and_then(|a| a.name())
                    .map(|n| n.text().to_string())
                    .unwrap_or_else(|| name.clone());
                let mut arguments = Vec::new();
                if let Some(args) = f.arguments() {
                    for arg in args.arguments() {
                        let arg_name = arg
                            .name()
                            .ok_or(DocumentError::Malformed("argument without name"))?
                            .text()
                            .to_string();
                        let value = arg
                            .value()
                            .ok_or(DocumentError::Malformed("argument without value"))?;
                        arguments.push((arg_name, convert_value(value)?));
                    }
                }
                let cache_only = f.directives().is_some_and(|directives| {
                    directives.directives().any(|directive| {
                        directive
                            .name()
                            .is_some_and(|name| name.text() == "cacheOnly")
                    })
                });
                let selection_set = match f.selection_set() {
                    Some(s) => convert_selection_set(s, fragments, depth + 1)?,
                    None => Vec::new(),
                };
                out.push(Selection::Field(FieldNode {
                    response_key,
                    name,
                    cache_only,
                    conditions: prepare::conditions(f.directives())?,
                    arguments,
                    selection_set,
                }));
            }
            cst::Selection::InlineFragment(frag) => {
                let type_condition = frag
                    .type_condition()
                    .and_then(|tc| tc.named_type())
                    .and_then(|nt| nt.name())
                    .map(|n| n.text().to_string());
                let selection_set = convert_selection_set(
                    frag.selection_set().ok_or(DocumentError::Malformed(
                        "inline fragment without selections",
                    ))?,
                    fragments,
                    depth + 1,
                )?;
                out.push(Selection::Fragment {
                    type_condition,
                    conditions: prepare::conditions(frag.directives())?,
                    selection_set,
                });
            }
            cst::Selection::FragmentSpread(spread) => {
                let name = spread
                    .fragment_name()
                    .and_then(|n| n.name())
                    .ok_or(DocumentError::Malformed("fragment spread without name"))?
                    .text()
                    .to_string();
                let def = fragments
                    .get(&name)
                    .ok_or_else(|| DocumentError::UnknownFragment(name.clone()))?;
                let type_condition = def
                    .type_condition()
                    .and_then(|tc| tc.named_type())
                    .and_then(|nt| nt.name())
                    .map(|n| n.text().to_string());
                let selection_set = convert_selection_set(
                    def.selection_set()
                        .ok_or(DocumentError::Malformed("fragment without selections"))?,
                    fragments,
                    depth + 1,
                )?;
                prepare::conditions(def.directives())?;
                out.push(Selection::Fragment {
                    type_condition,
                    conditions: prepare::conditions(spread.directives())?,
                    selection_set,
                });
            }
        }
    }
    Ok(out)
}

fn convert_value(value: cst::Value) -> Result<ArgValue, DocumentError> {
    Ok(match value {
        cst::Value::Variable(v) => ArgValue::Variable(v.text().to_string()),
        cst::Value::StringValue(s) => ArgValue::Const(Json::String(String::from(s))),
        cst::Value::IntValue(i) => {
            let text = i.syntax().text().to_string();
            let n: serde_json::Number = text
                .parse::<i64>()
                .map(Into::into)
                .map_err(|_| DocumentError::Malformed("invalid int literal"))?;
            ArgValue::Const(Json::Number(n))
        }
        cst::Value::FloatValue(f) => {
            let text = f.syntax().text().to_string();
            let parsed: f64 = text
                .parse()
                .map_err(|_| DocumentError::Malformed("invalid float literal"))?;
            let n = serde_json::Number::from_f64(parsed)
                .ok_or(DocumentError::Malformed("non-finite float literal"))?;
            ArgValue::Const(Json::Number(n))
        }
        cst::Value::BooleanValue(b) => {
            ArgValue::Const(Json::Bool(b.syntax().text().to_string().trim() == "true"))
        }
        cst::Value::NullValue(_) => ArgValue::Const(Json::Null),
        cst::Value::EnumValue(e) => ArgValue::Const(Json::String(e.text().to_string())),
        cst::Value::ListValue(l) => {
            let mut items = Vec::new();
            for item in l.values() {
                items.push(convert_value(item)?);
            }
            ArgValue::List(items)
        }
        cst::Value::ObjectValue(o) => {
            let mut fields = Vec::new();
            for f in o.object_fields() {
                let name = f
                    .name()
                    .ok_or(DocumentError::Malformed("object field without name"))?
                    .text()
                    .to_string();
                let value = f
                    .value()
                    .ok_or(DocumentError::Malformed("object field without value"))?;
                fields.push((name, convert_value(value)?));
            }
            ArgValue::Object(fields)
        }
    })
}

#[derive(Debug, Error)]
#[error("missing variable `{0}`")]
pub struct MissingVariable(pub String);

/// Resolves an argument value against operation variables into plain JSON.
pub fn resolve_arg(
    value: &ArgValue,
    variables: &serde_json::Map<String, Json>,
) -> Result<Json, MissingVariable> {
    Ok(match value {
        ArgValue::Const(v) => v.clone(),
        ArgValue::Variable(name) => variables
            .get(name)
            .cloned()
            .ok_or_else(|| MissingVariable(name.clone()))?,
        ArgValue::List(items) => Json::Array(
            items
                .iter()
                .map(|i| resolve_arg(i, variables))
                .collect::<Result<_, _>>()?,
        ),
        ArgValue::Object(fields) => {
            let mut map = serde_json::Map::new();
            for (k, v) in fields {
                map.insert(k.clone(), resolve_arg(v, variables)?);
            }
            Json::Object(map)
        }
    })
}

/// Resolves all of a field's arguments against operation variables.
pub fn resolve_args(
    field: &FieldNode,
    variables: &serde_json::Map<String, Json>,
) -> Result<serde_json::Map<String, Json>, MissingVariable> {
    let mut map = serde_json::Map::new();
    for (name, value) in &field.arguments {
        map.insert(name.clone(), resolve_arg(value, variables)?);
    }
    Ok(map)
}

/// Converts already-resolved field arguments to their canonical storage-key
/// suffix (`None` when the field declares no arguments).
pub fn resolved_args_key(
    field: &FieldNode,
    arguments: &serde_json::Map<String, Json>,
) -> Option<String> {
    (!field.arguments.is_empty()).then(|| canonical_json(&Json::Object(arguments.clone())))
}

/// Resolves a field's arguments to a canonical string (`None` when the field
/// has no arguments), for use in field storage keys.
pub fn resolve_args_key(
    field: &FieldNode,
    variables: &serde_json::Map<String, Json>,
) -> Result<Option<String>, MissingVariable> {
    let arguments = resolve_args(field, variables)?;
    Ok(resolved_args_key(field, &arguments))
}

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

    const DOC: &str = r#"
        query Soup($input: SoupInput!) {
          soup(input: $input) {
            items {
              __typename
              id
              ... on GraphqlSoupDocument { docName: name }
              ...ChatFields
            }
            nextCursor
          }
        }
        fragment ChatFields on GraphqlSoupChat { chatName: name }
    "#;

    #[test]
    fn parses_real_shape() {
        let doc = Document::parse(DOC).unwrap();
        let op = doc.operation(Some("Soup")).unwrap();
        assert_eq!(op.name.as_deref(), Some("Soup"));
        let Selection::Field(soup) = &op.selection_set[0] else {
            panic!("expected field");
        };
        assert_eq!(soup.name, "soup");
        assert!(matches!(&soup.arguments[0].1, ArgValue::Variable(v) if v == "input"));

        // fragment spread flattened with type condition
        let Selection::Field(items) = &soup.selection_set[0] else {
            panic!()
        };
        let conditions: Vec<_> = items
            .selection_set
            .iter()
            .filter_map(|s| match s {
                Selection::Fragment { type_condition, .. } => type_condition.clone(),
                _ => None,
            })
            .collect();
        assert_eq!(conditions, vec!["GraphqlSoupDocument", "GraphqlSoupChat"]);
    }

    #[test]
    fn alias_and_args_key() {
        let doc = Document::parse(DOC).unwrap();
        let op = doc.operation(Some("Soup")).unwrap();
        let Selection::Field(soup) = &op.selection_set[0] else {
            panic!()
        };
        let mut vars = serde_json::Map::new();
        vars.insert(
            "input".into(),
            serde_json::json!({"limit": 20, "cursor": null}),
        );
        assert_eq!(
            resolve_args_key(soup, &vars).unwrap().unwrap(),
            r#"{"input":{"cursor":null,"limit":20}}"#
        );
        assert!(matches!(
            resolve_args_key(soup, &serde_json::Map::new()),
            Err(MissingVariable(v)) if v == "input"
        ));
    }

    #[test]
    fn parses_operation_kinds() {
        let doc = Document::parse(DOC).unwrap();
        assert_eq!(
            doc.operation(Some("Soup")).unwrap().kind,
            OperationKind::Query
        );

        let doc = Document::parse("mutation M { doThing }").unwrap();
        assert_eq!(
            doc.operation(Some("M")).unwrap().kind,
            OperationKind::Mutation
        );

        let doc = Document::parse("subscription S { soupUpdates { __typename } }").unwrap();
        assert_eq!(
            doc.operation(Some("S")).unwrap().kind,
            OperationKind::Subscription
        );

        // Shorthand operations are queries.
        let doc = Document::parse("{ user { id } }").unwrap();
        assert_eq!(doc.operation(None).unwrap().kind, OperationKind::Query);
    }

    #[test]
    fn rejects_unknown_fragment() {
        let err = Document::parse("query Q { a { ...Nope } }").unwrap_err();
        assert!(matches!(err, DocumentError::UnknownFragment(_)));
    }
}