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.

8.5 KB
Raw Blame
//! Incremental projections of ordinary GraphQL queries. The read compiler owns
//! aliases, arguments and concrete fragment types; transports only apply paths.
//!
//! Field bindings patch leaf edits without reading. When they cannot (a link,
//! list, tombstone or type change, or a journal barrier), the query is re-read
//! and diffed against the retained response, which is the subscriber's base.

use super::*;
use crate::denormalize::QueryProjection;
use crate::engine::live_query::LiveFieldPatch;
use serde::Serialize;
use std::sync::Arc;

mod diff;

const WATCH_CAPACITY: usize = 64;
const WATCH_BYTES: usize = 16 * 1024 * 1024;
// A patch replacing most of the response (a compacted page) saves subscribers
// little, while the engine must copy every replaced value into it. Beyond this
// share a re-read publishes the shared result instead. Small ones always patch.
const MAX_REPLACED_SHARE: usize = 2;
const MIN_REPLACED_BYTES: usize = 16 * 1024;

/// An atomic query read. A patch is applicable only to the exact revision the
/// subscriber supplied; eviction, spec changes and revision mismatches reset it.
#[derive(Debug, Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum QueryUpdate {
    /// Complete replacement, also establishing a new patch base. The watch
    /// shares it as its diff base; serialization is that of the plain JSON.
    Hit {
        #[serde(serialize_with = "serialize_shared")]
        data: Arc<Json>,
        revision: String,
    },
    /// Selected field replacements, including an empty update for no change.
    Patch {
        patches: Vec<LiveFieldPatch>,
        revision: String,
    },
    /// Required data is missing; the caller must use its normal network policy.
    Miss { revision: String },
}

fn serialize_shared<S: serde::Serializer>(
    data: &Arc<Json>,
    serializer: S,
) -> Result<S::Ok, S::Error> {
    data.as_ref().serialize(serializer)
}

#[derive(PartialEq, Eq)]
struct QuerySpec {
    query: String,
    operation_name: Option<String>,
    variables: serde_json::Map<String, Json>,
    entity_resolvers: Vec<EntityResolver>,
}

struct QueryWatch {
    spec: QuerySpec,
    projection: QueryProjection,
    base: Base,
    revision: CacheRevision,
    bytes: usize,
}

/// The subscriber's result at the watch revision: the base for re-read diffs.
struct Base {
    /// Shared with the last `Hit`; hosts drop theirs once it is encoded.
    data: Arc<Json>,
    bytes: usize,
}

impl QueryWatch {
    fn new(
        spec: QuerySpec,
        projection: QueryProjection,
        base: Base,
        revision: CacheRevision,
    ) -> Self {
        let bytes = spec.query.len()
            + serde_json::to_vec(&spec.variables).map_or(0, |json| json.len())
            + projection.retained_bytes()
            + base.bytes;
        Self {
            spec,
            projection,
            base,
            revision,
            bytes,
        }
    }

    /// Frees the stale bindings before a re-read compiles new ones, so both are
    /// never resident together.
    fn into_base(self) -> Base {
        self.base
    }
}

pub(super) struct QueryWatches {
    views: LruCache<OpId, QueryWatch>,
    bytes: usize,
}

impl Default for QueryWatches {
    fn default() -> Self {
        Self {
            views: LruCache::new(NonZeroUsize::new(WATCH_CAPACITY).unwrap()),
            bytes: 0,
        }
    }
}

impl QueryWatches {
    fn pop(&mut self, op: OpId) -> Option<QueryWatch> {
        let view = self.views.pop(&op)?;
        self.bytes -= view.bytes;
        Some(view)
    }

    pub(super) fn remove(&mut self, op: OpId) {
        self.pop(op);
    }

    fn put(&mut self, op: OpId, view: QueryWatch) {
        if view.bytes > WATCH_BYTES {
            return;
        }
        while self.bytes + view.bytes > WATCH_BYTES || self.views.len() == WATCH_CAPACITY {
            let Some((_, old)) = self.views.pop_lru() else {
                break;
            };
            self.bytes -= old.bytes;
        }
        self.bytes += view.bytes;
        self.views.put(op, view);
    }
}

