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.1 KB
Raw Blame
//! Write path: response JSON → normalized records.

use crate::deps::{DependencyTracker, QueryDependencies};
use crate::document::{
    FieldNode, MissingVariable, Operation, OperationKind, Selection, resolve_args, resolve_args_key,
};
use crate::entity_resolver::EntityResolverLookup;
use crate::meta::{FieldKind, TypeKind};
use crate::value::{CacheValue, EntityKey, Record, field_key};
use serde_json::Value as Json;
use std::collections::BTreeMap;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum NormalizeError {
    #[error(transparent)]
    Document(#[from] crate::document::DocumentError),
    #[error(transparent)]
    MissingVariable(#[from] MissingVariable),
    #[error("unknown type `{0}` (schema drift? rebuild after schema changes)")]
    UnknownType(String),
    #[error("unknown field `{type_name}.{field}`")]
    UnknownField { type_name: String, field: String },
    #[error(
        "`{type_name}` is abstract but the response object has no __typename; add __typename to the selection"
    )]
    MissingTypename { type_name: String },
    #[error(
        "key field `{type_name}.{field}` is missing or not a string/number in the response; every query fetching `{type_name}` must select its key"
    )]
    BadKeyField { type_name: String, field: String },
    #[error("response field `{type_name}.{field}` has unexpected shape: {detail}")]
    Shape {
        type_name: String,
        field: String,
        detail: &'static str,
    },
}

/// Records produced by normalizing one response. Each record contains only
/// the fields this response provided — the store merges them into existing
/// records.
pub type RecordUpdates = BTreeMap<EntityKey<'static>, Record>;

/// Whether response-derived dependencies exactly describe a future cache read.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum DependencyCompleteness {
    Exact,
    Broad,
}

/// Normalized updates and dependencies captured without reading records back.
pub(crate) struct NormalizeResult {
    pub updates: RecordUpdates,
    pub dependencies: QueryDependencies,
    pub completeness: DependencyCompleteness,
}

struct DependencyCapture<'a> {
    keys: QueryDependencies,
    completeness: DependencyCompleteness,
    entity_resolvers: &'a EntityResolverLookup,
}

impl DependencyCapture<'_> {
    fn mark_broad(&mut self) {
        self.completeness = DependencyCompleteness::Broad;
    }
}

struct WriteContext<'a, 'resolver> {
    variables: &'a serde_json::Map<String, Json>,
    records: &'a mut RecordUpdates,
    dependencies: &'a mut DependencyCapture<'resolver>,
}

/// Normalizes a response's `data` object into record updates.
///
/// Query responses are rooted at [`ROOT_QUERY`](crate::value::ROOT_QUERY).
/// Mutation and subscription responses traverse from their schema roots:
/// nested entities are normalized as usual, but operation-root fields are
/// discarded. Those roots are transient cache entry points, never read back.
pub fn normalize(
    schema: &crate::meta::Schema,
    op: &Operation,
    variables: &serde_json::Map<String, Json>,
    data: &Json,
) -> Result<RecordUpdates, NormalizeError> {
    Ok(normalize_with_dependencies(
        schema,
        op,
        variables,
        data,
        &EntityResolverLookup::default(),
    )?
    .updates)
}

/// Normalizes a response and captures the records a cache read would depend on.
pub(crate) fn normalize_with_dependencies(
    schema: &crate::meta::Schema,
    op: &Operation,
    variables: &serde_json::Map<String, Json>,
    data: &Json,
    entity_resolvers: &EntityResolverLookup,
) -> Result<NormalizeResult, NormalizeError> {
    let prepared = op.prepare(variables)?;
    let op = &prepared;
    let root_type = operation_root_type(schema, op)?;
    let Json::Object(data) = data else {
        return Err(NormalizeError::Shape {
            type_name: root_type.to_string(),
            field: "(data)".to_string(),
            detail: "response data is not an object",
        });
    };
    let mut records = RecordUpdates::new();
    let mut root = Record::default();
    let mut dependencies = DependencyCapture {
        keys: QueryDependencies::default(),
        completeness: DependencyCompleteness::Exact,
        entity_resolvers,
    };
    let root_key = (op.kind == OperationKind::Query).then(EntityKey::root);
    write_object_fields(
        schema,
        &op.selection_set,
        root_type,
        data,
        &mut root.fields,
        root_key.as_ref(),
        &mut WriteContext {
            variables,
            records: &mut records,
            dependencies: &mut dependencies,
        },
    )?;
    if let Some(root_key) = root_key {
        merge_into(&mut records, root_key, root);
    }
    Ok(NormalizeResult {
        updates: records,
        dependencies: dependencies.keys,
        completeness: dependencies.completeness,
    })
}

