pub struct QueryHandler { /* private fields */ }Expand description
Production query effect handler.
Implements QueryEffects by:
- Using
AuraQueryfor Datalog execution via Biscuit - Delegating subscription management to
ReactiveHandler - Tracking query dependencies for invalidation
- Optionally using IndexedJournalEffects for efficient fact lookups
§Authorization Model
Capability checks use a permissive model: queries pass if no capabilities
are explicitly required OR if all required capabilities are granted.
For production use with Biscuit integration, inject capabilities via
grant_capability() based on the authenticated token.
§Indexed Journal Integration
When an indexed journal is provided via with_indexed_journal(), the handler:
- Uses bloom filter pre-filtering to skip queries for non-existent predicates
- Can load facts directly from the index for O(log n) lookups
§Query Isolation
Supports four isolation levels:
ReadUncommitted: Immediate query against current CRDT stateReadCommitted: Wait for specific consensus IDs before queryingSnapshot: Query against historical state by prestate hashReadLatest: Wait for all pending consensus in a scope
Implementations§
Source§impl QueryHandler
impl QueryHandler
Sourcepub fn new(reactive: Arc<ReactiveHandler>) -> Self
pub fn new(reactive: Arc<ReactiveHandler>) -> Self
Create a new query handler with a reactive handler for subscriptions.
Sourcepub fn new_with_policy(
reactive: Arc<ReactiveHandler>,
policy: CapabilityPolicy,
) -> Self
pub fn new_with_policy( reactive: Arc<ReactiveHandler>, policy: CapabilityPolicy, ) -> Self
Create a new query handler with an explicit capability policy.
Sourcepub fn with_indexed_journal(
reactive: Arc<ReactiveHandler>,
indexed_journal: Arc<dyn IndexedJournalEffects + Send + Sync>,
) -> Self
pub fn with_indexed_journal( reactive: Arc<ReactiveHandler>, indexed_journal: Arc<dyn IndexedJournalEffects + Send + Sync>, ) -> Self
Create a query handler with indexed journal support.
When an indexed journal is provided, the handler can:
- Load facts from the index for efficient O(log n) predicate lookups
- Use bloom filter to quickly check if facts exist before expensive queries
Sourcepub fn with_indexed_journal_with_policy(
reactive: Arc<ReactiveHandler>,
indexed_journal: Arc<dyn IndexedJournalEffects + Send + Sync>,
policy: CapabilityPolicy,
) -> Self
pub fn with_indexed_journal_with_policy( reactive: Arc<ReactiveHandler>, indexed_journal: Arc<dyn IndexedJournalEffects + Send + Sync>, policy: CapabilityPolicy, ) -> Self
Create a query handler with indexed journal support and explicit policy.
Sourcepub fn with_consensus_timeout(self, timeout: Duration) -> Self
pub fn with_consensus_timeout(self, timeout: Duration) -> Self
Set the consensus wait timeout.
Sourcepub async fn add_fact(&self, predicate: &str, args: Vec<String>)
pub async fn add_fact(&self, predicate: &str, args: Vec<String>)
Add a fact to the query store.
Facts added here are available for all subsequent queries. In production, facts come from the journal via a fact stream.
Sourcepub async fn clear_facts(&self)
pub async fn clear_facts(&self)
Clear all facts.
Sourcepub async fn grant_capability(&self, cap: QueryCapability)
pub async fn grant_capability(&self, cap: QueryCapability)
Grant a capability for subsequent queries.
In production, capabilities are typically derived from Biscuit tokens after authentication. This method allows manual capability injection for testing or scenarios where capabilities are determined externally.
Sourcepub async fn set_capability_policy(&self, policy: CapabilityPolicy)
pub async fn set_capability_policy(&self, policy: CapabilityPolicy)
Set capability enforcement policy.
Use AllowAll in tests or offline scenarios that do not enforce Biscuit checks.
Sourcepub async fn load_facts_for_predicate(
&self,
predicate: &str,
) -> Result<usize, QueryError>
pub async fn load_facts_for_predicate( &self, predicate: &str, ) -> Result<usize, QueryError>
Load facts from the indexed journal for a specific predicate.
This uses O(log n) B-tree lookup to fetch all facts matching the predicate. Facts are loaded into the local store for query execution.
Returns the number of facts loaded.
Sourcepub fn might_contain_fact(&self, predicate: &str, value: &FactValue) -> bool
pub fn might_contain_fact(&self, predicate: &str, value: &FactValue) -> bool
Check if facts with the given predicate and value might exist.
Uses the bloom filter for O(1) membership testing.
Returns true if facts might exist, false if definitely not present.
This is useful for early query rejection - if returns false, the query
can be skipped entirely.
Sourcepub async fn register_query_binding<Q: Query>(
&self,
signal: &Signal<Q::Result>,
query: Q,
) -> Result<(), QueryError>
pub async fn register_query_binding<Q: Query>( &self, signal: &Signal<Q::Result>, query: Q, ) -> Result<(), QueryError>
Register a query binding for reactive refresh.
This stores the query and signal mapping and emits the initial query result.
Sourcepub async fn mark_consensus_completed(&self, id: ConsensusId)
pub async fn mark_consensus_completed(&self, id: ConsensusId)
Mark a consensus instance as completed.
Call this when a consensus operation completes to wake up any
queries waiting with ReadCommitted isolation.
Sourcepub async fn register_pending_consensus(
&self,
scope: ResourceScope,
id: ConsensusId,
)
pub async fn register_pending_consensus( &self, scope: ResourceScope, id: ConsensusId, )
Register a pending consensus instance for a resource scope.
Call this when a new consensus operation is started to track it
for ReadLatest isolation.
Sourcepub async fn create_snapshot(&self, prestate_hash: Hash32)
pub async fn create_snapshot(&self, prestate_hash: Hash32)
Create a snapshot of current facts at a specific prestate hash.
Call this when a consensus operation starts to enable Snapshot
isolation queries against this state.
Sourcepub async fn remove_snapshot(&self, prestate_hash: Hash32)
pub async fn remove_snapshot(&self, prestate_hash: Hash32)
Remove a snapshot (e.g., after garbage collection window).
Sourcepub async fn has_snapshot(&self, prestate_hash: &Hash32) -> bool
pub async fn has_snapshot(&self, prestate_hash: &Hash32) -> bool
Check if a snapshot exists for a prestate hash.