impl<S: Storage> Engine<S> {
    /// Watch any cache-readable query using its ordinary document and variables.
    /// The caller owns `op_id` until `teardown_operation`. Retention is bounded;
    /// losing a plan only causes a replacement read, never a missed update.
    pub async fn watch_query(
        &mut self,
        op_id: OpId,
        query: &str,
        operation_name: Option<&str>,
        variables: &serde_json::Map<String, Json>,
        entity_resolvers: &[EntityResolver],
        since: Option<CacheRevision>,
    ) -> Result<QueryUpdate, EngineError<S::Error>> {
        self.hydrate_optimistic().await?;
        let spec = QuerySpec {
            query: query.to_owned(),
            operation_name: operation_name.map(str::to_owned),
            variables: variables.clone(),
            entity_resolvers: entity_resolvers.to_vec(),
        };
        let Some(mut view) = self
            .query_watches
            .pop(op_id)
            .filter(|view| view.spec == spec && Some(view.revision) == since)
        else {
            return self.read_watched(op_id, spec, None).await;
        };
        // A journal barrier cannot say what changed; only a re-read can.
        let Some(changes) = self
            .live_queries
            .changes_since(view.revision, self.revision)
        else {
            return self.read_watched(op_id, spec, Some(view.into_base())).await;
        };
        let keys = changes
            .records
            .into_iter()
            .filter(|key| view.projection.binds(key))
            .collect();
        let bases = self.load_bases(&keys).await?;
        let effective = effective_records(&bases, &self.optimistic, &keys);
        let Some((patches, binding_delta)) = view.projection.update(&effective) else {
            return self.read_watched(op_id, spec, Some(view.into_base())).await;
        };
        let Some(data_delta) = diff::apply_patches(Arc::make_mut(&mut view.base.data), &patches)
        else {
            // A binding path missing from the base would desynchronize diffs.
            return self.read_watched(op_id, spec, None).await;
        };
        view.revision = self.revision;
        // Values (especially opaque scalars) may grow between reads.
        view.base.bytes = view.base.bytes.saturating_add_signed(data_delta);
        view.bytes = view.bytes.saturating_add_signed(binding_delta + data_delta);
        self.query_watches.put(op_id, view);
        Ok(QueryUpdate::Patch {
            patches,
            revision: self.revision.to_string(),
        })
    }

    /// Reads the whole query and recompiles its bindings. With the subscriber's
    /// base it publishes a diff, falling back to a replacement for a new root.
    async fn read_watched(
        &mut self,
        op_id: OpId,
        spec: QuerySpec,
        base: Option<Base>,
    ) -> Result<QueryUpdate, EngineError<S::Error>> {
        let (result, projection) = self
            .read_query_tracked(
                Some(op_id),
                &spec.query,
                spec.operation_name.as_deref(),
                &spec.variables,
                &spec.entity_resolvers,
                true,
            )
            .await?;
        let revision = self.revision.to_string();
        let ReadResult::Hit { data } = result else {
            return Ok(QueryUpdate::Miss { revision });
        };
        let Some(projection) = projection else {
            return Ok(QueryUpdate::Hit {
                data: Arc::new(data),
                revision,
            });
        };
        let diff = base.and_then(|base| {
            let budget = (base.bytes / MAX_REPLACED_SHARE).max(MIN_REPLACED_BYTES);
            diff::diff_response(&base.data, &data, budget).map(|diff| (diff, base.bytes))
        });
        let data = Arc::new(data);
        let (update, bytes) = match diff {
            Some((diff, bytes)) => (
                QueryUpdate::Patch {
                    patches: diff.patches,
                    revision,
                },
                bytes.saturating_add_signed(diff.byte_delta),
            ),
            None => (
                QueryUpdate::Hit {
                    data: Arc::clone(&data),
                    revision,
                },
                diff::json_bytes(&data),
            ),
        };
        let base = Base { data, bytes };
        self.query_watches.put(
            op_id,
            QueryWatch::new(spec, projection, base, self.revision),
        );
        Ok(update)
    }
}

#[cfg(test)]
mod test;