sqlitegraph/

backend.rs

//! Backend trait bridging sqlitegraph with higher-level graph consumers.
//!
//! This module contains the core GraphBackend trait and redirects to modular
//! backend implementations. SQLite-specific implementations are in the sqlite submodule.

// Include the modular backend structure
mod sqlite;

// Include native backend storage layer (no GraphBackend implementation yet)
pub mod native;

// Re-export from sqlite submodule
pub use sqlite::SqliteGraphBackend;

// Re-export from native submodule
pub use native::NativeGraphBackend;

// Re-export types for external users
pub use crate::multi_hop::ChainStep;
#[allow(unused_imports)] // Backend trait API types for future GraphBackend implementations
pub use sqlite::types::{BackendDirection, EdgeSpec, NeighborQuery, NodeSpec};

// KV store types (re-exported for public API)
#[cfg(feature = "native-v2")]
pub use crate::backend::native::v2::kv_store::types::{KvStoreError, KvValue};

// Pub/Sub types (re-exported for public API)
#[cfg(feature = "native-v2")]
pub use crate::backend::native::v2::pubsub::{PubSubEvent, SubscriptionFilter};

use crate::{
    SqliteGraphError,
    graph::GraphEntity,
    pattern::{PatternMatch, PatternQuery},
    snapshot::SnapshotId,
};

/// Backend trait defining the interface for graph database backends.
///
/// Each trait method delegates to backend-specific primitives while ensuring
/// deterministic behavior and a single integration surface for consumers.
///
/// # Snapshot Isolation
///
/// All read operations require a `snapshot_id: SnapshotId` parameter to enforce
/// ACID compliance. Reads only observe data committed at or before the snapshot.
pub trait GraphBackend {
    // Write operations (unchanged - commit returns SnapshotId in future)
    fn insert_node(&self, node: NodeSpec) -> Result<i64, SqliteGraphError>;
    fn insert_edge(&self, edge: EdgeSpec) -> Result<i64, SqliteGraphError>;

    // Read operations (require snapshot_id parameter)
    fn get_node(&self, snapshot_id: SnapshotId, id: i64) -> Result<GraphEntity, SqliteGraphError>;
    fn neighbors(
        &self,
        snapshot_id: SnapshotId,
        node: i64,
        query: NeighborQuery,
    ) -> Result<Vec<i64>, SqliteGraphError>;
    fn bfs(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        depth: u32,
    ) -> Result<Vec<i64>, SqliteGraphError>;
    fn shortest_path(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        end: i64,
    ) -> Result<Option<Vec<i64>>, SqliteGraphError>;
    fn node_degree(
        &self,
        snapshot_id: SnapshotId,
        node: i64,
    ) -> Result<(usize, usize), SqliteGraphError>;
    fn k_hop(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        depth: u32,
        direction: BackendDirection,
    ) -> Result<Vec<i64>, SqliteGraphError>;
    fn k_hop_filtered(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        depth: u32,
        direction: BackendDirection,
        allowed_edge_types: &[&str],
    ) -> Result<Vec<i64>, SqliteGraphError>;
    fn chain_query(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        chain: &[crate::multi_hop::ChainStep],
    ) -> Result<Vec<i64>, SqliteGraphError>;
    fn pattern_search(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        pattern: &PatternQuery,
    ) -> Result<Vec<PatternMatch>, SqliteGraphError>;

    /// Trigger WAL checkpoint for backends that support write-ahead logging
    ///
    /// For Native backend with WAL: flushes WAL to graph file
    /// For SQLite backend: executes PRAGMA wal_checkpoint(TRUNCATE)
    /// For backends without WAL: returns Ok(()) as no-op
    fn checkpoint(&self) -> Result<(), SqliteGraphError>;

    /// Create a backup of the database
    ///
    /// Creates a consistent snapshot of the database including all data pages.
    /// For Native V2 backend, optionally checkpoints before backup to ensure
    /// WAL is applied and snapshot is consistent.
    ///
    /// # Arguments
    /// * `backup_dir` - Destination directory for backup files
    ///
    /// # Returns
    /// Backup result with paths, checksum, and metadata
    fn backup(&self, backup_dir: &std::path::Path) -> Result<BackupResult, SqliteGraphError>;