/// Projects fields not marked `@cacheOnly` directly from a network response.
/// Cache-only branches are not traversed or cloned.
pub fn project_hydration_response(
    schema: &crate::meta::Schema,
    op: &Operation,
    data: &Json,
) -> Result<Option<Json>, NormalizeError> {
    let root_type = operation_root_type(schema, op)?;
    let Json::Object(data) = data else {
        return Err(NormalizeError::Shape {
            type_name: root_type.to_string(),
            field: "(data)".to_string(),
            detail: "response data is not an object",
        });
    };
    Ok(project_object_fields(schema, &op.selection_set, root_type, data)?.map(Json::Object))
}

fn operation_root_type<'schema>(
    schema: &'schema crate::meta::Schema,
    op: &Operation,
) -> Result<&'schema str, NormalizeError> {
    match op.kind {
        OperationKind::Query => Ok(schema.query_root()),
        OperationKind::Mutation => schema
            .mutation_root()
            .ok_or_else(|| NormalizeError::UnknownType("(mutation root)".to_string())),
        OperationKind::Subscription => schema
            .subscription_root()
            .ok_or_else(|| NormalizeError::UnknownType("(subscription root)".to_string())),
    }
}

fn project_object_fields(
    schema: &crate::meta::Schema,
    selections: &[Selection],
    type_name: &str,
    data: &serde_json::Map<String, Json>,
) -> Result<Option<serde_json::Map<String, Json>>, NormalizeError> {
    let concrete = match selected_typename(selections, data) {
        Some(Json::String(name)) => name.as_str(),
        _ => type_name,
    };
    let mut fields = Vec::new();
    collect_fields(schema, selections, concrete, &mut fields);
    let mut projected = serde_json::Map::new();
    for field in fields {
        if field.cache_only {
            continue;
        }
        let Some(value) = data.get(&field.response_key) else {
            continue;
        };
        if field.name == "__typename" {
            projected.insert(field.response_key.clone(), value.clone());
            continue;
        }
        let field_meta = schema.field_meta(concrete, &field.name).ok_or_else(|| {
            NormalizeError::UnknownField {
                type_name: concrete.to_string(),
                field: field.name.clone(),
            }
        })?;
        if let Some(value) =
            project_value(schema, field, field_meta.ty.name, field_meta.ty.kind, value)?
        {
            projected.insert(field.response_key.clone(), value);
        }
    }
    Ok((!projected.is_empty()).then_some(projected))
}

fn project_value(
    schema: &crate::meta::Schema,
    field: &FieldNode,
    named_type: &str,
    kind: FieldKind,
    value: &Json,
) -> Result<Option<Json>, NormalizeError> {
    match (kind, value) {
        (FieldKind::Composite, Json::Object(object)) => {
            Ok(
                project_object_fields(schema, &field.selection_set, named_type, object)?
                    .map(Json::Object),
            )
        }
        (FieldKind::Composite, Json::Array(items)) => {
            if !field.selection_set.iter().any(selection_returns_data) {
                return Ok(None);
            }
            let mut projected = Vec::with_capacity(items.len());
            for item in items {
                let item = match item {
                    Json::Null => Json::Null,
                    Json::Object(object) => {
                        project_object_fields(schema, &field.selection_set, named_type, object)?
                            .map_or_else(|| Json::Object(serde_json::Map::new()), Json::Object)
                    }
                    _ => {
                        return Err(NormalizeError::Shape {
                            type_name: named_type.to_string(),
                            field: field.name.clone(),
                            detail: "expected object list",
                        });
                    }
                };
                projected.push(item);
            }
            Ok(Some(Json::Array(projected)))
        }
        (FieldKind::Composite, Json::Null) => {
            let has_projected_selection = field.selection_set.iter().any(selection_returns_data);
            Ok(has_projected_selection.then_some(Json::Null))
        }
        (FieldKind::Composite, _) => Err(NormalizeError::Shape {
            type_name: named_type.to_string(),
            field: field.name.clone(),
            detail: "expected object",
        }),
        (_, value) => Ok(Some(value.clone())),
    }
}

fn selection_returns_data(selection: &Selection) -> bool {
    match selection {
        Selection::Field(field) => !field.cache_only,
        Selection::Fragment { selection_set, .. } => {
            selection_set.iter().any(selection_returns_data)
        }
    }
}

fn merge_into(records: &mut RecordUpdates, key: EntityKey<'static>, record: Record) {
    records.entry(key).or_default().merge(record);
}

