Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Engine host: the cache engine + Turso storage behind an async mutex.
//!
//! `cache-core`'s `Storage` futures are `MaybeSend` — `Send` on native
//! targets — so the engine is driven directly from the tauri/tokio runtime;
//! the async mutex serializes commands the same way the browser worker's
//! queue does. Turso work completes immediately on its native synchronous IO
//! driver, so holding a runtime thread through it is fine.
//!
//! Operation ids cross the IPC boundary as strings (`"{clientId}:{urqlKey}"`)
//! so multiple webviews can register operations against the one shared
//! engine without collisions; they're interned to the engine's `u64` ids
//! internally — the same scheme as the `cache-wasm` shell.
use cache_core::deps::OpId;
use cache_core::engine::{
BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,
InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,
RollbackOptimisticWriteResult, WriteResult,
};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant, QueryInspection};
use cache_core::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationUpsertKind,
};
use cache_core::record_selection::{SelectedRecord, cache::RecordSelectionCache};
use cache_core::revision::CacheRevision;
use cache_core::search::{SearchPage, SearchRequest};
use cache_core::value::EntityKey;
use cache_turso::{TursoStorage, TursoStorageCloseOutcome};
use serde::Serialize;
use std::collections::HashMap;
use std::sync::Arc;
mod access;
use access::EngineAccess;
mod calendar;
mod soup;
pub use calendar::CalendarRangeResultWire;
pub use soup::{
EntityFilterRequest, EntityFilterResult, LiveQueryResult, PredicateBaselineEntry,
PredicateFilterResult,
};
/// Mirrors `ReadResult` in `apps/web/src/lib/graphql-cache/protocol.ts`.
#[derive(Debug, Serialize)]
#[serde(tag = "kind", rename_all = "camelCase")]
pub enum ReadResultWire {
/// Fully answerable from cache.
Hit {
/// Denormalized response data.
data: serde_json::Value,
},
/// Not answerable; the exchange forwards to the network.
Miss,
}
/// Mirrors `WriteResult` in `apps/web/src/lib/graphql-cache/protocol.ts`.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct WriteResultWire {
/// Optional complete displayed-window invalidation proofs.
#[serde(skip_serializing_if = "Option::is_none")]
pub unchanged_views: Option<Vec<String>>,
/// Effective scalar patches; absent when a query reread is required.
#[serde(skip_serializing_if = "Option::is_none")]
pub field_changes: Option<Vec<cache_core::field_changes::RecordFieldChange>>,
/// Bindings omitted while preserving a normalizable server response.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub identity_errors: Vec<String>,
/// Effective-view revision installed by this logical mutation.
pub revision: String,
/// Whether this write advanced `revision`.
pub revision_advanced: bool,
/// Known search changes for query responses; absent for conservative refreshes.
#[serde(skip_serializing_if = "Option::is_none")]
pub search_changed_buckets: Option<std::collections::BTreeSet<String>>,
/// Entity keys whose records changed.
pub changed: Vec<String>,
/// Registered operation ids affected by the change (origin excluded).
pub affected_ops: Vec<String>,
/// True when the identity witness wiped and rebound the cache before
/// this write (silent restart).
pub reset: bool,
/// Queries to fetch after successful optimistic settlement.
pub revalidations: Vec<QueryRevalidation>,
/// Stable caller identity on settlement.
#[serde(skip_serializing_if = "Option::is_none")]
pub mutation_uuid: Option<String>,
}
/// Internal hydration result used to fan out changes before returning only
/// the caller-visible projection across IPC.
pub struct HydrationWriteResultWire {
/// Displayed windows proven unchanged by complete engine journal evidence.
pub unchanged_views: Vec<String>,
/// Quick Access buckets changed by hydration.
pub search_changed_buckets: std::collections::BTreeSet<String>,
/// Cache changes required for host notifications.
pub write_result: WriteResultWire,
/// Fields not marked `@cacheOnly`, or `None` when there are none.
pub data: Option<serde_json::Value>,
}
/// Revision-qualified normalized record selection result.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RecordSelectionResultWire {
/// Revision observed by record selection.
pub revision: String,
/// Selected normalized records.
pub records: Vec<SelectedRecord>,
}
/// Revision-qualified affected operation ids.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AffectedOperationsResultWire {
/// Revision installed by the invalidation or deletion.
pub revision: String,
/// Registered operation ids affected by the change.
pub affected_ops: Vec<String>,
}
/// Result of durably enqueueing an optimistic mutation and attempting to
/// claim the strict queue head.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct EnqueueOptimisticMutationResultWire {
/// Engine-assigned id; settle with commit/rollback. A string because JS
/// numbers lose precision past 2^53 (same as the wasm shell).
pub transaction_id: String,
/// How the caller UUID changed the queue.
pub upsert_kind: MutationUpsertKindWire,
/// Visible composed-view changes caused by the new optimistic layer.
#[serde(flatten)]
pub result: WriteResultWire,
/// Claim outcome determined before cache-change events are emitted.
pub initial_claim: InitialMutationClaimWire,
}
/// Queue collision outcome serialized for the webview.
#[derive(Debug, Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
pub enum MutationUpsertKindWire {
/// A new UUID was appended.
Inserted,
/// A pending row was removed and replaced at the tail.
ReplacedPending {
/// Removed queue transaction.
removed_transaction_id: String,
},
/// A live row was retained and superseded.
AppendedAfterActive {
/// Still-active queue transaction.
active_transaction_id: String,
},
}
impl From<MutationUpsertKind> for MutationUpsertKindWire {
fn from(kind: MutationUpsertKind) -> Self {
match kind {
MutationUpsertKind::Inserted => Self::Inserted,
MutationUpsertKind::ReplacedPending { removed_id } => Self::ReplacedPending {
removed_transaction_id: removed_id.to_string(),
},
MutationUpsertKind::AppendedAfterActive { active_id } => Self::AppendedAfterActive {
active_transaction_id: active_id.to_string(),
},
}
}
}
/// Tagged outcome of the initial strict-head claim attempt.
#[derive(Debug, Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum InitialMutationClaimWire {
/// The strict queue head was durably leased.
Claimed {
/// Mutation request and lease metadata for the claimed head.
mutation: ClaimedMutationWire,
},
/// The queue head is currently leased, deferred, or absent.
NotRunnable,
/// Enqueue succeeded, but the claim attempt failed.
Failed {
/// Diagnostic claim error.
error: String,
},
}
/// Claimed queue head returned to the JavaScript mutation runner.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ClaimedMutationWire {
/// Opaque client correlation restored from the durable source.
pub client_metadata: Option<serde_json::Value>,
/// Durable mutation id.
pub transaction_id: String,
/// Caller coalescing UUID.
pub uuid: String,
/// Whether a newer current row superseded this request.
pub superseded: bool,
/// Whether settlement must recover a server identity before a replacement runs.
pub requires_confirmation: bool,
/// Claim generation required for settlement.
pub lease_generation: String,
/// GraphQL mutation document.
pub query: String,
/// Selected operation name.
pub operation_name: Option<String>,
/// Variables parsed from their durable canonical JSON representation.
pub variables: serde_json::Value,
/// Identity witness captured when the mutation was enqueued.
pub identity: Option<String>,
/// Number of network attempts including this claim.
pub attempt_count: u32,
/// Retryable server failures, excluding transport failures.
pub server_failure_count: u32,
}
/// Tagged result of deferring or discarding a failed queue attempt.
#[derive(Debug, Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
pub enum DeferOptimisticWriteResultWire {
/// Retry state was retained normally.
Deferred,
/// A superseded row was discarded instead of retried.
DiscardedSuperseded {
/// Current transaction carrying the newer intent.
replacement_transaction_id: String,
/// Cache changes caused by discarding the old layer.
#[serde(flatten)]
result: WriteResultWire,
},
}
/// Tagged result of committing a current or superseded queue attempt.
#[derive(Debug, Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
pub enum CommitOptimisticWriteResultWire {
/// Invalid response identity data permanently failed this attempt.
Failed {
/// Diagnostic for the cache error handler.
error: String,
/// Newer intent preserved when this attempt was superseded.
#[serde(skip_serializing_if = "Option::is_none")]
replacement_transaction_id: Option<String>,
/// Cache changes caused by discarding the failed layer.
#[serde(flatten)]
result: WriteResultWire,
},
/// The current mutation committed normally.
Committed {
/// Cache changes caused by commit.
#[serde(flatten)]
result: WriteResultWire,
},
/// The response committed beneath a newer optimistic replacement.
CommittedSuperseded {
/// Current transaction carrying the newer intent.
replacement_transaction_id: String,
/// Cache changes caused by commit.
#[serde(flatten)]
result: WriteResultWire,
},
}
/// Tagged result of permanently failing or superseding a queue attempt.
#[derive(Debug, Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
pub enum RollbackOptimisticWriteResultWire {
/// The current mutation permanently failed.
RolledBack {
/// Cache changes caused by rollback.
#[serde(flatten)]
result: WriteResultWire,
},
/// A superseded attempt was accepted and discarded.
DiscardedSuperseded {
/// Current transaction carrying the newer intent.
replacement_transaction_id: String,
/// Cache changes caused by discarding the old layer.
#[serde(flatten)]
result: WriteResultWire,
},
}
impl TryFrom<ClaimedMutation> for ClaimedMutationWire {
type Error = String;
fn try_from(claimed: ClaimedMutation) -> Result<Self, Self::Error> {
let requires_confirmation = claimed.queued.requires_confirmation();
let client_metadata = cache_core::queue::decode_optimistic_source(
&claimed.queued.optimistic.optimistic_data_json,
)?
.client_metadata;
let request = claimed.queued.mutation.request;
Ok(Self {
client_metadata,
transaction_id: claimed.queued.id.to_string(),
uuid: claimed.queued.uuid.to_string(),
superseded: claimed.queued.superseded,
requires_confirmation,
lease_generation: claimed.lease_generation.to_string(),
query: request.query,
operation_name: request.operation_name,
variables: serde_json::from_str(&request.variables_json).map_err(|e| e.to_string())?,
identity: request.identity,
attempt_count: claimed.queued.mutation.attempt_count,
server_failure_count: claimed.queued.mutation.server_failure_count,
})
}
}
/// Interns host-side string operation ids to engine `u64` ids.
#[derive(Default)]
struct OpInterner {
by_name: HashMap<String, OpId>,
by_id: HashMap<OpId, String>,
next: OpId,
}
impl OpInterner {
fn intern(&mut self, name: &str) -> OpId {
if let Some(id) = self.by_name.get(name) {
return *id;
}
self.next += 1;
let id = self.next;
self.by_name.insert(name.to_string(), id);
self.by_id.insert(id, name.to_string());
id
}
fn remove(&mut self, name: &str) -> Option<OpId> {
let id = self.by_name.remove(name)?;
self.by_id.remove(&id);
Some(id)
}
fn names(&self, ids: impl IntoIterator<Item = OpId>) -> Vec<String> {
ids.into_iter()
.filter_map(|id| self.by_id.get(&id).cloned())
.collect()
}
}
type Variables = serde_json::Map<String, serde_json::Value>;
/// Optional active-query registration installed by a network write.
pub struct WriteRegistration {
/// Host operation id.
pub op_id: String,
/// Synthetic read relations used by the query.
pub entity_resolvers: Vec<EntityResolver>,
}
/// Owned inputs for a network response write.
pub struct WriteRequest {
/// Origin operation excluded from immediate invalidation.
pub origin_op_id: Option<String>,
/// Active query registration to install.
pub registration: Option<WriteRegistration>,
/// GraphQL document.
pub query: String,
/// Selected operation name.
pub operation_name: Option<String>,
/// Operation variables.
pub variables: Variables,
/// GraphQL response data.
pub data: serde_json::Value,
/// Opaque identity witness.
pub identity: Option<String>,
}
struct EngineState {
engine: Engine<TursoStorage>,
ops: OpInterner,
selections: RecordSelectionCache,
}
/// Cheaply-clonable handle to the shared engine. Foreground methods serialize
/// through the async mutex. Hydration yields and refetches when superseded.
/// Errors are stringified for the IPC boundary
/// (the JS host rejects the pending call, and the exchange degrades to the
/// network).
#[derive(Clone)]
pub struct EngineHandle {
inner: Arc<EngineAccess<EngineState>>,
// Shared by cloned handles, changed when the native engine is reopened.
// Revisions alone may repeat across process restarts.
mail_generation: String,
}
fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {
WriteResultWire {
unchanged_views: None,
field_changes: result.field_changes,
identity_errors: result.identity_errors,
revision: result.revision.to_string(),
revision_advanced: result.revision_advanced,
search_changed_buckets: result.search_changed_buckets,
changed: result
.changed
.into_iter()
.map(|key| key.0.into_owned())
.collect(),
affected_ops: ops.names(result.affected_ops),
reset: result.reset,
revalidations: result.revalidations,
mutation_uuid: result.mutation_uuid,
}
}
fn parse_u64(value: &str, label: &str) -> Result<u64, String> {
value
.parse::<u64>()
.map_err(|_| format!("invalid {label} `{value}`"))
}
fn parse_transaction_id(id: &str) -> Result<u64, String> {
parse_u64(id, "optimistic transaction id")
}
impl EngineHandle {
/// Wraps an opened storage backend. A `hot_capacity` of 0 is treated as
/// unset (engine default).
pub fn new(storage: TursoStorage, hot_capacity: Option<u32>) -> Self {
Self::with_schema(storage, hot_capacity, cache_core::meta::bundled_schema())
}
/// Constructs the native engine with metadata loaded from its frontend bundle.
pub fn with_schema(
storage: TursoStorage,
hot_capacity: Option<u32>,
schema: Arc<cache_core::meta::Schema>,
) -> Self {
let engine = Engine::with_schema(
storage,
hot_capacity
.filter(|c| *c > 0)
.map_or(cache_core::engine::DEFAULT_HOT_CAPACITY, |c| c as usize),
schema,
);
EngineHandle {
mail_generation: soup_filter_cache_adapter::mail::new_generation(),
inner: Arc::new(EngineAccess::new(EngineState {
engine,
ops: OpInterner::default(),
selections: RecordSelectionCache::default(),
})),
}
}
/// Consumes the sole handle and explicitly closes native Turso storage.
pub fn shutdown(self) -> Result<(), String> {
let mutex = Arc::try_unwrap(self.inner)
.map_err(|_| "graphql cache still has active command handles".to_string())?;
let state = mutex.into_inner();
let outcome = state
.engine
.into_storage()
.try_close()
.map_err(|error| error.to_string())?;
match outcome {
TursoStorageCloseOutcome::Healthy | TursoStorageCloseOutcome::ResetRequired(_) => {
Ok(())
}
}
}
/// Returns the current in-memory cache revision.
pub async fn current_revision(&self) -> CacheRevision {
self.inner.lock().await.engine.current_revision()
}
/// Returns the durable cache generation, initializing it when absent.
pub async fn current_storage_generation(&self) -> Result<String, String> {
self.inner
.lock()
.await
.engine
.current_storage_generation()
.await
.map(|generation| generation.to_string())
.map_err(|error| error.to_string())
}
/// Validates and persists compatible metadata before publishing it to native operations.
pub async fn install_schema(
&self,
schema: &cache_core::meta::Schema,
path: &std::path::Path,
) -> Result<(), String> {
let mut state = self.inner.lock().await;
let merged = state
.engine
.schema()
.merge(schema)
.map_err(|e| e.to_string())?;
persist_schema(path, &merged)?;
state
.engine
.install_schema(&merged)
.map_err(|e| e.to_string())
}
/// Cache read; registers `op_id` as active when given.
#[tracing::instrument(name = "graphql_cache.native.read", skip_all, err)]
pub async fn read(
&self,
op_id: Option<String>,
query: String,
operation_name: Option<String>,
variables: Variables,
entity_resolvers: Vec<EntityResolver>,
) -> Result<ReadResultWire, String> {
let mut state = self.inner.lock().await;
let EngineState { engine, ops, .. } = &mut *state;
let op = op_id.map(|name| ops.intern(&name));
engine
.read_query_with_entity_resolvers(
op,
&query,
operation_name.as_deref(),
&variables,
&entity_resolvers,
)
.await
.map(|result| match result {
ReadResult::Hit { data } => ReadResultWire::Hit { data },
ReadResult::Miss => ReadResultWire::Miss,
})
.map_err(|e| e.to_string())
}
/// Incrementally project a query; operation teardown releases its bindings.
#[tracing::instrument(name = "graphql_cache.native.watch", skip_all, err)]
pub async fn watch(
&self,
op_id: String,
query: String,
operation_name: Option<String>,
variables: Variables,
entity_resolvers: Vec<EntityResolver>,
since: Option<String>,
) -> Result<cache_core::engine::watch_query::QueryUpdate, String> {
let since = since
.map(|value| value.parse::<CacheRevision>())
.transpose()
.map_err(|error| error.to_string())?;
let mut state = self.inner.lock().await;
let EngineState { engine, ops, .. } = &mut *state;
let op = ops.intern(&op_id);
engine
.watch_query(
op,
&query,
operation_name.as_deref(),
&variables,
&entity_resolvers,
since,
)
.await
.map_err(|error| error.to_string())
}
/// Projects explicit normalized entity keys without scanning storage.
pub async fn read_records_by_keys(
&self,
document: String,
fragment_name: String,
keys: Vec<String>,
) -> Result<RecordSelectionResultWire, String> {
let mut state = self.inner.lock().await;
let schema = state.engine.schema_snapshot();
let selection = state
.selections
.get(&schema, document, fragment_name)
.map_err(|error| error.to_string())?;
let keys: Vec<_> = keys.into_iter().map(|key| EntityKey(key.into())).collect();
state
.engine
.read_records_by_keys(&selection, &keys)
.await
.map(|result| RecordSelectionResultWire {
revision: result.revision.to_string(),
records: result.value,
})
.map_err(|error| error.to_string())
}
/// Searches the compact materialized projection without record scans.
pub async fn search(&self, request: SearchRequest) -> Result<SearchPage, String> {
self.inner
.lock()
.await
.engine
.search(&request)
.await
.map_err(|error| error.to_string())
}
/// Evaluates a Soup predicate or a cached Mail page.
pub async fn entity_filter(
&self,
request: EntityFilterRequest,
) -> Result<EntityFilterResult, String> {
let mut state = self.inner.lock().await;
let state = &mut *state;
soup::filter(
&mut state.engine,
&mut state.selections,
&self.mail_generation,
request,
)
.await
}
/// Reads a retained live view, atomically checking its specification identity.
pub async fn resume_entity_filter(
&self,
id: String,
registration_id: cache_core::engine::live_query::LiveQueryRegistration,
since: Option<String>,
) -> Result<Option<soup::LiveQueryResult>, String> {
let since = since
.map(|revision| revision.parse())
.transpose()
.map_err(|error: cache_core::revision::ParseCacheRevisionError| error.to_string())?;
self.inner
.lock()
.await
.engine
.resume_live_query(&id, registration_id, since)
.await
.map(|update| update.map(|update| soup::LiveQueryResult::LiveQuery { update }))
.map_err(|error| error.to_string())
}
/// Recovers cached query variables without materializing each variant.
pub async fn inspect_query_variants(
&self,
query: String,
operation_name: Option<String>,
path: Vec<String>,
) -> Result<Vec<CachedQueryVariant>, String> {
self.inner
.lock()
.await
.engine
.inspect_query_variants(&QueryInspection {
query,
operation_name,
path,
variable_filters: Vec::new(),
})
.await
.map_err(|error| error.to_string())
}
/// Enumerates and materializes cached variants of one generated query field.
pub async fn inspect_query(
&self,
query: String,
operation_name: Option<String>,
path: Vec<String>,
variable_filters: Vec<serde_json::Map<String, serde_json::Value>>,
) -> Result<Vec<CachedQueryInstance>, String> {
self.inner
.lock()
.await
.engine
.inspect_query(&QueryInspection {
query,
operation_name,
path,
variable_filters,
})
.await
.map_err(|error| error.to_string())
}
/// Normalizes and stores a network response.
#[tracing::instrument(name = "graphql_cache.native.write", skip_all, err)]
pub async fn write(&self, request: WriteRequest) -> Result<WriteResultWire, String> {
let WriteRequest {
origin_op_id,
registration,
query,
operation_name,
variables,
data,
identity,
} = request;
let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let origin = origin_op_id.map(|name| ops.intern(&name));
let registration = registration.map(|registration| {
let op_id = ops.intern(®istration.op_id);
(op_id, registration.entity_resolvers)
});
let projections = soup::write_projections(
engine,
&query,
operation_name.as_deref(),
&variables,
&data,
identity.as_deref(),
)
.await?;
engine
.write_query_with_registration_and_projections(
origin,
registration
.as_ref()
.map(|(op_id, entity_resolvers)| QueryRegistration {
op_id: *op_id,
entity_resolvers,
}),
NetworkWrite {
query: &query,
operation_name: operation_name.as_deref(),
variables: &variables,
data: &data,
identity: identity.as_deref(),
},
projections,
)
.await
.map(|result| wire_write_result(ops, result))
.map_err(|e| e.to_string())
}
/// Stores a query response and returns only fields not marked
/// `@cacheOnly`.
#[tracing::instrument(name = "graphql_cache.native.hydrate_query", skip_all, err)]
pub async fn hydrate_query(
&self,
query: String,
operation_name: Option<String>,
variables: Variables,
data: serde_json::Value,
identity: Option<String>,
) -> Result<HydrationWriteResultWire, String> {
let mut state = self.inner.hydrate().await?;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::write_projections(
engine,
&query,
operation_name.as_deref(),
&variables,
&data,
identity.as_deref(),
)
.await?;
let result = engine
.hydrate_query_with_projections(
&query,
operation_name.as_deref(),
&variables,
&data,
identity.as_deref(),
projections,
)
.await
.map_err(|error| error.to_string())?;
// Invalidation evidence is optional: a failed proof must not reject a committed hydration.
let unchanged_views = engine
.unchanged_observed_windows()
.await
.unwrap_or_default();
Ok(HydrationWriteResultWire {
unchanged_views,
search_changed_buckets: result.search_changed_buckets,
write_result: wire_write_result(ops, result.write_result),
data: result.data,
})
}
/// Durably queues a mutation and its optimistic layer, then attempts to
/// claim the strict queue head while retaining the same engine lock.
#[allow(clippy::too_many_arguments)]
pub async fn enqueue_optimistic_mutation(
&self,
origin_op_id: Option<String>,
uuid: String,
query: String,
operation_name: Option<String>,
variables: Variables,
data: serde_json::Value,
link_patches: Vec<OptimisticLinkPatch>,
revalidations: Vec<QueryRevalidation>,
identity_bindings: Vec<cache_core::identity::IdentityBinding>,
created_at_ms: i64,
lease_owner: String,
now_ms: i64,
lease_expires_at_ms: i64,
client_metadata: Option<serde_json::Value>,
uncertain_calendar_event_keys: Vec<String>,
) -> Result<EnqueueOptimisticMutationResultWire, String> {
let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let origin = origin_op_id.map(|name| ops.intern(&name));
let projections = soup::optimistic_projections(
engine,
&query,
operation_name.as_deref(),
&variables,
&data,
created_at_ms,
)
.await?;
let result = engine
.enqueue_optimistic_mutation_with_calendar(
origin,
BeginOptimisticWrite {
client_metadata: client_metadata.as_ref(),
uuid: &uuid,
query: &query,
operation_name: operation_name.as_deref(),
variables: &variables,
data: &data,
link_patches: &link_patches,
revalidations: &revalidations,
created_at_ms,
identity_bindings: &identity_bindings,
},
MutationClaimRequest {
owner: lease_owner,
now_ms,
lease_expires_at_ms,
},
projections,
uncertain_calendar_event_keys
.into_iter()
.map(|key| EntityKey(key.into()))
.collect(),
)
.await
.map_err(|error| error.to_string())?;
let initial_claim = match result.initial_claim {
InitialClaimOutcome::Claimed(claimed) => InitialMutationClaimWire::Claimed {
mutation: ClaimedMutationWire::try_from(*claimed)?,
},
InitialClaimOutcome::NotRunnable => InitialMutationClaimWire::NotRunnable,
InitialClaimOutcome::Failed(error) => InitialMutationClaimWire::Failed {
error: error.to_string(),
},
};
Ok(EnqueueOptimisticMutationResultWire {
transaction_id: result.transaction_id.to_string(),
upsert_kind: result.upsert_kind.into(),
result: wire_write_result(ops, result.write_result),
initial_claim,
})
}
/// Reads queued operations without acquiring their leases.
pub async fn inspect_mutations(
&self,
) -> Result<Vec<cache_core::queue::MutationInspection>, String> {
let state = self.inner.lock().await;
state
.engine
.inspect_mutations()
.await
.map_err(|error| error.to_string())
}
/// Claims the strict mutation queue head when it is runnable.
pub async fn claim_next_mutation(
&self,
owner: String,
now_ms: i64,
lease_expires_at_ms: i64,
) -> Result<Option<ClaimedMutationWire>, String> {
let mut state = self.inner.lock().await;
state
.engine
.claim_next_mutation(MutationClaimRequest {
owner,
now_ms,
lease_expires_at_ms,
})
.await
.map_err(|e| e.to_string())?
.map(ClaimedMutationWire::try_from)
.transpose()
}
/// Retains a retryable mutation and releases its claim.
pub async fn defer_optimistic_write(
&self,
transaction_id: String,
lease_owner: String,
lease_generation: String,
next_attempt_at_ms: i64,
error: String,
server_failure: bool,
) -> Result<DeferOptimisticWriteResultWire, String> {
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
let mut state = self.inner.lock().await;
let EngineState { engine, ops, .. } = &mut *state;
match engine
.defer_optimistic_write(
transaction,
claim,
next_attempt_at_ms,
error,
server_failure,
)
.await
.map_err(|e| e.to_string())?
{
DeferOptimisticWriteResult::Deferred => Ok(DeferOptimisticWriteResultWire::Deferred),
DeferOptimisticWriteResult::DiscardedSuperseded(result) => {
Ok(DeferOptimisticWriteResultWire::DiscardedSuperseded {
replacement_transaction_id: result.replacement_transaction_id.to_string(),
result: wire_write_result(ops, result.write_result),
})
}
}
}
/// Replaces a claimed optimistic layer with the real network response.
pub async fn commit_optimistic_write(
&self,
transaction_id: String,
lease_owner: String,
lease_generation: String,
query: String,
operation_name: Option<String>,
variables: Variables,
data: serde_json::Value,
) -> Result<CommitOptimisticWriteResultWire, String> {
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::write_projections(
engine,
&query,
operation_name.as_deref(),
&variables,
&data,
None,
)
.await?;
match engine
.commit_optimistic_write_with_projections_outcome(
transaction,
claim,
&query,
operation_name.as_deref(),
&variables,
&data,
projections,
)
.await
.map_err(|e| e.to_string())?
{
CommitOptimisticWriteResult::Failed(result) => {
Ok(CommitOptimisticWriteResultWire::Failed {
error: result.error,
replacement_transaction_id: result
.replacement_transaction_id
.map(|id| id.to_string()),
result: wire_write_result(ops, result.write_result),
})
}
CommitOptimisticWriteResult::Committed(result) => {
Ok(CommitOptimisticWriteResultWire::Committed {
result: wire_write_result(ops, result),
})
}
CommitOptimisticWriteResult::CommittedSuperseded(result) => {
Ok(CommitOptimisticWriteResultWire::CommittedSuperseded {
replacement_transaction_id: result.replacement_transaction_id.to_string(),
result: wire_write_result(ops, result.write_result),
})
}
}
}
/// Permanently fails a claimed mutation and drops its optimistic layer.
pub async fn rollback_optimistic_write(
&self,
transaction_id: String,
lease_owner: String,
lease_generation: String,
) -> Result<RollbackOptimisticWriteResultWire, String> {
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
match engine
.rollback_optimistic_write_with_outcome(transaction, claim)
.await
.map_err(|e| e.to_string())?
{
RollbackOptimisticWriteResult::RolledBack(result) => {
Ok(RollbackOptimisticWriteResultWire::RolledBack {
result: wire_write_result(ops, result),
})
}
RollbackOptimisticWriteResult::DiscardedSuperseded(result) => {
Ok(RollbackOptimisticWriteResultWire::DiscardedSuperseded {
replacement_transaction_id: result.replacement_transaction_id.to_string(),
result: wire_write_result(ops, result.write_result),
})
}
}
}
/// Evicts records by entity key; returns the affected registered op ids.
pub async fn invalidate(
&self,
keys: Vec<String>,
) -> Result<AffectedOperationsResultWire, String> {
let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::invalidation_projections(engine, &keys).await?;
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
let affected = engine
.invalidate_keys_with_projections(&keys, projections)
.await
.map_err(|error| error.to_string())?;
Ok(AffectedOperationsResultWire {
revision: affected.revision.to_string(),
affected_ops: ops.names(affected.value),
})
}
/// Deletes stale records from durable and hot storage and returns the
/// registered operations that traversed them.
pub async fn delete_records(
&self,
keys: Vec<String>,
) -> Result<AffectedOperationsResultWire, String> {
let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::deletion_projections(engine, &keys).await?;
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
let affected = engine
.delete_keys_with_projection_changes(&keys, projections)
.await
.map_err(|e| e.to_string())?;
Ok(AffectedOperationsResultWire {
revision: affected.revision.to_string(),
affected_ops: ops.names(affected.value),
})
}
/// Unregisters an operation (urql teardown).
pub async fn teardown(&self, op_id: String) -> Result<(), String> {
let mut state = self.inner.lock().await;
let EngineState { engine, ops, .. } = &mut *state;
if let Some(id) = ops.remove(&op_id) {
engine.teardown_operation(id);
}
Ok(())
}
/// Drops all cached state (logout).
pub async fn clear(&self) -> Result<CacheRevision, String> {
let mut state = self.inner.write().await;
state.engine.clear().await.map_err(|e| e.to_string())
}
}
#[cfg(test)]
mod test;
/// Atomically persists metadata separately from user records; no database reset occurs.
pub(crate) fn persist_schema(
path: &std::path::Path,
schema: &cache_core::meta::Schema,
) -> Result<(), String> {
let bytes = serde_json::to_vec(schema.artifact()).map_err(|e| e.to_string())?;
let temporary = path.with_extension("json.tmp");
use std::io::Write;
let mut file = std::fs::File::create(&temporary).map_err(|e| e.to_string())?;
file.write_all(&bytes).map_err(|e| e.to_string())?;
file.sync_all().map_err(|e| e.to_string())?;
drop(file);
std::fs::rename(&temporary, path).map_err(|e| e.to_string())?;
#[cfg(unix)]
if let Some(parent) = path.parent() {
std::fs::File::open(parent)
.and_then(|dir| dir.sync_all())
.map_err(|e| e.to_string())?;
}
Ok(())
}