    /// Export database snapshot to the specified directory
    ///
    /// Creates a consistent snapshot of the current database state.
    /// For Native backend: uses V2 snapshot format
    /// For SQLite backend: uses JSON dump format
    ///
    /// # Arguments
    /// * `export_dir` - Directory path where snapshot will be written
    ///
    /// # Returns
    /// Snapshot metadata including file paths and size information
    fn snapshot_export(
        &self,
        export_dir: &std::path::Path,
    ) -> Result<SnapshotMetadata, SqliteGraphError>;

    /// Import database snapshot from the specified directory
    ///
    /// Restores database state from a previously created snapshot.
    /// For Native backend: loads V2 snapshot format
    /// For SQLite backend: loads JSON dump format
    ///
    /// # Arguments
    /// * `import_dir` - Directory path containing snapshot files
    ///
    /// # Returns
    /// Import metadata including number of records imported
    fn snapshot_import(
        &self,
        import_dir: &std::path::Path,
    ) -> Result<ImportMetadata, SqliteGraphError>;

    /// Get a value from the KV store at the given snapshot
    ///
    /// # Arguments
    /// * `snapshot_id` - Only return data committed at or before this snapshot
    /// * `key` - Key to retrieve (arbitrary bytes)
    ///
    /// # Returns
    /// The value if found and visible at snapshot, or None if not found
    #[cfg(feature = "native-v2")]
    fn kv_get(
        &self,
        snapshot_id: SnapshotId,
        key: &[u8],
    ) -> Result<Option<crate::backend::native::v2::kv_store::types::KvValue>, SqliteGraphError>;

    /// Set a value in the KV store
    ///
    /// This operation participates in the current transaction and will
    /// be committed atomically with other graph operations.
    ///
    /// # Arguments
    /// * `key` - Key to set (arbitrary bytes)
    /// * `value` - Value to store
    /// * `ttl_seconds` - Optional TTL in seconds (None = no expiration)
    #[cfg(feature = "native-v2")]
    fn kv_set(
        &self,
        key: Vec<u8>,
        value: crate::backend::native::v2::kv_store::types::KvValue,
        ttl_seconds: Option<u64>,
    ) -> Result<(), SqliteGraphError>;

    /// Delete a value from the KV store
    ///
    /// This operation participates in the current transaction and will
    /// be committed atomically with other graph operations.
    ///
    /// # Arguments
    /// * `key` - Key to delete
    #[cfg(feature = "native-v2")]
    fn kv_delete(&self, key: &[u8]) -> Result<(), SqliteGraphError>;

    // Pub/Sub operations (in-process event notification)

    /// Subscribe to graph change events
    ///
    /// Returns a subscriber ID and a receiver channel for events.
    /// The receiver will receive events that match the given filter.
    ///
    /// # Events
    ///
    /// Events are emitted ONLY on transaction commit:
    /// - `NodeChanged` - node created or modified
    /// - `EdgeChanged` - edge created or modified
    /// - `KVChanged` - KV entry created, modified, or deleted
    /// - `SnapshotCommitted` - transaction committed
    ///
    /// # Best-Effort Delivery
    ///
    /// - No persistence of events
    /// - If receiver is dropped, events are silently dropped
    /// - If channel is full, events are silently dropped
    /// - No delivery guarantees
    ///
    /// # Example
    ///
    /// ```ignore
    /// let (sub_id, rx) = graph.subscribe(SubscriptionFilter::all());
    /// // In another thread/task:
    /// for event in rx {
    ///     match event {
    ///         PubSubEvent::NodeChanged { node_id, snapshot_id } => {
    ///             // Read node state at snapshot_id
    ///         }
    ///         _ => {}
    ///     }
    /// }
    /// }
    /// ```
    #[cfg(feature = "native-v2")]
    fn subscribe(
        &self,
        filter: SubscriptionFilter,
    ) -> Result<(u64, std::sync::mpsc::Receiver<PubSubEvent>), SqliteGraphError>;

    /// Unsubscribe from events
    ///
    /// Cancels the subscription and stops receiving events.
    /// Returns true if subscription existed and was removed.
    ///
    /// # Arguments
    /// * `subscriber_id` - The subscriber ID returned by subscribe()
    #[cfg(feature = "native-v2")]
    fn unsubscribe(&self, subscriber_id: u64) -> Result<bool, SqliteGraphError>;

    // ========== Pub/Sub Enhancement APIs (v1.4.0) ==========