/// Flattens fragments applicable to `concrete_type` and visits each field.
fn collect_fields<'a>(
    schema: &crate::meta::Schema,
    selections: &'a [Selection],
    concrete_type: &str,
    out: &mut Vec<&'a FieldNode>,
) {
    for sel in selections {
        match sel {
            Selection::Field(f) => out.push(f),
            Selection::Fragment {
                type_condition,
                selection_set,
                ..
            } => {
                let applies = match type_condition {
                    None => true,
                    Some(cond) => schema.type_matches(concrete_type, cond),
                };
                if applies {
                    collect_fields(schema, selection_set, concrete_type, out);
                }
            }
        }
    }
}

/// Writes the selected fields of one response object into `target` (a
/// record's or embedded object's field map), normalizing children into
/// `records`.
fn write_object_fields(
    schema: &crate::meta::Schema,
    selections: &[Selection],
    type_name: &str,
    data: &serde_json::Map<String, Json>,
    target: &mut BTreeMap<String, CacheValue>,
    owner: Option<&EntityKey<'static>>,
    context: &mut WriteContext<'_, '_>,
) -> Result<(), NormalizeError> {
    // The concrete type: trust __typename in the response when present.
    let concrete = match selected_typename(selections, data) {
        Some(Json::String(t)) => t.as_str(),
        _ => type_name,
    };
    if let Some(owner) = owner {
        context.dependencies.keys.record(owner);
        context
            .dependencies
            .keys
            .field(owner, concrete, "__typename");
    }
    target.insert(
        "__typename".to_string(),
        CacheValue::String(concrete.to_string()),
    );

    let mut fields = Vec::new();
    collect_fields(schema, selections, concrete, &mut fields);

    for f in fields {
        if f.name == "__typename" {
            continue; // handled above
        }
        let fmeta =
            schema
                .field_meta(concrete, &f.name)
                .ok_or_else(|| NormalizeError::UnknownField {
                    type_name: concrete.to_string(),
                    field: f.name.clone(),
                })?;
        let args = resolve_args_key(f, context.variables)?;
        let storage_key = field_key(&f.name, args.as_deref());
        if let Some(owner) = owner {
            context
                .dependencies
                .keys
                .field(owner, concrete, &storage_key);
        }

        // GraphQL guarantees selected fields are present in data. Missing
        // fields are still tolerated, but an exact dependency set cannot be
        // proven because a merged record may retain an older relation.
        let Some(value) = data.get(&f.response_key) else {
            context.dependencies.mark_broad();
            continue;
        };

        let cache_value = write_value(
            schema,
            f,
            fmeta.ty.name,
            fmeta.ty.kind,
            value,
            owner,
            context,
        )
        .map_err(|detail| NormalizeError::Shape {
            type_name: concrete.to_string(),
            field: f.name.clone(),
            detail,
        })??;

        if let Some(resolver) = context.dependencies.entity_resolvers.get(concrete, &f.name) {
            let expected_key = resolve_args(f, context.variables)
                .ok()
                .and_then(|arguments| resolver.entity_key(&arguments));
            match (expected_key, value, &cache_value) {
                (Some(expected), Json::Object(_), CacheValue::Ref(actual))
                    if expected == *actual =>
                {
                    context.dependencies.keys.record(&expected);
                }
                _ => context.dependencies.mark_broad(),
            }
        }
        match target.get_mut(&storage_key) {
            Some(previous) => merge_selected_value(previous, cache_value),
            None => {
                target.insert(storage_key, cache_value);
            }
        }
    }
    Ok(())
}

/// Converts one response value. Outer `Result` is shape errors (with static
/// detail); inner carries nested structured errors.
#[allow(clippy::type_complexity)]
fn write_value(
    schema: &crate::meta::Schema,
    field: &FieldNode,
    named_type: &str,
    kind: FieldKind,
    value: &Json,
    owner: Option<&EntityKey<'static>>,
    context: &mut WriteContext<'_, '_>,
) -> Result<Result<CacheValue, NormalizeError>, &'static str> {
    Ok(match value {
        Json::Null => Ok(CacheValue::Null),
        Json::Array(items) => {
            let mut out = Vec::with_capacity(items.len());
            for item in items {
                match write_value(schema, field, named_type, kind, item, owner, context)? {
                    Ok(v) => out.push(v),
                    Err(e) => return Ok(Err(e)),
                }
            }
            Ok(CacheValue::List(out))
        }
        Json::Bool(b) => match kind {
            FieldKind::Leaf => Ok(CacheValue::Bool(*b)),
            FieldKind::OpaqueScalar => Ok(CacheValue::opaque(value)),
            FieldKind::Composite => return Err("expected object, got boolean"),
        },
        Json::Number(n) => match kind {
            FieldKind::Leaf => Ok(CacheValue::Number(n.into())),
            FieldKind::OpaqueScalar => Ok(CacheValue::opaque(value)),
            FieldKind::Composite => return Err("expected object, got number"),
        },
        Json::String(s) => match kind {
            FieldKind::Leaf => Ok(CacheValue::String(s.clone())),
            FieldKind::OpaqueScalar => Ok(CacheValue::opaque(value)),
            FieldKind::Composite => return Err("expected object, got string"),
        },
        Json::Object(obj) => match kind {
            FieldKind::OpaqueScalar => Ok(CacheValue::opaque(value)),
            FieldKind::Leaf => return Err("expected scalar, got object"),
            FieldKind::Composite => {
                match normalize_object(schema, field, named_type, obj, owner, context) {
                    Ok(v) => Ok(v),
                    Err(e) => return Ok(Err(e)),
                }
            }
        },
    })
}

