lora-python 0.2.0__tar.gz → 0.3.0__tar.gz

{lora_python-0.2.0 → lora_python-0.3.0}/Cargo.lock

@@ -116,6 +116,15 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "bincode"
+version = "1.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1f45e9417d87227c7a56d22e471c6206462cba514c7590c09aff4cf6d1ddcad"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "bindgen"
 version = "0.72.1"
@@ -283,6 +292,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "criterion"
 version = "0.8.2"
@@ -611,7 +629,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lora-analyzer"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "lora-ast",
  "lora-parser",
@@ -621,14 +639,14 @@ dependencies = [
 
 [[package]]
 name = "lora-ast"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "smallvec 2.0.0-alpha.12",
 ]
 
 [[package]]
 name = "lora-compiler"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -636,7 +654,7 @@ dependencies = [
 
 [[package]]
 name = "lora-database"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "criterion",
@@ -652,7 +670,7 @@ dependencies = [
 
 [[package]]
 name = "lora-executor"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -666,7 +684,7 @@ dependencies = [
 
 [[package]]
 name = "lora-ffi"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "lora-database",
  "lora-store",
@@ -676,7 +694,7 @@ dependencies = [
 
 [[package]]
 name = "lora-node"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "lora-database",
@@ -690,7 +708,7 @@ dependencies = [
 
 [[package]]
 name = "lora-parser"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "lora-ast",
  "pest",
@@ -701,7 +719,7 @@ dependencies = [
 
 [[package]]
 name = "lora-python"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "lora-database",
@@ -713,10 +731,11 @@ dependencies = [
 
 [[package]]
 name = "lora-server"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "axum",
+ "http-body-util",
  "lora-database",
  "serde",
  "serde_json",
@@ -726,15 +745,19 @@ dependencies = [
 
 [[package]]
 name = "lora-store"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
+ "bincode",
+ "crc32fast",
  "js-sys",
  "lora-ast",
+ "serde",
+ "thiserror",
 ]
 
 [[package]]
 name = "lora-wasm"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "console_error_panic_hook",
@@ -749,7 +772,7 @@ dependencies = [
 
 [[package]]
 name = "lora_ruby"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "lora-database",

{lora_python-0.2.0 → lora_python-0.3.0}/Cargo.toml

@@ -4,7 +4,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.2.0"
+version = "0.3.0"
 license = "BUSL-1.1"
 authors = ["LoraDB, Inc."]
 repository = "https://github.com/lora-db/lora"
@@ -15,13 +15,13 @@ rust-version = "1.87"
 # Internal crates — versions are kept in lockstep with [workspace.package].version
 # by `scripts/sync-versions.mjs`. Both `path` and `version` are set so that
 # `cargo publish` works (crates.io cannot resolve path-only deps).
-lora-ast = { path = "crates/lora-ast", version = "=0.2.0" }
-lora-parser = { path = "crates/lora-parser", version = "=0.2.0" }
-lora-analyzer = { path = "crates/lora-analyzer", version = "=0.2.0" }
-lora-compiler = { path = "crates/lora-compiler", version = "=0.2.0" }
-lora-store = { path = "crates/lora-store", version = "=0.2.0" }
-lora-executor = { path = "crates/lora-executor", version = "=0.2.0" }
-lora-database = { path = "crates/lora-database", version = "=0.2.0" }
+lora-ast = { path = "crates/lora-ast", version = "=0.3.0" }
+lora-parser = { path = "crates/lora-parser", version = "=0.3.0" }
+lora-analyzer = { path = "crates/lora-analyzer", version = "=0.3.0" }
+lora-compiler = { path = "crates/lora-compiler", version = "=0.3.0" }
+lora-store = { path = "crates/lora-store", version = "=0.3.0" }
+lora-executor = { path = "crates/lora-executor", version = "=0.3.0" }
+lora-database = { path = "crates/lora-database", version = "=0.3.0" }
 
 # External crates.
 anyhow = "1"
@@ -37,3 +37,5 @@ serde_json = "1.0.149"
 regex = "1"
 tower = "0.5.3"
 criterion = { version = "0.8.2", features = ["html_reports"] }
+bincode = "1.3"
+crc32fast = "1.4"

{lora_python-0.2.0 → lora_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lora-python
-Version: 0.2.0
+Version: 0.3.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8

{lora_python-0.2.0 → lora_python-0.3.0}/crates/lora-analyzer/src/analyzer.rs

@@ -5,10 +5,10 @@ use lora_ast::{
     ReadingClause, RelationshipPattern, Remove, RemoveItem, Return, Set, SetItem, SinglePartQuery,
     SingleQuery, Statement, Unwind, UpdatingClause, With,
 };
-use lora_store::GraphStorage;
+use lora_store::GraphCatalog;
 use std::collections::{BTreeMap, BTreeSet};
 
-pub struct Analyzer<'a, S: GraphStorage + ?Sized> {
+pub struct Analyzer<'a, S: GraphCatalog + ?Sized> {
     storage: &'a S,
     scopes: ScopeStack,
     symbols: SymbolTable,
@@ -22,7 +22,7 @@ enum PatternContext {
     Write,
 }
 
-impl<'a, S: GraphStorage + ?Sized> Analyzer<'a, S> {
+impl<'a, S: GraphCatalog + ?Sized> Analyzer<'a, S> {
     pub fn new(storage: &'a S) -> Self {
         Self {
             storage,

lora_python-0.3.0/crates/lora-database/src/database.rs

@@ -0,0 +1,301 @@
+use std::collections::BTreeMap;
+use std::fs::{File, OpenOptions};
+use std::io::{BufReader, BufWriter};
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Mutex, MutexGuard};
+
+use anyhow::Result;
+use lora_analyzer::Analyzer;
+use lora_ast::Document;
+use lora_compiler::{CompiledQuery, Compiler};
+use lora_executor::{
+    ExecuteOptions, LoraValue, MutableExecutionContext, MutableExecutor, QueryResult,
+};
+use lora_parser::parse_query;
+use lora_store::{GraphStorage, GraphStorageMut, InMemoryGraph, SnapshotMeta, Snapshotable};
+
+/// Minimal abstraction any transport can depend on to run Lora queries.
+pub trait QueryRunner: Send + Sync + 'static {
+    fn execute(&self, query: &str, options: Option<ExecuteOptions>) -> Result<QueryResult>;
+}
+
+/// Owns the graph store and orchestrates parse → analyze → compile → execute.
+pub struct Database<S> {
+    store: Arc<Mutex<S>>,
+}
+
+impl Database<InMemoryGraph> {
+    /// Convenience constructor: a fresh, empty in-memory graph database.
+    pub fn in_memory() -> Self {
+        Self::from_graph(InMemoryGraph::new())
+    }
+}
+
+impl<S> Database<S>
+where
+    S: GraphStorage + GraphStorageMut,
+{
+    /// Build a database from a pre-wrapped, shared store.
+    pub fn new(store: Arc<Mutex<S>>) -> Self {
+        Self { store }
+    }
+
+    /// Build a database by taking ownership of a bare graph store.
+    pub fn from_graph(graph: S) -> Self {
+        Self::new(Arc::new(Mutex::new(graph)))
+    }
+
+    /// Handle to the underlying shared store — useful for callers that need
+    /// to snapshot or share the graph across multiple databases.
+    pub fn store(&self) -> &Arc<Mutex<S>> {
+        &self.store
+    }
+
+    /// Parse a query string into an AST without executing it.
+    pub fn parse(&self, query: &str) -> Result<Document> {
+        Ok(parse_query(query)?)
+    }
+
+    fn lock_store(&self) -> MutexGuard<'_, S> {
+        self.store
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
+    fn compile_query(&self, query: &str) -> Result<(MutexGuard<'_, S>, CompiledQuery)> {
+        let document = self.parse(query)?;
+        let store = self.lock_store();
+
+        let resolved = {
+            let mut analyzer = Analyzer::new(&*store);
+            analyzer.analyze(&document)?
+        };
+
+        let compiled = Compiler::compile(&resolved);
+        Ok((store, compiled))
+    }
+
+    /// Execute a query and return its result.
+    pub fn execute(&self, query: &str, options: Option<ExecuteOptions>) -> Result<QueryResult> {
+        self.execute_with_params(query, options, BTreeMap::new())
+    }
+
+    /// Execute a query with bound parameters.
+    pub fn execute_with_params(
+        &self,
+        query: &str,
+        options: Option<ExecuteOptions>,
+        params: BTreeMap<String, LoraValue>,
+    ) -> Result<QueryResult> {
+        let (mut store, compiled) = self.compile_query(query)?;
+
+        let mut executor = MutableExecutor::new(MutableExecutionContext {
+            storage: &mut *store,
+            params,
+        });
+
+        Ok(executor.execute_compiled(&compiled, options)?)
+    }
+
+    // ---------- Storage-agnostic utility helpers ----------
+    //
+    // Bindings previously reached into `Arc<Mutex<InMemoryGraph>>` to answer
+    // stat / admin calls; these helpers let them depend on `Database<S>`
+    // instead, so swapping in a new backend only requires changing one type
+    // parameter.
+
+    /// Drop every node and relationship.
+    pub fn clear(&self) {
+        let mut guard = self.lock_store();
+        guard.clear();
+    }
+
+    /// Number of nodes currently in the graph.
+    pub fn node_count(&self) -> usize {
+        let guard = self.lock_store();
+        guard.node_count()
+    }
+
+    /// Number of relationships currently in the graph.
+    pub fn relationship_count(&self) -> usize {
+        let guard = self.lock_store();
+        guard.relationship_count()
+    }
+
+    /// Run a closure with a shared borrow of the underlying store. Used by
+    /// bindings to answer ad-hoc queries without locking the mutex themselves.
+    pub fn with_store<R>(&self, f: impl FnOnce(&S) -> R) -> R {
+        let guard = self.lock_store();
+        f(&*guard)
+    }
+
+    /// Run a closure with an exclusive borrow of the underlying store. Reserved
+    /// for admin paths (restore, bulk load); regular mutation goes through
+    /// `execute_with_params`.
+    pub fn with_store_mut<R>(&self, f: impl FnOnce(&mut S) -> R) -> R {
+        let mut guard = self.lock_store();
+        f(&mut *guard)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot helpers
+//
+// A second impl block so the `Snapshotable` bound only constrains backends
+// that actually need it. `Database<InMemoryGraph>` picks these up
+// automatically; hypothetical backends that don't implement `Snapshotable`
+// still get the core query API above.
+// ---------------------------------------------------------------------------
+
+impl<S> Database<S>
+where
+    S: GraphStorage + GraphStorageMut + Snapshotable,
+{
+    /// Serialize the current graph state to the given path. Writes are
+    /// atomic: the payload goes to `<path>.tmp`, is `fsync`'d, and then
+    /// renamed over the target; a torn write can never leave a half-written
+    /// file at `path`. If any step before the rename fails, the stale
+    /// `<path>.tmp` is removed so a crashed save never leaks scratch files.
+    ///
+    /// Holds the store mutex for the duration of the save so concurrent
+    /// queries see a consistent point-in-time snapshot.
+    pub fn save_snapshot_to(&self, path: impl AsRef<Path>) -> Result<SnapshotMeta> {
+        let path = path.as_ref();
+        let tmp = snapshot_tmp_path(path);
+
+        // Acquire the lock once so the snapshot is point-in-time consistent.
+        let guard = self.lock_store();
+
+        let file = OpenOptions::new()
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .open(&tmp)?;
+        // Arm cleanup immediately after `open` succeeds: every early return
+        // below must either surface an error *and* unlink the tmp, or commit
+        // the guard once the rename takes effect.
+        let tmp_guard = TempFileGuard::new(tmp.clone());
+        let mut writer = BufWriter::new(file);
+
+        let meta = guard.save_snapshot(&mut writer)?;
+
+        // Flush the BufWriter before fsync; otherwise we fsync an empty
+        // underlying file.
+        use std::io::Write;
+        writer.flush()?;
+        let file = writer.into_inner().map_err(|e| e.into_error())?;
+        file.sync_all()?;
+        drop(file);
+
+        std::fs::rename(&tmp, path)?;
+        // The tmp path no longer has a file behind it — disarm the guard so
+        // it doesn't try to remove the just-renamed target by name race.
+        tmp_guard.commit();
+
+        // Best-effort parent-dir fsync so the rename itself is durable on
+        // power loss. Non-fatal if the parent can't be opened.
+        if let Some(parent) = path.parent() {
+            if let Ok(dir) = File::open(parent) {
+                let _ = dir.sync_all();
+            }
+        }
+
+        Ok(meta)
+    }
+
+    /// Replace the current graph state with a snapshot loaded from `path`.
+    /// Holds the store mutex for the duration of the load; concurrent
+    /// queries block until restore completes.
+    pub fn load_snapshot_from(&self, path: impl AsRef<Path>) -> Result<SnapshotMeta> {
+        let file = File::open(path.as_ref())?;
+        let reader = BufReader::new(file);
+
+        let mut guard = self.lock_store();
+        Ok(guard.load_snapshot(reader)?)
+    }
+}
+
+impl Database<InMemoryGraph> {
+    /// Convenience constructor: open (or create) an empty in-memory database
+    /// and immediately restore it from `path`. Errors if the file cannot be
+    /// opened or the snapshot is malformed.
+    pub fn in_memory_from_snapshot(path: impl AsRef<Path>) -> Result<Self> {
+        let db = Self::in_memory();
+        db.load_snapshot_from(path)?;
+        Ok(db)
+    }
+}
+
+fn snapshot_tmp_path(target: &Path) -> PathBuf {
+    let mut tmp = target.as_os_str().to_owned();
+    tmp.push(".tmp");
+    PathBuf::from(tmp)
+}
+
+/// RAII handle that deletes its path on drop unless [`commit`] is called.
+///
+/// The snapshot save path creates `<target>.tmp` before the payload is
+/// written; if any step between then and the final rename fails (or the
+/// thread unwinds), the guard's `Drop` removes the scratch file so a crashed
+/// save never leaves leftovers on disk.
+///
+/// [`commit`]: Self::commit
+struct TempFileGuard {
+    path: Option<PathBuf>,
+}
+
+impl TempFileGuard {
+    fn new(path: PathBuf) -> Self {
+        Self { path: Some(path) }
+    }
+
+    /// Disarm the guard. Call this once the tmp file's contents have been
+    /// handed off (e.g. renamed to their final destination) so the `Drop`
+    /// impl does not try to remove them.
+    fn commit(mut self) {
+        self.path.take();
+    }
+}
+
+impl Drop for TempFileGuard {
+    fn drop(&mut self) {
+        if let Some(path) = self.path.take() {
+            // Best-effort: cleanup failure is not worth surfacing — the
+            // worst case is a leaked scratch file that the next save
+            // overwrites via `OpenOptions::truncate(true)`.
+            let _ = std::fs::remove_file(path);
+        }
+    }
+}
+
+/// Storage-agnostic admin surface for HTTP / binding callers that want to
+/// drive snapshot operations without naming the backend type parameter.
+///
+/// `Database<S>` picks up a blanket impl when `S: Snapshotable + 'static`.
+/// Transports (e.g. `lora-server`) type-erase on `Arc<dyn SnapshotAdmin>`.
+pub trait SnapshotAdmin: Send + Sync + 'static {
+    fn save_snapshot(&self, path: &Path) -> Result<SnapshotMeta>;
+    fn load_snapshot(&self, path: &Path) -> Result<SnapshotMeta>;
+}
+
+impl<S> SnapshotAdmin for Database<S>
+where
+    S: GraphStorage + GraphStorageMut + Snapshotable + Send + 'static,
+{
+    fn save_snapshot(&self, path: &Path) -> Result<SnapshotMeta> {
+        self.save_snapshot_to(path)
+    }
+
+    fn load_snapshot(&self, path: &Path) -> Result<SnapshotMeta> {
+        self.load_snapshot_from(path)
+    }
+}
+
+impl<S> QueryRunner for Database<S>
+where
+    S: GraphStorage + GraphStorageMut + Send + 'static,
+{
+    fn execute(&self, query: &str, options: Option<ExecuteOptions>) -> Result<QueryResult> {
+        Database::execute(self, query, options)
+    }
+}

{lora_python-0.2.0 → lora_python-0.3.0}/crates/lora-database/src/lib.rs

@@ -16,7 +16,7 @@
 
 mod database;
 
-pub use database::{Database, QueryRunner};
+pub use database::{Database, QueryRunner, SnapshotAdmin};
 
 // Re-export the core execution types so callers don't need a direct
 // dependency on `lora-executor`.
@@ -26,5 +26,9 @@ pub use lora_executor::{ExecuteOptions, LoraValue, QueryResult, ResultFormat};
 // depend on `lora-database` for the happy path.
 pub use lora_store::InMemoryGraph;
 
+// Snapshot surface — re-exported so bindings/servers don't need a direct
+// `lora-store` dependency just to name the meta / error types.
+pub use lora_store::{SnapshotError, SnapshotMeta, Snapshotable};
+
 // Standalone parsing entry point (does not require building a `Database`).
 pub use lora_parser::parse_query;