    /// Scan all KV entries with a given prefix
    ///
    /// Returns all keys that start with the given prefix, along with their values.
    /// Results are in lexicographic order by key.
    ///
    /// # Arguments
    /// * `snapshot_id` - Only return data committed at or before this snapshot
    /// * `prefix` - Prefix to match (empty prefix returns all keys)
    ///
    /// # Returns
    /// Vector of (key, value) pairs for all matching keys
    #[cfg(feature = "native-v2")]
    fn kv_prefix_scan(
        &self,
        snapshot_id: SnapshotId,
        prefix: &[u8],
    ) -> Result<Vec<(Vec<u8>, crate::backend::native::v2::kv_store::types::KvValue)>, SqliteGraphError>;

    /// Query all nodes with a given kind
    ///
    /// Returns all node IDs where the node's kind equals the given string.
    /// Results are sorted by node ID for deterministic output.
    ///
    /// # Arguments
    /// * `snapshot_id` - Only return data committed at or before this snapshot
    /// * `kind` - Kind string to match (case-sensitive)
    ///
    /// # Returns
    /// Vector of node IDs with matching kind
    fn query_nodes_by_kind(
        &self,
        snapshot_id: SnapshotId,
        kind: &str,
    ) -> Result<Vec<i64>, SqliteGraphError>;

    /// Query nodes by name pattern using glob matching
    ///
    /// Returns all node IDs where the node's label matches the glob pattern.
    /// Pattern syntax:
    /// - `*` matches any sequence of characters
    /// - `?` matches exactly one character
    ///
    /// # Arguments
    /// * `snapshot_id` - Only return data committed at or before this snapshot
    /// * `pattern` - Glob pattern to match against node labels
    ///
    /// # Returns
    /// Vector of node IDs with matching labels
    fn query_nodes_by_name_pattern(
        &self,
        snapshot_id: SnapshotId,
        pattern: &str,
    ) -> Result<Vec<i64>, SqliteGraphError>;
}

/// Metadata returned by snapshot export operations
#[derive(Debug, Clone)]
pub struct SnapshotMetadata {
    /// Path to the snapshot file
    pub snapshot_path: std::path::PathBuf,
    /// Snapshot size in bytes
    pub size_bytes: u64,
    /// Number of entities in snapshot
    pub entity_count: u64,
    /// Number of edges in snapshot
    pub edge_count: u64,
}

/// Metadata returned by snapshot import operations
#[derive(Debug, Clone)]
pub struct ImportMetadata {
    /// Path to the imported snapshot
    pub snapshot_path: std::path::PathBuf,
    /// Number of entities imported
    pub entities_imported: u64,
    /// Number of edges imported
    pub edges_imported: u64,
}

/// Result returned by backup operations
#[derive(Debug, Clone)]
pub struct BackupResult {
    /// Path to backup snapshot file
    pub snapshot_path: std::path::PathBuf,

    /// Path to backup manifest file
    pub manifest_path: std::path::PathBuf,

    /// Backup size in bytes
    pub size_bytes: u64,

    /// Backup checksum
    pub checksum: u64,

    /// Number of records in backup
    pub record_count: u64,

    /// Backup duration in seconds
    pub duration_secs: f64,

    /// Backup timestamp (Unix epoch)
    pub timestamp: u64,

    /// Whether checkpoint was performed before backup
    pub checkpoint_performed: bool,
}