/// Normalizes a composite response object: either into its own record
/// (keyable → `Ref`) or an embedded object value.
fn normalize_object(
    schema: &crate::meta::Schema,
    field: &FieldNode,
    named_type: &str,
    obj: &serde_json::Map<String, Json>,
    owner: Option<&EntityKey<'static>>,
    context: &mut WriteContext<'_, '_>,
) -> Result<CacheValue, NormalizeError> {
    let named_meta = schema
        .type_meta(named_type)
        .ok_or_else(|| NormalizeError::UnknownType(named_type.to_string()))?;

    let concrete: &str = match selected_typename(&field.selection_set, obj) {
        Some(Json::String(t)) => t,
        _ if named_meta.kind == TypeKind::Object => named_type,
        _ => {
            return Err(NormalizeError::MissingTypename {
                type_name: named_type.to_string(),
            });
        }
    };
    let concrete_meta = schema
        .type_meta(concrete)
        .ok_or_else(|| NormalizeError::UnknownType(concrete.to_string()))?;

    match &concrete_meta.key_fields {
        Some(key_fields) => {
            let mut key_values = Vec::with_capacity(key_fields.len());
            for kf in key_fields {
                let mut selected = Vec::new();
                collect_fields(schema, &field.selection_set, concrete, &mut selected);
                let key_value = obj.get(kf).or_else(|| {
                    selected
                        .iter()
                        .find(|field| field.name == *kf)
                        .and_then(|field| obj.get(&field.response_key))
                });
                let v = match key_value {
                    Some(Json::String(s)) => s.clone(),
                    Some(Json::Number(n)) => n.to_string(),
                    _ => {
                        return Err(NormalizeError::BadKeyField {
                            type_name: concrete.to_string(),
                            field: kf.to_string(),
                        });
                    }
                };
                key_values.push(v);
            }
            let key = EntityKey::entity(
                concrete,
                &key_values.iter().map(|s| s.as_str()).collect::<Vec<_>>(),
            );
            let mut record = Record::default();
            write_object_fields(
                schema,
                &field.selection_set,
                concrete,
                obj,
                &mut record.fields,
                Some(&key),
                context,
            )?;
            merge_into(context.records, key.clone(), record);
            Ok(CacheValue::Ref(key))
        }
        None => {
            let mut embedded = BTreeMap::new();
            write_object_fields(
                schema,
                &field.selection_set,
                concrete,
                obj,
                &mut embedded,
                owner,
                context,
            )?;
            Ok(CacheValue::Object(embedded))
        }
    }
}

// Identity fields may be selected through aliases, including inside fragments.
fn selected_typename<'a>(
    selections: &[Selection],
    data: &'a serde_json::Map<String, Json>,
) -> Option<&'a Json> {
    data.get("__typename").or_else(|| {
        selections.iter().find_map(|selection| match selection {
            Selection::Field(field) if field.name == "__typename" => data.get(&field.response_key),
            Selection::Fragment { selection_set, .. } => selected_typename(selection_set, data),
            _ => None,
        })
    })
}

// Merge duplicate selections within one response only. Separate network writes
// still replace embedded values according to the normal record merge policy.
fn merge_selected_value(target: &mut CacheValue, value: CacheValue) {
    match (target, value) {
        (CacheValue::Object(target), CacheValue::Object(values)) => {
            for (key, value) in values {
                match target.get_mut(&key) {
                    Some(previous) => merge_selected_value(previous, value),
                    None => {
                        target.insert(key, value);
                    }
                }
            }
        }
        (CacheValue::List(target), CacheValue::List(values)) if target.len() == values.len() => {
            for (target, value) in target.iter_mut().zip(values) {
                merge_selected_value(target, value);
            }
        }
        (target, value) => *target = value,
    }
}