Struct QueryCacheCoordinator 

pub struct QueryCacheCoordinator { /* private fields */ }

Coordinates query-result caching: owns the QueryCache, the reverse table -> query index used for mutation invalidation, and the auth-scope derivation that keys cache entries per principal.

Splitting these out of super::router::FunctionRouter keeps the router focused on dispatch and lets the cache concerns be tested in isolation.

Implementations

impl QueryCacheCoordinator

pub fn new(registry: &FunctionRegistry) -> Self

Create a coordinator from the function registry. The reverse index is built once at construction so mutation invalidation is a hash lookup.

pub fn get_by_scope( &self, function_name: &str, args: &Value, scope: Option<&str>, ) -> Option<Arc<Value>>

Lookup a cached value with an already-derived scope. Use this when the caller has computed Self::auth_scope up front (e.g. before auth is moved into a context).

pub fn set_by_scope( &self, function_name: &str, args: &Value, scope: Option<&str>, value: Value, ttl: Duration, )

Store a value with an already-derived scope.

pub fn set_arc_by_scope( &self, function_name: &str, args: &Value, scope: Option<&str>, value: Arc<Value>, ttl: Duration, )

Store a pre-wrapped Arc<Value> with an already-derived scope.

pub fn invalidate_for_mutation(&self, info: &FunctionInfo)

Invalidate cached queries whose table dependencies overlap with the mutation’s write set, narrowed by column intersection when both sides know which columns they touch.

Conservative on uncertainty: when either the mutation’s changed_columns or the candidate query’s selected_columns is empty (extractor couldn’t determine columns from the SQL), the query is invalidated. False positives are cheap (re-execute a query); false negatives would serve stale data.

pub fn invalidate_by_change(&self, change: &Change)

Invalidate cached queries affected by a forge_changes NOTIFY event.

Used to propagate mutations across cluster nodes: every node listening to forge_changes runs this for each peer-emitted change so its local cache stays consistent. Without this, mutations on node A leave stale cache entries on node B until TTL expires.

Mirrors invalidate_for_mutation’s column-intersection logic but uses the change’s runtime changed_columns rather than the mutation’s compile-time set. An empty change column list means “could be any column” (older trigger payloads, INSERT/DELETE) — fall back to full invalidation for that table.

pub fn spawn_cluster_invalidator( self: Arc<Self>, rx: Receiver<Change>, ) -> JoinHandle<()>

Spawn a background task that drains a Change broadcast and evicts matching cache entries. Returns a handle the caller can abort on shutdown. The receiver typically comes from Reactor::change_subscriber().

pub fn auth_scope(auth: &AuthContext) -> Option<String>

Derive a stable cache scope from auth context. Anonymous callers share the "anon" scope; authenticated callers get a hash that mixes role + claims so cross-tenant cache bleed is impossible.

Volatile JWT claims (iat, nbf, exp, jti, auth_time, sid, nonce) are excluded — they change on every token refresh for the same logical principal and would otherwise fragment the cache, killing hit rate for any system using refresh tokens.