/// Reference implementation for GraphBackend trait that works with references.
impl<B> GraphBackend for &B
where
    B: GraphBackend + ?Sized,
{
    fn insert_node(&self, node: NodeSpec) -> Result<i64, SqliteGraphError> {
        (*self).insert_node(node)
    }

    fn get_node(&self, snapshot_id: SnapshotId, id: i64) -> Result<GraphEntity, SqliteGraphError> {
        (*self).get_node(snapshot_id, id)
    }

    fn insert_edge(&self, edge: EdgeSpec) -> Result<i64, SqliteGraphError> {
        (*self).insert_edge(edge)
    }

    fn neighbors(
        &self,
        snapshot_id: SnapshotId,
        node: i64,
        query: NeighborQuery,
    ) -> Result<Vec<i64>, SqliteGraphError> {
        (*self).neighbors(snapshot_id, node, query)
    }

    fn bfs(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        depth: u32,
    ) -> Result<Vec<i64>, SqliteGraphError> {
        (*self).bfs(snapshot_id, start, depth)
    }

    fn shortest_path(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        end: i64,
    ) -> Result<Option<Vec<i64>>, SqliteGraphError> {
        (*self).shortest_path(snapshot_id, start, end)
    }

    fn node_degree(
        &self,
        snapshot_id: SnapshotId,
        node: i64,
    ) -> Result<(usize, usize), SqliteGraphError> {
        (*self).node_degree(snapshot_id, node)
    }

    fn k_hop(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        depth: u32,
        direction: BackendDirection,
    ) -> Result<Vec<i64>, SqliteGraphError> {
        (*self).k_hop(snapshot_id, start, depth, direction)
    }

    fn k_hop_filtered(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        depth: u32,
        direction: BackendDirection,
        allowed_edge_types: &[&str],
    ) -> Result<Vec<i64>, SqliteGraphError> {
        (*self).k_hop_filtered(snapshot_id, start, depth, direction, allowed_edge_types)
    }

    fn chain_query(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        chain: &[crate::multi_hop::ChainStep],
    ) -> Result<Vec<i64>, SqliteGraphError> {
        (*self).chain_query(snapshot_id, start, chain)
    }

    fn pattern_search(
        &self,
        snapshot_id: SnapshotId,
        start: i64,
        pattern: &PatternQuery,
    ) -> Result<Vec<PatternMatch>, SqliteGraphError> {
        (*self).pattern_search(snapshot_id, start, pattern)
    }

    fn checkpoint(&self) -> Result<(), SqliteGraphError> {
        (*self).checkpoint()
    }

    fn backup(&self, backup_dir: &std::path::Path) -> Result<BackupResult, SqliteGraphError> {
        (*self).backup(backup_dir)
    }

    fn snapshot_export(
        &self,
        export_dir: &std::path::Path,
    ) -> Result<SnapshotMetadata, SqliteGraphError> {
        (*self).snapshot_export(export_dir)
    }

    fn snapshot_import(
        &self,
        import_dir: &std::path::Path,
    ) -> Result<ImportMetadata, SqliteGraphError> {
        (*self).snapshot_import(import_dir)
    }

    #[cfg(feature = "native-v2")]
    fn kv_get(
        &self,
        snapshot_id: SnapshotId,
        key: &[u8],
    ) -> Result<Option<crate::backend::native::v2::kv_store::types::KvValue>, SqliteGraphError>
    {
        (*self).kv_get(snapshot_id, key)
    }

    #[cfg(feature = "native-v2")]
    fn kv_set(
        &self,
        key: Vec<u8>,
        value: crate::backend::native::v2::kv_store::types::KvValue,
        ttl_seconds: Option<u64>,
    ) -> Result<(), SqliteGraphError> {
        (*self).kv_set(key, value, ttl_seconds)
    }

    #[cfg(feature = "native-v2")]
    fn kv_delete(&self, key: &[u8]) -> Result<(), SqliteGraphError> {
        (*self).kv_delete(key)
    }

    #[cfg(feature = "native-v2")]
    fn subscribe(
        &self,
        filter: SubscriptionFilter,
    ) -> Result<(u64, std::sync::mpsc::Receiver<PubSubEvent>), SqliteGraphError> {
        (*self).subscribe(filter)
    }

    #[cfg(feature = "native-v2")]
    fn unsubscribe(&self, subscriber_id: u64) -> Result<bool, SqliteGraphError> {
        (*self).unsubscribe(subscriber_id)
    }

    #[cfg(feature = "native-v2")]
    fn kv_prefix_scan(
        &self,
        snapshot_id: SnapshotId,
        prefix: &[u8],
    ) -> Result<Vec<(Vec<u8>, crate::backend::native::v2::kv_store::types::KvValue)>, SqliteGraphError> {
        (*self).kv_prefix_scan(snapshot_id, prefix)
    }

    fn query_nodes_by_kind(
        &self,
        snapshot_id: SnapshotId,
        kind: &str,
    ) -> Result<Vec<i64>, SqliteGraphError> {
        (*self).query_nodes_by_kind(snapshot_id, kind)
    }

    fn query_nodes_by_name_pattern(
        &self,
        snapshot_id: SnapshotId,
        pattern: &str,
    ) -> Result<Vec<i64>, SqliteGraphError> {
        (*self).query_nodes_by_name_pattern(snapshot_id, pattern)
    }
}